Initial proxy port monitor TUI

README.md

@@ -0,0 +1,126 @@
+# 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 个。
+- `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`