文档站构建、发布与更新

本机开发

在仓库根目录切换到文档工程，使用 Node.js 22 或以上版本：

cd docs
npm ci
npm start

默认地址为 http://127.0.0.1:3200/。站点仅监听本机，start 与 serve 使用同一端口，运行其中一个即可。

发布前构建

npm run check:docs
npm run build
npm run serve

完整性检查核对确认菜单、正文、来源和内部链接；Docusaurus 继续检查路由、MDX 和构建。使用构建预览检查三类菜单、中文搜索结果跳转、Mermaid 和代码预览，再看桌面及移动端截图。

正式托管准备

文档站地址为 https://zhoujiyouqiu.docs.duoge.work，部署在项目交付的 Rancher local 集群 mcms 命名空间。静态构建通过独立 Nginx 容器发布；源码目录与 governance/ 不在公开发布集合中。

构建时使用本站实际 DOCS_URL，镜像推送后固定摘要，先部署服务并验证 HTTP，再配置 DNS 和本站独立 SSL。具体清单、更新与回退入口见仓库 docs/deployment/README.md。

当前站点没有登录和权限域隔离；content/、static/ 及搜索索引属于同一发布集合。noindex 不能代替认证，部署公开内容前需逐项检查敏感信息与资产来源。

更新与回退

保存源码和 lockfile，记录构建版本与校验结果；部署后核对真实页面和索引，缓存策略需能刷新 HTML 与对应资源。回退使用完整的旧构建集合，不混用旧 HTML 和新资源。本站使用确定镜像摘要滚动更新，TLS Secret 由现有 Certbot DNS-01 续期机制同步，不随每次正文发布重新签发。