# 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。