文档站部署：Cloudflare Pages¶

项目已有 v1 Worker 在 Cloudflare 上运行，文档站（MkDocs 构建产物）同步走 Cloudflare Pages，与业务系统共用账号、缓存与分析能力。

1. 部署架构总览¶

GitHub (main 分支 push)
   │
   ├─ CF Pages: drill-eval-docs   →  docs.drill-eval.com   （MkDocs 静态站）
   │
   └─ CF Workers: drill-eval-v1   →  app.drill-eval.com    （v1 业务系统，已上线）

两者共用一个 Cloudflare 账号、一套域名 DNS、一份 Web Analytics。

2. 一次性配置步骤¶

2.1 方式 A：通过 wrangler CLI 部署（推荐，命令行自动）¶

# 1. 安装 wrangler（如果还没安装）
npm install -g wrangler

# 2. 登录 Cloudflare
npx wrangler login

# 3. 一键部署（预览环境）
./deploy-docs.sh preview

# 或者部署到生产
./deploy-docs.sh production

脚本会自动： - ✅ 创建/激活虚拟环境 - ✅ 安装 MkDocs 依赖 - ✅ 构建文档站 - ✅ 部署到 Cloudflare Pages - ✅ 输出访问地址

2.2 方式 B：Cloudflare Dashboard 手动配置¶

登录 https://dash.cloudflare.com
Workers & Pages → Create → Pages → Connect to Git
选择 drill-eval 仓库、main 分支
构建配置：
Framework preset：None
Build command：pip install mkdocs-material pymdown-extensions && mkdocs build
Build output directory：site
Root directory：/（仓库根）
Environment variables：
- PYTHON_VERSION = 3.12
域名绑定：Custom domains → Add → docs.drill-eval.com

两种方式的对比： - wrangler CLI：适合本地快速预览、CI/CD 集成 - Dashboard：适合生产环境、自动 Git 触发部署

2.3 本地预览¶

pip install mkdocs-material pymdown-extensions
mkdocs serve
# http://127.0.0.1:8000

3. 自动部署机制¶

推送到 main 分支 → Cloudflare Pages 自动构建 → 直接发布到生产域名
推送到其他分支 → 自动生成预览部署（形如 https://<commit>.drill-eval-docs.pages.dev）
不再需要 .github/workflows/docs.yml（已删除）

4. LLM SEO 友好配置¶

Cloudflare Pages 支持仓库内 _headers / _redirects / robots.txt 文件透传。已在 docs/ 目录配置：

文件	作用
`docs/robots.txt`	明确允许 LLM 爬虫访问
`docs/llms.txt`	给 LLM 看的站点摘要索引
`docs/llms-full.txt`	完整文本索引（标准对齐条款 + 核心文档）
`docs/_headers`	为不同路径配置 Cache-Control 与 CORS

MkDocs 默认会把 docs/ 下非 .md 文件原样复制到 site/，所以这些文件发布后会在 https://docs.drill-eval.com/robots.txt 等根路径可访问。

5. 与 v1 Worker 共享域名的建议¶

drill-eval.com              → 品牌主站（静态，Pages）
www.drill-eval.com          → 301 → drill-eval.com
docs.drill-eval.com         → MkDocs 文档站（Pages）
app.drill-eval.com          → v1 业务系统（Workers）
api.drill-eval.com          → 预留给独立 API Worker
demo.drill-eval.com         → 只读演示环境

全部在同一 Cloudflare 账号管理，DNS 都走 CF 代理（橙色云朵），天然获得 CDN + DDoS + Rate Limit。

6. 迁移 Checklist¶

删除 .github/workflows/docs.yml
在 CF Dashboard 创建 Pages 项目 drill-eval-docs
绑定自定义域名
把 mkdocs.yml 的 site_url 改为真实域名
首次 push 验证自动部署
在 CF Web Analytics 配置站点
配置 robots.txt / llms.txt（见下节）

7. 部署后验证清单¶

部署完成后，执行以下验证：

# 1. 验证站点可访问
curl -I https://docs.drill-eval.com
# 应返回 200 OK

# 2. 验证 robots.txt 正确（LLM SEO 关键）
curl https://docs.drill-eval.com/robots.txt | grep "GPTBot"
# 应返回 "User-agent: GPTBot" + "Allow: /"

# 3. 验证 llms.txt 可访问
curl https://docs.drill-eval.com/llms.txt | head -5
# 应返回站点摘要

# 4. 验证 JSON Schema 可访问（CORS 头）
curl -I https://docs.drill-eval.com/evaluation-report-schema.json
# 应包含 "Access-Control-Allow-Origin: *"

# 5. 验证 sitemap
curl https://docs.drill-eval.com/sitemap.xml | head -10
# 应返回 XML sitemap

# 6. 测试 LLM 索引（手动）
# 在 Perplexity 或 Kimi 搜索："GB/T 46792-2025 评估报告模板"
# 观察是否出现你的站点链接

8. 监控与回滚¶

监控：CF Pages → Deployments 列表，每次部署都可查看构建日志
回滚：任何历史部署可一键 "Rollback to this deployment"
告警：CF Notifications → 建议启用 "Pages deployment failed"