文档站部署¶
EvoSpeech Research Observatory 使用 Material for MkDocs 生成纯静态文件，并通过 Cloudflare
Pages Direct Upload 发布。GitHub 仓库可以继续保持 private；部署只上传构建后的 site/，不会
上传源码、模型权重、原始音频、私有测试集或本机环境。
为什么使用 Direct Upload¶
当前 GitHub 账号计划不支持 private repository 的 GitHub Pages。Cloudflare 官方将 Direct Upload 定义为从本机或自有构建系统上传预构建静态目录的方式，正好符合本项目需求。
Direct Upload 项目以后不能原地切换为 Git integration；如果将来需要 Cloudflare 自动读取 GitHub private repo，应新建另一个 Git-integrated Pages 项目，再迁移域名。这个限制不影响 Wrangler 持续上传新的生产版本和预览分支。
冻结配置¶
- Pages project：
evospeech-research； - production URL：https://evospeech-research.pages.dev/；
- production branch：
main； - build output：
site/； - Wrangler：
4.112.0； - Mermaid browser bundle：
11.16.0，构建时校验完整 SHA-256 后同源发布； - Wrangler 配置：
wrangler.jsonc； - 部署脚本：
scripts/deploy_cloudflare_pages.sh。
站点是纯静态文档，当前不使用 KV、D1、R2 或 Pages Functions。研究数字继续以
research/ 和实验 JSON 为事实源，不把 Cloudflare 变成第二份数据库。
本地验证与部署¶
首次准备文档环境：
部署：
脚本按顺序执行 registry 校验、生成页面陈旧检查、固定 Mermaid asset 校验和 MkDocs 严格构建，
然后只上传 site/。Mermaid 不在读者打开页面时临时依赖第三方 CDN；构建器从固定 URL 获取后
要求 SHA-256 精确为 74d7c46d…58fb9b，再随站点同源上传。部署记录附带当前 Git commit、
commit message 和 dirty 状态。生产部署前应优先保持工作树干净。
预览服务可以使用：
发布前安全检查¶
每次部署至少确认：
mkdocs build --strict无警告；site/中没有 secret、邮箱、本机绝对路径或私有语料；- 没有模型 checkpoint、原始音频或超过 Cloudflare 限额的文件；
- 页面中的作者声明和本地结果仍明确分栏；
- 当前 commit 已推送，部署可从 Cloudflare deployment 追溯。