🧭 节点分类与四轴职责模型
更新：2026-10-04
📌 结论摘要
AgentMeshOS 的节点分类已经统一为四轴模型：primary_role 表示唯一主职责，service_roles 表示节点当前运行的服务，capabilities 表示节点可提供的能力，operational_state 表示纳管、健康、Edge 和 Exit Node 等运行状态。四轴不能互相冒充，也不能根据在线状态、端口开放或某次部署结果临时改变。
四轴必须分开读取，能力不能冒充主职责。
当前机器权威登记源是 tools/node-registry/registry.json。节点管理、网络态势、Status、API Gateway、System Operations Bridge、Headscale 相关生成器和发布 bundle 都从这一份文件读取或映射；node.role 与 node.node_type 只保留给旧客户端兼容，不能再作为主职责判断依据。
这次收口确认当前分类整体正确：RR 为生产控制面，101 为项目交付与发布协调，102 为计算节点，MM、d02、dog-public 为公网边缘，DD 为主职责存储但具备 Edge 和中继能力，Home 为管理入口，nas-sz 为 NAS，移动端为客户端。DD 具备 Edge 能力不等于它是 Edge 主机，MM 运行 derper 也不等于 derp 是主职责。
📚 目录
🧩 权威来源与更新路径
分类权威只允许存在于版本化登记源，禁止在 Console、Status、拓扑脚本或部署脚本里重新硬编码一份节点角色表。旧字段兼容只解决滚动发布期间的接口读取，不产生第二份事实。
| 层级 | 当前对象 | 作用 | 约束 |
|---|---|---|---|
| 权威登记 | tools/node-registry/registry.json |
定义节点、别名、四轴事实、拓扑位置和指标身份 | 任何分类变更必须先改这里 |
| 拓扑生成 | scripts/maintenance/agentmeshos-network-topology.py |
将 Registry 事实与实时 Tailscale、DERP、Peer Relay、Exit Node 状态合并 | 不能新增独立主职责映射 |
| API 投影 | tools/api-gateway/src/main.py、network_topology.py |
对公开状态和拓扑做严格脱敏、校验和标签补充 | 未知名称为待分类，不能猜测 |
| 节点管理 | tools/system-operations-bridge/src/node_management.py |
将 Registry 事实合并到可管理节点清单 | 部署画像不能覆盖主职责 |
| Console | tools/console-site/src/app.js |
展示四轴并执行链路、主职责、能力三组 AND 筛选 | 不再用 node_type/role 推断主职责 |
| Status | tools/status-site/src/app.js |
展示主职责、服务职责、能力与运行状态统计 | 主职责必须直接读取 primary_role |
| 发布 | scripts/ci/create-release-bundle.sh、部署脚本 |
将 Registry 随 API Gateway bundle 和生产镜像发布 | 缺失或非法时失败关闭 |
Registry 中节点地址有两层权威来源：已配置资源遥测的节点使用 metrics.address，只有拓扑身份的管理终端使用 topology.tailnet_ipv4；API 身份索引必须同时覆盖两者，并纳入 aliases 与 topology.tailnet_aliases，不能因为缺少 metrics 就把已登记节点降级为“待分类”。
更新顺序固定为：先改 Registry，再跑 Registry 与下游契约测试，随后检查拓扑、API、Console、Status 和文档是否一致，最后提交 GitHub、等待 Actions、执行 RR 发布并通过公网回读。只改页面文字不改 Registry 属于漂移；只改 Registry 不跑下游测试属于未完成。
🧱 四轴模型
四轴的设计目的是把“这台机器是什么”“它运行什么”“它能提供什么”“它现在是什么状态”拆开。这样同一台 DD 可以主职责为存储、运行 Cloudreve 和 DERP、具备 Edge 能力，同时保持 edge_role=candidate，不会因为多个身份混在一起而失去唯一主职责。
| 轴 | 字段 | 含义 | 取值规则 |
|---|---|---|---|
| 主职责 | primary_role |
节点在系统中唯一的首位职责 | 每台主机只能有一个值；能力、在线状态和临时服务不能覆盖 |
| 服务职责 | service_roles |
当前实际运行的正式服务 | 可多个；使用 derper、peer-relay、edge-proxy 等服务名 |
| 能力 | capabilities |
节点具备提供的可配置能力 | 可多个；使用 edge、derp、peer_relay、exit_node、batch-worker、auto-deploy |
| 运行状态 | operational_state |
纳管、生产、系统管理、批量、自动部署、Edge 角色、Nomad 画像及实时健康 | 必须区分静态声明与实时状态，不能把 active 直接写成可用结论 |
当前合法主职责为 control、delivery、management、edge、compute、storage、nas、client、unclassified。当前合法服务职责包括 ai-runtime、headscale、headplane、nomad-server、nomad-client、control-api、control-plane-standby、ci-runner、release-coordinator、node-inventory、node-exporter、omniroute、edge-proxy、derper、peer-relay、cloudreve、threedogs、ssh-management、windows-management、codex-bridge、nas-storage 和 android-probe。
| 易混项 | 正确口径 | 错误口径 |
|---|---|---|
derp 与 derper |
derp 是公网 DERP 能力，derper 是节点上的服务职责 |
把 derp 当成服务名或主职责 |
peer_relay 与 peer-relay |
下划线形式是能力，连字符形式是服务 | 在 Headscale ACL 与 UI 能力筛选中混用 |
| Edge 与 DERP | Edge 负责 Nginx/TLS 公网入口，DERP 负责 Tailnet 中继 | 认为 Edge 在线就等于 Tailnet 中继可用 |
| Exit Node 能力与使用 | 能力表示可被选择，使用状态必须是客户端显式选择 | 把“可提供出口”写成“当前正在使用出口” |
📊 当前节点分类矩阵
下表以 2026-10-05 的 Registry 为静态事实，并参考最近一次 Tailnet、拓扑和发布回读。离线状态只改变 operational_state，不改变 primary_role。
| 节点 | 主职责 | 服务职责 | 能力 | 运行状态要点 | 分类结论 |
|---|---|---|---|---|---|
rr |
生产控制面 | AI Runtime、Headscale、Headplane、Nomad Server、控制面 API、节点清单 | Exit Node | 已纳管、生产节点、系统管理机；不承担 Edge | 控制面唯一写权威 |
101 |
项目交付与发布协调 | CI Runner、发布协调、节点清单 | 无额外能力 | 已纳管、系统管理机；不承载生产 Runtime | 交付与发布协调，不是生产控制面 |
102 |
计算节点 | OmniRoute、Nomad Client、节点遥测、只读备用控制面 | 批量计算、自动部署 | 已纳管；当前唯一生产 OmniRoute 权威 | 计算与模型访问节点 |
mm |
公网边缘 | 公网边缘代理、DERP、Peer Relay、节点遥测 | Edge、DERP、Peer Relay、Exit Node | 当前活动 Edge；region 900 | 当前生产公网入口 |
d02 |
公网边缘 | 公网边缘代理、DERP、Peer Relay、Nomad Client、节点遥测 | Edge、DERP、Peer Relay、Exit Node | Edge 候选；region 902 | 可替换边缘与中继候选 |
dog-public |
公网边缘 | 公网边缘代理、DERP、Peer Relay、ThreeDogs、Nomad Client、节点遥测 | Edge、DERP、Peer Relay、Exit Node | Edge 候选；region 903 | 独立站与备用边缘节点 |
dd |
存储节点 | Cloudreve、DERP、Peer Relay、节点遥测 | Edge、DERP、Peer Relay、Exit Node | Edge 候选；region 901 | 主职责存储，能力可与 Edge 并存 |
home |
管理入口 | SSH 管理、Windows 管理、Codex Host Bridge | 无额外能力 | 已纳管、系统管理机 | Windows 同级管理入口 |
nas-sz |
NAS | NAS 存储、节点遥测 | 无额外能力 | 已纳管 | 用户存储资源，不承担计算或系统云盘后端 |
little-s20 |
客户端 | Android 探针、SSH 管理 | 无额外能力 | 已纳管、在线；地址 100.64.0.8；2026-10-04 17:41:52 CST 受控重启后 Tailscale 于 18:17:50 自动恢复，资源遥测于 18:18:17 恢复；19:14 CST 再次重启后 Tailnet-only 入站 sshd 约 204 秒恢复 |
安卓移动管理与观测节点，支持 RR/101/Home 反向管理；现场名 Little 的 S20+，Tailnet DNS 名为 andriod-s20 |
honor-magic2 |
客户端 | Android 探针、SSH 管理 | 无额外能力 | 已纳管、在线；地址 100.64.0.13；实时 Tailnet 节点名 andriod-magic2；整机重启后 Tailscale、sshd、supervisor 和 push-loop 自动恢复；资源快照为 degraded，仅因 Android 10 隐藏网络元数据 |
Honor Magic2 移动管理与观测节点，支持 RR/101/Home 反向管理；Termux、Termius、TermRover 已配置九个出站目标，TermRover 完成 RR/101 真机登录 |
mac-mini |
管理入口 | 无 | 无额外能力 | 当前离线；不列为当前管理员来源 | 历史管理终端 |
windows-summer |
管理入口 | 无 | 无额外能力 | 当前离线 | Windows 管理终端 |
benson-nb |
管理入口 | 无 | 无额外能力 | 当前离线 | Windows 管理终端 |
officesummer |
管理入口 | 无 | 无额外能力 | 当前离线 | Windows 管理终端 |
分类正确性的关键判断有两类。第一类是唯一主职责：RR 与 101 都有管理或发布能力，但 RR 是控制面、101 是交付协调；DD 具备 Edge 能力，但主职责仍是存储，避免把“可以承担”写成“当前就是”。第二类是服务与能力分离：MM、d02、dog-public 和 DD 可以同时运行 derper 与 Peer Relay，但 Edge、DERP、Peer Relay 是正交能力，不能合并为一种角色。
🌐 网络态势分类
#topology 现在使用三组可组合筛选。三组条件之间是 AND 关系，组内是单选；逻辑入口 edge.yohan.fun 作为链路锚点保留，不会被错误当成真实 Edge 主机。
| 筛选组 | 当前选项 | 数据来源 | 说明 |
|---|---|---|---|
| 链路类型 | 公网 HTTPS、Tailnet 直连、DERP 中继、Peer Relay、SSH 管理、公网数据面 | links[].path_type |
只决定链路是否显示 |
| 主职责 | 控制面、交付、管理、边缘、计算、存储、NAS、客户端、逻辑入口 | nodes[].primary_role |
只按唯一主职责收窄主机节点 |
| 能力 / 出口 | Edge、DERP、Peer Relay、Exit Node 可选、正在使用 Exit Node | nodes[].capabilities、exit_node_available、exit_node_in_use |
能力与使用状态分开显示 |
节点圆圈和详情均显示主职责、服务职责、能力与运行状态。Exit Node 提供者使用能力徽标和虚线环，正在使用 Exit Node 的客户端使用独立使用环与标记；默认直连不会显示成“已使用”。这使“谁可以提供出口”和“谁正在使用出口”成为两个可独立验证的事实。
🧪 一致性验证
本次收口需要用以下门禁证明 Registry、API、Bridge、Console、Status 和发布包使用同一套四轴语义。任何一项失败都不得用页面截图、单个 Action 成功或手工替换生产文件来替代。
| 验证对象 | 命令 | 通过标准 |
|---|---|---|
| Registry 结构与唯一主职责 | python3 tools/node-registry/test_node_registry.py |
node_registry=passed |
| 拓扑生成与实时合并 | python3 scripts/maintenance/tests/network-topology-test.py |
network_topology_canary=passed |
| API 拓扑脱敏与四轴契约 | python3 tools/api-gateway/tests/test_network_topology.py |
gateway_network_topology=passed |
| 公开状态边界 | .venv/bin/python tools/api-gateway/tests/test_public_status.py |
public_status_boundary=passed |
| Bridge 节点目录 | .venv/bin/python -m pytest -q tools/system-operations-bridge/tests |
全部通过 |
| Status 展示契约 | bash tools/status-site/tests/display-contract.sh |
PASS status display contract |
| Console 浏览器契约 | bash tools/console-site/tests/browser-contract.sh |
全部通过 |
| 发布 bundle | bash scripts/ci/tests/create-release-bundle-test.sh |
manifest 包含 node-registry.json 且校验通过 |
生产发布还必须经过 bash scripts/ci/post-push-verify.sh，确认远端提交、Actions、101 Runner、RR 镜像和公网回读全部一致。只有输出 post_push_verify=pass 才能报告发布成功。
🔁 迁移、防复发与回退
防复发的核心是禁止旧字段回流。Console 与 Status 的主职责函数只接受 primary_role；API 的兼容字段 role、node_type 必须由 primary_role_label 生成；拓扑和 Bridge 必须拒绝未知主职责、未知能力以及把 derp 写成服务职责的输入。
迁移期间可能出现旧浏览器缓存继续显示旧字段，处理方式是发布新版静态资源并回读构建哈希，不能回写旧字段来适配。若新分类造成生产页面异常，回退方式是撤销本次提交对应的镜像与静态资源，Registry 恢复上一版已验证 JSON；不得在 Console 中临时硬编码节点名称。
⚠️ 未决项 / 需要用户决策
| 事项 | 当前事实 | 需要用户决定的边界 |
|---|---|---|
| 移动管理客户端的稳定性 | little-s20 与 honor-magic2 均已获授权并完成 Tailnet-only 入站管理；RR、101、Home 分别可在 100.64.0.8:8022、100.64.0.13:8022 反向登录。Magic2 已完成整机重启恢复、Registry 稳定身份统一、探针 v0.3.8 上报、TermRover 9 saved 与 RR/101 登录、Exit Node 和 Gemini 真机对话。2026-10-05 晚又发现 Termux 进程曾停止，需经 USB ADB 重新启动 Termux 并执行两个 boot 脚本恢复，因此后台长期驻留仍需观察 |
是否扩展协议、长期保持三套发起端私钥与 Android 入站服务；Termux 再次停止时按进程、Doze、内存回收和 logcat 做根因排查 |
| Edge 与中继能力启用顺序 | 能力矩阵已登记，生产切流仍按维护窗口执行 | 何时启用某台候选 Edge 或 DERP region |
| DD 的多能力组合 | 主职责保持存储，具备 Edge、DERP、Peer Relay 和 Exit Node 能力 | 是否允许 DD 承担某次生产切流或中继演练 |