跳转至

GitHub + Cloudflare 部署

目标拓扑：私有 GitHub 仓库负责源文件，Cloudflare Pages 负责构建与托管，Cloudflare Access 负责访问认证。

sequenceDiagram
    participant PC as 电脑 / Git
    participant GH as GitHub Private Repo
    participant CF as Cloudflare Pages
    participant AC as Cloudflare Access
    participant M as 手机浏览器
    PC->>GH: git push
    GH-->>CF: 触发拉取与构建
    CF->>CF: mkdocs build --strict
    M->>AC: 访问 pages.dev
    AC->>M: 邮箱 OTP / IdP 登录
    AC-->>M: 放行静态站点

1. 创建私有仓库并推送

在 GitHub 创建空的 Private 仓库后：

git init
git add .
git commit -m "init: AI Infra knowledge base"
git branch -M main
git remote add origin git@github.com:galenyu/tensor-to-transistor.git
git push -u origin main

私有仓库不是密钥仓库

Git 历史很难彻底清除。不要提交 Cloudflare API Token、SSH 私钥、公司内部资料或任何真实凭证；使用密码管理器或 CI Secret。

2. 创建 Pages 项目

Cloudflare Dashboard → Workers & Pages → Create application → Pages → Connect to Git，授权 GitHub 并选择私有仓库。

设置 值
Production branch main
Framework preset 可选 MkDocs；找不到时选 None
Build command mkdocs build --strict
Build output directory site
Root directory /
Environment variable PYTHON_VERSION = 3.12

requirements.txt 会让构建环境安装已锁定的 MkDocs Material 与 minify 插件。首次部署后先打开站点，确认首页和搜索正常。

3. 锁住正式 pages.dev 地址

Pages 的 Enable access policy 默认只保护哈希或分支形式的预览地址。按 Cloudflare 的 Pages Known issues 流程保护生产地址：

  1. Pages 项目 → Settings → General → Enable access policy。
  2. 点击管理新建的 Access policy。
  3. Zero Trust → Access → Applications → 项目 → Configure。
  4. 在 Public hostname 的 Subdomain 删除 *，使它从 *.<project>.pages.dev 变为 <project>.pages.dev，保存。
  5. 回到 Pages 设置，再次启用 access policy，恢复对预览地址的保护。
  6. 分别检查正式与预览应用的策略：Action 为 Allow，Include 为你自己的邮箱。
  7. Settings → Authentication 中启用 One-time PIN（或其他 IdP）。

验证是部署的一部分

用无痕窗口打开正式地址，确认会进入 Access 登录；再用未授权邮箱确认无法进入。不要只看控制台里是否存在策略。

4. 自定义域名（可选）

如使用 notes.example.com：

  1. 在 Pages 项目的 Custom domains 先完成域名绑定与证书验证。
  2. Zero Trust → Access → Applications → 新建 Self-hosted application。
  3. Domain 选择 notes.example.com，配置仅本人邮箱可访问的 Allow 策略。
  4. 再次用无痕窗口验证。

Cloudflare 要求 Self-hosted application 的普通 Domain 属于账号内的 active zone；因此不能把通用的“自定义域名”步骤原样套到 Cloudflare 所有权下的 pages.dev。pages.dev 应按上一节的 Pages 专用流程设置。

5. 更新与回滚

正常更新：

git add docs mkdocs.yml
git commit -m "docs: update inference notes"
git push

Cloudflare 会为提交生成部署。回滚时优先在 Pages 的 Deployments 中选择上一个成功版本；随后在 Git 中提交修复，保持代码与线上状态最终一致。

安全加固清单

  • GitHub 仓库可见性为 Private，成员权限最小化。
  • 正式和预览 pages.dev 地址都被 Access 覆盖。
  • 自定义域名有单独的 Access application。
  • OTP/IdP 只允许个人邮箱，未使用宽泛的邮箱域规则。
  • 无痕窗口与未授权邮箱验证通过。
  • docs/_headers 的 noindex 与基础安全响应头生效。
  • Git 历史不包含凭证或内部敏感数据。

官方指南