搭建记录：用 GitHub + Cloudflare 搭一个 AI 知识库网站¶

记录本站的搭建过程与技术选型，既作复盘，也作一份可复现的实战指南。日期：2026-07-08

1. 目标与需求¶

我想把平时的 AI 学习资料集中存放，并做到 "write once, run everywhere"：

内容包括：AI 学习笔记、自己写的 agent skills、self-development agents（文档 + 代码都有）。
换电脑、换公司时，不用重新备份 —— 只要能随处取回。
最好还能在浏览器里以网站形式舒适地阅读、搜索。

核心洞察：这本质是 两件事，拆开看就不复杂了：

存储与同步（必做）—— 用 Git 仓库即可完美解决，不需要域名、不需要网站。
渲染成网站（锦上添花）—— 在 Git 之上加一层"静态站生成 + 托管"。

2. 整体架构¶

分三层，各层解耦、可独立替换：

层	选型	作用
存储层	GitHub 私有仓库	所有内容的唯一真实来源，clone 即取回，push 即备份
托管层	Cloudflare Pages	把 Markdown 构建成网站并部署，push 后自动更新
鉴权层	Cloudflare Access（待补）	邮箱验证码登录门，让公网网站保持私有

数据流：

本地编辑 Markdown / 代码
   │  git push（到 main 分支）
   ▼
GitHub 私有仓库
   │  webhook 事件通知
   ▼
Cloudflare Pages
   │  pip install + mkdocs build → 部署 site/
   ▼
personal-ai-vault.pages.dev（网站，1–2 分钟后更新）

3. 技术选型与理由¶

静态站生成器：MkDocs Material

配置几行 YAML 就能跑，自带搜索、目录、代码高亮、明暗主题、中文界面。
内容就是纯 Markdown，天然适合 Git 版本管理，且不锁定 —— 哪天想换工具，内容原样带走。

存储：GitHub 私有仓库

代码 + 文档统一存放，skills/agents 本就是"代码 + Markdown"，放一个仓库最自然。
私有仓库可放敏感/工作相关内容。

托管：Cloudflare Pages

免费、自带 HTTPS、支持私有仓库构建，且能配合 Cloudflare Access 做登录鉴权 —— 这是"私有文档站"的最佳免费组合。
相比 GitHub Pages：后者对私有访问控制很弱（免费版要么全公开），所以选 Cloudflare。

关于取舍（结合"主要在中国大陆、常无 VPN"的实际情况）：

不买自定义域名：.pages.dev 免费地址对自用足够；且大陆把自定义域名指向境内服务器需要 ICP 备案（约 2–3 周），自用没必要。以后想要随时能加，不影响现在用。
不迁到 Gitee：GitHub 在大陆并未被墙，git push/clone 基本可用（偶尔慢），代码已在 GitHub，无需折腾迁移。
鉴权用邮箱验证码而非 Google 登录：大陆无 VPN 时 Google 登录不稳，邮箱验证码走邮件更可靠。

4. 今天完成的步骤（可复现）¶

4.1 仓库骨架与目录结构¶

设计原则：每个 skill / agent 自成一个文件夹，说明文档（SKILL.md / README.md）与可运行代码放在一起，与真实的 Claude Code skill 目录结构一致。

personal_documents/
├── docs/                      ← 网站内容根目录
│   ├── index.md               ← 首页
│   ├── knowledge/             ← AI 学习笔记
│   ├── skills/<name>/         ← 每个 skill：SKILL.md + scripts/
│   ├── agents/<name>/         ← 每个 agent：README.md + agent.py
│   └── guides/                ← 各种 how-to / 教程（按主题分子文件夹）
│       └── github-cloudflare-site/     ← 本主题：用 GitHub+Cloudflare 搭站
│           ├── index.md                ← 主题落地页
│           ├── setup-record.md         ← 本文（搭建记录 / 复盘）
│           └── deploy-steps.md         ← 部署操作清单（runbook）
├── mkdocs.yml                 ← 网站配置
├── requirements.txt           ← 构建依赖（mkdocs-material）
├── .gitignore                 ← 排除密钥 / 构建产物 / .venv
└── README.md

.gitignore 特意排除了常见密钥文件（.env、*.pem、credentials 等）、构建产物 site/ 和虚拟环境 .venv/。

4.2 本地验证构建¶

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs build --strict     # 验证能构建
mkdocs serve              # 本地预览 http://127.0.0.1:8000

4.3 推到 GitHub 私有仓库¶

在 GitHub 新建 Private 仓库（不勾选初始化 README），然后：

git init
git add -A
git commit -m "Initial commit: MkDocs 骨架 + 目录结构"
git branch -M main
git remote add origin <仓库地址>
git push -u origin main

踩坑：SSH 权限被拒

首次用 git@github.com:... 的 SSH 地址 push 报 Permission denied (publickey) —— 本机没有把 SSH 公钥关联到个人 GitHub。解决办法：改用 HTTPS 地址，并用 GitHub CLI（gh auth login，走浏览器授权）配置凭证，之后 git push 即成功。也可用 Personal Access Token 作为 HTTPS 密码。

4.4 Cloudflare Pages 连接仓库¶

踩坑：Workers 与 Pages 入口混淆

Cloudflare 新账号的 Create 默认引导到 Workers 流程（页面标题 "Create a Worker"，含 npx wrangler deploy），那里没有静态站需要的 "Framework preset / Build output directory"。正确做法是走 Pages 流程 —— 可直接访问 dash.cloudflare.com/<account_id>/pages/new/provider/github，进入 "Set up builds and deployments" 页面。

Pages 构建配置：

字段	值
Framework preset	`None`
Build command	`pip install -r requirements.txt && mkdocs build`
Build output directory	`site`
环境变量	`PYTHON_VERSION` = `3.12`
Production branch	`main`

Save and Deploy，约 1–2 分钟后部署成功，得到 personal-ai-vault.pages.dev。

4.5 自动部署机制¶

连接仓库时，Cloudflare 在 GitHub 仓库注册了一个 webhook。此后：

git push 到 main → GitHub 主动通知 Cloudflare → Cloudflare 拉取代码、构建、部署到生产站。
push 到其他分支 → 生成独立的 Preview 预览部署，不影响生产。
在后台改配置（如环境变量）→ 不会自动重建，需下次 push 或手动 Retry。

5. 过程中澄清的几个概念¶

Webhook 是"推"不是"拉"：不是 Cloudflare 不停轮询 GitHub，而是 GitHub 有 push 事件时主动 POST 通知 Cloudflare（事件驱动，平时零开销）。webhook 通知只带元数据，真正的代码由 Cloudflare 用授权去 clone，所以私有仓库也能拉。
配置都可改、可重新部署：进 Cloudflare 项目的 Settings 即可改构建命令、环境变量、分支、域名等；改完在 Deployments 页 Retry，或下次 push 生效。不用重建项目。
Cloudflare Access "50 用户额度"：指最多 50 个不同邮箱能登录被保护的网站。个人自用只占 1 个，等于无上限。

6. 当前状态¶

部分	状态
仓库骨架（MkDocs + knowledge/skills/agents）	✅ 完成
GitHub 私有仓库 + push	✅ 完成
Cloudflare Pages 自动构建部署	✅ 上线 `personal-ai-vault.pages.dev`
push 自动更新网站（webhook）	✅ 生效
访问鉴权（Cloudflare Access）	⏳ 待补（见下节）

核心目标 "write once, run everywhere" 已达成：换电脑 git clone 全取回，git push 即备份并更新网站。

7. 待办：访问鉴权（Cloudflare Access）¶

本节为占位，将在配置完成后单独补充。

为什么是可选的一层：并非所有人都需要私有网站 —— 有人不介意内容公开，或只想先跑起来。因此把鉴权作为独立、可选的进阶步骤，单独提交，历史更清晰。

计划：用 Cloudflare Access（Zero Trust Free 版）加一道邮箱一次性验证码登录门，仅允许指定邮箱登录，让公网网站保持私有。详细步骤见同主题的部署操作清单第 4 步。

在鉴权配好之前

网站当前是公网可访问的。虽然地址不为人知，但 .pages.dev 的 HTTPS 证书会进入公开的 Certificate Transparency 日志、可被扫描发现，所以此前不要提交任何敏感内容 （API key、内部信息、私人笔记）。