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