proxy-port-monitor-tui

项目定位

用于在本机终端查看 Proxy Port Monitor 的目标连通性，并通过既有的同源 controller 转发查看 mihomo Selector 组、做低流量延迟探测，以及手动切换单个 Selector 的运行态当前节点。

它不是通用代理客户端，不直接 SSH 到目标机，不编辑 subscription、mixin、 host_vars 或远端 mihomo 配置文件。

本 README 说明本地客户端；服务入口、Tailscale Service 和 controller secret 边界仍由 proxy-port-monitor 的 service README 维护。

这是本机客户端工具，没有 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 保存到本地状态路径。支持的环境变量：

客户端只读取 /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 组和一个候选节点。