# 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`