first commit

2026-06-03 10:09:03 +08:00
commit 81f5039458
6266 changed files with 188236 additions and 0 deletions
@@ -0,0 +1,295 @@
+# 七牛云上传功能文档索引
+
+## 快速开始
+
+如果你想快速测试七牛云上传功能，请按以下顺序阅读：
+
+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