Report 仓库 MkDocs + Cloudflare Pages 自动部署¶

日期： 2026-05-01 目标： 将 report 仓库从纯 Markdown 升级为 MkDocs + Material 文档站，通过 GitHub Actions 自动部署到 Cloudflare Pages

背景¶

用户有一个 GitHub 仓库 Setsuna-Yukirin/report，用于存放 Hermes Agent 研究报告。之前是纯 Markdown 文件，计划改造为 MkDocs 静态文档站，并实现 push 即自动部署。

域名 yukirin.moe 托管在 Cloudflare，最终目标地址为 report.setsuna.yukirin.moe。

操作步骤¶

1. 部署方案选型¶

讨论了三个方案： - 方案 A：GitHub Pages — 最省事但国内可能被墙 - 方案 B：推送到 HK 服务器 — 可控但需维护 nginx/SSL - 方案 C：Cloudflare Pages — 免费 CDN、自动 HTTPS、用户域名已在 CF

最终选择方案 C。

2. 解决 GitHub 账号关联问题¶

Cloudflare Pages 的 "Connect to Git" 需要在仓库所有者账号安装 GitHub App。

report 仓库在 Setsuna-Yukirin 账号下
用户的 Cloudflare 绑定的是 Vanilla-Yukirin 账号
光加 collaborator 不够，Cloudflare App 必须装在仓库所有者侧

解决方案：放弃 Connect to Git，改用 GitHub Actions + Wrangler 方式部署。只需 API Token，不需要账号关联。

3. 配置 Cloudflare 凭证¶

用户在 Cloudflare 创建 API Token： - Token 名称：GitHub Actions Pages Deploy Setsuna Report - 权限：Account → Cloudflare Pages → 编辑 - Account ID：60be4ba6870069c24dbcbe58e6b02044

通过 gh secret set 配置到 GitHub Secrets：

gh secret set CLOUDFLARE_API_TOKEN --body "<token>"
gh secret set CLOUDFLARE_ACCOUNT_ID --body "60be4ba6870069c24dbcbe58e6b02044"

4. 创建 Cloudflare Pages 项目¶

通过 API 创建：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<id>/pages/projects" \
  -H "Authorization: Bearer <token>" \
  -d '{"name":"report","production_branch":"main"}'

项目域名：report-67e.pages.dev

5. 编写 MkDocs 配置和文档结构¶

创建 mkdocs.yml，使用 Material 主题： - 中文界面、暗色/亮色切换 - 自动导航（无手动 nav 配置） - navigation.indexes 功能（README.md 作为分组首页） - 代码高亮、提示块、Mermaid 图表等扩展

创建 docs/ 目录，将现有 Markdown 文件复制进去保持目录结构。

6. 编写 GitHub Actions Workflow¶

# .github/workflows/deploy.yml
name: Deploy to Cloudflare Pages
on:
  push:
    branches: [main]
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.11' }
      - run: pip install mkdocs-material
      - run: mkdocs build --strict
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy site --project-name=report

7. 绑定自定义域名¶

通过 Cloudflare API 绑定 report.setsuna.yukirin.moe：

curl -X POST "https://api.cloudflare.com/client/v4/accounts/<id>/pages/projects/report/domains" \
  -H "Authorization: Bearer <token>" \
  -d '{"name":"report.setsuna.yukirin.moe"}'

用户手动在 Cloudflare DNS 添加 CNAME 记录： - Name: report.setsuna - Target: report-67e.pages.dev - Proxied: yes

证书自动签发（Google CA），等待几分钟后生效。

8. 改为自动导航模式¶

删除 mkdocs.yml 中的 nav: 配置，MkDocs 自动扫描 docs/ 目录生成导航。导航名 = Markdown 文件的 H1 标题。

添加 navigation.indexes 功能，README.md 作为分组首页。

9. 添加自定义 Logo¶

从用户的 OneDrive 复制图片（刹那的 Q 版插画），裁切为圆形 PNG：

from PIL import Image, ImageDraw
# 正方形裁切 → 圆形遮罩 → 保存为 PNG

缩小到 128x128（30KB），配置到 mkdocs.yml 的 logo 和 favicon。

10. 创建 archive 归档 skill¶

将用户提供的归档技能适配到 Hermes Agent 环境： - Windows 路径 → WSL 路径 - Claude Code 路径 → Hermes Agent 路径 - 默认归档位置：~/report/docs/archives/ - 每次归档后自动 git commit + push

遇到的问题与解决¶

问题1：Cloudflare 看不到 GitHub 仓库¶

现象：Cloudflare Pages Connect to Git 搜索 report 显示 "No repositories found" 原因：Cloudflare GitHub App 装在 Vanilla-Yukirin 账号下，但 repo 在 Setsuna-Yukirin 账号下。加 collaborator 不够，App 必须装在仓库所有者侧解决：放弃 Connect to Git，改用 GitHub Actions + Wrangler 部署（只需 API Token）

问题2：自定义域名 SSL 证书未签发¶

现象：访问 report.setsuna.yukirin.moe 提示 "此主机名未被证书覆盖" 原因：CNAME 记录刚添加，Cloudflare 签发证书需要几分钟解决：等待约 1 分钟后自动生效，HTTP 200

问题3：Logo 文件太大¶

现象：原图 850x850，557KB，加载慢解决：裁切为圆形 128x128 PNG，压缩到 30KB

知识清单¶

Cloudflare Pages 部署方式：Connect to Git（需 App 装在仓库所有者侧）vs GitHub Actions + Wrangler（只需 API Token，更灵活）
MkDocs 自动导航：不写 nav: 配置时，自动扫描 docs/ 目录，用 H1 标题作为导航名
navigation.indexes：让 README.md 成为分组首页而非普通导航项
Cloudflare Pages 自定义域名：API 创建 → DNS CNAME → 证书自动签发（几分钟）
Pillow 圆形裁切：ImageDraw.ellipse 创建遮罩 → putalpha 应用

待办 / 遗留¶

[x] MkDocs 基础搭建
[x] GitHub Actions 自动部署
[x] 自定义域名 + SSL
[x] 自动导航
[x] 自定义 Logo
[ ] 完善 docs/archives/ 目录结构和 README.md 索引
[ ] 考虑添加自定义 CSS（extra.css）
[ ] 考虑添加 404 页面