本文件用于固定 docs.zhenrobot.com 的发布链、验证方式与回滚思路，避免“本地改了但线上没更新 / 线上看起来像回滚”这类问题反复出现。
提示一条建议
发布后先用 curl 验证线上 HTML 是否包含最新内容，再打开浏览器确认视觉效果（避免缓存误判）。
1. 本站是什么
- 这是一个 静态协议文档站（Docusaurus 构建产物）。
- 站点内容用于解释接入路径、字段形态、边界与上线检查；不在这里承诺未公开的能力与开放范围。
2. 关键目录
- 源码仓库（可版本控制）：
/home/openclaw/docs.zhenrobot.com - 线上静态站根目录（nginx 直接服务）：
/www/wwwroot/docs.zhenrobot.com/build
3. 标准发布流程（推荐）
在源码仓库执行：
cd /home/openclaw/docs.zhenrobot.com
npm run build
npm run verify:public
sudo rsync -a build/ /www/wwwroot/docs.zhenrobot.com/build/
说明：
npm run verify:public会检查关键页面是否存在，以及首页/页面 intro 关键文案是否渲染成功。- nginx root 指向
build/目录（线上服务的是构建产物，而不是源码目录）。
4. 发布后如何确认
优先用命令行确认 HTML 是否包含最新内容（避免浏览器缓存误判）：
curl -sS https://docs.zhenrobot.com/protocols/c2ai2x/widget-embed/ | head
如本次发布涉及 Widget 或 Console 入口，可额外执行一次外部入口健康检查：
npm run check:external-entry-health
该检查只发起无认证的 GET 请求，不创建渠道、不访问项目数据，也不纳入构建门禁。它会确认 Console 起始页、Provider 入口、Widget 运行时、/integrations 的登录跳转与认证入口仍可访问。
5. API 网关定时监测
生产机通过 zhen-api-gateway-health.timer 每 15 分钟运行一次同一检查，覆盖 API 健康入口、OpenAPI、HTTP→HTTPS、HSTS、受控接口边界与证书剩余有效期。
sudo systemctl status zhen-api-gateway-health.timer
sudo journalctl -u zhen-api-gateway-health.service -n 50 --no-pager
受控单元定义保存在 ops/systemd/。修改后先执行 sudo systemctl daemon-reload，再重启 timer。
如果看到的不是最新页面，优先排查：
- 是否把
build/同步到了/www/wwwroot/docs.zhenrobot.com/build - nginx root 是否仍指向源码目录（会导致 403 或页面不更新）
- CDN / 浏览器缓存（本站已对 HTML 做了 no-cache，但仍建议用 curl 验证）
6. 回滚思路
本站以 Git 提交作为回滚来源：
cd /home/openclaw/docs.zhenrobot.com
git log --oneline --max-count=20
git checkout <commit>
npm run build && npm run verify:public
sudo rsync -a build/ /www/wwwroot/docs.zhenrobot.com/build/
回滚完成后再切回主分支继续迭代：
git checkout main
7. 变更时必须同步更新本文件
- 发布链（构建命令、同步目标目录、nginx root）发生变化
- 验证脚本（
scripts/verify-public-docs.sh）新增或收紧关键检查项 - 文档的对外入口路径发生变化（例如 sidebar 结构调整）
推荐阅读