AgentMeshOS 部署规范

版本：v1.6.0

更新：2026-08-11

1. 部署职责

flowchart LR
    Internet["公网用户"] --> MM["MM BaoTa 80/443"]
    MM --> MainWeb["main：Console / Docs / OmniRoute 回源"]
    MM --> DD["dd：Cloudreve"]
    MainWeb --> Runtime["Runtime Docker"]
    Runtime --> Proxy["systemd socket proxy"]
    Proxy --> Omni["root 原生 OmniRoute loopback"]
    Runtime -. "可选固定内网" .-> CliGateway["CLI Agent Gateway Docker"]
    Runtime --> OpsBridge["root 固定动作 Bridge"]
    Runtime --> Nomad["Nomad"]
    Nomad --> Workers["101 / 103 / jj Docker Worker"]

MM BaoTa Nginx 是唯一公网 80/443 入口；不得安装或启用第二套 Ubuntu Nginx。
Cloudreve 保持 dd 上当前官方容器部署与既有反代，不对其个人文件、镜像标签、端口或反代进行本次外延调整。
101/103/jj 只运行 Nomad Client、Docker 计算任务和节点遥测；不得重新部署 KodBox、CSI、JuiceFS、MariaDB 或 NFS 云盘外挂。Project rclone/bisync 同步当前保持停用，RR 不得运行 Project 挂载或同步；jj 当前资源较小，必须保持 batch_allowed=false，除非另行完成容量、稳定性和真实 Batch 验收。
RR 继续承担生产控制面与 Docker/Nomad 部署运行；RR 不再运行 Project 只读挂载或 AgentMeshOS 专用同步链路。
RR 的生产服务不得从 /root/project/AgentMeshOS 读取运行脚本；部署时必须把所需脚本安装到 /usr/local/lib/agentmeshos/ 等版本化运行目录，项目工作区删除不应影响已运行服务。

2. 系统云盘部署与验收

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

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

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

凭据只放在主节点 root-only 配置；不得输出、记录到 Git 或传给 Worker。

Project 项目库

Cloudreve 账号的 WebDAV 根目录已经限定为既有 Project，部署时不得再拼接第二层 Project。历史主节点使用的 Project 专用凭据和 rclone 配置已列为高风险残留，RR 上必须删除或停用：

101 的 /root/project 是本地项目根；AgentMeshOS 位于其中的子目录，不代表整个 Project 云端根；
RR 不得挂载 /mnt/cloudreve-project，不得运行 Project bisync 或同步 timer；
在 RR 残留清理、DD compose 数据库挂载修正和公网写入验收完成前，禁止执行 bisync、resync-path1、resync-path2 或启用 timer；
同步必须保留冲突副本、限制批量删除，并把本地历史写入 /srv/codex-hub-backup；
初次与每次同步后必须执行双端列表和关键文件哈希核验；
关闭服务或撤销凭据不得删除云端项目资料。

现行部署入口见项目云盘挂载与同步。

3. Tailnet 与数据面

Tailnet 是控制面网络，负责 SSH、Nomad、节点健康、部署和私有管理。它不是系统云盘传输通道。文件上传、下载、WebDAV 复制不得经 Tailnet、main、101 或 103 中转。

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

主机网络边界：主节点、101/103、MM、dd、jj 和其他 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。临时设备固定 accept-dns=false、accept-routes=false、--shields-up=true，不得作为 Exit Node 或发布子网路由，也不得加入 Nomad、Docker Worker 或资源池。生产发布与会话关闭均须验证节点已删除、SSH 公钥精确移除、原有 SSH 服务状态恢复；无法验证时记录 cleanup_failed。

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、构建私有镜像或恢复历史隔离构建链。

当前生产版本固定为官方 omniroute@3.8.49，运行在系统 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。

Runtime 容器只能通过 agentmeshos-omniroute-runtime-proxy.socket 的 172.30.70.1:39181 访问 loopback OmniRoute；UFW 只放行 172.30.70.2。不得把 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 职责分离：/etc/agentmeshos/omniroute-core/admin.env 保存 agentmeshos-runtime-admin 管理 Key；model-client.env 保存 agentmeshos-model-client 普通模型 Key。两者以及 runtime-call.env 必须保持 root:root 0600，不得进入 Agent、Worker、浏览器、Console 响应、普通日志或 Git。普通模型 Key 只允许 chat/models、Boss/Worker 两个正式 Combo 和 self:usage，不允许直接模型、Provider、Combo 或其他管理接口。

官方 3.8.49 的 /api/mcp/tools 与 /api/mcp/stream 实测仍要求 manage/admin；只授予 mcp:connect 和工具 scope 会返回 403 AUTH_001。因此当前 runtime-call.env 继续注入与管理 Key 相同的高权限值以保持已验收 MCP 能力，普通模型 Key暂不注入 Runtime。Runtime 代码仍只允许固定模型接口和 MCP 白名单，不能借此开放 Provider、Combo、预算、缓存或代理写操作。后续只有在官方版本用普通 Key真实通过 MCP 目录、初始化和白名单工具调用后，才允许把 Runtime 切换到普通模型 Key。

Runtime 部署必须在写入环境前通过官方 /api/combos 验证：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，并使用官方响应质量校验拒绝模型不存在、需要订阅等伪成功正文。持续返回上游错误的连接可以保留供复测，但不得继续留在正式 Combo 中。

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

每次升级前必须完成：

保存未脱敏的完整 SQLite、WAL/SHM、数据目录、环境契约和官方包 SHA-256；Provider 备份同时保留本机副本和 Cloudreve 长期目录副本。
用原始 STORAGE_ENCRYPTION_KEY 在隔离副本中启动，等待迁移和 Provider 内存加载完成后，再核对健康摘要、认证 /api/providers、连接/Provider/Combo/API Key 数量及 SQLite 完整性。
每次升级前使用官方 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。连接/Provider 数量减少源于已明确删除不允许经 OmniRoute 中转的 AgentRouter；当前只保留双角色正式 Combo，API Key 数量包含 Runtime 管理 Key 与普通客户端访问 Key。升级或恢复验收必须同时核对历史备份清单和切换前的当前运行清单，不得用任一数字覆盖另一时间点的事实。

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。2026-08-05 Codex gpt-5.6-sol、Claude claude-opus-4-8 与 claude-opus-5 均已逐模型完成生产 Gateway 与正式 Boss API Smoke，三个开关当前均为 true。

8. System Operations Bridge

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

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

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

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

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

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

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

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

新数据库与只读成果接口。
智能规划但不自动执行。
手动测试计划执行。
Runtime 轻量检查器与无凭据 Nomad 验证 Worker。
AI BOSS 结构化审核和普通任务自动验收。
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 页数、字符数和执行时间。