Cloudflare Pages + Access 私有部署

• 来源：部署路径确认 2026-09-22
• 状态：脚手架已入库；上线需 owner 登录 Cloudflare（本仓库 不 改公开）

本库保持 Origin private。不要把仓库改成 public，不要做客户端假登录页。门禁放在 Cloudflare 边缘（Access），不是写在 VitePress 里。

本地预览

工作目录：仓库根。脚本见 package.json。

npm install
npm run docs:dev

• docs:dev：vitepress dev docs --host 0.0.0.0，默认 http://localhost:5173/
• docs:build：vitepress build docs
• docs:preview：vitepress preview docs --host 0.0.0.0，默认 **http://localhost:4173/**（先 build）

docs/.vitepress/config.mts 没有覆盖 outDir。VitePress 源目录是 docs/，静态产物是：

docs/.vitepress/dist

（官方 VitePress 部署说明对 Cloudflare Pages 也写这个目录。）

为什么用 wrangler Direct Upload

Cloudflare Pages 的 Git 自动构建目前只一等支持 GitHub / GitLab。官方 Known issues：GitHub and GitLab are currently the only supported platforms for automatic CI/CD builds. Direct Upload allows you to integrate your own build platform or upload from your local computer.

本仓在 Origin，不是 CF 一等 Git 源。不要为了接 Git 去镜像成公开 GitHub。也不要先接 Git 再想改 Direct Upload——官方写明 Git 集成项目不能事后改成 Direct Upload。

预定路径：本机（或你们自己的私有 CI）docs:build，再 wrangler pages deploy 上传 docs/.vitepress/dist。

部署一行

首次只需 Cloudflare 账号登录（npx wrangler login）或环境变量令牌。不要把 token / Account ID 写进仓库。

npm run docs:deploy

等价于：

npm run docs:build
npx --yes wrangler pages deploy

wrangler.toml 已写：

字段	值
name	world-model-kb
pages_build_output_dir	docs/.vitepress/dist

环境变量（只放本机或 CI secret）：

变量	用途
CLOUDFLARE_API_TOKEN	非交互上传。Dashboard → My Profile → API Tokens，模板用 Edit Cloudflare Workers（含 Pages）
CLOUDFLARE_ACCOUNT_ID	令牌能看见多个账号时才需要

成功后生产 URL 形如 https://world-model-kb.pages.dev（*.pages.dev 子域创建后不可改名）。

搜索引擎不要索引

docs/public/_headers 会随 VitePress 拷到产物根。Cloudflare Pages 解析该文件（本身不当静态页返回）：

/*
  X-Robots-Tag: noindex, nofollow

这是边缘响应头，不是前端藏页面。Access 未配好时，pages.dev 仍可能被直接打开——门禁靠下一节 Access，不要只靠 noindex。

Access：没有「团队共享密码」

Cloudflare Access 没有给浏览器访客的「一条共享口令」政策。不要自造登录页。

对人，最简单且官方支持的是：

• 登录方式：One-time PIN（邮箱 OTP，发件 noreply@notify.cloudflare.com）
• 政策：Allow + Include Emails（白名单几个受信地址）
• 可选：Access Group 只是把同一份邮箱列表挂到多个应用上，不是口令

对机器 / CI（不是给人打开网页）：

• 政策 Action 用 Service Auth
• 请求头：CF-Access-Client-Id + CF-Access-Client-Secret（Zero Trust → Access controls → Service credentials → Service Tokens）

Owner 一次性点击路径

1. 登录 Cloudflare Dashboard，确认账号能建 Pages 与 Zero Trust / Cloudflare One（Access 免费档即可）。
2. Workers & Pages → Create → Pages。选 Direct Upload（或空项目）。Project name = world-model-kb。不要接 GitHub/GitLab。
3. 本机执行 npx wrangler login（或设好 CLOUDFLARE_API_TOKEN），再 npm run docs:deploy。打开打印出的 https://world-model-kb.pages.dev 确认静态站已上（此时若尚未开 Access，URL 仍是公开的）。
4. Zero Trust → Settings → Authentication → Login methods：确认 One-time PIN 已启用（默认常已开）。
5. 保护 preview 与 生产 pages.dev（Pages 控制台「Enable access policy」默认只挡 preview，见 Known issues）：
   1. Workers & Pages → world-model-kb → Settings → General → Enable access policy
   2. 点该策略的 Manage → Access → Applications → 打开刚生成的应用 → Configure
   3. Public hostname → Subdomain 里删掉通配符 * → Save（必要时改应用名以免冲突）。此时生产 world-model-kb.pages.dev 已在 Access 后。
   4. 回到 Pages Settings → General，再点一次 Enable access policy，重新保护 preview：*.world-model-kb.pages.dev
   5. 确认存在 两个 Access 应用：一个生产主机，一个 preview 通配。
6. 对这两个应用分别设政策（或用同一个 Access Group）：
   • Action = Allow
   • Include = Emails → 加入 owner 自己的邮箱（再加少数读者）
   • 不要 Include Everyone；OTP 必须绑邮箱名单，否则任意邮箱都能收码进站
7. 无痕窗口打开 https://world-model-kb.pages.dev：应看到 Cloudflare Access 要邮箱 → 收 PIN → 进站。未列入的邮箱不应收到 PIN。
8. 若以后加 自定义域名：必须再为该主机单独建 Self-hosted Access 应用（官方：只保护 pages.dev 时，自定义域会出现 Access 页但验证失败）。先完成域名校验再开 Access。

不要做的事

• 不要把 Origin 仓库改 public，也不要为了 CF Git 去建公开镜像。
• 不要在 VitePress 里做假登录 / 前端口令。
• 不要把 CLOUDFLARE_API_TOKEN、Account ID、Service Token secret 提交进 git。
• 不要以为只开了 Pages 的「Enable access policy」生产站就安全——那一步默认只管 preview。

相关：笔记索引 · SolarWM-Wan2.2-5B 摸底清单。