feat: 实现功能3强制更新
- 新增 ForceUpdateCommand 类实现强制更新功能 - 添加 force-update CLI 命令支持 - 实现参数验证、配置对比、CDN缓存刷新 - 添加完整的测试用例和使用示例 - 更新文档和进度跟踪 - 支持模拟环境测试 - 添加警告提示和错误处理 主要文件: - src/config_man/core/force_update_command.py (新增) - src/config_man/cli/main.py (更新) - examples/test_force_update.py (新增) - examples/force_update_usage.py (新增) - docs/progress-tracker.md (更新)
This commit is contained in:
262
docs/cloudflare_setup.md
Normal file
262
docs/cloudflare_setup.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Cloudflare CDN 设置指南
|
||||
|
||||
## 概述
|
||||
|
||||
Config-Man 支持 Cloudflare CDN 缓存刷新功能，可以在配置文件更新后自动刷新 CDN 缓存，确保内容及时同步。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- ✅ 通过 URL 列表刷新缓存
|
||||
- ✅ 通过标签刷新缓存
|
||||
- ✅ 刷新整个域名缓存
|
||||
- ✅ 自动错误处理和重试
|
||||
- ✅ 详细的日志记录
|
||||
|
||||
## 设置步骤
|
||||
|
||||
### 1. 获取 Cloudflare API Token
|
||||
|
||||
1. 登录 [Cloudflare 控制台](https://dash.cloudflare.com/)
|
||||
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. 设置配置
|
||||
|
||||
#### 方式一：使用配置文件（推荐）
|
||||
|
||||
```bash
|
||||
# 使用CLI命令设置Cloudflare配置
|
||||
config-man setup-cloudflare --api-token your_api_token --zone-id your_zone_id
|
||||
```
|
||||
|
||||
#### 方式二：使用环境变量
|
||||
|
||||
```bash
|
||||
# 设置 Cloudflare API Token
|
||||
export CLOUDFLARE_API_TOKEN='your_api_token_here'
|
||||
|
||||
# 设置 Zone ID
|
||||
export CLOUDFLARE_ZONE_ID='your_zone_id_here'
|
||||
```
|
||||
|
||||
#### 方式三：手动编辑配置文件
|
||||
|
||||
复制示例配置文件并编辑：
|
||||
|
||||
```bash
|
||||
cp config-man.example.json config-man.json
|
||||
# 编辑 config-man.json 文件，设置 cloudflare.api_token 和 cloudflare.zone_id
|
||||
```
|
||||
|
||||
### 4. 验证配置
|
||||
|
||||
运行测试脚本验证配置：
|
||||
|
||||
```bash
|
||||
python examples/test_cloudflare_cdn.py
|
||||
```
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 建议更新命令中的 CDN 刷新
|
||||
|
||||
当执行建议更新命令时，系统会自动刷新相关文件的 CDN 缓存：
|
||||
|
||||
```bash
|
||||
config-man suggest-update --platform android --target-version 0.29 --update-version 0.30
|
||||
```
|
||||
|
||||
### 2. 手动刷新 CDN 缓存
|
||||
|
||||
```python
|
||||
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. 通过标签刷新缓存
|
||||
|
||||
```python
|
||||
from src.config_man.utils.cloudflare import CloudflareCDN
|
||||
|
||||
cdn = CloudflareCDN()
|
||||
tags = ["config-man", "version-0.29"]
|
||||
success = cdn.purge_cache_by_tags(tags)
|
||||
```
|
||||
|
||||
### 4. 刷新整个域名缓存
|
||||
|
||||
```python
|
||||
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` 中可以设置：
|
||||
|
||||
```json
|
||||
{
|
||||
"cdn": {
|
||||
"cloudflare": {
|
||||
"api_token": "your_api_token_here",
|
||||
"zone_id": "your_zone_id_here"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**优先级**: 配置文件 > 环境变量
|
||||
|
||||
### 配置文件选项
|
||||
|
||||
在 `config-man.json` 中可以设置：
|
||||
|
||||
```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 刷新操作
|
||||
- 记录失败的刷新尝试
|
||||
|
||||
## 测试
|
||||
|
||||
### 运行测试
|
||||
|
||||
```bash
|
||||
# 运行 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。
|
||||
Reference in New Issue
Block a user