🌐 WxBot Enhanced - Cloudflare Pages 部署指南¶

本文档介绍如何将WxBot Enhanced文档部署到Cloudflare Pages。

🚀 快速开始¶

1. 获取Cloudflare API凭证¶

登录Cloudflare控制台: https://dash.cloudflare.com
获取Account ID:
右侧边栏找到 "Account ID"
复制Account ID值
创建API Token:
点击右上角用户头像 → "My Profile"
切换到 "API Tokens" 标签
点击 "Create Token"
选择 "Custom token"

2. API Token权限配置¶

创建Token时设置以下权限：

Permissions:
  - Account - Cloudflare Pages:Edit
  - Zone - Zone Settings:Read
  - Zone - Zone:Read

Account Resources:
  - Include - All accounts

Zone Resources:
  - Include - All zones (或选择特定域名)

3. 配置GitHub Secrets¶

在GitHub仓库中添加以下Secrets：

Settings → Secrets and variables → Actions → New repository secret

需要添加的Secrets:

Secret名称	值	说明
`CLOUDFLARE_API_TOKEN`	你的API Token	用于API认证
`CLOUDFLARE_ACCOUNT_ID`	你的Account ID	Cloudflare账户标识

4. 创建Cloudflare Pages项目¶

进入Pages控制台: https://dash.cloudflare.com/pages
创建新项目:
点击 "Create a project"
选择 "Direct Upload" (因为我们使用GitHub Actions部署)
项目名称: wxbot-enhanced-docs
点击 "Create project"

📁 项目结构¶

部署后的目录结构：

wxbot-enhanced-docs/
├── index.html                 # 文档首页
├── quickstart/               # 快速开始
├── development/              # 开发文档
├── api/                      # API参考
├── operations/               # 运维指南
├── games/                    # 游戏功能
├── assets/                   # 静态资源
│   ├── stylesheets/
│   ├── javascripts/
│   └── images/
└── sitemap.xml              # 站点地图

⚙️ 自定义配置¶

自定义域名¶

如果你有自己的域名，可以配置自定义域名：

添加域名:
在Cloudflare Pages项目中点击 "Custom domains"
点击 "Set up a custom domain"
输入你的域名（如：docs.wxbot.com）

DNS配置:

Type: CNAME
Name: docs (或你的子域名)
Target: wxbot-enhanced-docs.pages.dev

环境变量¶

如果需要在构建时使用环境变量：

# 在 .github/workflows/deploy-cf.yml 中添加
env:
  SITE_URL: https://docs.wxbot.com
  ENABLE_ANALYTICS: true

重定向规则¶

创建 docs/_redirects 文件配置重定向：

# 重定向规则示例
/old-page /new-page 301
/api/* /api-reference/:splat 200

🔧 构建配置¶

MkDocs配置优化¶

更新 mkdocs.yml 以适配Cloudflare Pages：

# 添加到mkdocs.yml
site_url: https://wxbot-enhanced-docs.pages.dev  # 或你的自定义域名

# CDN优化
extra:
  # 启用CDN加速
  social:
    - icon: fontawesome/brands/cloudflare
      link: https://pages.cloudflare.com

# 构建优化
plugins:
  - search:
      lang: zh
  - minify:  # 压缩HTML/CSS/JS
      minify_html: true
      minify_js: true
      minify_css: true
  - optimize  # 图片优化

构建脚本优化¶

更新 scripts/build-docs.sh 添加Cloudflare Pages支持：

# 添加Cloudflare Pages部署功能
deploy_cloudflare() {
    print_status "部署到Cloudflare Pages..."

    if [[ -z "$CLOUDFLARE_API_TOKEN" ]]; then
        print_error "未设置CLOUDFLARE_API_TOKEN环境变量"
        exit 1
    fi

    # 构建文档
    build_docs

    # 上传到Cloudflare Pages
    npx wrangler pages publish site \
        --project-name=wxbot-enhanced-docs \
        --compatibility-date=2024-01-01

    print_success "部署完成"
}

📊 部署状态监控¶

部署成功指标¶

✅ 构建时间: 通常2-5分钟
✅ CDN传播: 全球节点1-3分钟
✅ SSL证书: 自动配置HTTPS
✅ 访问速度: 全球CDN加速

常见问题排查¶

构建失败:

# 检查MkDocs配置
mkdocs build --strict --verbose

API Token权限不足:
```
Error: Authentication error
```
检查Token权限配置
确认Account ID正确
项目名称冲突:
```
Error: Project name already exists
```
修改workflow中的projectName
或删除现有项目重新创建

🌍 访问地址¶

部署成功后，你的文档将在以下地址可用：

默认地址: https://wxbot-enhanced-docs.pages.dev
自定义域名: https://docs.yourdomain.com (如果配置)

🔄 自动部署流程¶

推送代码 → GitHub仓库
触发构建 → GitHub Actions
构建文档 → MkDocs build
上传部署 → Cloudflare Pages
CDN分发 → 全球节点
访问就绪 → 用户可访问

📈 性能优势¶

⚡ 极速访问: 全球CDN节点
🔒 自动HTTPS: 免费SSL证书
📱 移动优化: 响应式设计
🔍 SEO友好: 自动sitemap生成
📊 访问统计: 内置分析工具

💡 最佳实践¶

图片优化: 使用WebP格式，压缩图片大小
缓存策略: 配置合适的Cache-Control头
监控部署: 设置部署通知和监控
备份方案: 保持多个部署平台备份

**🌐 Cloudflare Pages让你的文档飞起来！** **全球CDN + 自动HTTPS + 无限带宽 = 完美体验**