docs: merge the API guidelines into api.md; drop the one-off trial reports; fix the node-update description (Quadlet restart vs host updater); tidy TODO [CI]
This commit is contained in:
justme committed
1 parent
900bbde46a
commit
4609048865
12 files changed
+172
-224
No files matched your search
+6
-55
@@ -175,68 +175,19 @@ OpenWrt 默认不带 OpenSSL：`opkg install libopenssl3`（较新的快照和 2
|
||||
|
||||
实测常驻内存（RSS，回环，默认模板，稳定后）：Linux 上 Probe 约 21 MB、Agent 约 23 MB；Windows 上约 22 MB、25 MB。
|
||||
|
||||
### 跨机器的真实链路（Windows Probe → WSL2 里的 Agent 和 Backend）
|
||||
### 故障注入
|
||||
|
||||
`scripts/smoke-wsl.py` 用 Windows 上的 NativeAOT Probe 连 WSL2 里的 Agent（真实的虚拟网络，两端的单调时钟原点相差约 38 小时），并用 `tc netem` 在 WSL 里注入故障。结果（Probe 的 RTT 基线约 0.4 ms）：
|
||||
`scripts/smoke-wsl.py`：Windows 上的 NativeAOT Probe 连 WSL2 里的 Agent 和 Backend（真实的虚拟网络，两端的单调时钟原点不同），用 `tc netem` 注入单向丢包和延迟、8 秒黑洞、Agent / Probe 重启，检查指标落在预期的一侧：上行丢包只出现在 `loss.up`、下行只出现在 `loss.down`；黑洞期间 UDP 连续丢包、TCP 不丢包只在 RTT 里出现几秒的长尾；重启之后几秒内自动恢复。具体数字以脚本的输出为准，不记在这里。
|
||||
|
||||
| 注入 | 期望 | 实测 |
|
||||
| --- | --- | --- |
|
||||
| Agent→Probe 方向 10% 丢包、30 ms ± 5 ms 延迟（egress netem，只匹配 7443/7444） | 丢包在下行，下行抖动变大 | `loss.down` 8.2%、`loss.up` 0；`jitter.down.p95` 8.7 ms、`jitter.up.p95` 0.18 ms；RTT +31 ms；TCP：`tcp.rtt.p99` 1.2 s、`tcp.slow` 28.8%、`tcp.retrans` 5.9%（Agent 一侧内核计数） |
|
||||
| Probe→Agent 方向 10% 丢包、20 ms ± 3 ms 延迟（ingress + ifb） | 丢包在上行 | `loss.up` 9.4%、`loss.down` 0；`jitter.up.p95` 5.2 ms、`jitter.down.p95` 0 |
|
||||
| 8 秒黑洞（tc ingress drop 7443/7444） | UDP 连续丢包 ~80 个；TCP 不丢包，只有几秒的长尾 | UDP 最长连续丢包 80（10 Hz × 8 s）；`tcp.rtt.max` 9.5 s、`tcp.stall_max` 9.6 s |
|
||||
| `hy2_ladder`（10/25/50/100 Mbit/s） | 无丢包 | `train.loss` 0.006%、`train.jitter.p95` 0.64 ms、可持续 100 Mbit/s |
|
||||
| 杀掉 Agent / 杀掉 Probe 再启动 | 自动恢复 | Agent 重启后 2.1 s 恢复在线并重新连上 Probe；Probe 重启后 0.5 s 重新连上 |
|
||||
这类验证发现过的几个问题，都已经修掉，改动时要留意它们为什么存在：Probe 重启后序号从 0 开始，Agent 不能沿用上一个会话的记录（否则真正的上行丢失会被算成下行丢失）；TCP 回显的几秒中断必须记成延迟而不是丢包（TCP 的行要等回复，最长 30 秒才交出）；`hy2_ladder` 的阶梯要把同一阶段的块先合并再算（真实的 Probe 会把一个阶段切成几块）。
|
||||
|
||||
验证中发现并修掉的两个问题：
|
||||
### 家宽机器上的 Backend
|
||||
|
||||
- **Probe 重启后，Agent 沿用了上一个会话的记录**：Probe 重启之后序号从 0 开始，Agent 里同一个序号的旧 t2/t3 还在，于是真正的上行丢失被算成了下行丢失（黑洞测试里 `loss.up` 0、`loss.down` 7.4%）。现在新的 Probe 会话开始时 Agent 清空所有流的记录。
|
||||
- **TCP 回显的几秒中断被记成丢包**：Probe 像 UDP 那样等 2 秒就把没有回复的行交出去，TCP 随后才到的回复没有行可以回填，最严重的长尾反而在 RTT 里看不到（黑洞期间 `tcp.rtt.max` 只有 4 ms）。现在 TCP 的行等回复，30 秒仍然没有才当作连接已断（t4 缺失）。
|
||||
|
||||
没有覆盖的：Windows 上的 Agent（需要给 Windows 防火墙加入站规则）、NAT 重绑定。跨公网的线路见下一节。
|
||||
|
||||
### 跨公网的真实线路（广东移动家宽 → 日本 IIJ 的 VPS）
|
||||
|
||||
2026-10-03 在一条真实线路上试跑过：家宽机器（Debian 13，用户态运行，没有公网 IPv4 入站）跑 Probe 和 Backend，VPS（Debian 12，1 核 470 MB，上面本来就跑着 xray、hysteria2、caddy 等服务）跑 Agent。
|
||||
|
||||
```text
|
||||
浏览器 / 本机前端 ──► https://<公网域名> ──隧道（Cloudflare Tunnel 之类）──► 家宽机器: Backend (:29181)
|
||||
家宽机器: Probe ──WSS 到 https://<公网域名>──► Backend（身份、Agent 列表）
|
||||
家宽机器: Probe ──TCP/UDP 7443、TCP 7444──► VPS: Agent
|
||||
VPS: Agent ──WSS 到 https://<公网域名>──► Backend
|
||||
```
|
||||
|
||||
做法和要点：
|
||||
|
||||
- **Backend 通过隧道暴露**：隧道把一个公网域名转到家宽机器的 `29181`；Backend 监听 `http://0.0.0.0:29181`（只写一个监听地址，同时写 `0.0.0.0` 和 `[::]` 会报地址已被占用），家宽路由器的防火墙不放行这个端口，公网只能经隧道进来。Agent 用 `fleet-enroll --server https://<公网域名>` 注册，之后用 WSS 连回 Backend。
|
||||
- **对外地址自动识别**：Agent 在 hello 里上报本机的公网地址（IPv4 公网地址、IPv6 全球单播地址，排除私网、CGNAT、临时地址），面板自动填 `public_host` 和 `ipv6_host`，不需要手填。经隧道注册时来源地址是隧道出口，面板不会用它。只有 Agent 在 NAT 后面、本机看不到公网地址时才需要在管理端手填；手填的优先，勾选“自动识别”可以撤销。
|
||||
- **Probe 直连面板**：`probe.json` 里的 `fleet.server` 就是面板地址，Probe 用它连面板，Agent 列表由面板下发；密钥由 Probe 注册时自己生成，身份目录（`node.json`、`node.key`、`tls.pfx`）在 `fleet.identity_dir`。
|
||||
- **小 VPS 把 `limits.max_total_mbps` 调低**（试跑时用 100）；Agent 常驻约 23 MB，VPS 上原有的服务不受影响，结束后删除 `/opt/…`、停掉进程即可，没有留下任何东西。
|
||||
- 家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，SSH 地址要跟着换；面板走隧道的域名，不受影响。
|
||||
- 本地电脑没有直连 VPS 的路径时，用家宽机器当跳板（`SSH_ASKPASS` + `SSH_ASKPASS_REQUIRE=force`，密码放环境变量，不写进文件）。
|
||||
|
||||
**常驻（开机自启）**：
|
||||
|
||||
- 家宽机器（没有 root 时）：`~/.config/systemd/user/moshiro-backend.service` 和 `moshiro-probe.service`，`EnvironmentFile` 指向放配置的 `backend.env`，`Restart=always`，`systemctl --user enable --now …`，再用 `sudo loginctl enable-linger <用户>` 让它们不登录也能起来。Probe 的命令行是 `moshiro-probe --config <probe.json 路径>`（默认路径是 `/etc/moshiro/probe.json`）。
|
||||
- VPS：`/etc/systemd/system/moshiro-agent.service`，`Restart=always`，加 `NoNewPrivileges`、`ProtectSystem=strict`、`ReadWritePaths=/opt/moshiro`、`ProtectHome`、`PrivateTmp`。这是不走安装脚本的手动方式；正式安装用上面的 `packaging/systemd`。
|
||||
- 日志进 journal：`journalctl -u moshiro-agent`、`journalctl --user -u moshiro-probe`。重启 Backend 用 `systemctl` 而不是手动再起一个进程，否则会端口冲突。
|
||||
没有公网入站的家宽机器上跑 Backend 时，用隧道（Cloudflare Tunnel 之类）把一个公网域名转到 Backend 的端口；Backend 只写一个监听地址（同时写 `0.0.0.0` 和 `[::]` 会报地址已被占用）；Probe 的 `fleet.server` 就是这个面板地址。小 VPS 上把 `limits.max_total_mbps` 调低。家宽的 IPv6 前缀会在路由器重新拨号（比如停电）后变化，用 IPv6 直连时地址要跟着换；走隧道的域名不受影响。
|
||||
|
||||
**国家和运营商**：Backend 用 Probe、Agent 的来源地址向 IP 归属服务查一次，展示在国旗和运营商图标上（`MoShiro__GeoLookupUrl`，缺省 `https://ip.007995.xyz`；留空就不查；这个服务只供公益使用，署名和使用条款由部署的人自己遵守）。Probe、Agent 自己不访问外部服务，所以客户的防火墙审计里不会多出出站连接；Backend 发出去的只有公网 IP（内网地址不发）。
|
||||
|
||||
**从别处看这个面板**：本机跑前端，在页面里把数据源指向这个域名，用 API 令牌访问，Backend 设 `MoShiro__CorsOrigins` 放行前端的来源（见 [web/README.md](../../web/README.md)）。
|
||||
|
||||
实测（Probe 在广东移动家宽，Agent 在日本 IIJ）：
|
||||
|
||||
| 项目 | 结果 |
|
||||
| --- | --- |
|
||||
| 延迟 p50 / p95 / p99 | 107 / 107 / 114 ms |
|
||||
| 丢包 | 上行 0%，下行 8.1%（`hy2_ladder` 在 10、25、50、100 Mbit/s 四档下的丢包都是 8～10%，与速率无关：随机丢包，不是限速） |
|
||||
| 抖动 p95（上 / 下） | 0.9 / 5.2 ms |
|
||||
| TCP | 重传 1.9%（批量传输时 5.8%），RTT 最大 412 ms |
|
||||
| `reality_session` | 建连成功率 100%，TCP 建连 p95 115 ms，TLS 握手 p95 117 ms，30 秒长连接无重置；4 秒批量传输峰值 133 Mbit/s、中位数 90 Mbit/s（Agent 上限 100） |
|
||||
| 评分 | REALITY 82（含按需测试）、Hy2 42 |
|
||||
| Agent 主机状态 | CPU 1.5%，内存 274 / 493 MB，已运行约 20.5 天 |
|
||||
|
||||
这次试跑发现并修掉的问题：`hy2_ladder` 的阶梯按「块」而不是按「阶段」计算，真实的 Probe 把一个阶段切成几块，4 个阶段出了 7 步（模拟数据不切块，所以之前的测试没有发现）；现在同一阶段的块先合并。
|
||||
**从别处看这个面板**：本机跑前端，在页面里把数据源指向面板的地址，用 API 令牌访问，Backend 设 `MoShiro__CorsOrigins` 放行前端的来源（见 [web/README.md](../../web/README.md)）。
|
||||
|
||||
## 容器部署（Podman Quadlet 优先，Docker 用 compose）
|
||||
|
||||
|
||||
Reference in new issue
Block a user