# 七牛云上传测试步骤

## 前置条件

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