部署操作清单：私有文档站 + 自定义域名¶

这是一份可照做的操作清单（runbook）。想了解"当初为什么这么搭、踩了哪些坑"的叙事复盘，见同主题的搭建记录。

目标：把本仓库渲染成一个网站，绑定你自己的域名，并保持私有（只有你和你授权的邮箱能登录访问）。

推荐组合：GitHub 私有仓库 + Cloudflare Pages + Cloudflare Access + Cloudflare Registrar。除域名约 $10/年外全部免费。

第 0 步：本地先跑起来（可选，验证骨架）¶

cd <仓库根目录>
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve      # 浏览器打开 http://127.0.0.1:8000

看到网站正常渲染后，Ctrl+C 停止，继续下面的步骤。

第 1 步：推到 GitHub 私有仓库（你来操作）¶

在 https://github.com/new 新建仓库：
名称：例如 personal-ai-vault
可见性：Private（私有） ← 重要
不要勾选 "Add a README"（本地已有）
在本地关联并推送：

cd /Users/xhcao/AI/personal_documents
git init
git add -A
git commit -m "Initial commit: MkDocs 骨架 + 目录结构"
git branch -M main
git remote add origin git@github.com:<你的用户名>/personal-ai-vault.git
git push -u origin main

第 2 步：Cloudflare Pages 连接仓库（你来操作）¶

注册 / 登录 https://dash.cloudflare.com。
左侧 Workers & Pages → Create → Pages → Connect to Git。
授权 GitHub，选择 personal-ai-vault 私有仓库。
构建设置：
Framework preset: 选 None
Build command: pip install -r requirements.txt && mkdocs build
Build output directory: site
Environment variables → 加一个 PYTHON_VERSION = 3.12
点 Save and Deploy。首次构建约 1-2 分钟，完成后会给你一个 xxx.pages.dev 的临时地址。

之后每次 git push，Cloudflare 都会自动重新构建部署。

第 3 步：买域名并绑定（你来操作）¶

买域名：Cloudflare 后台 → Registrar → Register Domains，搜一个心仪的域名（.com 约 $10/年，成本价无加价）。
若你已在别处（Namecheap 等）买了域名，也可以把域名的 nameserver 指向 Cloudflare，或直接在 Cloudflare 加 DNS 记录。
绑定到 Pages：回到你的 Pages 项目 → Custom domains → Set up a custom domain → 输入你的域名（如 ai.example.com 或裸域 example.com）。Cloudflare 会自动加好 DNS 记录并签发 HTTPS 证书，几分钟生效。

第 4 步：加登录鉴权，保持私有（关键！你来操作）¶

默认情况下 Pages 网站是公网可访问的。用 Cloudflare Access 加一道登录门：

Cloudflare 后台 → Zero Trust（首次进入需创建一个 team，免费）。
Access → Applications → Add an application → Self-hosted。
配置：
Application name: AI Vault
Application domain: 填你绑定的域名（如 ai.example.com）
Policies → 新建一条 Allow 策略：
Action: Allow
Include → Emails → 填你自己的邮箱（可加多个授权邮箱）
保存。此后访问你的域名会先要求邮箱验证码 / Google 登录，只有名单内邮箱能进。

Cloudflare Access 免费额度 50 个用户，个人用绰绰有余。

完成后¶

写笔记 / 加 skill → git push → 网站自动更新。
换电脑 → git clone 私有仓库 → 一切照旧。
网站挂在公网域名，但只有你登录得进。

备用方案：GitHub Pages（不推荐用于私有内容）¶

.github/workflows/deploy.yml 里预置了一个 GitHub Actions 部署到 GitHub Pages 的流程，但 GitHub Pages 对私有访问控制很弱（免费版无法做登录鉴权）。若内容私有，请用上面的 Cloudflare 方案；该 workflow 仅作为你日后想公开某些内容时的备选。