AgentMeshOS 部署规范

版本：v1.8.1

更新：2026-10-04

📌 结论摘要

部署规范的结论是：101 负责代码、GitHub Actions 与发布协调，RR 只接收版本化产物并执行生产部署、健康检查和回滚；无状态服务自动发布，Stateful 服务保持人工门禁。P15 已完成多 Edge、DERP、Peer Relay 和 DNS 切换；P16 已完成 102 只读备用控制面、Edge 受控回退和 RR 重启演练。依据是 07 现有职责边界、reusable-rr-deploy.yml、GitHub 仓库变量、P16 完成归档和发布门禁。影响是文档推送、Console、Status 与 API 变更必须经过 101 自托管 Runner、固定 SHA 镜像和 RR 发布入口，不能停留在“构建成功但部署被永久跳过”。

🗂️ 目录

• 结论摘要
• 1. 部署职责
• 2. 系统云盘部署与验收
• 3. Tailnet 与数据面
• 4. Runtime Artifact
• 5. 已退役服务
• 6. OmniRoute
• 7. CLI Agent Gateway
• 8. System Operations Bridge
• 9. 故障修复与重启恢复原则
• 10. 时区与时间基准
• 11. 阶段四智能编排与成果闭环发布
• 未决项 / 需要决策

🚀 1. 部署职责

项目控制与生产发布

101 维护 /root/project/AgentMeshOS、GitHub 同步和 CI/CD。GitHub Actions 负责测试、文档构建、镜像/部署产物构建、SHA-256 摘要固定和发布记录，并在构建成功后通过受限物理 SSH 发布入口自动触发 RR 部署；RR 只接收已发布产物并执行生产部署、回滚和健康验收。GitHub/101 不运行生产 Runtime 或 Bridge，RR 不从项目工作树构建。CI/CD 不可用时允许人工使用同一已发布产物应急部署，必须保留审计和回滚记录。

无状态站点的自动发布边界固定为 docs-site、console-site、status-site 和 api-gateway。每次部署使用完整提交 SHA 对应的 GHCR sha-<40位SHA> 镜像，不使用漂移的 latest；RR 发布入口仅接受白名单服务、40 位提交 SHA 和固定部署参数，部署失败自动调用对应脚本的 rollback，并将结果写入 RR 发布日志。带数据库迁移、凭据轮换或外部副作用的 Runtime、Auth、CLI Gateway 等服务，必须先增加独立备份/迁移门禁，暂不纳入该无状态自动发布组。

自动发布默认由仓库变量 AGENTMESHOS_ENABLE_RR_PRODUCTION_DEPLOY 控制。需要临时停部署时，只把该变量设为 false 并记录原因；禁止像 P6 的遗留状态那样把 if: ${{ false }} 永久写入工作流。GitHub Actions 构建 Job 必须执行 scripts/ci/agentmeshos-production-deploy-gate-check.py，该检查会验证四个工作流仍使用统一变量门禁、没有硬编码禁用，并继续调用 reusable-rr-deploy.yml。P6 是一个已结束的临时边界，不能继续代表当前生产发布规则。

自动发布需要在 GitHub 仓库配置 production environment production-rr：RR_DEPLOY_SSH_KEY 为 RR 专用、不可交互的发布密钥，RR_DEPLOY_KNOWN_HOSTS 为 RR 物理入口主机指纹；变量 RR_DEPLOY_HOST、RR_DEPLOY_PORT、RR_DEPLOY_USER 只保存固定 RR 物理地址、SSH 端口和发布用户。GitHub Runner 使用当前 Run 的短期 GITHUB_TOKEN 下载小于 1 MiB 的不可变 Release bundle，并把同一 Run 的 packages:read 令牌放入仅通过 stdin 传输的 agentmeshos-release-transport/v1 头；RR 使用临时 DOCKER_CONFIG 登录 GHCR 后拉取固定 SHA 镜像，目录随工作目录清理，不保存长期 GitHub PAT，也不直接调用 GitHub API。RR 的 authorized_keys 必须将该公钥绑定到 agentmeshos-rr-release-deploy.sh 的强制命令，并关闭 PTY、转发和 agent forwarding；该入口只允许 deploy <白名单服务> <40位提交SHA>，不接受任意 Shell。首次启用前须用 workflow_dispatch 完成四个服务各一次部署、健康检查和故障回滚演练，并检查 RR 发布日志。

节点安装载荷受控分发

本节适用于 Nomad Client、节点 metrics 及后续同类节点安装载荷。101 和 GitHub Actions 负责构建与发布记录，RR 保持生产控制和部署职责；两者均不得向 Worker 传送载荷文件字节。固定顺序如下：

1. CI 为每个载荷生成不可变版本、SHA-256、大小、适用平台/架构、入口文件、构建提交和发布时间，并写入版本化发布清单。
2. 仅将 CI 已记录的载荷发布到 Cloudreve 受控共享目录。清单中的下载地址必须是 https://cloud.yohan.fun/；不得使用 Tailnet、SSH、SCP、SFTP、Nomad 分发、RR/101 HTTP 中转或未登记的镜像站。
3. RR Bridge 只传送固定控制命令和清单中的版本、URL、SHA-256、大小与入口元数据，不传载荷内容、不接受任意 URL、路径、命令或摘要。
4. 目标节点只接受清单精确列出的 URL，下载后先限制大小、校验 SHA-256，再解包并验证入口文件；任一下载、域名、重定向、大小、摘要或结构校验失败时不得执行，并记录失败审计。
5. 成功执行后记录版本、摘要、节点、动作、开始/结束时间和健康复核；下载临时副本只能位于节点任务临时目录，成功或失败都必须清理。Worker 不保存 Cloudreve/WebDAV、GitHub、SSH、Docker、Nomad、Provider 或 Bridge 凭据。

迁移必须先在非生产节点完成隔离验收：正确下载和摘要校验、错误域名拒绝、错误摘要不执行、失败后临时文件清理、成功后的健康复核和审计记录。只有该验收、RR 接收记录与回滚演练均完成后，才能移除旧 SSH/SCP 文件传输；在此之前保留现网链路和回滚材料，不以本规范更新冒充已经迁移。

回滚仅允许选择此前成功发布且摘要相同的版本化载荷，重新走同一清单、下载、校验、审计与健康复核流程；不得从 RR 工作树临时构建、从节点缓存执行未知版本，或绕过摘要校验。发布清单、审计和回滚记录属于长期恢复材料，不自动删除。

flowchart LR
    Internet["公网用户"] --> MM["MM BaoTa 80/443"]
    Internet --> EdgePool["d02 / DD / dog-public Edge 候选"]
    MM --> MainWeb["RR：Console / Auth / API / Runtime 回源"]
    EdgePool --> MainWeb
    MainWeb -. "P16 只读回退" .-> Standby["102：只读 Console / Auth / API"]
    MM --> DD["dd：Cloudreve"]
    MainWeb --> Runtime["Runtime Docker"]
    Runtime --> Proxy["systemd socket proxy"]
    Proxy --> Omni["root 原生 OmniRoute loopback"]
    Runtime -. "可选固定内网" .-> CliGateway["CLI Agent Gateway Docker"]
    RRRuntime["RR 生产 Runtime"] --> OpsBridge["RR root 固定动作 Bridge"]
    Runtime --> Nomad["Nomad"]
    Nomad --> Workers["101 / 102 / 103 Docker Worker"]

• MM BaoTa Nginx 是唯一公网 80/443 入口；不得安装或启用第二套 Ubuntu Nginx。
• Cloudreve 保持 dd 上当前官方容器部署与既有反代，不对其个人文件、镜像标签、端口或反代进行本次外延调整。
• 101/102/103 只运行 Nomad Client、Docker 计算任务和节点遥测；RR 是生产部署与运行节点，MM 是公网边缘入口，DD 是存储节点；不得在这些节点重新部署 KodBox、CSI、JuiceFS、MariaDB 或 NFS 云盘外挂。
• main 只承担控制面与受控自动化，不参与文件内容转发。

💾 2. 系统云盘部署与验收

当前链路：客户端或 WebDAV 客户端到 MM BaoTa Nginx，再到 dd Cloudreve 和 dd 本地持久化存储。

每次涉及云盘的变更，至少验证：

1. cloud.yohan.fun 的公网 HTTPS 响应。
2. WebDAV 认证与受限系统目录的目录读取。
3. 临时目录内的上传、下载比对与删除烟测。
4. 长期目录存在且未执行自动删除。
5. dd 的 Cloudreve 容器健康、CPU、内存、磁盘空间。

项目 Project 凭据只放在 101 的 root-only 配置；RR 的生产 Runtime/Bridge 凭据只放在 RR 的 root-only 配置。两类凭据不得混用、输出、记录到 Git 或传给 Worker。

Project 项目库（与 101 暂不同步，RR 已退役）

RR 不再挂载或同步 Cloudreve Project，不得重新部署旧 Project rclone/bisync 服务或 timer。Cloudreve Project 的 Linux 客户端只能部署在 101，且必须是唯一的受限单向控制器；项目代码权威为 101 /root/project/AgentMeshOS 和 GitHub，RR 只运行发布载荷。

历史上 Cloudreve Project 曾由 RR 上的独立 rclone 挂载/同步链路访问；该链路、配置、缓存、状态和定时器均已删除或停用。101 不实施双向实时同步；101 的 Project 专用凭据只供受控单向控制器使用，不得创建 /mnt/cloudreve-project 挂载、bisync 或未经本规范验收的旁路任务。控制器不得以 lsjson --recursive、远端递归列举或不完整远端清单决定上传和删除；失败健康探针只跳过本轮。本文档其他历史表述与本边界冲突时，以本条为准。

Project 同步与三渠道备份由独立任务负责。101 的受限单向控制器须先完成 Cloudreve、WebDAV、SQLite、锁、网络中断和重启恢复验收，才可启用 5 分钟 timer；DD 副本须独立完成目标身份、物理 SSH 入口、隔离历史、rsync --dry-run、实际增量、清单/哈希回读和重启恢复验收后，才可启用每日 timer。DD 副本只允许由 101 向 DD /root/project 单向写入，不得经 Tailnet、挂载、双向同步或 DD 反向回写。

Project 三渠道备份的运行目标是持续自动成功，而不是以高水位门禁长期暂停。101 必须启用 agentmeshos-backup-health-check.timer，将 Project 云盘同步、DD 异机副本、Project 本机快照、101 角色恢复备份和 Codex Hub 本机备份的失败、过期与恢复事件写入 Console 告警中心；告警只能由同一组件真实恢复关闭。空间保护仅保留防止独立备份盘写满的最低安全线，默认不阻止当前规模的增量同步和快照。三渠道必须各自具备自动容量循环：Cloudreve Project 按镜像语义删除已从 101 /root/project 移除的对象并清理本地报告；DD 副本在写入前检查远端空间、保留 2 份历史并清理 14 天前隔离目录；Project 本机快照在写入前后执行保留策略，空间低于告警线时先删除超出保留目标的旧快照，再决定是否报警失败；Codex Hub 本机恢复快照最多保留 10 份，写入前先清理到 9 份并在容量不足时继续清理到最低保留线，且排除临时目录、虚拟环境、依赖目录、构建产物和缓存目录。云盘同步的 5 分钟触发频率不等于单次追赶窗口；首轮积压或大文件增量允许服务实例运行到受控超时，期间不得并发启动第二个同步实例。

🌐 3. Tailnet 与数据面

Tailnet 是控制面网络，负责 SSH、Nomad、节点健康、部署和私有管理。镜像、安装包、构建产物、业务数据和长期同步内容不得经 Tailnet、main、101 或 103 中转；小于 1 MiB 的受控配置、凭据和紧急脚本可以临时经 Tailnet 传输，但必须校验来源、目标、SHA-256 和权限并清理临时文件。系统云盘文件上传、下载和 WebDAV 复制仍走公网 HTTPS 数据面。

节点管理由生产 RR AI Runtime 调用 RR System Operations Bridge 自动完成。101 负责项目代码、CI/CD 和发布协调；Benson 只需登记一次节点地址、SSH 授权源、Headscale 入网授权源和固定角色模板；之后 Boss 可自主执行预检、Tailnet 接入、Docker/Nomad/遥测部署、验收、重试和卸载，不设置逐次人工批准或 Headplane 中间步骤。首版模板为 compute-general，卸载保留主机 Docker、系统包、用户数据和 SSH。

主机网络边界：主节点、101/102/103、MM、dd 和其他 Linux 节点上的所有系统级应用默认使用本机物理网卡和本机 DNS。只有明确属于 AgentMeshOS 项目的服务才使用 Tailnet 地址进行控制面通信；节点恢复必须持久化 accept-dns=false、accept-routes=false，并验证公网默认路由不指向 tailscale0。不得以项目服务或 Tailnet DNS 作为系统级应用启动前置条件。

P9 隔离 Tailnet 临时远程协助节点（已关闭）

P9 已关闭且不再实施。以下边界只作为以后重新立项时的历史输入：部署前必须先在隔离测试策略验证 Headscale/Tailscale 实际 ACL 语法、一次性 Auth Key、tag:temporary-support 和主机到临时设备的 SSH；未经真实隔离验证不得修改生产 ACL。

P10 MM 公网 IP 可替换架构部署边界

P10 的部署顺序固定为：全量文档 review 与计划状态收口，DNS 与域名清单冻结，端点快照和渲染器测试，SSH 双通道与权限矩阵验证，直连/DERP 路径复核，控制台拓扑与金丝雀验收，最后才允许做边缘切换和回退演练。以上可执行范围已经完成并归档；真实第二生产边缘切换需要完整证书、回源、资源、DNS 和维护窗口，作为外部前置保留。P11 已完成兼容性复核并冻结归档，P12 已完成节点纳管验收，均不重新打开 DERP 或第二边缘计划。

活跃部署配置只保存 edge.yohan.fun 等逻辑身份；当前公网 IPv4/IPv6 只写入 root-only 运行时端点快照和必要的 last-known-good。Nginx allow、UFW、Headscale DERP Map、SSH Host、Gemini egress unit 和重启恢复脚本必须读取同一受控来源或使用明确双通道，不得各自维护 MM 公网地址。当前 VPS 公网入口统一使用 IPv4，edge、MM 和 dog 不发布公共 AAAA；只有在所有活动 Edge 候选都具备经过验证的可靠双栈后，才允许重新启用 IPv6。任何切换都必须先验证新地址、DNS、TLS、SSH、Tailscale、DERP 和业务入口，再清理旧值；失败时先恢复网络可用性，再回退文件。

公网路径承载业务大流量，Tailnet 只承载控制面、SSH 和小于 1 MiB 的受控交换文件。节点直连优先，DERP 只作失败兜底；MM 公网失效时，MM SSH 双通道和 MM DERP 不能同时作为唯一恢复路径，必须保留 RR、101、Home 等独立管理入口和 DD region 901 候选。

P15 多 Edge、DERP、Peer Relay 与 DNS 切换部署边界

P15 部署顺序固定为：基线、资格门禁与计划迁移，拓扑数据与交互修正，DERP/Peer Relay 逐区扩展，三台新 Edge 同时建设，DNS 自动切换，最后做发布与真实回退验收。三台新 Edge 全部通过 SSH 双路径、Nginx -t、证书链、核心域名回源、浏览器登录和重启恢复前，不修改 edge.yohan.fun 的活动 A 记录。

Edge 只承担公网 DNS、TLS、Nginx 和回源，不复制 Console、Docs、API、OmniRoute 或其他后端服务。核心域名为 mesh/cloud/auth/console/docs/status/api/omni/nomad/ai；Three Dogs 使用 threedogs.vip、www.threedogs.vip 和逻辑 Origin origin-threedogs.yohan.fun，四个 Edge 必须持有同构 vhost 和独立续期证书，Origin 来源从 Edge 候选动态生成并使用认证头。Three Dogs 的 dog WordPress 仍是单 Origin，Edge 切换不解决 dog 整机故障。现有 Cloudreve、宝塔、Shadowsocks Rust、Nginx、SSH 和业务端口必须保留，候选节点资格至少满足 512 MiB 内存余量、2 GiB 磁盘余量、443/tcp、39478/udp 和 40000/udp 可用，且启用后资源下降不超过基线 10%。

DERP 使用官方 derper，MM 为 region 900，DD 为 901，d02 为 902，dog-public 为 903。稳定域名分别为 derp-mm.yohan.fun、dd.yohan.fun、d02.yohan.fun 和 dog.yohan.fun，对外使用 443/tcp 与 39478/udp；DERP vhost 必须同时保留 /derp 与 /verify，其中 /verify 经主节点私有网关转到 Headscale，缺失时禁止 apply。MM 专用域名必须单独签发并续期证书，不得重新复用会随 Edge 切换的 mesh.yohan.fun。Peer Relay 使用 40000/udp，只设置 --relay-server-port=40000，清空 RelayServerStaticEndpoints，由 Tailscale 自行发布公网端点。Headscale relay grant 必须从 tools/headscale/relay-registry.json 精确生成，禁止使用 src:["*"]。

DNS 控制器只在 101 运行写操作，RR 只做只读监督。101 与 RR 连续三次一致判定当前 Edge 不可用后，才通过阿里云基础 DNS OpenAPI 写入 edge A 记录；当前账号拒绝 60 秒 TTL，活动与候选记录统一使用 600 秒，不批量修改 CNAME，切换后至少稳定 10 分钟才允许自动回切。凭据只存在 101 root-only 0600 文件，失败、缺失、401、地址冲突或健康证据冲突时禁止写入并明确告警；show/check/dry-run/switch/rollback 必须通过同一控制器的契约测试。

P16 控制面只读备用与 Edge 回退部署边界

P16 部署顺序固定为：先完成 RR Auth SQLite 一致性快照、Schema/账号/Key 计数和 SHA-256 回读，再在 102 启动使用同一 AUTH_SESSION_SECRET 的只读备用 Auth；随后部署只读 Console 与 API Gateway 投影，接入 Edge 主备 upstream，最后执行停止 RR 后端、关闭 RR 整机、损坏快照和恢复 RR 的真实演练。认证快照与运行凭据保持 root:root 0600，不得把会话密钥、认证数据库或管理凭据写入仓库、日志、前端或普通回复。

102 的备用控制面只允许 Console、Auth 和 API Gateway 的只读投影。Auth 可以验证已有账号和读取既有会话，但必须拒绝密码修改、Key 撤销和其他管理写操作；API 只允许 topology、node inventory、alerts 和 bridge status 等只读路径，不得代理 Runtime、Nomad 管理、系统操作或任何写接口。RR 始终是唯一写权威，102 不得反向覆盖认证库或拓扑数据。

Edge 只对 console/auth/api 增加主备 upstream；回退只对连接失败、超时和上游 500/502/503/504 生效，不使用客户端重试造成重复写。备用响应必须包含 deployment_mode=standby_readonly、read_only=true、source=rr-last-known-good 和 snapshot_age_seconds；拓扑快照超过 5 分钟标记 stale，超过 30 分钟标记 unavailable。RR 恢复后必须自动回到主路径，并保留切换、回退和快照年龄证据。

📦 4. Runtime Artifact

旧 MinIO/S3 Artifact 后端已删除，不得恢复。Worker 回调只允许最大 1 MiB 的结构化 JSON，由 Runtime 校验大小和 SHA-256 后写入 SQLite 的独立 BLOB 表；Worker 不获得存储凭据、宿主机路径或可选对象键。只有 SQLite 持久化成功后才消耗任务级一次性 Token，失败必须允许同一 Token 重试。

该 SQLite 路径只承担小型任务证据，不等于外部长期 Artifact 存储。Cloudreve WebDAV StorageAdapter 已完成独立权限、上传、回读、SHA-256 和长期内容不自动删除验收，可用于较大或长期 Artifact；其凭据只存在于主节点 root-only Runtime 配置。

🗄️ 5. 已退役服务

KodBox、Nomad CSI、JuiceFS、MariaDB Galera、MinIO、MM 39062 中转、disk.yohan.fun 和对应定时器/恢复脚本均已退役。禁止以历史文档或旧备份重新部署它们。

🤖 6. OmniRoute

P3-6-2 官方 OmniRoute 模型核心接入只允许使用官方 npm 包、官方 Node、官方 CLI/API、官方控制台和官方正式发布；禁止修改上游源码、添加补丁、维护私有 Fork/私有分支、构建私有镜像、重新编译、手工替换已安装包文件、改写构建产物或恢复历史隔离构建链。

102 当前生产版本固定为官方 omniroute@3.8.51，运行在系统 Node 22.23.0 与 agentmeshos-omniroute.service 中。服务以 root 运行，使用官方全局 npm 安装；不维护 AgentMeshOS 版本软链接。官方默认数据目录为 /root/.omniroute，数据库为 /root/.omniroute/storage.sqlite，环境文件为 /root/.omniroute/.env。API/UI 只监听 127.0.0.1:39180，Live WS 只监听 127.0.0.1:39182；生产由只对 RR 与 MM 放行的 100.64.0.4:39200 私有入口承接。RR 3.8.50 的数据、全局包、service、cutover 备份和网关 vhost 已按 P13-C 删除，RR 不再保留回退点。

P13 的 102 生产安装使用 scripts/deploy/omniroute-native/agentmeshos-omniroute-native-deploy.sh v0.1.1 一次性直接安装 Node 22.23.0 与 omniroute@3.8.51。全局包位于 /usr/local/lib/node_modules/omniroute，数据目录同为 /root/.omniroute，服务同为 agentmeshos-omniroute.service；MemoryHigh=8 GiB、MemoryMax=10 GiB、LimitNOFILE=65536，只监听 127.0.0.1:39180/39182。脚本在 preflight() 强制要求 sqlite3，因为官方 snapshot-data.sh 使用 VACUUM INTO 生成一致性快照；缺失时不得继续用退化复制方式冒充完整快照。该脚本本身不恢复数据、不修改 MM 回源、不停止 RR；任意时刻只允许一个 SQLite 写者。

宿主层入口由 scripts/deploy/omniroute-native/agentmeshos-omniroute-edge.sh v0.2.0 管理：在 102 同时建立 Tailnet 入口 100.64.0.4:39200 与局域网入口 192.168.50.102:39200，由同一 systemd-socket-proxyd 反代 loopback，并按 tailscale0 与 enp0s31f6 分别执行 raw PREROUTING/INPUT 来源 guard。101 默认使用 Tailnet URL；LAN 只作为明确测试和人工切换入口。edge 服务必须显式保持 LimitNOFILE=65536:65536、--connections-max=4096 和失败重启；2026-10-01 曾因软上限停在 1024 导致长时间连接累积后 Too many open files 和公网超时，check 现在会对这两个参数做硬门禁。P14-1 未修改 OmniRoute 包、数据库或服务文件。RR 的 agentmeshos-omniroute-cutover.sh 已随 P13-C 退役删除，因为 RR 本地 OmniRoute 和 omni vhost 都已不存在；不得从历史文档恢复。

P13-B 在 P13-4 之后把 MM 公网入口从“经 RR 共用回源网关”改成“直连 102 私有入口”：MM 面板源 /www/server/proxy_project/sites/omni.yohan.fun/omni.yohan.fun.json 与渲染配置 /www/server/panel/vhost/nginx/omni.yohan.fun.conf 的 proxy_pass 都由 100.64.0.1:39200 改为 100.64.0.4:39200，并保留 /、/dashboard 跳转和 /login 的 auth_token 规范化。RR 的 100.64.0.1:39200 仍是 console、docs、status、api、auth、nomad、mesh 等 7 个服务的回源网关，只有 omni 从中退出。RR 到 102 的 Runtime 私有代理（本机 AI Runtime 容器经 172.30.70.1:39181 使用）继续保留。

P13-C 取消了原 P13-5 固定等待期，原相位观察器已迁移为无阶段阻塞含义的 scripts/maintenance/agentmeshos-omniroute-health-observation.py v0.2.0 和 agentmeshos-omniroute-health-observation.timer。101 每 15 分钟只读检查 102 版本与服务、edge FD/连接上限、资源、SQLite、公网 health、RR omni 退役路径和 Runtime 代理目标，记录写入 /srv/codex-hub-backup/agentmeshos/omniroute-health/observations/。新首轮记录 20261001T022814Z.json 为 pass；后续健康异常按运维事件处理，但不再要求等待固定观察时长才关闭 P13。

Gemini Web 只允许使用 OmniRoute 官方 Provider、官方管理 API 和官方 VNC 登录/harvest 流程。禁止在 RR 上创建独立 Gemini Chrome profile、9333 CDP 常驻实例、固定出口代理或任何自建 gemini-web-session、gemini-egress systemd 服务；这些重复常驻实例曾于 2026-09-27 触发 RR 全局 OOM，现已作为退役实验清除。需要添加或切换账号时，必须直接使用 Omni 控制台连接中的官方“添加/登录”流程；临时 VNC 容器完成登录后按官方接口回收，不进入正式常驻服务。

宿主层 systemd、Privoxy 等出口代理和 loopback 转发只有在确有非 Gemini 的官方集成需求时才允许保留；Gemini Web 不再允许依赖这些自建出口组件。所有此类配置必须记录用途、文件路径、回滚点，并在升级后重新执行真实 Smoke；如果官方版本原生支持同等能力，优先改用官方配置并删除重复的宿主层适配。

Runtime 容器只能通过 agentmeshos-omniroute-runtime-proxy.socket 的 172.30.70.1:39181 访问 OmniRoute；UFW 只放行 172.30.70.2。P13-4 后该代理最终目标为 100.64.0.4:39200，并明确不依赖 RR 本地 agentmeshos-omniroute.service。P13-C 删除 RR 本地 OmniRoute 后该代理仍为 active，因为它是 RR 本机容器访问 102 的稳定入口；不得把 102 OmniRoute 改为 0.0.0.0，不得把 Runtime 重新接入旧 omniroute-core_default Docker 网络。

Bridge 和 Runtime Proxy 的 systemd 启动不得把 Docker 设为硬 Requires：Docker 或 containerd 首次启动出现瞬时失败时，Bridge 必须以现有 restart 策略等待 Docker 变为 active 后重试；Proxy socket 使用 FreeBind 独立恢复，不能因 Docker 首次失败永久 inactive。

OmniRoute 当前采用双 Key 职责分离：管理 Key 与普通模型 Key 的正式权威保存在 102 的 root-only OmniRoute 环境边界，不得进入 Agent、Worker、浏览器、Console 响应、普通日志或 Git。普通模型 Key 允许 chat/models、Boss/Worker 两个正式 Combo、这两个 Combo 当前实际包含的去重目标模型、受控图片模型和 self:usage，不允许 Provider、Combo 管理接口或其他管理操作。原因是官方 OmniRoute 在调用 Combo 时会逐个检查内部目标模型的权限；只放行 Combo 名称会让所有目标模型在实际调用前被跳过。P13-C 后，RR 的 AI Runtime 部署脚本不再读取 /etc/agentmeshos/omniroute-core/*、不再通过本机 39180 管理 Combo，也不得重新创建 RR 本地 OmniRoute；它只验证 P13 私有代理到 102，并保留 /etc/agentmeshos/ai-runtime.env 中已经验签可用的 AI_RUNTIME_OMNIROUTE_KEY。Combo 与 Key 权限的任何调整继续通过 102 上的官方 API 或控制台执行。

官方 3.8.49 的 /api/mcp/tools 与 /api/mcp/stream 实测要求 manage/admin；只授予 mcp:connect 和工具 scope 会返回 403 AUTH_001。2026-09-28 在 RR 的官方 3.8.50 上再次用 agentmeshos-model-client 做同类正向测试，两个端点仍返回 403 AUTH_001，因此该限制不是旧版本缓存或调用方式问题。runtime-call.env 继续注入与管理 Key 相同的高权限值以保持已验收 MCP 能力，普通模型 Key只用于受限模型客户端。Runtime 代码仍只允许固定模型接口和 MCP 白名单，不能借此开放 Provider、Combo、预算、缓存或代理写操作。后续只有在官方版本用普通 Key真实通过 MCP 目录、初始化和白名单工具调用后，才允许把 Runtime 切换到普通模型 Key。

OmniRoute 的 Combo 策略必须在 102 的生产权威上维护：Worker Combo agentmeshos-free-capacity-pool 的策略必须为 least-used，Boss Combo agentmeshos-free-quality-first 的策略必须为 fill-first。Boss 按质量顺序优先消耗 GPT/Codex、Claude 和 O3 的免费额度；Worker 按“模型 + 账号”的实际调用次数均衡容量。两个 Combo 当前各含 195 个候选、覆盖 24 家 Provider，均关闭 session stickiness，并使用官方响应质量校验拒绝模型不存在、需要订阅、Pollen 不足或账户余额不足等伪成功正文。RR Runtime 部署只通过私有代理验证鉴权与健康，不在 RR 重放 Combo/Key 写操作。

从低权限 Key 切换时，必须先验证高权限 Key、完成 Runtime 真实调用，再通过官方 API/CLI 删除低权限 Key。删除后生成新的完整未脱敏备份；本机和 Cloudreve SHA-256 回读、101 隔离恢复及 53/52/2/1 基线全部通过后，才允许删除包含旧 Key 的历史备份。

每次升级前必须完成：

1. 保存未脱敏的完整 SQLite、WAL/SHM、数据目录、环境契约和官方包 SHA-256；Provider 备份同时保留本机副本和 Cloudreve 长期目录副本。
2. 用原始 STORAGE_ENCRYPTION_KEY 在隔离副本中启动，等待迁移和 Provider 内存加载完成后，再核对健康摘要、认证 /api/providers、连接/Provider/Combo/API Key 数量及 SQLite 完整性。
3. 每次升级前使用官方 snapshot-data.sh 或等价的一致性快照备份 /root/.omniroute；任一数量、解密、健康或协议 Smoke 不一致即停止切换并恢复快照，不修改生产 Provider。

当前迁移验收基线为 53 条连接、52 个 Provider、2 个 Combo、1 个高权限 API Key、迁移 133、SQLite quick_check=ok。root 官方默认原生迁移、Provider 恢复、Runtime 重启、真实调用和公网入口均已通过；旧 Docker、兼容数据目录和旧 Redis 已清理。当前完整未脱敏备份为 /backup/agentmeshos/omniroute-root-native-admin-20260803T035230Z.tar，SHA-256 为 716fb95e23cb93aba362df3548e9f48a5112ca9c98bdd29e9ba0b5421ef0cfa3；归档清单记录 53/52/2/1、迁移 133、SQLite 完整性、4596 条调用日志和 429 条用量历史，并已在 Cloudreve AgentMeshOS-长期/OmniRoute-Root-Native-Admin-20260803T035230Z 回读及 101 隔离恢复验收。任何新轮换必须先完成同等验收。

迁移后的历史运行基线单独记录为 52 条连接、51 个 Provider、2 个 Combo、2 个 API Key，SQLite quick_check=ok。2026-10-01 P13-2 的当前生产基线更新为 70 条连接、19 个 Combo、4 个 API Key、迁移 160/163、SQLite quick_check=ok；102 隔离副本恢复后计数同为 70/19/4、迁移 193/196、quick_check=ok。连接/Provider 数量的历史变化必须按时间点记录，升级或恢复验收必须同时核对历史恢复清单和切换前的当前运行清单，不得用任一数字覆盖另一时间点的事实。

🧩 7. CLI Agent Gateway

CLI Agent Gateway 是可选的 AI Boss 备用执行器，不是 OmniRoute Provider。容器固定接入 agentmeshos-ai-runtime 网络的 172.30.70.3:39190，不得发布宿主机端口；Runtime 固定为 172.30.70.2。凭据文件 /etc/agentmeshos/cli-agent-gateway.env 必须为 root:root 0600，Runtime 只复制内部调用 Key，不复制 AgentRouter Key。该文件不存在时，Runtime 必须继续以 OmniRoute-only 启动。

容器必须非 root、只读根文件系统、删除全部 Capability、启用 no-new-privileges，且不得挂载仓库、宿主机 HOME、Docker Socket、Nomad、Cloudreve、SSH 或其他基础设施路径。唯一持久卷只保存脱敏调用 SQLite；Prompt、Token 和 raw stderr 不得落盘。

三个候选首次部署默认关闭。只有目标 CLI 的真实请求返回预期文本、退出码为 0、无错误事件，并完成 Gateway、Runtime 与 Console 端到端 Smoke 后，才允许单独设置对应 CLI_GATEWAY_ENABLE_*。目录可见、CLI 可启动或 Gateway 健康不能替代真实生成验证。Claude Code 接入 AgentRouter 时必须使用 ANTHROPIC_AUTH_TOKEN Bearer Token 和不带 /v1 的 ANTHROPIC_BASE_URL，不得同时注入 ANTHROPIC_API_KEY 或使用强制 API Key 语义的 --bare。历史记录中的通过结论不代表当前运行状态；当前生产复验对 AgentRouter 上游返回 HTTP 401，三个候选均保持待复验，不能作为默认通道或自动发布放行依据。

🛠️ 8. System Operations Bridge

RR Bridge 必须以 root systemd 服务运行，只监听 RR Runtime Docker 网关 172.30.70.1:39184。UFW 只允许 172.30.70.2，不得发布到公网、Tailnet 或 BaoTa。HMAC Key 位于 RR /etc/agentmeshos/system-operations-bridge.env，必须为 root:root 0600；Runtime 部署脚本只把调用副本注入自己的 root-only 环境，不进入浏览器、模型、Worker、日志或 Git。101 不运行第二套 Bridge。

部署顺序固定为：先部署 Bridge，再部署 Runtime，最后部署 Console。验收必须包含：

1. Bridge 只绑定 172.30.70.1:39184，公网、Tailnet和非 Runtime 来源不可访问动作接口。
2. 缺失签名、过期时间、重复 nonce、修改正文和未知 Action 均被拒绝。
3. Runtime 容器仍为只读根文件系统、CapDrop=ALL、no-new-privileges，且无 Docker Socket、SSH和主机目录。
4. 固定诊断、固定服务重启、Docs 部署/回滚均保存 Runtime 和 Bridge 双重审计；执行后必须完成健康复核。
5. Nomad 重试/清理只接受 Runtime SQLite 已登记的任务，不能传任意 Job ID或 HCL。
6. 任何失败均记录真实状态；不得把请求已接受冒充动作已完成。

🔁 9. 故障修复与重启恢复原则

1. 任何重启恢复故障必须先采集 systemd、内核、Docker/containerd、容器网络与端口的时间线证据，先确认根因再变更配置；没有证据的部分只能标记为待验证。
2. 如果 Docker 重启后容器的网络端点、端口映射、挂载或健康状态与部署声明不一致，禁止继续对同一运行对象反复 start 或追加旁路配置。应保存必要诊断后清理受污染容器对象，调用对应正式部署脚本重建，禁止删除业务数据卷、root-only 环境文件或项目凭据。
3. 重建完成后必须同时验证本机回源、BaoTa Nginx 公网入口、主机物理默认路由/DNS、Tailnet accept-dns=false/accept-routes=false、Nomad 节点、Runtime/Bridge/Proxy、Cloudreve 项目挂载与下载侧同步；仅局部 HTTP 200 不构成恢复完成。
4. Docker daemon 异常退出的外部终止来源若无法从当前主机证据确认，必须保留该未知项并通过下一次受控重启复核，不能编造杀进程主体或宣称永久修复。

🕘 10. 时区与时间基准

AgentMeshOS 的节点、原生服务、容器和运行日志统一使用上海时区。Linux 主机为 Asia/Shanghai，Windows 主机使用系统时区 China Standard Time；Windows 时间服务必须为 Automatic 且运行中。宿主机时区只通过操作系统时间配置维护，项目脚本不得在任务运行时手工改宿主机时间。

项目容器镜像必须在 Dockerfile 中显式提供 ENV TZ=Asia/Shanghai 和可解析的上海时区数据；正式部署脚本的每个 docker run 必须同时传入 -e TZ=Asia/Shanghai，NAS Container Station 载荷必须在 Env 中传入同一值。新增容器、备用节点和回滚入口都必须进入 scripts/ci/agentmeshos-container-timezone-check.py 的契约检查，禁止依赖宿主机偶然继承、一次性 docker exec 或部署后的手工修正。

数据库和外部应用可以保持 UTC 存储；展示层必须明确数据源时区，并按客户端时区转换。OmniRoute 3.8.51 的 MCP 审计页存在独立的官方显示缺陷：mcp_tool_audit.created_at 由 SQLite datetime('now') 按 UTC 写入，官方 API 将不带时区的 createdAt 原样返回，官方前端再用 new Date(createdAt).toLocaleString() 渲染；浏览器会将该字符串按本地时间解释，不会完成 UTC 到上海时间的加八小时转换。因此修改 102 宿主、浏览器或 VNC 时区均不能修正该页面，页面值应按 UTC 读取，或等待官方上游修复；不得修改 OmniRoute 官方前端、包文件、数据库结构或构建产物。

🧪 11. 阶段四智能编排与成果闭环发布

阶段四新增计划、成果与验收对象时必须先备份 Runtime SQLite 并执行 PRAGMA quick_check。迁移只能增量新增表、索引和可空兼容字段，不覆盖旧消息、任务、Artifact、记忆、附件、审核或审计；旧任务保持原策略快照，新 Runtime 将其映射为 legacy-v1 和 legacy_recorded，不得伪造新的 Benson 验收记录。

发布功能开关必须相互独立：数据库只读能力、智能规划、自动执行、检查器、自动验收和 Console 成果中心。灰度顺序固定为：

1. 新数据库与只读成果接口。
2. 智能规划但不自动执行。
3. 手动测试计划执行。
4. Runtime 轻量检查器与无凭据 Nomad 验证 Worker。
5. AI BOSS 结构化审核和普通任务自动验收。
6. Benson 高风险决定。

组件发布顺序固定为“验证 Worker 镜像 -> Runtime -> Console -> Docs”。每一步必须记录 Git 提交、GitHub Actions、镜像摘要、数据库备份、健康、真实接口和真实任务证据；正式部署只使用合并后主分支镜像。生产验收至少覆盖多任务计划、无依赖并行、依赖等待最终验收、Nomad 公开任务、Cloudreve 回读哈希、网站 DNS/TLS/HTTP/浏览器链路、数据质量检查、返工与版本替代、Benson 决定、重开、Runtime 重启恢复、幂等不重复消费 Token，并确认 P5 主动循环未启用。

回滚前必须先关闭新 P4 任务入口，等待或取消运行中任务，再回滚 Runtime、验证 Worker和 Console 镜像。新表、成果、长期 Cloudreve 文件和审计不得删除；Console 必须根据后端能力隐藏不支持区域并显示真实原因。回滚后重新执行 SQLite 完整性、健康、旧对话、旧任务、Cloudreve 边界和公网入口验证。

验证 Worker 必须以版本化无凭据镜像运行，不接收任意 Shell、本地路径、动态安装、私网、localhost、Tailnet、云元数据或 Cloudreve/Provider/Nomad/SSH/Docker 凭据。URL 检查必须覆盖重定向、DNS 重绑定和私网拒绝；文件检查必须限制大小、层数、解压总量、文件数、像素、PDF 页数、字符数和执行时间。

⚠️ 未决项 / 需要决策

P14 已完成并归档，102 继续是唯一生产 OmniRoute 权威，RR 仅保留本机 Runtime 私有代理。P15 的 Edge、DERP、Peer Relay、真实 MM → d02 切流、AAAA 删除、回切、AAAA 恢复和 RR 冷启动修复已经完成并归档；AliDNS 凭据、候选记录与 30 秒控制器均已落地。P16 已完成 102 只读 Auth、Console、API Gateway、Edge 回退与 RR 重启演练，见 P16 完成归档。P17 正在执行代理 Master、四个 panel-* 节点面板、Console #proxyNetwork 架构页和真实客户端验收，见 P17 计划；节点 2095/2096 仍只监听 Tailnet。discovery、媒体、语义缓存和日志正文导出不得因搜索接入自动启用。