9.3 KiB
9.3 KiB
七牛云直传配置说明
概述
新的上传机制实现了前端直接上传到七牛云，不再通过后端中转，大幅提升大文件上传效率。
上传流程对比
旧流程（低效）
前端 → 后端服务器 → 七牛云
(中转暂存)
问题：
- 大文件需要先上传到服务器，再由服务器上传到七牛云
- 占用服务器带宽和磁盘空间
- 上传时间翻倍
- 服务器压力大
新流程（高效）
前端 → 七牛云（直传）
后端 → 数据库（仅保存记录）
优势：
- 前端直接上传到七牛云，不经过服务器
- 节省服务器资源
- 上传速度快
- 支持断点续传
安装依赖
前端安装七牛云 SDK
cd platform
npm install qiniu-js
或使用 yarn：
yarn add qiniu-js
后端 API
1. 获取存储配置
接口: GET /platform/storage/config
响应:
{
"code": 200,
"data": {
"storageType": "qiniu", // 或 "local"
"qiniuDomain": "http://7colud.yunzer.cn",
"qiniuRegion": "z0"
}
}
2. 获取上传凭证
接口: GET /platform/qiniu/token
响应:
{
"code": 200,
"data": {
"token": "七牛云上传token",
"domain": "http://7colud.yunzer.cn",
"bucket": "your-bucket",
"region": "z0",
"keyPrefix": "2026/04/09/1775722615052606500",
"expires": 1712654400,
"uploadUrl": "https://up-z0.qiniup.com"
}
}
3. 保存文件记录
接口: POST /platform/qiniu/save
请求:
{
"key": "2026/04/09/1775722615052606500.png",
"hash": "FhGxwBzoLwO_RGws...",
"size": 1024000,
"name": "screenshot.png",
"mimeType": "image/png",
"cate": 0
}
响应:
{
"code": 200,
"data": {
"url": "http://7colud.yunzer.cn/2026/04/09/1775722615052606500.png",
"id": 123,
"name": "screenshot.png",
"key": "2026/04/09/1775722615052606500.png"
}
}
前端使用
基础用法
import { smartUpload } from '@/utils/qiniuUpload';
// 自动选择上传方式（本地或七牛云）
const result = await smartUpload(file, {
cate: 0, // 文件分类
onProgress: (progress) => {
console.log('上传进度:', progress.percent + '%');
console.log('已上传:', progress.loaded);
console.log('总大小:', progress.total);
},
});
console.log('上传成功:', result);
// { url: '...', id: 123, name: '...', key: '...' }
在组件中使用
<template>
<el-upload
:http-request="handleUpload"
:on-progress="handleProgress"
>
<el-button>上传文件</el-button>
</el-upload>
<el-progress v-if="uploading" :percentage="uploadPercent" />
</template>
<script setup>
import { ref } from 'vue';
import { smartUpload } from '@/utils/qiniuUpload';
import { ElMessage } from 'element-plus';
const uploading = ref(false);
const uploadPercent = ref(0);
async function handleUpload(options) {
const file = options.file?.raw || options.file;
uploading.value = true;
try {
const result = await smartUpload(file, {
cate: 0,
onProgress: (progress) => {
uploadPercent.value = progress.percent;
},
});
ElMessage.success('上传成功');
options.onSuccess?.(result);
} catch (error) {
ElMessage.error(error.message || '上传失败');
options.onError?.(error);
} finally {
uploading.value = false;
}
}
</script>
批量上传
import { batchUpload } from '@/utils/qiniuUpload';
const files = [file1, file2, file3];
const results = await batchUpload(files, {
cate: 0,
onFileProgress: (file, progress) => {
console.log(`${file.name}: ${progress.percent}%`);
},
onFileComplete: (file, result) => {
console.log(`${file.name} 上传成功:`, result);
},
onFileError: (file, error) => {
console.error(`${file.name} 上传失败:`, error);
},
});
console.log('所有文件上传完成:', results);
工作原理
1. 智能选择上传方式
smartUpload 函数会自动检测后端配置：
// 1. 获取存储配置
const config = await getStorageConfig();
// 2. 根据配置选择上传方式
if (config.storageType === 'qiniu') {
// 七牛云直传
return uploadToQiniu(file, options);
} else {
// 本地上传（通过后端）
return uploadToLocal(file, options);
}
2. 七牛云直传流程
// 1. 获取上传凭证
const tokenRes = await getQiniuToken();
const { token, keyPrefix } = tokenRes.data;
// 2. 生成文件 key
const key = `${keyPrefix}.${ext}`;
// 3. 使用七牛云 SDK 直接上传
const observable = qiniu.upload(file, key, token);
// 4. 监听上传进度
observable.subscribe({
next(res) {
// 进度回调
onProgress(res.total.percent);
},
complete(res) {
// 上传完成，保存记录到数据库
await saveFileRecord({
key: res.key,
hash: res.hash,
size: file.size,
name: file.name,
});
},
});
3. 本地上传流程
// 通过后端中转（兼容本地存储）
const formData = new FormData();
formData.append('file', file);
const res = await request({
url: '/platform/uploadfile',
method: 'post',
data: formData,
onUploadProgress: (e) => {
onProgress(e.loaded / e.total * 100);
},
});
配置说明
七牛云区域配置
| 区域代码 | 区域名称 | 上传地址 |
|---|---|---|
| z0 | 华东 | https://up-z0.qiniup.com |
| z1 | 华北 | https://up-z1.qiniup.com |
| z2 | 华南 | https://up-z2.qiniup.com |
| na0 | 北美 | https://up-na0.qiniup.com |
| as0 | 新加坡 | https://up-as0.qiniup.com |
| cn-east-2 | 华东-浙江2 | https://up-cn-east-2.qiniup.com |
上传策略配置
后端生成 token 时的策略：
putPolicy := storage.PutPolicy{
Scope: cfg.QiniuBucket,
ReturnBody: `{"key":"$(key)","hash":"$(etag)","size":$(fsize),"mimeType":"$(mimeType)"}`,
Expires: 3600, // 1小时有效期
}
安全性
1. Token 有效期
上传 token 有效期为 1 小时，过期后需要重新获取。
2. 权限验证
- 获取 token 需要登录认证
- 保存文件记录需要登录认证
- 文件记录关联到当前用户和租户
3. 文件去重
通过 MD5 检查文件是否已存在，避免重复上传。
性能优化
1. 断点续传
七牛云 SDK 支持断点续传（大文件自动分片）：
const config = {
useCdnDomain: true,
region: qiniu.region.z0,
chunkSize: 4, // 分片大小（MB）
concurrentRequestLimit: 3, // 并发上传数
};
const observable = qiniu.upload(file, key, token, putExtra, config);
2. CDN 加速
启用 CDN 域名加速上传：
const config = {
useCdnDomain: true, // 使用 CDN 加速
};
3. 并发上传
批量上传时可以控制并发数：
// 限制同时上传 3 个文件
const concurrency = 3;
const results = [];
for (let i = 0; i < files.length; i += concurrency) {
const batch = files.slice(i, i + concurrency);
const batchResults = await Promise.all(
batch.map(file => smartUpload(file, options))
);
results.push(...batchResults);
}
故障排查
1. 上传失败：获取 token 失败
错误: "当前未配置七牛云存储"
解决:
- 检查数据库存储配置
- 确认
storage_type为'qiniu' - 确认七牛云配置完整
2. 上传失败：token 无效
错误: "401 Unauthorized"
解决:
- 检查 AccessKey 和 SecretKey 是否正确
- 检查 token 是否过期（1小时有效期）
- 重新获取 token
3. 上传失败：bucket 不存在
错误: "no such bucket"
解决:
- 检查 bucket 名称是否正确
- 检查 bucket 是否在对应区域
- 登录七牛云控制台确认
4. 保存记录失败
错误: "保存文件记录失败"
解决:
- 检查数据库连接
- 检查文件信息是否完整
- 查看后端日志
迁移指南
从旧版本迁移
- 安装依赖:
npm install qiniu-js
- 更新导入:
// 旧版本
import { uploadFile } from '@/api/file';
// 新版本
import { smartUpload } from '@/utils/qiniuUpload';
- 更新上传代码:
// 旧版本
const formData = new FormData();
formData.append('file', file);
const res = await uploadFile(formData, { cate: 0 });
// 新版本
const result = await smartUpload(file, { cate: 0 });
- 兼容性:
smartUpload会自动检测存储配置- 如果配置为本地存储，会自动使用旧的上传方式
- 无需修改其他代码
相关文件
后端
go/controllers/qiniu_upload.go- 七牛云上传控制器go/routers/platform/platform.go- 路由配置go/services/storage_service.go- 存储服务
前端
platform/src/utils/qiniuUpload.js- 七牛云上传工具platform/src/views/platform/softwareupgrade/components/edit.vue- 软件升级组件（示例）
更新日期
2026-04-09