8.1 KiB
8.1 KiB
七牛云上传功能文档索引
快速开始
如果你想快速测试七牛云上传功能，请按以下顺序阅读：
-
七牛云上传测试步骤 ⭐ 推荐先看
- 测试前的准备工作
- 详细的测试步骤
- 常见问题排查
-
- 了解最近修复的区域配置问题
- 查看修复的具体内容
-
- 完整的技术文档
- API 接口说明
- 代码使用示例
-
- 可视化流程图
- 帮助理解上传机制
文档说明
七牛云上传测试步骤.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. 显示上传成功
详细流程
支持的区域
| 区域代码 | 区域名称 | 上传地址 | 状态 |
|---|---|---|---|
| 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
Q2: 上传时出现 "incorrect region" 错误？
A: 已修复。参见 七牛云区域配置修复说明.md
Q3: 如何切换到其他区域？
A: 修改数据库配置即可，无需改代码：
UPDATE system_storage_config
SET qiniu_region = 'z1' -- 切换到华北
WHERE id = 1;
Q4: 如何在其他页面使用上传功能？
A: 参见 七牛云直传配置.md 的"前端使用"章节
Q5: 大文件上传会超时吗？
A: 不会。七牛云 SDK 支持：
- 自动分片上传
- 断点续传
- 并发上传
- 前端已设置
timeout: 0（无超时限制）
Q6: 上传是否经过服务器？
A: 不经过。前端直接上传到七牛云，服务器只负责：
- 生成上传凭证
- 保存文件记录到数据库
Q7: 如何回滚到本地存储？
A: 修改数据库配置：
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
相关链接
联系方式
如有问题，请联系开发团队。
更新日期
2026-04-09