aun-doc 工程交接文档

本文档面向接手 aun-doc 的工程师，目标是让接手者能快速理解项目定位、本地开发、文档同步、线上部署、验证方式和常见排障路径。

本文档不记录真实密钥值。涉及服务器、Token、Webhook、SSH 权限等敏感内容时，只记录变量名、用途、路径和验证方式。

1. 项目定位

aun-doc 是 AUN（Agent Union Network）协议文档站，基于 VitePress 构建。

AUN 定义 Agent 之间安全通信的标准接口，核心内容包括：

身份与凭证协议。
证书与信任体系。
Gateway / Peer / Relay / Group / Storage / Stream 等子协议。
服务调用、错误码、状态机和安全考虑。
SDK 接入说明和最佳实践。
面向 LLM/Agent 阅读的 llms.txt、llms-small.txt、llms-full.txt。

接手时不要把它当成普通静态 Markdown 站点。协议与 SDK 内容的源头在 aun-sdk-core，本项目通过 scripts/sync-docs.mjs 同步、改写链接、生成站点结构，再由 VitePress 构建发布。

2. 技术栈与运行方式

文档框架：VitePress。
运行时：Node.js。
包管理：项目规范要求使用 pnpm。
主要语言：Markdown、TypeScript、JavaScript、Shell。
线上静态服务：nginx:1.27-alpine。
线上构建：Docker Compose 的 builder 服务，受 CPU、内存和 pids 限制。
线上定时同步：Docker Compose 的 syncer 服务。

常用本地命令：

bash

pnpm install
pnpm docs:dev
pnpm docs:build
pnpm docs:preview

质量检查与打包命令：

bash

node scripts/check-site-quality.mjs
pnpm docs:build
pnpm deploy:pack

pnpm deploy:pack 会生成源码部署包：

text

/tmp/aun-doc-deploy.tgz

3. 必读规范

接手后先读这些文件：

.claude/CLAUDE.md：本项目部署规范和线上约束。
README.md：项目结构、本地命令和 Docker 部署概览。
docs/.vitepress/config.ts：导航、侧边栏、站点元信息和 sitemap 配置。
scripts/sync-docs.mjs：从 aun-sdk-core 同步协议与 SDK 文档的核心逻辑。
scripts/check-site-quality.mjs：站点质量守卫。
docker-compose.yml：线上 builder、syncer、nginx 服务形态。
nginx.conf：静态站点、健康检查和缓存规则。

执行约束：

使用简体中文沟通、提交说明和文档记录。
JavaScript / TypeScript 命令使用 pnpm。
浏览器自动化测试使用 chrome-devtools MCP。
连接或操作命名服务器使用 SSH skill / octssh，不要裸 ssh/scp。
不要使用宿主机 80 端口，本服务固定映射 8081:80。
不要恢复 Traefik，本项目只负责 VitePress 静态站点容器。
生产禁止直接 docker compose up -d --build，避免绕过 builder 资源限制。
服务器部署包是源码包，不包含 docs/.vitepress/dist。
如果工作区存在无关改动，不要擅自回滚。

4. 目录速览

text

aun-doc/
├── docs/
│   ├── guide/              # 入门、快速开始、核心概念、FAQ
│   ├── protocol/           # AUN 协议规范
│   ├── sdk/                # SDK 文档
│   ├── public/             # logo、favicon、robots、llms 等静态文件
│   └── .vitepress/         # VitePress 配置和主题
├── scripts/
│   ├── sync-docs.mjs       # 从 aun-sdk-core 同步文档
│   ├── check-site-quality.mjs
│   ├── generate-changelog.mjs
│   ├── package-deploy.sh   # 生成源码部署包
│   ├── build-on-server.sh  # 远端 builder 内执行同步和构建
│   ├── auto-sync.sh        # syncer 单次同步逻辑
│   ├── auto-sync-loop.sh   # syncer 循环入口
│   └── publish-dist.sh     # 发布 dist 到站点卷
├── docker-compose.yml
├── nginx.conf
├── Dockerfile
├── package.json
└── README.md

5. 文档同步链路

协议和 SDK 文档源文件维护在同级目录的 aun-sdk-core 仓库。

本地推荐目录结构：

text

/Users/axin/git/molian/
├── aun-doc/
└── aun-sdk-core/

同步命令：

bash

pnpm sync:docs

同步逻辑由 scripts/sync-docs.mjs 控制：

PROTOCOL_MAP 把上游协议文件名映射为站点路由文件名。
SDK_MAP 把上游 SDK 文件名映射为站点路由文件名。
同步会覆盖 docs/protocol/ 和 docs/sdk/ 下的生成内容。
脚本会检查未映射文档，避免上游新增文件没有进入站点。
内部链接会被改写为 VitePress 路由。

重要风险：

不要只手改 docs/protocol/index.md 来修复导航。远端 builder 和 syncer 会先跑 sync-docs.mjs，手改内容可能被同步覆盖。
上游新增协议文档时，要同步更新 mapping、sidebar 和质量检查。
链接修复后要跑 scripts/check-site-quality.mjs，避免旧 .md 链接进入线上。

6. 质量检查

本地至少执行：

bash

node scripts/check-site-quality.mjs
pnpm docs:build
pnpm deploy:pack

合格标准：

check-site-quality.mjs 退出码为 0。
pnpm docs:build 退出码为 0。
构建产物存在 docs/.vitepress/dist/index.html。
构建产物存在 docs/.vitepress/dist/sitemap.xml。
部署包存在 /tmp/aun-doc-deploy.tgz。
站点内链、标题层级、logo、robots、llms、sitemap 等检查通过。

VitePress 大 chunk warning 和 Rollup PURE annotation warning 在当前项目里通常不是致命错误，但不能掩盖构建失败。

7. 线上部署现状

服务器与路径：

服务器别名：mg-home
服务器 IP：47.83.210.194
线上目录：/root/aun-doc
部署包路径：/root/aun-doc-deploy.tgz
线上域名：https://agentunionnetwork.com/
线上备用域名：https://www.agentunionnetwork.com/
宿主机端口：8081
容器端口：80

线上访问入口：

text

主入口：https://agentunionnetwork.com/
www 入口：https://www.agentunionnetwork.com/
本机健康检查：http://127.0.0.1:8081/healthz

反向代理配置在 mg-home 服务器的 1Panel/OpenResty 配置里，只读核实到的路径如下：

text

/opt/1panel/www/conf.d/agentunionnetwork.com.conf
/opt/1panel/www/sites/agentunionnetwork.com/proxy/root.conf

当前代理关系：

agentunionnetwork.com 和 www.agentunionnetwork.com 同一个 server block。
HTTP 请求会 301 到 HTTPS。
HTTPS server include /www/sites/agentunionnetwork.com/proxy/*.conf。
root.conf 里 location ^~ / 代理到 http://127.0.0.1:8081。
8081 对应本项目 aun-doc 容器的 8081:80 映射。

注意：本项目交接只记录线上访问入口和反向代理位置。不要在本仓库内维护或修改服务器上的 1Panel/OpenResty 配置；排障时先确认 127.0.0.1:8081 本机服务正常，再判断入口层问题。

线上容器：

aun-doc：nginx:1.27-alpine，对外提供静态站点。
aun-doc-syncer：node:20-alpine，定时同步 aun-sdk-core 并重建发布。
builder：只在部署或手动构建时运行，默认不常驻。

当前核实过的线上形态：

/root/aun-doc 不是 Git 工作区，这是当前设计。
线上发布目录通过源码包切换，不在服务器上 git pull 部署。
aun-doc 容器映射 0.0.0.0:8081->80/tcp。
http://127.0.0.1:8081/healthz 返回 ok。
http://127.0.0.1:8081/ 返回 200。
syncer 周期为 21600 秒，日志里会显示是否发现上游变更。

8. 标准部署流程

本项目部署不是服务器 git pull，而是本地生成源码包后上传到服务器。

8.1 本地准备

在本地仓库执行：

bash

git status --short
node scripts/check-site-quality.mjs
pnpm docs:build
pnpm deploy:pack
ls -lh /tmp/aun-doc-deploy.tgz

如果 git status 里有无关用户改动，不要回滚；只确认部署包包含需要发布的内容。

8.2 上传部署包

优先使用 SSH skill / octssh 上传：

text

machine: mg-home
localPath: /tmp/aun-doc-deploy.tgz
remotePath: /root/aun-doc-deploy.tgz

8.3 远端构建与切换

在 mg-home 执行：

bash

cd /root
ts="$(date +%Y%m%d%H%M%S)"
next="/root/aun-doc.next.$ts"
backup="/root/aun-doc.backup.$ts"
mkdir -p "$next"
tar -xzf /root/aun-doc-deploy.tgz -C "$next"
cd "$next"
docker compose --profile build run --rm builder
test -f docs/.vitepress/dist/index.html
test -f docs/.vitepress/dist/sitemap.xml
cd /root
if [ -d /root/aun-doc ]; then mv /root/aun-doc "$backup"; fi
mv "$next" /root/aun-doc
cd /root/aun-doc
docker compose up -d
docker compose ps
find . -name '._*' | wc -l

部署合格标准：

builder 在资源限制内构建成功。
docs/.vitepress/dist/index.html 存在。
docs/.vitepress/dist/sitemap.xml 存在。
docker compose up -d 成功。
docker compose ps 显示 aun-doc 和 aun-doc-syncer 均为 Up。
端口为 0.0.0.0:8081->80/tcp。
macOS 资源叉文件数量为 0。

9. 部署后验证

服务器侧验证：

bash

cd /root/aun-doc
docker compose ps
docker compose logs --tail=80 aun-doc
docker compose logs --tail=80 syncer
curl -i http://127.0.0.1:8081/healthz
curl -I http://127.0.0.1:8081/
curl -I https://agentunionnetwork.com/
curl -I https://www.agentunionnetwork.com/
curl -I http://127.0.0.1:8081/robots.txt
curl -I http://127.0.0.1:8081/llms.txt
curl -I http://127.0.0.1:8081/sitemap.xml

浏览器侧验证：

使用 Chrome DevTools MCP 打开 https://agentunionnetwork.com/。
检查首页、协议页、SDK 页、FAQ。
对 https://agentunionnetwork.com/protocol/ 跑站内主要链接检查。
控制台不能有明显 error。
有条件时跑 Lighthouse mobile/navigation。

验收重点：

robots.txt、llms.txt、sitemap.xml 不能被 fallback 到首页 HTML。
协议总览里的主文档链接必须全部能打开。
新增协议文档不能只出现在上游仓库，要通过 sync mapping 进入站点。

10. 回滚流程

仅当新部署失败且无法快速修复时回滚。

先查看备份：

bash

ls -dt /root/aun-doc.backup.* | head

确认目标备份后执行：

bash

cd /root
failed="/root/aun-doc.failed.$(date +%Y%m%d%H%M%S)"
mv /root/aun-doc "$failed"
mv /root/aun-doc.backup.YYYYMMDDHHMMSS /root/aun-doc
cd /root/aun-doc
docker compose up -d
docker compose ps
curl -i http://127.0.0.1:8081/healthz

把 YYYYMMDDHHMMSS 替换为实际备份目录时间戳。

11. 常见故障

11.1 线上链接返回首页

常见原因：

文档里还有旧文件名 .md 链接。
VitePress 路由文件没有生成。
sync-docs.mjs 的 mapping 缺少上游新增文件。

处理：

bash

rg "\\.md\\)" docs scripts
node scripts/check-site-quality.mjs
pnpm docs:build

如果是上游新增文件，补 PROTOCOL_MAP 或 SDK_MAP，再补 sidebar 和质量检查。

11.2 `robots.txt` / `llms.txt` / `sitemap.xml` 返回首页

说明静态文件缺失或构建没有生成目标文件。

处理：

确认 docs/public/robots.txt、docs/public/llms.txt 存在。
确认 docs/.vitepress/config.ts 配置了 sitemap hostname。
重新执行 pnpm docs:build。
检查 docs/.vitepress/dist/sitemap.xml。
重新部署。

11.3 远端 builder 看起来卡住

mg-home 资源有限，VitePress build 在 building client + server bundles... 停几分钟可能正常。

处理：

bash

docker stats
docker ps --filter name=builder
docker logs --tail=80 <builder-container>

不要在没有确认 CPU/内存/日志状态前误判为 hang。

11.4 端口冲突

不要改成宿主机 80。本项目固定 8081:80，入口层由 mg-home 上的 1Panel/OpenResty 代理到 127.0.0.1:8081。本仓库只记录入口关系，不维护入口配置。

11.5 syncer 不更新

检查：

bash

cd /root/aun-doc
docker compose logs --tail=120 syncer
docker compose exec syncer sh -lc 'ls -la /app/aun-sdk-core | head'

重点看：

上游是否有新 commit。
aun-sdk-core 是否能正常 clone/fetch。
check-site-quality.mjs 是否失败。
builder 是否因为资源限制退出。

12. 敏感数据与风险边界

不要提交 SSH Key、Token、Webhook URL。
不要把真实服务器凭据写进文档。
不要把 node_modules、.git、构建缓存、macOS 资源叉文件打包上传。
不要在生产服务器直接运行无限制构建命令。
不要删除 /root/aun-doc.backup.*，除非已经明确确认。
不要把本项目的反向代理问题和静态站点容器问题混在一起排查；先测 127.0.0.1:8081，再测 https://agentunionnetwork.com/。

13. 接手建议流程

读 .claude/CLAUDE.md、README.md、本交接文档。
本地跑 pnpm install、node scripts/check-site-quality.mjs、pnpm docs:build。
理解 sync-docs.mjs 的 mapping、sidebar 和质量检查之间的关系。
用 SSH skill 只读检查 mg-home 的 /root/aun-doc、容器和健康检查。
修改文档时先判断内容源头在 aun-doc 还是 aun-sdk-core。
发布前打源码包，远端用受限 builder 构建。
发布后做服务器侧 curl、浏览器侧页面和链接验证。

aun-doc 工程交接文档 ​

1. 项目定位 ​

2. 技术栈与运行方式 ​

3. 必读规范 ​

4. 目录速览 ​

5. 文档同步链路 ​

6. 质量检查 ​

7. 线上部署现状 ​

8. 标准部署流程 ​

8.1 本地准备 ​

8.2 上传部署包 ​

8.3 远端构建与切换 ​

9. 部署后验证 ​

10. 回滚流程 ​

11. 常见故障 ​

11.1 线上链接返回首页 ​

11.2 robots.txt / llms.txt / sitemap.xml 返回首页 ​

11.3 远端 builder 看起来卡住 ​

11.4 端口冲突 ​

11.5 syncer 不更新 ​

12. 敏感数据与风险边界 ​

13. 接手建议流程 ​

aun-doc 工程交接文档

1. 项目定位

2. 技术栈与运行方式

3. 必读规范

4. 目录速览

5. 文档同步链路

6. 质量检查

7. 线上部署现状

8. 标准部署流程

8.1 本地准备

8.2 上传部署包

8.3 远端构建与切换

9. 部署后验证

10. 回滚流程

11. 常见故障

11.1 线上链接返回首页

11.2 `robots.txt` / `llms.txt` / `sitemap.xml` 返回首页

11.3 远端 builder 看起来卡住

11.4 端口冲突

11.5 syncer 不更新

12. 敏感数据与风险边界

13. 接手建议流程