# 七牛云上传功能文档索引

## 快速开始

如果你想快速测试七牛云上传功能，请按以下顺序阅读：

1. **[七牛云上传测试步骤](./七牛云上传测试步骤.md)** ⭐ 推荐先看
   - 测试前的准备工作
   - 详细的测试步骤
   - 常见问题排查

2. **[七牛云区域配置修复说明](./七牛云区域配置修复说明.md)**
   - 了解最近修复的区域配置问题
   - 查看修复的具体内容

3. **[七牛云直传配置](./七牛云直传配置.md)**
   - 完整的技术文档
   - API 接口说明
   - 代码使用示例

4. **[七牛云区域配置流程图](./七牛云区域配置流程图.md)**
   - 可视化流程图
   - 帮助理解上传机制

## 文档说明

### 七牛云上传测试步骤.md
**适合人群**: 测试人员、开发人员

**内容**:
- 测试前的准备工作
- 详细的测试步骤
- 验证方法
- 常见问题排查
- 性能测试指南

**何时阅读**: 准备测试上传功能时

---

### 七牛云区域配置修复说明.md
**适合人群**: 开发人员、运维人员

**内容**:
- 问题描述和原因分析
- 解决方案详解
- 修复的文件列表
- 验证步骤
- 区域切换方法

**何时阅读**: 遇到区域配置问题或想了解修复细节时

---

### 七牛云直传配置.md
**适合人群**: 开发人员

**内容**:
- 上传流程对比（旧 vs 新）
- 安装依赖
- 后端 API 文档
- 前端使用示例
- 工作原理
- 安全性说明
- 性能优化
- 故障排查
- 迁移指南

**何时阅读**: 需要了解完整技术实现或集成到其他页面时

---

### 七牛云区域配置流程图.md
**适合人群**: 所有人

**内容**:
- 问题和解决方案的可视化对比
- 完整上传流程图
- 区域映射关系图
- 代码对比
- 优势对比

**何时阅读**: 想快速理解上传机制时

---

## 最近更新 (2026-04-09)

### ✅ 已完成
- 修复了七牛云区域配置问题
- 添加了 `getQiniuRegion()` 函数
- 实现了动态区域配置
- 创建了完整的测试文档

### 🔧 修复的问题
**问题**: 上传时出现 "incorrect region" 错误

**原因**: 前端硬编码区域为 z0（华东），但数据库配置为 z2（华南）

**解决**: 前端动态从后端获取区域配置，自动使用正确的区域

### 📝 涉及的文件
- `platform/src/utils/qiniuUpload.js` - 添加区域映射函数
- `go/controllers/qiniu_upload.go` - 返回区域配置
- `platform/docs/*.md` - 创建文档

---

## 技术架构

```
┌─────────────────────────────────────────────────────────┐
│                    七牛云直传架构                         │
└─────────────────────────────────────────────────────────┘

前端 (Vue3)
├── platform/src/utils/qiniuUpload.js
│   ├── smartUpload()        - 智能选择上传方式
│   ├── uploadToQiniu()      - 七牛云直传
│   ├── uploadToLocal()      - 本地上传（中转）
│   ├── getStorageConfig()   - 获取存储配置
│   ├── getQiniuToken()      - 获取上传凭证
│   ├── saveFileRecord()     - 保存文件记录
│   ├── batchUpload()        - 批量上传
│   └── getQiniuRegion()     - 区域映射 ⭐ 新增
│
└── platform/src/views/platform/softwareupgrade/components/edit.vue
    └── 使用 smartUpload() 上传文件

后端 (Go + Beego)
├── go/controllers/qiniu_upload.go
│   ├── GetStorageConfig()   - 获取存储配置
│   ├── GetUploadToken()     - 生成上传凭证
│   ├── SaveFileRecord()     - 保存文件记录
│   └── getQiniuUploadURL()  - 获取上传地址
│
├── go/routers/platform/platform.go
│   ├── GET  /platform/storage/config
│   ├── GET  /platform/qiniu/token
│   └── POST /platform/qiniu/save
│
└── go/models/storage_config.go
    └── GetStorageConfig()   - 从数据库读取配置

数据库 (MySQL)
├── system_storage_config    - 存储配置表
│   ├── storage_type         - 存储类型 (local/qiniu)
│   ├── qiniu_region         - 七牛云区域 (z0/z1/z2/...)
│   ├── qiniu_bucket         - 存储空间名称
│   ├── qiniu_domain         - 访问域名
│   ├── qiniu_access_key     - AccessKey
│   └── qiniu_secret_key     - SecretKey
│
└── system_file              - 文件记录表
    ├── id                   - 文件 ID
    ├── name                 - 文件名
    ├── src                  - 文件 URL
    ├── size                 - 文件大小
    ├── md5                  - 文件 MD5
    └── ...

七牛云 (Qiniu Cloud)
└── 存储空间: yunzerwebsite
    ├── 区域: z2 (华南)
    ├── 域名: http://7colud.yunzer.cn
    └── 上传地址: https://up-z2.qiniup.com
```

---

## 上传流程

### 简化流程
```
1. 用户选择文件
   ↓
2. 前端获取存储配置 (storageType: 'qiniu')
   ↓
3. 前端获取上传凭证 (token, region: 'z2')
   ↓
4. 前端直接上传到七牛云 (up-z2.qiniup.com)
   ↓
5. 前端保存文件记录到数据库
   ↓
6. 显示上传成功
```

### 详细流程
参见 [七牛云区域配置流程图.md](./七牛云区域配置流程图.md)

---

## 支持的区域

| 区域代码 | 区域名称 | 上传地址 | 状态 |
|---------|---------|---------|------|
| z0 | 华东 | up-z0.qiniup.com | ✓ 支持 |
| z1 | 华北 | up-z1.qiniup.com | ✓ 支持 |
| z2 | 华南 | up-z2.qiniup.com | ✓ 支持 (当前) |
| na0 | 北美 | up-na0.qiniup.com | ✓ 支持 |
| as0 | 新加坡 | up-as0.qiniup.com | ✓ 支持 |
| cn-east-2 | 华东-浙江2 | up-cn-east-2.qiniup.com | ✓ 支持 |

---

## 常见问题

### Q1: 如何测试上传功能？
**A**: 参见 [七牛云上传测试步骤.md](./七牛云上传测试步骤.md)

### Q2: 上传时出现 "incorrect region" 错误？
**A**: 已修复。参见 [七牛云区域配置修复说明.md](./七牛云区域配置修复说明.md)

### Q3: 如何切换到其他区域？
**A**: 修改数据库配置即可，无需改代码：
```sql
UPDATE system_storage_config 
SET qiniu_region = 'z1'  -- 切换到华北
WHERE id = 1;
```

### Q4: 如何在其他页面使用上传功能？
**A**: 参见 [七牛云直传配置.md](./七牛云直传配置.md) 的"前端使用"章节

### Q5: 大文件上传会超时吗？
**A**: 不会。七牛云 SDK 支持：
- 自动分片上传
- 断点续传
- 并发上传
- 前端已设置 `timeout: 0`（无超时限制）

### Q6: 上传是否经过服务器？
**A**: 不经过。前端直接上传到七牛云，服务器只负责：
- 生成上传凭证
- 保存文件记录到数据库

### Q7: 如何回滚到本地存储？
**A**: 修改数据库配置：
```sql
UPDATE system_storage_config 
SET storage_type = 'local' 
WHERE id = 1;
```
前端会自动切换到本地上传方式。

---

## 性能对比

### 旧方案（服务器中转）
```
100MB 文件上传时间：
- 上传到服务器：2 分钟
- 服务器上传到七牛云：2 分钟
- 总计：4 分钟
```

### 新方案（直传）
```
100MB 文件上传时间：
- 直接上传到七牛云：2 分钟
- 总计：2 分钟
```

**效率提升**: 50%

---

## 依赖

### 前端
- `qiniu-js@^3.4.4` - 七牛云 JavaScript SDK

### 后端
- `github.com/qiniu/go-sdk/v7@v7.18.2` - 七牛云 Go SDK

---

## 相关链接

- [七牛云官方文档](https://developer.qiniu.com/)
- [七牛云存储区域](https://developer.qiniu.com/kodo/1671/region-endpoint-fq)
- [qiniu-js SDK 文档](https://developer.qiniu.com/kodo/1283/javascript)

---

## 联系方式

如有问题，请联系开发团队。

---

## 更新日期

2026-04-09