运行手册

本地文档检查

./scripts/docs-check.sh

发布原则

1. 完成代码与文档更新。
2. 运行项目测试和文档检查。
3. 提交并推送到私有 Git 仓库。
4. 由服务器拉取已提交版本并构建 Quartz。

线上文档站

• 访问地址：https://docs.gogo996.com
• 默认端口：http://docs.gogo996.com:9966
• 服务隔离：文档站运行在独立目录 /opt/project-docs 与 /var/www/project-docs，使用独立系统用户 project-docs，不复用其他项目的 Node 运行时。
• 入口保护：如启用访问口令，口令只线下保存，不写入 Git、文档或脚本。
• HTTPS：使用 Let’s Encrypt 免费证书，当前证书通过 DNS TXT 校验签发。
• 证书续期：当前手动 DNS 校验证书到期前需要重新执行校验；如果后续腾讯云公网拦截解除，可改回 HTTP 自动续期。
• DNS：docs.gogo996.com 的 A 记录指向 134.175.173.58。
• 安全组：若 9966 端口公网无法访问，需要在腾讯云安全组放行 TCP 9966。

服务器操作

sudo /opt/project-docs/scripts/build-docs.sh
sudo /opt/project-docs/scripts/check-docs-cert.sh

自动发布

本地修改并检查文档后，按 Git 版本发布：

./scripts/publish-docs.sh "更新文档"

脚本会先执行文档检查和 Git 空白检查，再提交、推送 GitHub private 仓库，并推送到 server 的 main 分支。服务器收到推送后会自动同步 docs/ 并重建 Quartz。

Codex 知识库同步

• 详细规范：Codex与线上知识库同步
• 交接记录目录：README
• 新建交接模板：

./scripts/new-handoff.sh "项目名"

每次完成项目或阶段交接，必须新增交接文档并发布到线上文档站。

证书续期

当前证书有效期到 2026-10-18。服务器已配置每日证书到期检查；当剩余有效期不足 21 天时，会写入系统日志。

若要改成完全自动续期，需要在服务器上配置 DNSPod API 凭据，并使用 DNS 校验插件完成续期。API 凭据不得写入项目仓库。

回滚原则

通过 Git 回滚代码与同一版本的文档，避免两者状态不一致。