config-man/docs/cloudflare_setup.md

Cloudflare CDN 设置指南

概述

Config-Man 支持 Cloudflare CDN 缓存刷新功能，可以在配置文件更新后自动刷新 CDN 缓存，确保内容及时同步。

功能特性

• ✅ 通过 URL 列表刷新缓存
• ✅ 通过标签刷新缓存
• ✅ 刷新整个域名缓存
• ✅ 自动错误处理和重试
• ✅ 详细的日志记录

设置步骤

1. 获取 Cloudflare API Token

1. 登录 Cloudflare 控制台
2. 进入 "My Profile" -> "API Tokens"
3. 点击 "Create Token"
4. 选择 "Custom token" 模板
5. 设置权限：
   • Zone:Zone:Read - 读取域名信息
   • Zone:Cache Purge:Edit - 清除缓存
6. 设置 Zone Resources：
   • 选择 "Include" -> "Specific zone" -> 选择你的域名
7. 点击 "Continue to summary" -> "Create Token"
8. 复制生成的 API Token

2. 获取 Zone ID

1. 在 Cloudflare 控制台中选择你的域名
2. 在右侧边栏找到 "Zone ID"
3. 复制 Zone ID

3. 设置配置

方式一：使用配置文件（推荐）

# 使用CLI命令设置Cloudflare配置
config-man setup-cloudflare --api-token your_api_token --zone-id your_zone_id

方式二：使用环境变量

# 设置 Cloudflare API Token
export CLOUDFLARE_API_TOKEN='your_api_token_here'

# 设置 Zone ID
export CLOUDFLARE_ZONE_ID='your_zone_id_here'

方式三：手动编辑配置文件

复制示例配置文件并编辑：

cp config-man.example.json config-man.json
# 编辑 config-man.json 文件，设置 cloudflare.api_token 和 cloudflare.zone_id

4. 验证配置

运行测试脚本验证配置：

python examples/test_cloudflare_cdn.py

使用方法

1. 建议更新命令中的 CDN 刷新

当执行建议更新命令时，系统会自动刷新相关文件的 CDN 缓存：

config-man suggest-update --platform android --target-version 0.29 --update-version 0.30

2. 手动刷新 CDN 缓存

from src.config_man.utils.cloudflare import refresh_cloudflare_cache

# 刷新指定 URL 的缓存
urls = [
    "https://your-domain.com/path/to/file.json"
]
success = refresh_cloudflare_cache(urls)

3. 通过标签刷新缓存

from src.config_man.utils.cloudflare import CloudflareCDN

cdn = CloudflareCDN()
tags = ["config-man", "version-0.29"]
success = cdn.purge_cache_by_tags(tags)

4. 刷新整个域名缓存

from src.config_man.utils.cloudflare import CloudflareCDN

cdn = CloudflareCDN()
success = cdn.purge_entire_cache()

配置选项

配置选项

环境变量

变量名	说明	必需
CLOUDFLARE_API_TOKEN	Cloudflare API Token	是
CLOUDFLARE_ZONE_ID	Cloudflare Zone ID	是

配置文件选项

在 config-man.json 中可以设置：

{
  "cdn": {
    "cloudflare": {
      "api_token": "your_api_token_here",
      "zone_id": "your_zone_id_here"
    }
  }
}

优先级: 配置文件 > 环境变量

配置文件选项

在 config-man.json 中可以设置：

{
  "cdn": {
    "timeout": 10,
    "retry_count": 3
  }
}

选项	说明	默认值
timeout	API 请求超时时间（秒）	10
retry_count	重试次数	3

错误处理

常见错误

1. 配置不完整

   警告: Cloudflare配置不完整，跳过CDN缓存刷新
   请设置以下环境变量:
     CLOUDFLARE_API_TOKEN: Cloudflare API Token
     CLOUDFLARE_ZONE_ID: Cloudflare Zone ID
   

2. API 权限不足

   Cloudflare API错误: [{'code': 10000, 'message': 'Authentication error'}]
   

3. Zone ID 错误

   Cloudflare API请求失败: 400 - {"success":false,"errors":[{"code":7003,"message":"Invalid zone id"}]}
   

故障排除

1. 检查 API Token 权限

   • 确保 Token 有 Zone:Cache Purge:Edit 权限
   • 确保 Token 适用于正确的域名

2. 检查 Zone ID

   • 确保 Zone ID 正确
   • 确保域名在 Cloudflare 中激活

3. 检查网络连接

   • 确保可以访问 Cloudflare API
   • 检查防火墙设置

安全注意事项

1. API Token 安全

   • 不要在代码中硬编码 API Token
   • 使用环境变量存储敏感信息
   • 定期轮换 API Token

2. 权限最小化

   • 只授予必要的权限
   • 定期审查 API Token 权限

3. 监控和日志

   • 监控 CDN 刷新操作
   • 记录失败的刷新尝试

测试

运行测试

# 运行 Cloudflare CDN 测试
python examples/test_cloudflare_cdn.py

# 运行建议更新测试（包含 CDN 刷新）
python examples/test_suggest_update.py

测试内容

• ✅ Cloudflare 配置验证
• ✅ API Token 权限检查
• ✅ 域名信息获取
• ✅ URL 缓存刷新
• ✅ 标签缓存刷新
• ✅ 整个缓存刷新
• ✅ 建议更新中的 CDN 刷新

示例输出

成功刷新

信息: 正在刷新Cloudflare CDN缓存: https://your-domain.com/path/to/file.json
✅ Cloudflare CDN缓存刷新成功: https://your-domain.com/path/to/file.json

配置不完整

信息: 正在刷新Cloudflare CDN缓存: https://your-domain.com/path/to/file.json
警告: Cloudflare配置不完整，跳过CDN缓存刷新
请设置以下环境变量:
  CLOUDFLARE_API_TOKEN: Cloudflare API Token
  CLOUDFLARE_ZONE_ID: Cloudflare Zone ID
警告: Cloudflare CDN缓存刷新失败: https://your-domain.com/path/to/file.json

总结

Cloudflare CDN 刷新功能已完全集成到 Config-Man 中，提供了：

1. 自动化集成: 建议更新命令自动刷新相关缓存
2. 灵活控制: 支持多种刷新方式
3. 错误处理: 完善的错误处理和重试机制
4. 安全可靠: 基于官方 API 的安全实现

按照本指南设置后，Config-Man 将能够自动管理 Cloudflare CDN 缓存，确保配置文件更新后及时同步到 CDN。