Shujakuin
128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# proxy-port-monitor-tui
|
||
|
||
- 文档层级：客户端工具
|
||
- 应用性质：客户端 TUI
|
||
- 源码来源：repo 原生
|
||
- 运行关系：客户端工具
|
||
- 部署模型：无
|
||
- 对应服务：无
|
||
- 对应 stack：无
|
||
- Secret 边界：无 secret
|
||
- 分发方式：`uv run` / `uv tool install`。
|
||
- 包名：`proxy-port-monitor-tui`
|
||
- 命令名：`proxy-monitor-tui`
|
||
- 本地状态路径：`~/.config/proxy-port-monitor-tui/`
|
||
- 目标 API：server2 的 proxy-port-monitor Tailscale Service。
|
||
- 备注：客户端不保存 SSH 凭据、mihomo controller secret、订阅 URL 或节点密码。
|
||
|
||
## 项目定位
|
||
|
||
用于在本机终端查看 Proxy Port Monitor 的目标连通性，并通过既有的
|
||
同源 controller 转发查看 mihomo Selector 组、做低流量延迟探测，以及
|
||
手动切换单个 Selector 的运行态当前节点。
|
||
|
||
它不是通用代理客户端，不直接 SSH 到目标机，不编辑 subscription、mixin、
|
||
host_vars 或远端 mihomo 配置文件。
|
||
|
||
## 文档边界
|
||
|
||
本 README 说明本地客户端；服务入口、Tailscale Service 和 controller secret
|
||
边界仍由 proxy-port-monitor 的 service README 维护。
|
||
|
||
## 源码结构
|
||
|
||
- `proxy_monitor_tui.py`：CLI、HTTP API client、Textual 视图和运行态切换确认。
|
||
- `tests/test_proxy_monitor_tui.py`：mock HTTP server 覆盖状态、控制器路径、测速和切换请求。
|
||
- `pyproject.toml`：Python 包与命令入口。
|
||
|
||
## 对应服务文档
|
||
|
||
- `services/server2/systemd/proxy-port-monitor/current/README.md`
|
||
|
||
## 运行与部署模型
|
||
|
||
这是本机客户端工具，没有 systemd、Compose 或 Ansible 部署模型。开发时可直接运行：
|
||
|
||
``BT@@text
|
||
cd apps/proxy-port-monitor-tui
|
||
uv run proxy-monitor-tui
|
||
``BT@@
|
||
|
||
安装为当前用户命令：
|
||
|
||
``BT@@text
|
||
uv tool install git+https://gitea.shujk.top/shujakuin/proxy-port-monitor-tui.git
|
||
proxy-monitor-tui
|
||
``BT@@
|
||
|
||
升级到仓库最新版本：
|
||
|
||
``BT@@text
|
||
uv tool install --upgrade git+https://gitea.shujk.top/shujakuin/proxy-port-monitor-tui.git
|
||
``BT@@
|
||
|
||
若要把它作为某个 Python 项目的依赖（而非安装为当前用户命令），在该项目目录运行：
|
||
|
||
``BT@@text
|
||
uv add git+https://gitea.shujk.top/shujakuin/proxy-port-monitor-tui.git
|
||
uv run proxy-monitor-tui
|
||
``BT@@
|
||
|
||
默认 API 地址是 `https://proxy.tailbeb9ad.ts.net`。可使用 `--api-url` 覆盖，或以
|
||
`--save-config` 保存到本地状态路径。支持的环境变量：
|
||
|
||
- `PROXY_MONITOR_TUI_API_URL`
|
||
- `PROXY_MONITOR_TUI_API_URL_FILE`
|
||
- `PROXY_MONITOR_TUI_REFRESH_SECONDS`
|
||
- `PROXY_MONITOR_TUI_TIMEOUT`
|
||
- `PROXY_MONITOR_TUI_TEST_URL`
|
||
- `PROXY_MONITOR_TUI_TEST_TIMEOUT_MS`
|
||
- `PROXY_MONITOR_TUI_DELAY_CONCURRENCY`
|
||
|
||
## 配置与 Secret 边界
|
||
|
||
客户端只读取 `/status.json`，并限于调用每台机器的 `proxies`、`delay` 和 Selector
|
||
切换 controller API；不会调用 Proxy Port Monitor 的 `/config` 写接口。
|
||
|
||
controller secret 始终由 server2 的 proxy-port-monitor 服务注入。客户端不读取
|
||
SOPS 文件、运行时 env、SSH key 或 mihomo 配置。
|
||
|
||
## 使用方式
|
||
|
||
主列表显示机器的 17890 可达性、连续失败数、出口位置和最近检查时间：
|
||
|
||
- `Enter`：仅在目标在线时进入其 controller 详情。
|
||
- `r`：刷新连通性状态。
|
||
- `t`：对当前 Selector 组的候选节点做 mihomo delay 探测；默认使用
|
||
`https://www.gstatic.com/generate_204`，最多并发 4 个。每个 candidate 完成后会立即
|
||
更新 delay 和当前推荐，慢节点或超时节点不会阻塞先完成的结果显示。
|
||
- `s`：对当前选择的候选节点发起运行态切换。TUI 会显示机器、组、旧节点和新节点，
|
||
必须按 `y` 二次确认；成功后立即读取 controller 验证当前节点。
|
||
|
||
测速只推荐最低延迟的成功节点，绝不自动切换。切换不会写回订阅、mixin、受管模型
|
||
或仓库真源，服务重启或上游配置刷新后的持久化行为以目标 mihomo 实现为准。
|
||
|
||
可用 `--once` 只打印当前机器连通性后退出，适用于脚本或只读排障。
|
||
|
||
## 测试与发布
|
||
|
||
本地验证：
|
||
|
||
``BT@@text
|
||
cd apps/proxy-port-monitor-tui
|
||
uv run python -m unittest discover -s tests -v
|
||
``BT@@
|
||
|
||
测试使用本地 mock HTTP server，不访问 Tailscale、controller 或任何远端服务。
|
||
|
||
首次连接真实环境时，先执行 `--once` 或只做读取和延迟探测。任何节点切换都属于
|
||
运行态控制操作，必须在当次获得明确授权，并限定为一台机器、一个 Selector 组和
|
||
一个候选节点。
|
||
|
||
## Files
|
||
|
||
- `apps/proxy-port-monitor-tui/proxy_monitor_tui.py`
|
||
- `apps/proxy-port-monitor-tui/tests/test_proxy_monitor_tui.py`
|
||
- `apps/proxy-port-monitor/README.md`
|
||
- `services/server2/systemd/proxy-port-monitor/current/README.md`
|