从 git 仓库发布站点

适用场景：文档源在共享 git 仓库，希望以仓库为唯一事实源，由服务器端克隆并构建——发布端不再本地构建、不再上传产物大包，只需服务器能访问该仓库。

前置条件：服务器可以访问该 git 仓库；已知服务器地址与访问令牌。

操作步骤

1. 执行（站点源在仓库根目录，docdoc.json 即仓库根的 docdoc.json）：

   docdoc add --remote docdoc://docs.example.com:10001 https://github.com/your-org/your-docs.git --name my-docs
   

2. 固定分支或标签时追加 --ref：

   docdoc add --remote docdoc://docs.example.com:10001 https://github.com/your-org/your-docs.git --name my-docs --ref v1.2.0
   

3. 站点源在仓库子目录时追加 --path（该目录需包含 docdoc.json）：

   docdoc add --remote docdoc://docs.example.com:10001 https://github.com/your-org/monorepo.git --name my-docs --path docs
   

4. 看到 注册成功：my-docs，N 页，构建于 <时间> 即完成，访问 http://<服务器>:端口/my-docs/ 核验。

在托管服务器本机操作时可用 --config /etc/docdoc/config.yaml 代替 --remote，token 自动取配置。

注意

• 服务器克隆失败会返回 422「git 克隆失败」，检查仓库地址与服务器网络可达性
• 私有仓库：服务器克隆走服务器本机 git 凭据——安装脚本已执行 gh auth setup-git，以 root 运行的服务可克隆 gh 账号有权限的私有仓库；凭据缺失时补跑 gh auth setup-git（root 身份）后重试
• 内容更新全自动：git push 后，服务器轮询发现 ref 指向的提交变化即自动重新克隆构建（间隔为 service.gitPollSeconds 配置，缺省 60 秒，粒度到秒）；构建失败保留旧版本继续服务，下轮自动重试
• 更换域名、分支、子目录或子文档筛选仍需重走发布：删除同名站点后再执行 add