⚙️ AgentMeshOS 技术选型说明¶

版本：v0.1.0

阶段：工程技术决策阶段

1️⃣ 设计原则¶

优先成熟稳定技术
优先生态完善方案
优先可扩展架构
避免过度自研
允许未来替换，但必须接口化
所有可部署服务和控制面默认必须自托管在项目自有服务器上，不以第三方托管控制台作为长期默认方案

2️⃣ 网络层：Tailscale¶

选型：Tailscale 客户端 + Headscale 自托管控制面

部署边界：¶

tailscaled 属于节点级网络系统服务，需要管理虚拟网卡、路由、DNS、NAT 穿透和节点密钥，不作为普通业务容器运行。
Tailscale 客户端可安装在本机节点；节点注册、ACL 和设备协调默认必须接入自托管 Headscale 控制面。
Headscale 必须使用自有域名、自有服务器、可备份配置和可恢复数据目录承载。
Tailscale 官方控制面不得作为默认实施路径；如需临时使用，必须先说明原因、期限、数据边界、迁移方案和回滚方案，并经项目负责人确认。

为什么选择它：¶

自动 NAT 穿透
无需复杂 WireGuard 手动配置
节点自动发现
支持动态节点加入/退出
Headscale 可自托管控制面，避免核心网络控制权依赖第三方托管平台

替代方案：¶

WireGuard（手动配置复杂）
ZeroTier（稳定性略低）
Tailscale 官方控制面（运维简单但依赖第三方托管，不作为默认方案）

3️⃣ 调度层：Nomad¶

选型：Nomad

为什么选择它：¶

轻量级调度系统
比 Kubernetes 更简单
支持多驱动（Docker / Exec）
适合中小规模集群

替代方案：¶

Kubernetes（过重）
Docker Swarm（已弱化）

4️⃣ 执行层：Docker¶

为什么选择 Docker：¶

生态最成熟
跨平台一致性强
Nomad 原生支持
易于部署 AI / 服务 / Agent

替代方案：¶

containerd（复杂度更高）
LXC（隔离能力弱）

5️⃣ 存储层：S3 标准¶

选型：¶

S3 Compatible API（对象数据统一接口）

为什么选择 S3：¶

行业标准接口
可替换实现（MinIO / Ceph / AWS S3）
AI 训练 / 文件 / 状态存储统一模型

原则：¶

禁止绑定单一存储实现
对象数据通过 S3 接口暴露；控制面元数据允许使用独立 Metadata Store，但不得向业务模块暴露直连能力

6️⃣ 控制节点：VPS¶

为什么 VPS：¶

公网固定入口
稳定控制面
易于部署 Nomad Server

原则：¶

控制层必须独立于计算节点
v0.1 固定单主控制节点，但必须具备备份、快照、重建与迁移预案
公网服务必须纳入统一域名体系，不得每部署一个服务就临时新增无规划域名
域名按系统边界划分，优先使用 mesh、console、api、docs、status、auth 等稳定子域名
所有公网域名默认解析到主节点公网 IP，由宝塔 Nginx 作为唯一公网入口，再按域名和路径反向代理到本机后端服务
公网域名和后端端口必须在 07_部署规范.md 的固定端口登记表中预先登记；部署服务前不得临时占用未登记端口

6.5️⃣ 为什么暂不引入多主控制面？¶

当前阶段优先降低部署复杂度，先验证单主控制面能稳定调度
个人/小团队资源有限，多主高可用会显著增加学习和运维成本
通过快照、配置备份、自动化重建先覆盖 v0.1 容灾需求

7️⃣ 操作系统：Linux¶

Ubuntu Server 优先
Debian 可作为替代

原则：¶

禁止 Windows 作为 Worker Node（生产环境）

8️⃣ 为什么不选 Kubernetes？¶

过度复杂（Control Plane 太重）
学习成本高
不适合个人/轻量 AI Mesh
维护成本过高

9️⃣ 为什么不自研调度系统？¶

调度系统复杂度极高
Nomad 已成熟稳定
避免重复造轮子

9.5️⃣ v0.1 技术决策记录¶

当前阶段的技术决策直接写入本技术选型文档，不单独新增 ADR 文件。

决策一：选择 Nomad 而不是 Kubernetes¶

原因：v0.1 目标是先跑通个人级资源池，Kubernetes 控制面过重，学习和维护成本高。
影响：Nomad 负责任务放置、节点调度、资源管理和生命周期管理。
重新评估条件：v1.0 后如果必须依赖 Kubernetes 生态或复杂多租户能力，再重新评估。

决策二：选择 Tailscale 作为私有网络¶

原因：节点可能分布在 VPS、家庭网络和本地机器后方，需要 NAT 穿透和动态加入。
影响：Tailscale 客户端负责节点互联、Tailnet IP 和接入简化，Headscale 负责自托管控制面、节点注册和网络协调。
安全边界：Tailnet 可达不等于已授权，内部 API 和节点注册仍必须认证。
自托管边界：默认禁止依赖 Tailscale 官方控制面；临时例外必须记录原因、期限和迁移路径。

决策三：S3 + Metadata Store 状态模型¶

原因：S3 适合对象数据，但任务、节点、租约、心跳、Token、审计事件和 AI 记忆索引需要结构化元数据。
影响：对象数据走 S3 Compatible API；控制面元数据允许进入 Metadata Store。
边界：Metadata Store 是控制面内部实现，Compute、Agent、Worker 不得直接访问。

🔟 技术替换原则¶

任何技术替换必须满足：

1. 不破坏模块边界
2. 提供兼容接口
3. 不影响 Scheduler
4. 不影响 AI Core
5. 必须通过 ADR 记录

📌 当前技术栈总结¶

Network   → Tailscale Client + Headscale
Scheduler → Nomad
Compute   → Docker
Storage   → S3 (MinIO)
OS        → Linux (Ubuntu / Debian)
Control   → VPS

🚀 下一步¶

下一份文档：

06_工程规范.md

代码规范
目录规范
命名规范
模块规范
Agent 编码规范