# 七牛云区域配置流程图

## 问题：区域不匹配

```
┌─────────────────────────────────────────────────────────────┐
│                      修复前（错误）                           │
└─────────────────────────────────────────────────────────────┘

前端代码                    后端数据库                七牛云服务器
┌──────────┐              ┌──────────┐              ┌──────────┐
│          │              │          │              │          │
│ 硬编码:   │              │ 配置:     │              │ 实际:     │
│ region:  │              │ qiniu_   │              │ bucket   │
│ z0 (华东) │  ────X────>  │ region:  │  ────X────>  │ 在 z2    │
│          │   不匹配      │ z2 (华南) │   不匹配      │ (华南)   │
│          │              │          │              │          │
└──────────┘              └──────────┘              └──────────┘
                                                           │
                                                           ▼
                                                    ┌──────────┐
                                                    │  错误:    │
                                                    │ incorrect│
                                                    │  region  │
                                                    └──────────┘
```

## 解决方案：动态获取区域

```
┌─────────────────────────────────────────────────────────────┐
│                      修复后（正确）                           │
└─────────────────────────────────────────────────────────────┘

前端                      后端                      七牛云
┌──────────┐            ┌──────────┐            ┌──────────┐
│          │            │          │            │          │
│ 1. 请求   │            │ 2. 查询   │            │          │
│ 获取配置  │  ───────>  │ 数据库    │            │          │
│          │            │          │            │          │
└──────────┘            └──────────┘            └──────────┘
     │                       │
     │                       ▼
     │                  ┌──────────┐
     │                  │ 返回:     │
     │  <───────────    │ region:  │
     │                  │ 'z2'     │
     │                  └──────────┘
     ▼
┌──────────┐
│ 3. 调用   │
│ getQiniu │
│ Region() │
└──────────┘
     │
     ▼
┌──────────┐            ┌──────────┐            ┌──────────┐
│ 4. 使用   │            │          │            │          │
│ qiniu.   │            │          │            │ 5. 上传   │
│ region.  │  ───────────────────────────────>  │ 成功 ✓   │
│ z2       │     上传到 up-z2.qiniup.com        │          │
│          │                                    │          │
└──────────┘                                    └──────────┘
```

## 详细流程

```
┌─────────────────────────────────────────────────────────────┐
│                    完整上传流程                               │
└─────────────────────────────────────────────────────────────┘

用户操作                前端                    后端                    七牛云
   │                    │                      │                      │
   │ 1. 点击上传         │                      │                      │
   ├──────────────────> │                      │                      │
   │                    │                      │                      │
   │                    │ 2. GET /platform/    │                      │
   │                    │    storage/config    │                      │
   │                    ├─────────────────────>│                      │
   │                    │                      │                      │
   │                    │                      │ 3. 查询数据库         │
   │                    │                      │    storage_type:     │
   │                    │                      │    'qiniu'           │
   │                    │                      │    qiniu_region:     │
   │                    │                      │    'z2'              │
   │                    │                      │                      │
   │                    │ 4. 返回配置           │                      │
   │                    │ { storageType:       │                      │
   │                    │   'qiniu',           │                      │
   │                    │   qiniuRegion: 'z2' }│                      │
   │                    │<─────────────────────│                      │
   │                    │                      │                      │
   │                    │ 5. GET /platform/    │                      │
   │                    │    qiniu/token       │                      │
   │                    ├─────────────────────>│                      │
   │                    │                      │                      │
   │                    │                      │ 6. 生成上传凭证       │
   │                    │                      │    (使用 AccessKey   │
   │                    │                      │     和 SecretKey)    │
   │                    │                      │                      │
   │                    │ 7. 返回 token 和配置  │                      │
   │                    │ { token: '...',      │                      │
   │                    │   region: 'z2',      │                      │
   │                    │   bucket: '...',     │                      │
   │                    │   uploadUrl:         │                      │
   │                    │   'up-z2.qiniup.com' }                      │
   │                    │<─────────────────────│                      │
   │                    │                      │                      │
   │                    │ 8. 调用              │                      │
   │                    │    getQiniuRegion('z2')                     │
   │                    │    返回: qiniu.region.z2                    │
   │                    │                      │                      │
   │                    │ 9. 直接上传文件       │                      │
   │                    │    (使用 qiniu-js SDK)                      │
   │                    ├──────────────────────────────────────────> │
   │                    │                      │                      │
   │                    │                      │                      │ 10. 接收文件
   │                    │                      │                      │     存储到 z2
   │                    │                      │                      │     (华南)
   │                    │                      │                      │
   │                    │ 11. 返回上传结果      │                      │
   │                    │ { key: '...',        │                      │
   │                    │   hash: '...',       │                      │
   │                    │   size: ... }        │                      │
   │                    │<──────────────────────────────────────────│
   │                    │                      │                      │
   │                    │ 12. POST /platform/  │                      │
   │                    │     qiniu/save       │                      │
   │                    │ { key, hash, size,   │                      │
   │                    │   name, mimeType }   │                      │
   │                    ├─────────────────────>│                      │
   │                    │                      │                      │
   │                    │                      │ 13. 保存到数据库      │
   │                    │                      │     system_file 表   │
   │                    │                      │                      │
   │                    │ 14. 返回文件信息      │                      │
   │                    │ { url: '...',        │                      │
   │                    │   id: 123,           │                      │
   │                    │   name: '...' }      │                      │
   │                    │<─────────────────────│                      │
   │                    │                      │                      │
   │ 15. 显示上传成功    │                      │                      │
   │<──────────────────│                      │                      │
   │                    │                      │                      │
```

## 区域映射关系

```
┌─────────────────────────────────────────────────────────────┐
│                  getQiniuRegion() 函数                        │
└─────────────────────────────────────────────────────────────┘

数据库配置          函数输入          函数输出              上传地址
┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────┐
│ qiniu_   │      │          │      │          │      │                  │
│ region:  │ ───> │ 'z0'     │ ───> │ qiniu.   │ ───> │ up-z0.qiniup.com │
│ 'z0'     │      │          │      │ region.z0│      │ (华东)            │
└──────────┘      └──────────┘      └──────────┘      └──────────────────┘

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────┐
│ qiniu_   │      │          │      │          │      │                  │
│ region:  │ ───> │ 'z1'     │ ───> │ qiniu.   │ ───> │ up-z1.qiniup.com │
│ 'z1'     │      │          │      │ region.z1│      │ (华北)            │
└──────────┘      └──────────┘      └──────────┘      └──────────────────┘

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────┐
│ qiniu_   │      │          │      │          │      │                  │
│ region:  │ ───> │ 'z2'     │ ───> │ qiniu.   │ ───> │ up-z2.qiniup.com │
│ 'z2'     │      │          │      │ region.z2│      │ (华南) ✓ 当前     │
└──────────┘      └──────────┘      └──────────┘      └──────────────────┘

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────┐
│ qiniu_   │      │          │      │          │      │                  │
│ region:  │ ───> │ 'na0'    │ ───> │ qiniu.   │ ───> │ up-na0.qiniup.com│
│ 'na0'    │      │          │      │ region.  │      │ (北美)            │
│          │      │          │      │ na0      │      │                  │
└──────────┘      └──────────┘      └──────────┘      └──────────────────┘

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────┐
│ qiniu_   │      │          │      │          │      │                  │
│ region:  │ ───> │ 'as0'    │ ───> │ qiniu.   │ ───> │ up-as0.qiniup.com│
│ 'as0'    │      │          │      │ region.  │      │ (新加坡)          │
│          │      │          │      │ as0      │      │                  │
└──────────┘      └──────────┘      └──────────┘      └──────────────────┘

┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────────────────┐
│ qiniu_   │      │          │      │          │      │                      │
│ region:  │ ───> │'cn-east-2'──────>│ qiniu.   │ ───> │up-cn-east-2.qiniup.  │
│'cn-east-2'      │          │      │ region.  │      │com (华东-浙江2)       │
│          │      │          │      │ cnEast2  │      │                      │
└──────────┘      └──────────┘      └──────────┘      └──────────────────────┘
```

## 代码对比

### 修复前（硬编码）

```javascript
// ❌ 错误：硬编码区域
const config = {
  useCdnDomain: true,
  region: qiniu.region.z0,  // 总是使用华东
};
```

### 修复后（动态配置）

```javascript
// ✓ 正确：动态获取区域
const { region } = tokenRes.data;  // 从后端获取: 'z2'
const qiniuRegion = getQiniuRegion(region);  // 转换为: qiniu.region.z2

const config = {
  useCdnDomain: true,
  region: qiniuRegion,  // 使用正确的区域
};
```

## 优势对比

```
┌─────────────────────────────────────────────────────────────┐
│                      硬编码方式                               │
└─────────────────────────────────────────────────────────────┘

缺点:
❌ 区域固定，无法灵活切换
❌ 修改区域需要改代码、重新部署
❌ 容易出现区域不匹配错误
❌ 不同环境需要不同的代码版本

┌─────────────────────────────────────────────────────────────┐
│                      动态配置方式                             │
└─────────────────────────────────────────────────────────────┘

优点:
✓ 区域灵活，可随时切换
✓ 修改区域只需改数据库配置
✓ 自动使用正确的区域
✓ 所有环境使用同一套代码
✓ 支持多租户不同区域配置
```

## 更新日期

2026-04-09