私有仓库部署

使用私有文档源，生成的站点仍不会自动变为私有。需要限制读者访问时，请另行配置 Cloudflare Access 等访问控制；模板不会自动配置。

这里使用公开模板创建 Worker，文档来自你自己的私有 GitHub 仓库。部署模板的 GitHub 授权、读取文档的 Token 和站点访问权限彼此独立。

1. 用公开模板创建 Worker

打开 nimbus-docs-template 仓库 README，点击 Deploy to Cloudflare，完成 Cloudflare 与 GitHub 授权并创建模板副本及 Worker。

部署时确认以下构建配置，后续连接私有文档源时保持不变：

首次模板表单只有 DOCS_REPO、DOCS_BRANCH、DOCS_PATH 三个文档源字段。这一步先保留预填的公开示例值创建 Worker，再按下文补充私有文档源变量和 Secret。已经填写私有仓库但首次拉取失败时，也可以在 Worker 创建后补齐配置并重试。

Cloudflare GitHub App 的授权用于连接和构建模板仓库，不等同于文档拉取脚本所需的私有仓库凭据。文档拉取脚本通过 DOCS_TOKEN 使用 GitHub Personal Access Token（PAT）执行 Git fetch。

2. 准备私有仓库中的文档

下文以私有仓库中的 docs/ 目录为例，目录名不限制文档语言。如果将本模板的中文示例按原目录复制到私有仓库，将 DOCS_PATH 设为 docs-zh-CN，模板就会自动读取 docs-zh-CN/site.json。旧部署若已有显式 DOCS_CONFIG_PATH，需删除它或改成对应路径。

在目标私有仓库的文档分支中创建 docs/README.md，写好标题和正文后提交。这个文件会成为站点首页。添加更多页面和图片的方法见编写文档。

需要自定义站点名称、导航或品牌资源时，可以再添加 docs/site.json。最小配置为：

{
  "schemaVersion": 1
}

其他字段按需添加，详见站点配置。模板自动读取 DOCS_PATH 目录中的 site.json；没有文件时使用通用站点配置，无需添加 DOCS_CONFIG_PATH 或填写空值。

从私有仓库的 Code → HTTPS 复制 HTTPS 克隆地址，地址中不要添加 Token。同时记下文档所在分支，以及文档目录、配置文件相对于仓库根目录的路径。

3. 创建只读 GitHub Token

使用具有目标私有仓库读取权限的 GitHub 账号：

1. 打开个人 Settings → Developer settings → Personal access tokens → Fine-grained tokens，选择 Generate new token。
2. 填写便于识别的 Token 名称和到期时间，组织可能限制最长有效期。Token 到期后，构建将无法继续读取私有仓库，需要更新凭据。
3. 在 Resource owner 选择私有仓库所属的个人账号或组织。
4. 在 Repository access 选择 Only select repositories，仅勾选目标私有文档仓库。
5. 在 Repository permissions 将 Contents 设为 Read-only。GitHub 会自动提供所需的 Metadata: Read-only，不需要写入权限。
6. 生成 Token。若组织要求审批，需等待组织管理员批准后才能用于构建。处于 pending 状态的 Token 不能读取该组织的私有内容。

下一步将生成的 Token 保存到 Cloudflare 构建 Secret，不要写入文档、仓库配置、Git URL 或聊天消息。若无法选择目标组织或仓库，先检查账号权限，并确认组织允许使用 fine-grained PAT。

4. 配置构建变量和 Secret

打开目标 Worker 的 Settings → Builds → Build variables and secrets，按下表配置。文档源与站点参数使用普通变量；DOCS_TOKEN 单独选择 Secret 类型。四个可选站点变量不会出现在首次部署表单，有需要时再在这里添加。

文档源变量未覆盖时，模板会读取 wrangler.jsonc 中的公开默认值；仍适用的默认值无需重复填写。但 DOCS_REPO 必须改为你的私有仓库地址，否则仍会读取公开示例。可选站点变量不设置时按上表自动处理。

手动指定 DOCS_CONFIG_PATH 后，该文件必须存在且 JSON 有效。旧部署需先更新模板，再删除旧的 DOCS_CONFIG_PATH，才能启用自动查找。其他已保存的可选构建变量也会继续覆盖新默认行为，直到删除它们。

SITE_LOGO 和 SITE_FAVICON 填图片 URL 或仓库路径时，分别覆盖 JSON 的 brand.logo 和 brand.favicon。不设置时沿用 JSON，未配置对应字段时使用模板内置的 Nimbus 官方 Logo。原有 default 或空白值继续兼容相同规则。

这两个变量的路径都相对于 DOCS_REPO 仓库根目录，与站点 JSON 是否存在、存放在哪里无关。JSON 内的本地资源路径仍相对于 JSON 文件。构建可以用同一个只读 Token 读取仓库图片，无需额外添加图片凭据。

SITE_URL 不会自动绑定域名，使用自定义域名前需先完成域名配置。未设置这个变量时仍能浏览站点，只省略依赖正式站点地址的 canonical、SEO 输出和 sitemap。

这里的 Build variables and secrets 供构建进程使用。普通 Settings → Variables & Secrets 设置的是 Worker 运行时变量和 Secret，不会自动传给静态构建。因此，只在运行时区域填写 DOCS_TOKEN，文档拉取仍无法获得认证。Logo 和 favicon 的普通构建变量也需要保存后重新构建才会生效。

保存后，在构建记录中选择 Retry build。如果初始部署没有 Build Secret 入口，就在 Worker 创建后补齐上述配置，再重试构建，完成私有文档的首次构建。后续更换文档源或 Token，也在这里修改变量和 Secret，构建命令、部署命令及根目录保持不变。

5. 确认首次发布

构建和部署成功后，检查以下几项：

• 查看构建日志中的文档提交 SHA，核对它是否对应私有仓库所选分支的提交。这是文档源版本，不一定与 Cloudflare 显示的模板仓库提交相同。
• 打开 Worker 的站点地址，确认首页显示私有源中的正文，文档链接和图片可以访问。
• 查看页脚或 /_build.json 中的提交 SHA，确认线上页面使用的是本次读取的文档版本。

如果站点仍是默认示例，先检查 Build variables 中的 DOCS_REPO 是否保存到了当前 Worker，再重新触发构建。

6. 让文档推送触发更新

表单各字段的说明、推送验证和故障排查见原文档仓库构建挂钩。公开与私有仓库的触发流程相同，私有文档仍通过构建 Secret 中的 DOCS_TOKEN 读取。

私有文档源与 Builds 关联的模板仓库分开存放时，需要将原文档仓库的 push 连接到 Cloudflare Deploy Hook。首次构建不依赖 Webhook，发布成功后再配置即可：

1. 在 Worker 的 Settings → Builds → Deploy Hooks 创建 Hook，选择模板仓库的构建分支，复制生成的 URL。
2. 打开私有文档仓库的 Settings → Webhooks → Add webhook，按下表填写并保存。管理 Webhook 需要相应的仓库管理权限，与只读文档 Token 的权限分开管理。

Deploy Hook URL 本身就是触发凭据，请保存在 Webhook 设置中，不要提交到仓库。DOCS_TOKEN 仅用于构建时读取文档，不能用作此流程的 Webhook Secret。

向 DOCS_BRANCH 对应分支推送一次文档修改，先在 GitHub Webhook 的 Recent Deliveries 查看请求结果，再到 Cloudflare 查看新构建，并检查站点内容。Hook 选择的是模板分支，读取哪个文档分支则由 DOCS_BRANCH 决定，二者可以不同。

文档与模板若已在同一个 Builds 关联仓库、同一个分支，仓库自身的 push 会触发构建，无需重复设置这条 Webhook 链路。

7. 更新或更换 Token

Token 到期、被撤销或需要轮换时，按第 3 步创建新的只读 Token。完成组织审批后，更新该 Worker 的 Build variables and secrets → DOCS_TOKEN，保存并重新构建。确认新凭据可用，再撤销不再使用的旧 Token。

更换私有仓库时，同时更新 DOCS_REPO，并确保新 Token 的 Resource owner 和所选仓库覆盖新的文档源。无需把 Token 写回模板仓库，也无需修改 Webhook Secret。

常见问题

官方参考

• Cloudflare Workers Builds 配置
• GitHub Personal Access Token 管理说明

返回快速入门或首页。