🚀 AgentMeshOS 部署规范¶

版本：v0.1.0

阶段：基础设施部署阶段

1️⃣ 系统部署结构¶

                🌐 Internet
                     │
                     ▼
            ┌────────────────┐
            │ VPS 主节点     │
            │────────────────│
            │ Tailscale      │
            │ Nomad Server   │
            │ API Gateway    │
            └──────┬─────────┘
                   │
        ┌──────────┼──────────┐
        ▼          ▼          ▼
     Node A     Node B     Node C
   (Worker)   (Worker)   (Worker)
     │           │           │
   Docker     Docker     Docker
   Nomad      Nomad      Nomad

2️⃣ VPS 主节点部署¶

系统要求：¶

Ubuntu 22.04 / 24.04
公网 IP
SSH 访问

安装步骤：¶

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础工具
sudo apt install -y curl unzip git

# 安装 Docker
curl -fsSL https://get.docker.com | sh

3️⃣ 安装 Tailscale（所有节点）¶

基于 Tailscale 客户端 + Headscale 自托管控制面

Tailscale 客户端是节点级网络系统服务，不是普通业务服务；默认不得部署在业务 Docker 容器中。原因是它需要管理节点网络栈、虚拟网卡、路由、DNS、密钥和 NAT 穿透能力。若未来采用容器方式运行 Tailscale，必须先说明网络权限、宿主机影响、安全边界、故障恢复和替代方案，并经项目负责人确认。

Headscale 是本项目默认网络控制面，必须部署在自有服务器并绑定自有域名。节点不得默认连接 Tailscale 官方控制面；任何第三方控制面或远程授权只允许作为临时例外，必须先经项目负责人确认。

curl -fsSL https://tailscale.com/install.sh | sh

# 加入自托管 Headscale 控制面
tailscale up --login-server=https://<headscale-domain>

禁止直接执行无 --login-server 的 tailscale up 作为项目默认部署命令，因为它会连接 Tailscale 官方控制面完成节点注册和授权。允许的 Worker 注册方式只有两种：预授权 auth key 自动接入，或带 --login-server 的手动批准接入；二者都必须指向自托管 Headscale。

作用：¶

建立节点内网
自动 NAT 穿透
统一虚拟网络

4️⃣ 安装 Nomad（主节点）¶

基于 Nomad

# 安装 Nomad
wget https://releases.hashicorp.com/nomad/latest/nomad_*.zip
unzip nomad_*.zip
sudo mv nomad /usr/local/bin/

启动 Server：¶

nomad agent -server -bootstrap-expect=1 -data-dir=/opt/nomad

生产前必须补齐：ACL、TLS / mTLS、服务配置文件、systemd 托管、数据目录备份策略。禁止长期使用裸命令直接前台启动作为正式运行方式。

5️⃣ Worker Node 部署¶

每个 Worker 节点：¶

安装 Docker
安装 Tailscale
安装 Nomad Client

nomad agent -client \
  -data-dir=/opt/nomad \
  -bind=0.0.0.0 \
  -retry-join=

Worker 加入前必须具备节点身份校验、最小权限 Token、受控加入流程；不能把 Tailnet 互通等同于授权完成。

6️⃣ Node 加入机制¶

节点通过 Tailscale 自动发现
Nomad 自动注册 Worker
无需手动配置集群拓扑
自动发现不等于自动信任，节点注册前仍需身份校验与 ACL 授权

7️⃣ 网络模型¶

所有节点统一在 Tailscale 虚拟网络中：

Node IP ≠ Public IP
Node IP = Tailnet IP

8️⃣ 任务执行流程¶

User Request
   ↓
VPS API Gateway
   ↓
Nomad Scheduler
   ↓
Worker Node
   ↓
Docker Container
   ↓
Result Return

9️⃣ 部署原则¶

所有节点必须标准化安装流程
禁止手动修改运行环境
所有部署服务、控制面、调度面、网络协调面、存储服务和运行时服务，默认必须部署在项目自有服务器或自有节点上
第三方托管平台不得作为核心部署能力的默认依赖；如需临时使用，必须说明原因、期限、数据边界、回滚方案和自托管迁移路径，并经项目负责人确认
默认优先使用 Docker 部署可容器化组件；只要组件具备 Docker 部署条件，就必须使用 Docker 承载
正式部署服务端口必须统一使用 39000 到 39999 范围内的非常用端口；该规则用于端口治理和冲突隔离，不得替代 TLS、认证、ACL、防火墙和最小暴露等安全措施
公网入口原则上只开放 80 / 443 给 Nginx 或等价反向代理；后端服务应优先只监听 127.0.0.1 或私有网络地址
禁止使用 8080、3000、5000 等常见开发端口作为正式服务后端端口
Docker 端口映射必须保持主机端口与容器端口一致，例如 39088:39088；禁止用主机端口映射到不同容器端口制造隐性转换
无法部署在 Docker 中的组件，必须说明原因、影响范围、替代运行方式、回滚方案和后续迁移可能性，并在执行前与项目负责人确认
系统级基础组件可采用标准进程化部署，但必须明确标记为 Docker 例外，并纳入 systemd、配置文件、日志、备份和安全基线管理
Nginx 统一使用宝塔面板自带版本 /www/server/nginx/sbin/nginx；严禁通过 Ubuntu apt 安装或启用系统自带 Nginx，避免与宝塔 Nginx 抢占 80 / 443
如发现 Ubuntu 系统 Nginx 已安装，必须停止、禁用并清理，仅保留宝塔 Nginx 作为公网反向代理入口
涉及控制面的组件，必须优先采用自托管方案；存在第三方账号、外部控制台或远程授权时，必须按临时例外处理
节点加入必须自动化
控制面必须具备快照、配置备份、重建演练能力

文档站同步规则（强制）¶

项目文档站是仓库 docs/ 目录的静态发布结果，docs/ 才是唯一文档源头。禁止直接修改文档站容器、构建产物或 temp/docs-site-build/ 中的 HTML 来绕过源文档。

同步关系：

docs/                            -> 文档源文件
tools/docs-site/config/mkdocs.yml -> 文档站导航、主题和构建配置
scripts/                         -> 脚本源文件
tools/docs-site/docker/Dockerfile -> 把 docs/ 与 scripts/ 打包进文档站镜像
GitHub Actions                   -> 远程构建并推送文档站 Docker 镜像
docs.yohan.fun                   -> 宝塔 Nginx 反代文档站容器

执行要求：

修改 docs/**、tools/docs-site/**、scripts/clients/** 或 scripts/deploy/docs-site/** 后，必须触发文档站 GitHub Actions 远程构建。
文档站构建必须执行 MkDocs strict 构建检查，确保导航中文件存在、Markdown 可解析、链接结构可生成。
脚本库页面 docs/脚本库.md 必须与 scripts/ 源文件同步维护，脚本新增、删除、改名、版本变化或下载路径变化时必须同步更新。
文档站 Dockerfile 必须从仓库源文件复制脚本到站点 /scripts/ 下载目录，确保网页下载文件与仓库版本一致。
本地只允许进行语法、Markdown、MkDocs 和脚本检查；禁止在本机编译生产 Docker 镜像。
脚本和文档站的自动同步由 GitHub Actions 负责；凡是 docs/**、tools/docs-site/**、scripts/clients/** 或 scripts/deploy/docs-site/** 发生变更，推送后必须触发远程镜像构建。
远程镜像构建完成后，主节点通过文档站 Docker 菜单脚本拉取最新镜像并重启容器，完成线上同步。

9.1️⃣ 公网域名规划¶

AgentMeshOS 的公网域名必须统一规划，禁止每部署一个服务就临时创建一个无体系的域名。域名应按系统边界和安全边界划分，而不是按单个容器、单个端口或单个软件名称划分。

当前公网主节点 IP：

96.44.133.235

建议一次性准备并解析以下域名到主节点公网 IP，并预先按固定端口建立宝塔 Nginx 反向代理。后端服务未部署前，反代可先保留为未启用或返回维护页；服务部署完成后，只需验证本机端口、域名证书和公网访问即可。

域名	路径	后端监听地址	用途	当前状态
`www.yohan.fun`	`/`	`127.0.0.1:39100`	项目官网、对外介绍页或默认落地页	待公开，当前私人项目阶段不启用
`mesh.yohan.fun`	`/`	`302 -> /admin/`	人工访问入口，默认跳转 Headplane 管理后台	当前优先使用
`mesh.yohan.fun`	Headscale 协议路径	`127.0.0.1:39088`	Headscale 控制面，供 Tailscale 客户端和健康检查使用	当前优先使用
`mesh.yohan.fun`	`/admin/`	`127.0.0.1:39089`	Headplane 管理后台	当前优先使用
`console.yohan.fun`	`/`	`127.0.0.1:39110`	统一管理控制台，承载后续项目后台 Web	预留
`api.yohan.fun`	`/`	`127.0.0.1:39120`	对外 API 网关入口	预留
`docs.yohan.fun`	`/`	`127.0.0.1:39130`	项目文档站点	预留
`status.yohan.fun`	`/`	`127.0.0.1:39140`	状态页、监控展示或可用性页面	预留
`auth.yohan.fun`	`/`	`127.0.0.1:39150`	统一认证入口，如后续引入 SSO / OAuth	预留

当前节点网络服务映射规则：

https://mesh.yohan.fun/        -> 302 跳转到 /admin/
https://mesh.yohan.fun/admin/  -> Headplane 管理后台
https://mesh.yohan.fun/health  -> Headscale 健康检查
Headscale 协议路径             -> Headscale 控制面

mesh.yohan.fun/admin/ 是同一公网域名下的内部路径反向代理，不需要也不得把 39089 作为公网端口直接暴露。宝塔 Nginx 只监听公网 80 / 443，再按路径转发：

location = /       -> 302 /admin/
location ^~ /admin/ -> http://127.0.0.1:39089
location ^~ /       -> http://127.0.0.1:39088

一级域名 yohan.fun 不作为业务服务入口；如后续需要使用，只允许作为 DNS 根域、证书管理对象或跳转到 www.yohan.fun 的入口，不承载具体后端服务。www.yohan.fun 属于公开展示入口，当前项目仍为私人项目阶段，暂不配置 DNS、证书和反向代理；只有进入公开阶段后才启用。

固定端口登记规则¶

39000 到 39099：基础设施和集群控制面端口段。
39100 到 39199：公网 Web、API、文档、状态页和认证入口端口段。
39200 到 39999：后续业务服务、内部工具、实验服务和扩展模块预留端口段。
已登记端口不得复用；新增服务必须先更新本表或对应架构文档，再部署服务和配置反向代理。
同一公网域名下的不同路径可以反代到不同后端端口，但必须属于同一安全边界或强相关功能。

执行规则：

所有上述域名可提前解析到 96.44.133.235，但服务正式启用前必须先验证 DNS、证书、反向代理和后端健康检查。
强相关服务可以放在同一子域名下用路径区分，例如 mesh.yohan.fun/ 和 mesh.yohan.fun/admin/。
不同安全边界必须拆分子域名，例如网络控制面、项目后台、API 网关、文档站、状态页和认证入口不得混用同一个业务域名。
禁止使用具体软件名作为长期公网域名，例如 headscale.yohan.fun 只可作为临时测试域名，不作为正式规划域名。
宝塔 Nginx 是唯一公网入口；后端服务继续使用 127.0.0.1 或私有网络地址监听，并使用 39000 到 39999 范围内端口。
宝塔反向代理可提前按本表配置，但正式切流前必须确认目标服务已启动、端口监听正确、健康检查通过，并确认没有把未认证内部管理面直接暴露到公网。

9.5️⃣ 部署安全最小基线¶

Nomad Server / Client 必须启用 ACL
控制面与节点通信必须启用 TLS，优先 mTLS
Headscale 必须启用 HTTPS、自有域名、受控节点注册、配置备份和数据恢复方案
Tailscale 节点必须通过自托管 Headscale 使用受控 auth key、tag 或策略文件加入
API Gateway 必须置于认证层之后，禁止裸暴露内部控制接口
所有关键配置必须可备份、可恢复、可轮换

9.6️⃣ MVP 执行路径¶

v0.1 MVP 只验证最小闭环：一个 VPS 控制节点、一个 Worker 节点、Tailscale 网络、Nomad 调度和 Docker 执行。

前置条件¶

一台 Ubuntu 22.04 / 24.04 VPS，并具备 SSH 访问权限。
一台 Ubuntu / Debian Worker 节点。
已准备 Headscale 自托管控制面域名、TLS 证书方案与受控节点加入方式。
不得把生产 Secret、Token、Auth Key 写入仓库或 shell 历史。

VPS 控制节点¶

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl unzip git ca-certificates
curl -fsSL https://get.docker.com | sh
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up --login-server=https://<headscale-domain>

VPS 控制节点接入网络前，必须先确认 Headscale 控制面已部署完成；禁止使用 Tailscale 官方登录链接作为默认上线步骤。

Nomad 安装后必须使用配置文件或 systemd 托管，裸命令仅允许用于临时验证。

Worker 节点¶

安装 Docker、Tailscale、Nomad Client。
加入同一个 Tailnet。
使用 VPS 的 Tailnet IP 配置 Nomad Client 的 retry-join。
加入前必须完成节点身份校验和最小权限 Token 配置。

集群验证¶

nomad server members
nomad node status

预期结果：

一个 Nomad Server 处于可用状态。
至少一个 Worker 节点处于 ready 状态。

第一个任务验证¶

第一个任务应使用最小 Docker 镜像执行 hello 级别冒烟测试，验证 Nomad 能调度任务、Worker 能运行容器、日志可观察、结果可回收。

MVP 验收清单：

VPS 已加入 Tailscale。
Worker 已加入 Tailscale。
Nomad Server 正常运行。
Nomad Client 成功加入 Server。
Docker 任务成功执行。
生产前安全基线缺口已记录。

🔟 当前部署状态（v0.1）¶

VPS 主节点：未部署
Worker 节点：未加入
Nomad 集群：未初始化
Tailscale 网络：未组网

🚀 下一步¶

下一份文档：

08_AI协作规范.md

ChatGPT / Codex / Claude 分工
AI 如何协作开发系统
任务分发机制
Agent 运行规范