AgentMeshOS 技术选型说明
版本：v1.8.1
更新：2026-10-04
📌 结论摘要
技术栈继续使用 Tailscale、Nomad、Docker、Cloudreve、薄 Runtime 和官方 OmniRoute。P16 已完成 102 只读备用控制面、同会话认证快照和 Edge 本地回退，未引入 GTM、双主写 DNS、Auth 双活或第二调度器；P17 复用 MM Nginx、RR 私有回源、Tailnet 节点 API 和现有 2S-UI/内嵌 sing-box，不重建数据面，也不引入跨节点 SSO 或私有 Fork。依据是 P16 完成归档、P17 计划与 docs/plans/state.json。
🧱 现行选型
| 能力 | 当前方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 |
|---|---|---|---|---|---|---|
| 私有控制网络 | Headscale / Tailnet | 已有运维方式稳定 | 中等 | 适合控制与管理 | 已掌握 | 可扩节点 |
| 调度 | Nomad | Worker 接入统一 | 中等 | 适合批处理调度 | 已掌握 | 可扩 Worker |
| 计算 | Docker | 服务隔离清晰 | 低 | 适合现有任务 | 低 | 可替换镜像 |
| 系统云盘 | Cloudreve + WebDAV + dd 本地持久化 | 单一应用边界清楚 | 低 | 公网直达 dd，不经转发 | 低 | 可按官方能力扩展 |
| 项目代码权威 | 101 /root/project/AgentMeshOS + GitHub | 与生产运行节点分离，RR 不保留 Project 同步链路 | 低 | 代码发布不引入云盘挂载压力 | 低 | 可独立扩展项目 |
| 项目 CI/CD 与生产发布 | 101 工作区 + GitHub Actions；RR 执行已发布产物 | 构建、测试、摘要和生产运行职责分离；可审计、可回滚 | 中 | 产物传递和验收开销可控 | 已有 GitHub Actions，学习成本低 | 可扩展环境、审批和签名策略 |
| 公网入口 | MM、d02、DD、dog-public 同源 Nginx Edge 候选 | 配置同源、单活动指针、可逐台回退 | 中 | 公网直达，不经 Tailnet 转发业务流量 | 已掌握 | 可按节点门禁扩展 |
| Tailnet 中继 | DERP region 900-903 + Peer Relay 40000/udp | 区域独立、ACL 精确、可逐区停用 | 中 | DERP 仅兜底，Peer Relay 独立路径 | 中 | 可扩节点和区域 |
| 控制面只读备用 | 102 Auth SQLite 一致性快照 + Console/API 只读投影 + Edge 本地回退 | 不双写，RR 仍是唯一写权威，状态可标注只读与快照年龄 | 中高 | 只读拓扑与状态请求在故障时接近本地延迟 | 中 | 可按后续真实需求扩展只读范围 |
| 模型核心 | 官方 OmniRoute npm + 系统 Node + systemd | 跟随官方 npm 发布，使用官方默认安装与数据目录 | 低 | loopback 原生调用，避免容器功能缺口 | 中等 | 可使用官方 CLI、升级和宿主机集成能力 |
| Runtime 形态 | 薄 Runtime + OmniRouteAdapter | Runtime 只保留业务编排与桥接 | 低于双 Router | 少一套重复路由与凭据读写 | 低 | 可随官方能力扩展 |
| AI Boss CLI 备用通道 | FastAPI + Gateway 加密 SQLite 单模型通道 + Codex/Claude CLI + Docker 隔离 | URL/Key 与 Runtime 分离，命令与审计边界清晰 | 中等；需维护 CLI 版本、主密钥和单独镜像 | 多一跳和进程启动开销，只适合显式选择 | 中等 | 可按真实 Smoke 单独启用单模型通道 |
| AI Boss 系统动作 | Runtime Adapter + Python 标准库 root systemd Bridge | 固定动作集中维护，Runtime 与主机权限分离 | 低；无额外 Python 框架和镜像 | 单机私网一跳，对运维动作可忽略 | 低 | 可逐个增加已验证 Handler，不扩大通用权限 |
| AI BOSS 交互 | FastAPI + SQLite 持久状态 + SSE | 沿用现有栈，状态可审计和恢复 | 低；不新增中间件 | 单向流式和状态推送开销低 | 低 | 后续可扩交互事件，不需要 WebSocket |
| AI BOSS 记忆 | SQLite + FTS5 | 单用户下事务与来源管理集中 | 低；复用 Runtime 数据库 | 适合当前数据量 | 低 | 检索质量不足时再评估向量索引 |
| AI BOSS 附件 | Cloudreve 临时空间 + SQLite 元数据 | 与既有 Storage 边界一致 | 中等；需解析和配额控制 | 原文件不进入 SQLite | 低 | 可按后端能力逐步开放多模态 |
| AI BOSS 智能编排 | OmniRoute 结构化 JSON + Pydantic 契约 + SQLite DAG | 语义判断与硬校验分层，沿用现有模块 | 低；不增加工作流服务 | 当前单用户和最多 20 步计划足够 | 低 | 可按能力目录扩 Worker 与任务类型 |
| 成果与验收 | SQLite 元数据 + Runtime 轻量检查器 + Nomad 验证 Worker | 状态统一，重型依赖与 Runtime 隔离 | 中；需维护版本化检查器镜像 | 轻重检查分流，不阻塞 Runtime | 低至中 | 可按成果类型增加检查器，不修改 SQL 枚举 |
| Console 成果中心 | Vanilla JavaScript + 认证回源 API | 延续现有页面和部署方式 | 低 | 无额外前端运行时 | 低 | 当前规模足够，后续按真实复杂度再评估组件框架 |
| API Gateway 目录 | 显式安全元数据生成的管理员只读目录 | 契约与页面使用同一元数据 | 低 | 只读目录开销可忽略 | 低 | 可随受控接口增加，不暴露原始 OpenAPI |
🔧 AI Boss 系统动作选型
📦 节点安装载荷受控分发选型
RR 的 System Operations Bridge 只承担固定动作的控制面，不得再把 Nomad、metrics 或其他节点安装脚本的文件字节经 SSH/SCP 送往目标节点。该限制不改变 RR 作为生产运行节点的职责，也不把生产 Runtime/Bridge 迁至 101。
| 方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 | 决策 |
|---|---|---|---|---|---|---|
| RR 经 SSH/SCP 下发脚本 | 脚本版本与传输逻辑耦合在 Bridge | 表面低，但违反数据面边界且难审计 | 小文件延迟低 | 已有方式 | 难以安全扩展 | 禁止，待受控迁移替换 |
docs.yohan.fun/scripts 直接下载 |
站点与发布清单、回滚记录脱节 | 中 | 较高 | 低 | 版本、访问和回滚语义不足 | 不采用 |
| Worker 使用 Cloudreve WebDAV 下载 | 会把 WebDAV 凭据扩散到 Worker | 中 | 较高 | 中 | 凭据边界不可接受 | 禁止 |
| Cloudreve 受控共享 HTTPS + 版本清单 + SHA-256 | 复用唯一文件数据面，控制与数据传输分离 | 中 | Worker 直连 Cloudreve，不经 RR/101 转发 | 低至中 | 可增加版本、签名、环境晋级和更多 Worker | 采用，须先完成隔离验收 |
正式链路为：101 提交并协调 GitHub Actions 构建；CI 生成不可变版本号、载荷、SHA-256 和发布清单；经 Cloudreve 受控共享目录提供仅限 https://cloud.yohan.fun/ 的下载地址；RR Bridge 仅向目标节点发送固定动作以及版本、下载 URL、SHA-256 和清单引用；目标节点自行下载、校验并在本机临时目录解包或执行。Worker 不保存 Cloudreve/WebDAV、GitHub、SSH、Docker、Nomad 或 Provider 凭据。此决策仅定义目标架构，当前 SSH/SCP 实现仍在运行，未经隔离验收不得宣称已迁移。
📦 P9 临时远程协助历史选型（已关闭）
| 方案 | 可维护性 | 部署复杂度 | 性能 | 学习成本 | 扩展性 | 决策 |
|---|---|---|---|---|---|---|
| 自建 HTTPS/WSS Gateway | 需维护协议、连接与撤销服务 | 高 | 多一跳 | 中高 | 高 | 不采用 |
| SSH 反向隧道 | 平台差异与入口管理较多 | 中 | 高 | 中 | 中 | 不采用为统一流程 |
| 现有 Headscale/Tailnet + SSH | 复用已有控制面与 SSH 运维方式 | 低 | 高 | 低 | 足够 | 采用 |
| 生产 Tailnet 全网互访 | 信任边界过大 | 低 | 高 | 低 | 高 | 禁止 |
P9 已关闭，不再实施；下表只保留历史候选和边界。若未来重新决策同类能力，仍采用同一 Headscale 控制面下的隔离 tag:temporary-support 和最小 ACL，不把受助设备视为可信 Worker。
🌐 P10 网络入口与恢复选型
| 能力 | 采用方案 | 不采用方案与原因 |
|---|---|---|
| 稳定边缘身份 | 单一稳定域名承载可替换边缘主机 | 不把 MM 主机名或公网 IP 当系统身份 |
| DNS | 当前生产 edge 权威记录只发布静态 A，业务域名使用 CNAME；VPS 公共 AAAA 暂不发布 |
避免未全量双栈时 IPv6 客户端命中失效地址；所有候选具备稳定 IPv6 后再切换 |
| 运行时地址 | root-only 端点快照、受控渲染和 last-known-good | 不在 Nginx、UFW、SSH、DERP 和恢复脚本重复写死 |
| 管理通道 | 公网 SSH 与 Tailnet SSH 显式双通道 | 不让 SSH 自动猜测地址或依赖单一 DERP |
| 节点直连 | Tailscale 直连优先，DERP 只作失败兜底 | 不把 DERP 当常态主路径 |
| 多区域中继 | MM 900、DD 901、d02 902、dog-public 903；每节点独立 Peer Relay 40000/udp | 不使用硬编码公网 IPv4，不用 src:["*"] 放宽 relay grant |
| Exit Node | RR、MM、DD、d02、dog-public 宣告双栈可选出口，Headscale 精确批准，全部节点默认直连；网络态势分开标记“出口能力”和“正在使用” | 不让管理或存储节点成为通用出口，不自动接管默认路由 |
| DNS 切换 | 101 双视角健康检查，连续三次一致失败后只修改 edge A，TTL 600 |
不使用 GTM 或双活 A；RR 不保存 DNS 写凭据 |
| 中继与业务高可用 | DERP/Peer Relay 只恢复 Tailnet，公网 Console 恢复由 Edge DNS 切换负责 | 不把 DERP 或 Peer Relay 当成 Nginx/TLS 高可用替代品 |
| 控制台拓扑 | 现有 Vanilla JavaScript 与 SVG/CSS 聚合只读状态 | 不引入第二图表框架或前端控制面 |
| 高风险回源 | 动态来源控制加服务自身认证 | 不实施 mTLS 和额外证书门禁 |
edge.yohan.fun 是稳定边界身份，不代表任何一台机器的永久身份；edge-mm、edge-d02、edge-dd、edge-dog 是稳定候选，derp-mm、dd、d02、dog 是 DERP region 900 至 903 的稳定域名。mesh.yohan.fun 继续承担核心公网入口和 Headscale 身份，不再承担 region 900；这样 Edge 自动切换不会改变 DERP region 的物理落点。网络态势节点详情展示 Edge 域名和 DERP 域名，圆圈只保留短别名。具体 IPv4、IPv6、网关和健康状态均属于可替换运行时数据。2026-10-11 起，VPS 公网接入统一使用 IPv4；MM 的 IPv6 地址存在 DAD 冲突，所有候选尚未全部具备可靠双栈，因此 edge 不发布 AAAA，控制器在切换和回滚时强制清理 AAAA。P15 已完成单活动切换、切流和回切；P16 已完成 Edge 本地只读回退和 RR 重启演练。公网承载业务大流量，Tailnet 只承载控制面、SSH 和受控小文件，DNS 切换和 DERP 中继不能替代后端能力。
未选择把 Docker Socket、SSH Key、主机根目录或任意 Shell 交给 Runtime：这些方案部署看似直接，但会让模型调用面与 root 执行面强耦合，权限和审计不可控。也未为小型固定动作 Bridge 引入 FastAPI/数据库框架；Python 标准库 HTTP、HMAC 和 SQLite 已满足当前吞吐，依赖与升级面更小。
Bridge 原生 systemd 运行是必要的系统级例外，因为它需要执行固定的 root 服务操作；Runtime、Console 和 Docs 仍保留现有 Docker 形态。后续扩展必须新增明确 Action、固定 Handler、前置检查、后置验证、回滚和测试，不能增加通用命令参数。
🔁 AI BOSS 交互与记忆选型
AI BOSS 的响应是服务端到浏览器的单向增量，现有 FastAPI 与 Vanilla JavaScript 均可直接支持 SSE。相比 WebSocket，SSE 的连接、鉴权、代理和断线恢复更简单；相比 Celery/Redis，SQLite 持久交互队列不增加常驻服务和运维面，当前单用户吞吐足够。若未来真实并发超过 SQLite 写入边界，再依据压测证据升级，不提前引入分布式队列。
长期记忆首版使用 SQLite/FTS5，并显式保存来源、确认状态、版本和数据等级。OmniRoute Memory 的隔离边界尚未成为 AgentMeshOS 的权威契约，向量数据库也会增加部署与调优成本，因此本阶段均不启用。附件原文件使用 Cloudreve 临时空间，SQLite 只保存元数据和引用；这样既避免 BLOB 膨胀，也能保持浏览器和模型不接触 WebDAV 凭据。
🎯 智能编排与成果验收选型
阶段四继续采用 FastAPI、Pydantic、SQLite 和 SSE。AI BOSS 通过现有 OmniRoute Boss Combo 生成严格 JSON 计划与结构化审核，Runtime 使用 Pydantic 和确定性规则验证能力、安全、预算、DAG 与状态。该分层保留 AI 对目标、逻辑能力、依赖和成果语义的判断，同时把权限和真实性边界留在可测试代码中；Runtime 不靠免费模型自行推测业务派工，Nomad 也不承担智能规划。
未选择 Celery/Redis 或 Temporal：它们能提供更完整的分布式队列或工作流能力，但当前单用户、最多 20 个计划步骤和有限并发不需要额外常驻服务，部署、备份、学习和故障恢复成本明显更高。SQLite 事务、持久事件和现有 Runtime 重启恢复已经满足当前规模；只有真实并发和可靠性数据超过边界时再重新选型。
未重写 React/Vue Console：成果中心的列表、详情、筛选和状态控制可以在现有 Vanilla JavaScript 体系内完成，重写会扩大回归和团队学习成本。接口按能力检测，旧 Runtime 不支持时隐藏新区域并展示原因，为以后组件化迁移保留 API 边界。
检查采用“Runtime 轻量检查 + Nomad 验证 Worker”：哈希、MIME、Schema 和小型文件检查留在 Runtime；浏览器链路或 CPU 较重分析进入版本化、无凭据的 Nomad Worker。未把全部重型依赖装入 Runtime 镜像，以免扩大启动、攻击和升级面；验证 Worker 不接受任意 Shell、本地路径、动态依赖或私网访问。成果类型使用可扩展注册 ID，未知类型仍可登记和人工验收，避免 SQL 枚举阻塞扩展。
API Gateway 不承担计划、成果、模型或验收接口。将其升级为统一执行网关会形成第二控制面并增加凭据与状态一致性风险；Console 继续经认证回源代理直达 Runtime。
💾 存储决策
Cloudreve 取代了 KodBox、CSI、JuiceFS、MariaDB Galera 与 MinIO 的组合。原组合层数多、恢复边界复杂，并使用户文件数据面绕经非存储节点；已完整退役。
当前系统云盘访问路径为：客户端到 MM，再到 dd Cloudreve。Tailnet 只服务控制面，不参与文件数据面。Cloudreve 当前为单机 master 与 dd 本地持久化存储，必须明确接受当前单点边界。
Runtime Artifact 不自动复用旧 S3/MinIO：旧后端已删除。Worker 的最大 1 MiB 结构化 JSON 回调证据与任务状态一起写入 Runtime SQLite，具备单机事务、SHA-256 回读校验和现有数据库备份能力；这种方案维护面和部署复杂度最低，适合当前小型回调。较大或长期 Artifact 使用主节点 Runtime 的 Cloudreve WebDAV Adapter，直写 AgentMeshOS-长期/runtime-artifacts；凭据只在 root-only Runtime 环境中，101/102/103 不保存，长期文件不自动删除。
用户既有 Project 不迁入 AgentMeshOS-长期。历史上曾在 RR 使用 rclone mount/rclone sync，该链路现已完全退役，RR 不再保存挂载、同步、缓存或专用凭据。AgentMeshOS 代码权威为 101 /root/project/AgentMeshOS 与 GitHub；RR 仅消费版本化发布载荷。恢复资料使用 Git Bundle、Git Archive 和 SHA-256 清单弥补 WebDAV 不保存 Unix 权限与 Git 历史的限制。
CI/CD 采用 GitHub Actions 作为默认构建、测试、产物固定和发布记录平台，101 负责提交与协调，RR 负责生产部署和运行。该方案维护边界清晰、部署复杂度适中、性能满足当前单用户发布频率，团队无需学习新的工作流系统；后续可增加环境晋级、签名和审批而不改变节点职责。人工应急发布保留为同一版本产物的回退路径，不允许在 RR 工作树临时构建或绕过摘要校验。
🚀 升级原则
OmniRoute 不进行源码改造，升级遵循官方发布节奏。升级前备份其 Provider 配置和运行状态，按官方文档验证升级与回滚；AgentMeshOS 只维护外部集成边界。
官方镜像与原生 npm 安装均使用上游发布物，不构成源码改造。102 当前生产以 root 运行官方 omniroute@3.8.51、系统 Node 22.23.0 与外部 systemd：全局包位于 /usr/local/lib/node_modules/omniroute，正式数据位于官方默认目录 /root/.omniroute。RR omni 数据、包、service、回退备份和 vhost 已在 P13-C 删除；RR 仅保留本机 AI Runtime 使用的私有代理。P13-4 已通过最终快照恢复、公网切换、Boss/Worker、Codex Responses、管理 API、SQLite 和负向鉴权验收；Provider 数据恢复已在 101 隔离环境、RR 生产数据和 102 3.8.51 隔离恢复中通过。AgentMeshOS 只维护外部 systemd、loopback、出口代理与 Runtime 私有代理，不修改包内容，也不维护专用用户、自定义版本软链接或容器兼容目录。
OmniRoute 的允许操作固定为官方控制台配置、官方 CLI/API、官方 npm/Release 对应版本的安装和升级，以及包外 systemd/网络适配。禁止修改上游源码、打补丁、维护私有 Fork 或私有分支、构建私有镜像、重新编译、手工替换已安装包文件或改写构建产物；宿主层适配必须独立记录、可回滚，并不得改变 OmniRoute 包内容。
Runtime 继续使用 Docker，因为其 Python 服务边界、只读根文件系统、固定网络地址和镜像回滚已经成熟。原生 OmniRoute 与 Runtime Docker 之间选择 systemd-socket-proxyd，维护面小、只有 TCP 转发开销且无需额外镜像；不用 sidecar，也不放宽 OmniRoute 的 loopback 监听。该组合比把 Runtime 一并原生化学习成本更低，也比恢复 OmniRoute Docker 网络更符合后续官方升级目标。
AgentRouter 未列入 OmniRoute Provider 时，不把它伪装成 OmniRoute Provider，也不让 Runtime 直接调用其 HTTP。备选方案中，OmniRoute ACP 会引入当前版本尚不成熟的进程/会话完成语义；Runtime 直接启动 CLI 则扩大主进程权限和依赖面。因此选择独立 Docker Gateway：可维护性高于把命令逻辑散入 Runtime，部署复杂度高于直接 HTTP，但能以非 root、只读根文件系统、无宿主机端口和无仓库挂载限制风险。该通道的性能不作为默认路径指标，团队只需维护固定 API 与 CLI 版本；未来扩展必须逐模型完成真实 Smoke，不能开放任意模型或参数。
该模型核心的现行实施计划为 P3-6-2 官方 OmniRoute 模型核心接入。
⚠️ 未决项 / 需要决策
| 事项 | 当前事实 | 下一步 |
|---|---|---|
| 原生 Node 与 OmniRoute | 102 3.8.51 已承接生产，RR omni 数据和回退路径已删除 |
健康观察独立持续运行；后续异常按新运维事件处理 |
| P15 归档 | 三台新 Edge 的证书链、SNI 回源、AliDNS 真实切流、AAAA 删除/恢复和 IPv6 客户端复核均已完成并归档 | 不再重开 P15；边缘漂移按新运维事件处理 |
| P16 控制面备用 | 102 认证快照、只读 Console/API、Edge 回退和 RR 重启演练已完成并归档 | 保持单写权威；不再重开，异常按新运维事件处理 |
| P17 范围 | 复用 MM、RR、Tailnet 和 2S-UI 建设统一入口与独立节点面板；Windows 真机已通过，Android/iOS 待验收 | 剩余真机、回退和发布门禁通过后再归档 |
| 新版本可选能力 | 媒体、语义缓存和日志正文导出未启用 | 按真实收益、权限和稳定性逐项验证，默认保持关闭 |