first commit

2026-06-03 10:09:03 +08:00
commit 81f5039458
6266 changed files with 188236 additions and 0 deletions
@@ -0,0 +1,201 @@
+# 七牛云上传测试步骤
+
+## 前置条件
+
+1. 数据库配置已正确设置：
+   - `storage_type = 'qiniu'`
+   - `qiniu_region = 'z2'` (华南)
+   - `qiniu_bucket = 'yunzerwebsite'`
+   - `qiniu_domain = 'http://7colud.yunzer.cn'`
+   - `qiniu_access_key` 和 `qiniu_secret_key` 已配置
+
+2. 前端依赖已安装：
+   - `qiniu-js@^3.4.4` ✓ (已在 package.json 中)
+
+3. 后端服务已重启：
+   ```bash
+   systemctl restart go-api
+   ```
+
+## 测试步骤
+
+### 1. 登录系统
+
+访问前端页面并登录：
+- URL: https://platform.yunzer.cn
+- 账号: hero920103
+- 密码: 920103
+
+### 2. 进入软件升级页面
+
+导航到：平台管理 → 软件升级
+
+### 3. 上传文件测试
+
+点击"新增"或"编辑"按钮，在弹出的对话框中：
+
+1. 点击"上传软件包"按钮
+2. 选择一个文件（建议先用小文件测试，如 1-10MB）
+3. 观察上传进度条
+4. 等待上传完成
+
+### 4. 验证上传结果
+
+#### 前端验证
+- 检查是否显示上传成功消息
+- 检查文件 URL 是否正确（应该是 `http://7colud.yunzer.cn/...`）
+- 检查文件是否可以预览/下载
+
+#### 后端日志验证
+```bash
+tail -f /www/wwwroot/api.yunzer.cn/go.log
+```
+
+查看日志中是否有：
+- `GET /platform/storage/config` - 获取存储配置
+- `GET /platform/qiniu/token` - 获取上传凭证
+- `POST /platform/qiniu/save` - 保存文件记录
+
+#### 七牛云控制台验证
+1. 登录七牛云控制台
+2. 进入 `yunzerwebsite` 存储空间
+3. 检查文件是否已上传
+4. 文件路径格式应为：`2026/04/09/时间戳.扩展名`
+
+#### 数据库验证
+```sql
+SELECT id, name, src, size, type, cate, md5, create_time 
+FROM system_file 
+ORDER BY id DESC 
+LIMIT 5;
+```
+
+检查：
+- `src` 字段应该是完整的七牛云 URL
+- `md5` 字段应该有值
+- `size` 字段应该正确
+
+## 预期结果
+
+### 成功标志
+1. 前端显示上传成功
+2. 文件 URL 格式正确：`http://7colud.yunzer.cn/2026/04/09/xxxxx.ext`
+3. 七牛云控制台能看到文件
+4. 数据库有对应记录
+5. 文件可以正常访问和下载
+
+### 上传流程
+```
+前端 → 获取存储配置 (storageType: 'qiniu')
+     → 获取上传凭证 (token, region: 'z2')
+     → 直接上传到七牛云 (up-z2.qiniup.com)
+     → 保存文件记录到数据库
+     → 返回文件 URL
+```
+
+## 常见问题排查
+
+### 问题 1: "incorrect region" 错误
+
+**错误信息**: 
+```
+xhr request failed, code: 400
+response: {"error":"incorrect region, please use up-z2.qiniup.com, bucket is: yunzerwebsite"}
+```
+
+**原因**: 前端使用的区域与七牛云 bucket 实际区域不匹配
+
+**解决**: 
+- 已修复：添加了 `getQiniuRegion()` 函数，根据后端返回的 region 动态设置
+- 后端返回 `region: 'z2'`，前端会自动使用 `qiniu.region.z2`
+
+### 问题 2: "获取上传凭证失败"
+
+**可能原因**:
+- 未登录或 token 过期
+- 存储配置未设置为七牛云
+- 七牛云配置不完整
+
+**解决**:
+1. 检查登录状态
+2. 检查数据库 `system_storage_config` 表
+3. 确认 AccessKey 和 SecretKey 正确
+
+### 问题 3: 上传后文件无法访问
+
+**可能原因**:
+- 七牛云域名配置错误
+- 域名未绑定或未备案
+- 文件权限设置问题
+
+**解决**:
+1. 检查 `qiniu_domain` 配置
+2. 登录七牛云控制台检查域名绑定
+3. 检查存储空间访问权限（应为公开）
+
+### 问题 4: 大文件上传失败
+
+**可能原因**:
+- 网络超时
+- 浏览器限制
+
+**解决**:
+1. 七牛云 SDK 支持断点续传，会自动重试
+2. 检查网络连接
+3. 尝试分片上传（SDK 自动处理）
+
+## 性能测试
+
+### 小文件测试 (< 10MB)
+- 预期时间：几秒内完成
+- 不会分片上传
+
+### 中等文件测试 (10MB - 100MB)
+- 预期时间：根据网速，通常 1-2 分钟
+- 可能会分片上传
+
+### 大文件测试 (> 100MB)
+- 预期时间：根据网速
+- 会自动分片上传
+- 支持断点续传
+
+## 对比测试
+
+### 旧方案（服务器中转）
+```
+100MB 文件上传时间：
+- 上传到服务器：2 分钟
+- 服务器上传到七牛云：2 分钟
+- 总计：4 分钟
+```
+
+### 新方案（直传）
+```
+100MB 文件上传时间：
+- 直接上传到七牛云：2 分钟
+- 总计：2 分钟
+```
+
+**效率提升**: 50%
+
+## 回滚方案
+
+如果七牛云直传有问题，可以临时切换回本地存储：
+
+```sql
+UPDATE system_storage_config 
+SET storage_type = 'local' 
+WHERE id = 1;
+```
+
+前端会自动检测并使用本地上传方式（通过服务器中转）。
+
+## 相关文件
+
+- `platform/src/utils/qiniuUpload.js` - 上传工具（已添加 getQiniuRegion 函数）
+- `go/controllers/qiniu_upload.go` - 后端控制器
+- `platform/docs/七牛云直传配置.md` - 详细配置文档
+
+## 更新日期
+
+2026-04-09