296 lines
8.1 KiB
Markdown
296 lines
8.1 KiB
Markdown
# 七牛云上传功能文档索引
|
||
|
||
## 快速开始
|
||
|
||
如果你想快速测试七牛云上传功能，请按以下顺序阅读：
|
||
|
||
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
|