知识库部署 · Cloudflare Pages + Access

让知识库 HTML 站远程随时能看、又只有你能看。本地照常 bun run docs:dev,互不影响。

决策:部署全部内容(含竞品/客户/销售策略),靠 Cloudflare Access 邮箱门禁保护。

为什么不用 GitHub Pages

仓库私有只保护源文件;一旦开 GitHub Pages,生成的站是单独公开服务,任何人有 URL 就能看(私有 Pages 仅 GitHub Enterprise 才有)。Cloudflare Access 给站点加邮箱门禁,补上这个缺口。

一、连仓库到 Cloudflare Pages

1. Cloudflare 控制台 → Workers & Pages → Create → Pages → Connect to Git。

2. 授权 Cloudflare 的 GitHub App 访问私有仓库 answermyname,选中它。

3. 部署分支:先选 claude/audio-recording-collection-MFA1c(想现在就看);合并到 main 后改回 main。

4. 构建设置(关键,四个值照填):

   字段	值
   Framework preset	None
   Root directory	文档
   Build command	npm run build
   Build output directory	.vitepress/dist

   • Root directory 必须填 文档:这是文档站的独立小包(只依赖 VitePress), Cloudflare 只在这里装依赖,绕开 monorepo 的 workspace:* 和 better-sqlite3 原生编译——否则在仓库根自动装会直接报错。
   • 这三项都是相对 文档 的,所以输出目录是 .vitepress/dist,不带 ..。
   • 不要设 PUBLIC_BUILD——要含竞品全量,靠下面的 Access 保护。

5. Save and Deploy。完成后得到 <项目名>.pages.dev。

此刻站点还是公开的,先别分享 URL,立刻做第二步。

二、加邮箱门禁(只有你能看)

1. Cloudflare → Zero Trust(首次建免费 team,选 Free 计划)。
2. Access → Applications → Add an application → Self-hosted。
3. Application domain 填 <项目名>.pages.dev;想连预览域也保护,再加 *.<项目名>.pages.dev。
4. Policies → Add → Action Allow → Include → Emails → 填你自己的邮箱。
5. 登录方式默认 One-time PIN(邮箱收验证码,无需注册)。Save。

之后访问先要邮箱验证码,只有你这个邮箱进得去。

三、和本地 / git 的关系

• 本地不变:bun run docs:dev 照旧,秒开。
• 自动更新:每次 push 到部署分支,Cloudflare 异步重建上线,不占你机器。
• 来源:站点读 文档/ 下的 Markdown 与 front-matter——改 Markdown push 即更新。
• 永不上站:文档/_原始材料/(录音/原文)被 srcExclude + gitignore 双重挡住。

红线

私有 repo + Cloudflare Access = 站点也私有。别关 Access,别把 URL 当公开链接发。真要对外公开某部分,另建一个 PUBLIC_BUILD=1 的站(自动剔除 _竞品/ 等横切内部目录)。

排错

• 构建日志显示 npm install + Unsupported URL Type "workspace:":Root directory 没填 文档 ——Cloudflare 在仓库根装了 monorepo。改 Root directory = 文档 重试。
• 找不到输出 / 404:确认 output directory 是 .vitepress/dist(相对 文档)。
• 首次构建报错:把 Cloudflare 构建日志贴来,我对着修。