阶段十八：中国网络可达性探针与临时 IP 自测
阶段状态：已完成（用户已授权在 P17 归档前提前执行并结案）
计划状态：已完成
当前工作包：无；P18 已完成并结案
📌 结论摘要
P18 将把中国网络可达性做成现有 Console“网络态势”中的正式监控能力。自动监控使用 Globalping 官方 API，默认使用华南监控，从深圳、广州和东莞探针检查 RR、MM、d02、DD、dog 五台公网 VPS；每 12 分钟检查一台，一小时完成一轮。页面使用高强度红、黄、绿状态卡，红黄绿必须第一眼可见，第一眼即可发现异常。管理员还可执行临时 IP 自测，输入现有 IP、计划替换的新 IP 或公网域名，临时自测覆盖全国，同时运行 ICMP Ping 和 TCP 443，失败后再按需运行 MTR，并给出 ping.pe 人工佐证入口。依据是 D1 至 D5 的正式决策、五台 VPS 的 ICMP 实测、Globalping 官方限额和现有 Console/API Gateway 架构；Globalping 不安装探针容器，影响范围限定在 Network、Console、API Gateway 和一个受控的网络探针服务，不修改 2S-UI、Clash 订阅、代理节点规则或 Edge 切换逻辑。
🗂️ 目录
- 结论摘要
- 已冻结决策
- 背景与现有证据
- 技术栈与架构选型
- 架构与数据契约
- Console 成品形态
- 工作包与依赖
- 分布式底座接入声明
- 发布批次与阶段门
- 验收矩阵
- 回退方案
- 风险与恢复
- 未决项 / 需要用户决策
✅ 已冻结决策
| 编号 | 决策 | 冻结结果 | 影响 |
|---|---|---|---|
| D1 | 节点名称 | 用户可见名称统一写 dog，后续不再新增 dog-public 文案；旧的内部键只在兼容映射中保留 |
Console、计划、告警和新增 API 统一显示 dog |
| D2 | 常态区域 | 自动监控默认使用华南 | 不依赖深圳单城，也不每小时消耗全国额度 |
| D3 | 华南范围 | 当前定义为深圳、广州和东莞；现场在线探针为 7 + 5 + 1 = 13 个 |
五台 VPS 每轮约 65 tests/hour |
| D4 | 临时自测 | 第一版同时支持 ICMP Ping 和 TCP 443，可扩展到全国 | 替换 IP 时可直接验证网络层和端口层 |
| D5 | 人工佐证 | 自测结果附带 https://ping.pe/<目标> 入口 |
出现争议时可直接用 ping.pe 复核 |
| D6 | 状态视觉 | 红、黄、绿必须非常明显，不能只靠一个小圆点 | 顶部大状态卡、整块底色、文字和图标同时使用 |
P18-0 只冻结以上契约，不修改当前 P17 阶段状态。2026-10-11 用户明确授权提前执行后，P18 进入执行并在 2026-10-12 完成结案；state.json 的当前阶段仍保持 P17，直到 P17 有真实归档决定。
🧩 背景与现有证据
ICMP 基线
2026-10-11 的现场检查确认，五台 VPS 的 ICMP 入站策略已经完成对齐：
| 节点 | 当前运行值 | 持久化值 | 重启模拟 | 结论 |
|---|---|---|---|---|
| RR | icmp_echo_ignore_all=0 |
/etc/sysctl.conf=0 |
systemd-sysctl 重放后回到 0 |
✅ |
| MM | icmp_echo_ignore_all=0 |
/etc/sysctl.conf=0 |
systemd-sysctl 重放后回到 0 |
✅ |
| d02 | icmp_echo_ignore_all=0 |
无覆盖项 | 新网络命名空间默认值为 0 |
✅ |
| DD | icmp_echo_ignore_all=0 |
/etc/sysctl.conf=0 |
systemd-sysctl 重放后回到 0 |
✅ |
| dog | icmp_echo_ignore_all=0 |
无覆盖项 | 新网络命名空间默认值为 0 |
✅ |
五台 VPS 的 icmp_echo_ignore_broadcasts=1 保持不变，UFW 仍默认拒绝入站，只允许 Echo Request、Destination Unreachable、Time Exceeded 和 Parameter Problem。该结果来自远端 sysctl -n、/usr/lib/systemd/systemd-sysctl --cat-config、UFW 与 iptables 只读回读；影响是重启后不会重新出现“禁 Ping 被误判为离线”的问题。
剩余安全修正
MM 当前为：
RR、d02、DD 和 dog 当前为 2。该差异不影响探针准确性，但 MM 的反向路径过滤弱于其他节点。P18-1 需要在备份后把 MM 对齐为宽松模式 2，并验证公网 Ping、Tailnet Ping、公网 SSH、Tailnet SSH、Docker、Nginx、DERP 和 Peer Relay；影响是安全基线统一，同时避免使用严格模式 1 造成多路由误丢包。
测试类型结论
| 类型 | 当前用途 | P18 决策 |
|---|---|---|
| ICMP Ping | 网络层连通、丢包和延迟 | 常态与临时自测主检测 |
| TCP 443 | 端口与服务可达性 | 临时自测必测；常态用于 ICMP 被过滤时解释结果 |
| MTR | 路由和逐跳丢包定位 | 仅临时自测异常后运行 |
| DNS | 域名解析 | 自动解析目标，不单独作为红绿判据 |
| HTTP | 应用、TLS、WAF 和状态码 | P18 第一版不纳入，避免 WAF 误判 |
依据是五台 VPS 当前均可以被 ICMP 或 TCP 443 命中，且用户明确要求临时自测“都加入测试”并保留 ping.pe 佐证；影响是自动监控保持轻量，临时排障获得更完整的网络层证据。
🧱 技术栈与架构选型
| 候选 | 可维护性 | 消耗控制 | 自动化能力 | 结论 |
|---|---|---|---|---|
| Globalping 官方 API | 高，正式 REST API 和公开 Schema | 注册用户 500 tests/hour |
高，可定时、可临时、可结构化返回 | ✅ 采用 |
ping.pe 自动化 |
中，无正式稳定 API，需要 Cookie、Token 和页面兼容 | 无公开正式额度模型 | 中，页面接口可能漂移 | ❌ 不采用 |
| 自建全球探针 | 低，需要多地主机和长期维护 | 成本不可控 | 可控但建设量过大 | ❌ 不采用 |
| 只依赖本地 101/102 | 高，但只能代表本地网络 | 成本低 | 高 | ❌ 不代表中国多地区 |
Globalping 提供注册用户每小时 500 次免费测试和单次最多 500 probes。当前全国中国探针约 49 个，华南当前约 13 个；常态华南方案每小时 65 tests，临时全国双协议约 98 tests，均低于免费额度。依据是 Globalping 官方 limits、measurements API 和现场探针清单；影响是无需赞助、无需托管探针容器，也不增加 VPS 上的第三方执行代码。
🗺️ 架构与数据契约
flowchart LR
Globalping["Globalping API"] --> Collector["RR 自动采集器"]
Collector --> Snapshot["/run/agentmeshos/network-topology/china-reachability-v1.json"]
Snapshot --> Gateway["API Gateway 只读投影"]
Gateway --> Console["Console #topology 中国可达性"]
Console --> ProbeAPI["RR 网络探针服务"]
ProbeAPI --> Globalping
Console --> PingPe["ping.pe 人工佐证"]自动监控与临时自测分离。采集器只读 Globalping，每 12 分钟写入一次新快照；替代运行 60 秒拓扑任务。临时自测是新服务，只在管理员点击后调用 Globalping，不把 Token 交给浏览器。
常态快照
快照路径固定为：
每个目标至少包含：
| 字段 | 含义 |
|---|---|
id |
rr、mm、d02、dd、dog |
label |
Console 人类可读名称 |
public_ipv4 |
当前公网 IPv4 |
scope |
shenzhen、south-china 或 national |
status |
healthy、degraded、down、unknown |
evidence |
ICMP、TCP 443 的探针数和成功数 |
latency_ms |
平均、最小、最大 |
checked_at |
最近一次实际测试时间 |
source |
globalping |
临时自测
临时自测输入只允许：
- 单个公网 IPv4 或 IPv6；
- 公网域名；
- 可选人类标签；
- 区域
shenzhen、south-china、national； - 固定协议组合
ICMP + TCP 443； - 固定探针上限，全国默认 50，华南默认 13。
结果不需要加入常态目标列表。确认替换后，管理员另行更新节点登记，不自动替换生产 IP。
Globalping 凭据契约
常态采集器和临时自测服务使用同一个 root-only 凭据文件：
固定格式如下，用户只需替换 GLOBALPING_API_TOKEN：
GLOBALPING_API_TOKEN=REPLACE_WITH_GLOBALPING_API_TOKEN
GLOBALPING_API_BASE_URL=https://api.globalping.io
GLOBALPING_DEFAULT_SCOPE=south-china
GLOBALPING_TIMEOUT_SECONDS=45
文件必须为 root:root 0600，不得进入 Git、项目 .env、日志、Console 响应或普通回复。systemd 服务通过 LoadCredential 读取，不把 Token 注入普通环境变量，也不允许浏览器访问。依据是 Globalping API 使用 Bearer Token，且用户已明确提供凭据边界；影响是 P18 可以复用同一凭据完成自动采集和临时自测。
该文件位于 RR 的 /etc/agentmeshos/，不属于项目工作树，也不随 Git、镜像、安装包或部署脚本传输。部署脚本只允许执行只读 preflight，检查文件存在性、所有者和 0600 权限；不得创建、覆盖、删除、复制或打印 Token。若文件缺失或权限错误，采集器和临时自测服务必须 fail closed，而不是生成假数据。部署前后必须记录凭据文件 SHA-256，验收要求 SHA 保持不变。
🎨 Console 成品形态
位置固定在：
页面顶部新增“中国网络可达性”区域，顺序为：
- 五台 VPS 的大状态卡。
- 每台节点的指标、区域、来源和最近测试时间。
- 管理员临时 IP 自测入口。
- 最近自测记录与
ping.pe佐证入口。
状态视觉
| 状态 | 视觉要求 | 判定意图 |
|---|---|---|
| 绿色 | 大色块、白色粗体“正常”、稳定图标 | 目标在中国方向可用 |
| 黄色 | 大色块、白色粗体“部分异常”、警示图标 | 部分探针或协议失败 |
| 红色 | 大色块、白色粗体“全国异常”、故障图标 | ICMP 与 TCP 均无法从中国方向抵达 |
| 灰色 | 中性色块、白色粗体“无法判定”、未知图标 | 缺少数据或平台失败 |
红黄绿必须同时使用颜色、文字和图标，不允许只靠小圆点。桌面端每行五张卡片，移动端单列堆叠，不能横向溢出。
🛠️ 工作包与依赖
P18-0 契约冻结与命名统一
前置条件：P17 已完成并归档。冻结 dog 为唯一用户可见名称、华南城市集合、常态 12 分钟调度、临时自测协议、红黄绿判据、Globalping Token 路径和回退边界。验收要求是计划、Schema、Console 文案、测试夹具和节点登记均不存在新增 dog-public 显示文案；旧内部键只允许在代码映射中保留。
P18-1 网络与安全基线对齐
前置条件：P18-0 完成。复核五台 VPS 的 ICMP 持久化，验证 icmp_echo_ignore_broadcasts=1 与 UFW 最小放行；将 MM 的 rp_filter 从 0 对齐为 2。每台修改前保留 root-only 备份，修改后完成公网和 Tailnet 回归。验收证据包括 sysctl、systemd-sysctl --cat-config、UFW、ping、SSH、Docker、Nginx、DERP 和 Peer Relay 回读。若 MM 出现任何路径异常，立即恢复备份值并停止 P18-2。
P18-2 Globalping 自动采集器
前置条件：P18-1 完成。实现 scripts/maintenance/agentmeshos-globalping-china-probe.py，从节点登记派生五台目标，使用华南范围，按固定顺序每 12 分钟检查一台，结果原子写入快照；失败保留 last-known-good，不把网络中断写成零结果。Token 只从 /etc/agentmeshos/globalping.env 读取。验收要求是连续至少两小时每分钟可回读有效或明确 stale 的快照，五台目标在一小时内全部更新，单轮消耗不超过 65 tests。
P18-3 API Gateway 只读投影
前置条件：P18-2 产出有效快照。扩展 tools/api-gateway/src/network_topology.py 和契约测试，把自动结果作为 china_reachability 返回；严格限制目标数量、字段类型、域名、IP、状态、错误码和最大响应体积。缺少快照时只影响该区块，不把完整网络态势判为 unavailable。验收要求包括正常、stale、超时、恶意字段、内网地址泄漏和超大响应负向测试。
P18-4 Console 常态状态卡
前置条件：P18-3 通过本地测试。在 #topology 增加高冲击力状态卡，五台目标统一显示 dog，展示 IP、红黄绿、ICMP/TCP 成功数、丢包、延迟、范围、来源和时间。验收要求包含浏览器契约、桌面 1440x900、移动端 390x844、无文字溢出、无颜色单独表达和旧快照显示 stale。
P18-5 临时自测服务
前置条件：P18-1 和 P18-2 完成。新增 agentmeshos-network-probe.service，只监听 RR 本机 127.0.0.1:39185，通过 main origin gateway 的管理员路径访问。服务只接受固定动作 manual.icmp_tcp_test 和 manual.mtr_diagnose，拒绝任意端口、URL、Headers、Shell、内网、Tailnet、回环、链路本地、组播和云元数据地址。使用 LoadCredential 注入 Globalping Token，服务不直接读取普通凭据。部署脚本禁止写入 /etc/agentmeshos/globalping.env。验收要求包括管理员鉴权、非管理员拒绝、限速、目标拒绝、ICMP+TCP 并行、MTR 条件触发、凭据文件 SHA 不变和 Token 不泄漏。
P18-6 Console 临时自测与 ping.pe 佐证
前置条件：P18-5 通过。自测面板允许输入公网 IP、域名和备注，默认全国；结果按城市和运营商列出 ICMP、TCP 443 和 MTR 明细，并提供 https://ping.pe/<目标> 新窗口入口。最近 20 次结果保存到服务 SQLite，超过 30 天自动清理，不进入常态目标。验收要求包括输入校验、结果可读、ping.pe 文案一致、异常和空结果可解释。
P18-7 测试、部署与发布
前置条件：P18-2 至 P18-6 完成。实现部署脚本、systemd unit、timer、回滚脚本和安装哈希校验；纳入 run-local-tests.sh。部署脚本只校验凭据文件的存在、所有者、权限和哈希，不写凭据内容。发布顺序固定为 collector、API Gateway、Console、network-probe service、origin gateway。验收要求包括本地全量门禁、浏览器契约、文档严格构建、提交精确 SHA、Actions、post-push-verify=pass、生产文件哈希、凭据文件 SHA 不变和回退镜像。
P18-8 生产验收与收口
前置条件：P18-7 发布完成。使用真实 Globalping 中国探针验证五台 VPS 的华南常态状态、五个目标的临时自测、ICMP、TCP 443、MTR、ping.pe 链接和重启持久性。阶段出口是五台目标连续一小时均有结果、异常态可复现、无 Token/内网泄漏、回退演练通过、文档和 Git 完成同步。
📊 当前执行证据
| 项目 | 当前证据 | 状态 |
|---|---|---|
| 代码提交 | c11ba087b7adad0dbbdfc9dd9ee4aa7e945a4dd0；API IPv4 修正提交 2020b500ad7368f151564d91d99e4993566915f4 |
✅ |
| 发布门禁 | 两次精确 SHA 的 post_push_verify=pass |
✅ |
| 网络探针服务 | agentmeshos-network-probe.service active，只监听 127.0.0.1:39185，NRestarts=0 |
✅ |
| 采集 timer | agentmeshos-network-collector.timer active，下一次约 12 分钟后触发 |
✅ |
| Globalping 凭据 | /etc/agentmeshos/globalping.env 为 root:root 0600，SHA-256 部署前后保持 98d3ba18abac42b89b21a74cc86ebd532e162447374cdf949ba981999cb1ca3d |
✅ |
| 自动结果 | 华南快照五台齐全，当前 4 正常、1 轻度异常；目标检查时间在一小时内轮换 | ✅ |
| TCP 443 显示 | ICMP 正常时常态采集器不触发 TCP 443，页面显示“未触发”，不再误导为“无法判定”；临时自测仍始终双协议 | ✅ |
| 临时自测 | 真实全国 ICMP + TCP 443 调用返回 healthy，SQLite 历史可读 | ✅ |
| MTR | 深圳范围真实 MTR 返回 finished，包含 6 个探针 |
✅ |
| Console/API | API Gateway 镜像已更新并返回五台 public_ipv4；Console 生产 app.js/styles.css 含新状态卡和自测表单 |
✅ |
| 沉浸式拓扑画板 | 提交 208db1b9d8c86be6b0066ba3926c2c4536e13eee 增加全屏近满高画布、普通/沉浸筛选浮层、详情覆盖抽屉、适配全部 和 适配选中；浏览器契约断言沉浸高度不低于 880px |
✅ |
| 浏览器登录态 | 使用 /root/.codex/credentials/agmentmeshos-console.env 的管理 API Key 登录生产 Console；状态卡、页签、拓扑大画布、临时自测和最近记录均完成截图验收 |
✅ |
| 生产页面自测 | 页面真实提交 192.227.170.39 全国自测：ICMP 正常、TCP 443 正常，ping.pe 和 Globalping 链接可见 |
✅ |
| 对比度门禁 | 状态卡说明、指标、页签和最近自测记录通过浏览器对比度断言，均不低于 4.5:1 |
✅ |
🧩 分布式底座接入声明
接入结论：接入 Network、Observability、Credentials、Console 与 docs-governance；本阶段不接入 Nomad、Compute、AI Runtime 或 StorageAdapter。
Network 使用五台现有 VPS 的公网入口、RR 出站 HTTPS、Globalping 远程探针和 ping.pe 人工佐证，不新增公网监听。Observability 使用现有 API Gateway、Console、systemd 状态和 Globalping 返回数据。Credentials 使用 systemd LoadCredential 注入 Globalping Token，浏览器、模型、日志和普通文件均不可见。
执行映射是 RR 运行采集 timer 和网络探针服务，101 继续负责代码、GitHub、CI 和发布协调，五台 VPS 只作为被测目标，不安装 Globalping 容器。数据路径是 Globalping API 到 RR 内存、到原子 JSON 或临时 SQLite、再到只读 API 和 Console；临时数据不进入 Cloudreve，长期证据只保留脱敏摘要、哈希和验收结果。
生命周期从 P17 归档后开始，失败时保留 last-known-good，不自动删除已有快照。采集器故障只让中国可达性区块显示 stale 或 unavailable，不影响现有拓扑、Edge 或 DNS。
🚀 发布批次与阶段门
| 批次 | 内容 | 进入条件 | 退出条件 |
|---|---|---|---|
| B1 | P18-0、P18-1 | P17 已归档，MM 回退备份已建立 | 五台 ICMP/安全基线一致 |
| B2 | P18-2、P18-3 | B1 通过，Globalping Token 已准备 | 采集器与只读 API 契约通过 |
| B3 | P18-4 | B2 生产快照连续有效 | 常态状态卡真机通过 |
| B4 | P18-5、P18-6 | B1 与 B2 通过 | 临时自测、MTR、ping.pe 佐证闭环 |
| B5 | P18-7、P18-8 | B1 至 B4 全部通过 | 生产验收、回退和发布门禁通过 |
🧪 验收矩阵
| 验收层 | 必验项目 | 成功标准 |
|---|---|---|
| 网络 | 五台 ICMP 持久化、MM rp_filter | 重启模拟不回落，公网与 Tailnet 均正常 |
| 采集 | 华南 13 个探针、每 12 分钟一台 | 一小时内五台全部更新，消耗约 65 tests |
| API | 只读 china_reachability |
正常、stale、缺失和恶意字段均返回受控结果 |
| Console | 红黄绿视觉与移动端 | 桌面和移动端第一眼可辨识，无溢出 |
| 自测 | 公网 IP、域名、ICMP、TCP 443 | 管理员可用，非管理员和内网目标被拒绝 |
| MTR | 异常路径诊断 | 仅异常触发，能显示逐跳结果 |
| ping.pe | 人工佐证 | 目标正确预填，新窗口可打开，不自动抓取 |
| 安全 | Token、限速、输入、日志 | 无凭据、内网地址、任意端口和 Shell 泄漏 |
| 发布 | Git、Actions、生产、回退 | post-push-verify=pass，生产与回退可回读 |
🔁 回退方案
采集器回退到上一版脚本并恢复上一份 last-known-good；API Gateway 回退到上一完整镜像 SHA；Console 回退到不含 P18 区块的镜像；网络探针服务停止并移除 origin gateway 路由；MM 的 rp_filter 恢复修改前备份值。所有回退必须保留 Globalping Token、历史自测摘要、ICMP 对齐结果和审计，不删除五台 VPS 的网络配置、业务数据或现有 Console 服务。
⚠️ 风险与恢复
| 风险 | 当前事实 | 处理 |
|---|---|---|
| Globalping API 临时失败 | 公开 API 无永久可用性承诺 | 保留 last-known-good，显示 stale，不判服务器宕机 |
| 中国探针上下线 | 现场数量会变化，华南当前约 13 个 | 记录实际 probesCount，不写死成功数 |
| ICMP 被再次过滤 | 用户或供应商可能修改配置 | 常态同时保留 TCP 443 证据，临时自测双协议 |
| MM rp_filter 修改影响多路由 | Tailscale、Docker 和 Nginx 同机 | 先备份、后修改、全路径回归，失败即回滚 |
ping.pe 页面漂移 |
无正式 API | 只提供人工佐证链接，不自动抓取 |
| 替换 IP 还未上线 | 临时自测必须能验证候选地址 | 不加入常态目标，不自动替换生产 IP |
⚠️ 未决项 / 需要用户决策
P18 的功能、默认范围、临时自测协议、ping.pe 佐证和红黄绿视觉均已冻结，无新增用户决策项。用户在 2026-10-11 明确授权提前执行 P18 生产变更；state.json 当前阶段仍保持 P17，避免把未完成的 P17 客户端验收伪造成已归档。