跳转至

文档站发布操作指南

本仓库的文档站由 MkDocs Material 驱动，支持两种免费托管方案。代码与配置已全部就绪，你只需完成下文标注「你需要做」的步骤即可上线。

文档站技术栈

组件 说明
文档框架 MkDocs Material — 开源项目最流行的文档主题
配置文件 mkdocs.yml（仓库根目录）
文档源 仓库根目录所有 .md 文件（复用现有文档，无需迁移）
首页 index.md
构建产物 site/ 目录（已加入 .gitignore，不入库）
部署方式 A GitHub Actions → GitHub Pages（推荐，最简单）
部署方式 B Cloudflare Pages（国内访问更快，无限带宽）

本地预览（可选）

# 安装依赖
pip install mkdocs mkdocs-material pymdown-extensions

# 本地预览（浏览器打开 http://127.0.0.1:8000）
mkdocs serve

# 本地构建（产物在 site/）
mkdocs build --clean

方案 A：GitHub Pages（推荐，最简单）

工作原理

代码已经配好：

  1. mkdocs.yml — 文档站配置
  2. .github/workflows/docs-pages.yml — GitHub Actions 自动构建部署脚本
  3. 当你 push 到 master 分支且改动了文档相关文件时，Action 自动触发：安装 MkDocs → 构建站点 → 发布到 GitHub Pages

你需要做的（一次性，约 2 分钟）

前置条件

你需要对仓库 charliedream1/ai_quant_trade 有 admin 权限。

步骤 1：确认 workflow 已随本次提交推送到 GitHub

在 GitHub 仓库页面进入 Actions 标签页，应能看到名为 Deploy MkDocs to GitHub Pages 的 workflow。如果没有，说明本次提交还未推送，先执行：

git push origin master

步骤 2：开启 GitHub Pages 的 Actions 源

  1. 打开 https://github.com/charliedream1/ai_quant_trade/settings/pages
  2. 在 Build and deployment 区域：
  3. Source 下拉框选择 GitHub Actions（不是 "Deploy from a branch"）
  4. 保存（页面会自动保存，无需点确认）

步骤 3：触发首次部署

  • 方式一（自动）：随便改一个文档文件并 push 到 master，workflow 自动触发
  • 方式二（手动）：进 Actions 标签页 → 选 Deploy MkDocs to GitHub Pages → 右侧 Run workflow 按钮 → 选 master 分支 → 点绿色按钮运行

步骤 4：访问文档站

部署成功后（约 2-3 分钟），打开：

https://charliedream1.github.io/ai_quant_trade/

后续维护

完全自动：以后只要 push 文档改动到 master，GitHub Actions 会自动重新构建并发布，无需任何手动操作。

常见问题

Actions 报错 mkdocs build --strict 失败

--strict 模式会把文档里找不到的链接、缺失文件当作错误。检查 mkdocs.yml 的 nav 里引用的 .md 路径是否都存在。

访问 GitHub Pages 显示 404
  1. 确认 Settings → Pages 的 Source 是 GitHub Actions（不是 branch）
  2. 确认 Actions 标签页里最新一次运行是绿色对勾
  3. GitHub Pages 首次生效可能需要 5-10 分钟
想改文档站主题色 / 导航结构

编辑 mkdocs.yml： - 主题色：theme.palette 下的 primary - 导航：nav 字段

方案 B：Cloudflare Pages（国内访问更快）

适合场景

  • 文档站访问者主要在中国大陆（Cloudflare CDN 国内速度优于 GitHub Pages）
  • 担心 GitHub Pages 100GB/月带宽不够（Cloudflare Pages 无限带宽）
  • 想要 DDoS 防护等额外安全功能

你需要做的（一次性，约 5 分钟）

步骤 1：注册 Cloudflare 账号

打开 https://dash.cloudflare.com/sign-up 注册（免费，无需信用卡）。如已有账号跳过。

步骤 2：创建 Pages 项目

  1. 登录后进入 https://dash.cloudflare.com/ → 左侧选 Workers & Pages
  2. 点 Create application → Pages 标签 → Connect to Git
  3. 授权 Cloudflare 访问你的 GitHub：点 Connect to Git → 选 GitHub → 授权 → 选中仓库 ai_quant_trade

  4. 填写项目配置：

    配置项 填写内容
    Project name ai-quant-trade-docs
    Production branch master
    Framework preset None
    Build command bash .cloudflare/scripts/build.sh
    Build output directory site
    Environment variables PYTHON_VERSION = 3.11

  5. 点 Save and Deploy

步骤 3：等待首次构建

Cloudflare 会自动拉取代码、执行 build.sh（安装 MkDocs + 构建）、部署。约 3-5 分钟。在 Pages 项目页能看到构建日志。

步骤 4：访问文档站

部署成功后，Cloudflare 会分配一个域名：

https://ai-quant-trade-docs.pages.dev/

后续维护

完全自动：以后 push 到 master，Cloudflare 自动重新构建部署。

可选：绑定自定义域名

  1. Pages 项目 → Custom domains → Set up a custom domain
  2. 输入你的域名（如 docs.yourdomain.com）
  3. 按提示在域名 DNS 添加 CNAME 记录指向 ai-quant-trade-docs.pages.dev
  4. Cloudflare 自动配置 HTTPS

常见问题

构建失败：Python 版本不对

在 Cloudflare Pages 项目设置 → Settings → Environment variables 添加 PYTHON_VERSION=3.11。Cloudflare Pages 默认环境已含 Python，但版本可能较旧。

构建失败：pip install 超时

Cloudflare 构建环境网络偶发波动，重试一次即可。也可在 build.sh 里加国内镜像源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

两种方案对比

维度 GitHub Pages（方案 A） Cloudflare Pages（方案 B）
你的手动操作 1 处（Settings 选 Actions 源） 5-6 处（注册+授权+配置）
手动操作耗时 ~2 分钟 ~5 分钟
带宽 100GB/月 无限
国内访问速度 一般 快
商业用途 灰色地带 明确允许
HTTPS 自动 自动
自定义域名 支持 支持
额外功能 无 DDoS 防护、Workers

建议

  • 只选一个：两种方案都从同一个 master 分支自动部署，同时启用会维护两份，没必要
  • 默认选 A（GitHub Pages）：操作最少，与 GitHub 生态无缝
  • 国内用户多选 B（Cloudflare Pages）：速度优势明显

我已经帮你做好的部分（无需你操作）

文件 作用
mkdocs.yml 文档站主配置（主题、导航、扩展）
index.md 文档站首页
.github/workflows/docs-pages.yml GitHub Pages 自动部署 workflow
.cloudflare/scripts/build.sh Cloudflare Pages 构建脚本
.cloudflare/wrangler.toml Cloudflare CLI 部署配置（可选）
.gitignore 已添加 site/ 排除构建产物

故障排查清单

如果部署失败，按顺序检查：

  1. 本地能否构建成功 

    pip install mkdocs mkdocs-material pymdown-extensions
mkdocs build --strict --clean
    若本地报错，先修文档（通常是 mkdocs.yml 的 nav 引用了不存在的文件）。

  2. GitHub Actions 日志 https://github.com/charliedream1/ai_quant_trade/actions — 点开失败的运行看红色错误行。

  3. Cloudflare 构建日志 Cloudflare Dashboard → Pages → 你的项目 → Deployments → 点失败的部署看日志。

  4. Pages 设置 https://github.com/charliedream1/ai_quant_trade/settings/pages — 确认 Source 是 GitHub Actions。

如遇问题，可在 https://github.com/charliedream1/ai_quant_trade/issues 提 issue。