244 lines
5.9 KiB
Markdown
244 lines
5.9 KiB
Markdown
# 大文件上传配置说明
|
||
|
||
## 概述
|
||
|
||
为支持大型软件安装包（如桌面客户端安装程序）的上传，系统已调整文件上传限制和超时配置。
|
||
|
||
## 配置修改
|
||
|
||
### 1. 文件大小限制
|
||
|
||
**文件位置**: `go/controllers/platform_file.go`
|
||
|
||
**修改内容**:
|
||
```go
|
||
// 修改前
|
||
const fileUploadMaxMB = 200 // 200MB
|
||
|
||
// 修改后
|
||
const fileUploadMaxMB = 2048 // 2GB，适用于大型软件安装包
|
||
```
|
||
|
||
### 2. 服务器超时配置
|
||
|
||
**文件位置**: `go/conf/app.conf`
|
||
|
||
**新增配置**:
|
||
```ini
|
||
# 服务器超时配置（支持大文件上传）
|
||
# 0 表示不设置超时限制
|
||
ServerTimeOut = 0
|
||
# 最大请求体大小（字节），0 表示不限制
|
||
MaxMemory = 0
|
||
```
|
||
|
||
## CORS 配置
|
||
|
||
**文件位置**: `go/routers/router.go`
|
||
|
||
当前 CORS 配置允许跨域请求：
|
||
|
||
```go
|
||
beego.InsertFilter("*", beego.BeforeRouter, func(ctx *context.Context) {
|
||
ctx.Output.Header("Access-Control-Allow-Origin", "*")
|
||
ctx.Output.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS")
|
||
ctx.Output.Header("Access-Control-Allow-Headers", "Origin, X-Requested-With, Content-Type, Accept, Authorization")
|
||
ctx.Output.Header("Access-Control-Max-Age", "86400")
|
||
|
||
if ctx.Input.Method() == "OPTIONS" {
|
||
ctx.Output.Status = 200
|
||
ctx.Output.Body([]byte(""))
|
||
return
|
||
}
|
||
})
|
||
```
|
||
|
||
### 生产环境 CORS 配置建议
|
||
|
||
在生产环境中，建议将 `Access-Control-Allow-Origin` 设置为具体的前端域名：
|
||
|
||
```go
|
||
// 开发环境
|
||
ctx.Output.Header("Access-Control-Allow-Origin", "*")
|
||
|
||
// 生产环境（推荐）
|
||
allowedOrigins := []string{
|
||
"https://platform.yunzer.cn",
|
||
"https://www.yunzer.cn",
|
||
}
|
||
origin := ctx.Request.Header.Get("Origin")
|
||
for _, allowed := range allowedOrigins {
|
||
if origin == allowed {
|
||
ctx.Output.Header("Access-Control-Allow-Origin", origin)
|
||
break
|
||
}
|
||
}
|
||
```
|
||
|
||
## 上传流程
|
||
|
||
### 1. 文件上传接口
|
||
|
||
**路由**: `POST /platform/uploadfile`
|
||
|
||
**控制器**: `PlatformFileController.UploadFile`
|
||
|
||
**处理流程**:
|
||
1. 验证用户身份（JWT token）
|
||
2. 解析 multipart form（最大 2GB）
|
||
3. 检查文件大小（不超过 2GB）
|
||
4. 获取存储服务（本地或七牛云）
|
||
5. 上传文件到存储服务
|
||
6. 检查文件 MD5 是否已存在
|
||
7. 保存文件记录到数据库
|
||
8. 返回文件信息（URL、ID、名称）
|
||
|
||
### 2. 存储服务
|
||
|
||
系统支持两种存储方式：
|
||
|
||
- **本地存储**: 文件保存在 `uploads/` 目录
|
||
- **七牛云存储**: 文件上传到七牛云 OSS
|
||
|
||
存储方式通过 `yz_system_storage_config` 表配置。
|
||
|
||
## 性能优化建议
|
||
|
||
### 1. Nginx 反向代理配置
|
||
|
||
如果使用 Nginx 作为反向代理，需要调整以下配置：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name api.yunzer.cn;
|
||
|
||
# 客户端请求体大小限制（0 表示不限制）
|
||
client_max_body_size 0;
|
||
|
||
# 客户端请求体缓冲区大小
|
||
client_body_buffer_size 128k;
|
||
|
||
# 超时配置
|
||
client_body_timeout 3600s;
|
||
send_timeout 3600s;
|
||
proxy_connect_timeout 3600s;
|
||
proxy_send_timeout 3600s;
|
||
proxy_read_timeout 3600s;
|
||
|
||
location / {
|
||
proxy_pass http://localhost:8081;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
|
||
# 禁用请求体缓冲（直接流式传输）
|
||
proxy_request_buffering off;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 磁盘空间监控
|
||
|
||
大文件上传需要足够的磁盘空间：
|
||
|
||
```bash
|
||
# 检查磁盘空间
|
||
df -h
|
||
|
||
# 监控 uploads 目录大小
|
||
du -sh uploads/
|
||
|
||
# 设置磁盘空间告警（推荐使用监控工具）
|
||
```
|
||
|
||
### 3. 数据库优化
|
||
|
||
对于频繁的文件查询，建议添加索引：
|
||
|
||
```sql
|
||
-- MD5 索引（用于去重）
|
||
CREATE INDEX idx_system_file_md5 ON yz_system_file(md5);
|
||
|
||
-- 租户 + 删除时间索引（用于文件列表查询）
|
||
CREATE INDEX idx_system_file_tid_delete ON yz_system_file(tid, delete_time);
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 1. 上传失败：文件过大
|
||
|
||
**错误信息**: "文件大小不能超过 2048MB"
|
||
|
||
**解决方案**:
|
||
- 检查 `fileUploadMaxMB` 常量设置
|
||
- 确认 Nginx `client_max_body_size` 配置
|
||
- 检查磁盘剩余空间
|
||
|
||
### 2. 上传超时
|
||
|
||
**错误信息**: "请求失败，请检查网络连接"
|
||
|
||
**解决方案**:
|
||
- 检查 `app.conf` 中的 `ServerTimeOut` 配置
|
||
- 检查 Nginx 超时配置
|
||
- 检查网络带宽和稳定性
|
||
|
||
### 3. CORS 错误
|
||
|
||
**错误信息**: "已拦截跨源请求：同源策略禁止读取..."
|
||
|
||
**解决方案**:
|
||
- 检查 `go/routers/router.go` 中的 CORS 配置
|
||
- 确认 `Access-Control-Allow-Origin` 包含前端域名
|
||
- 检查 `Access-Control-Allow-Headers` 包含 `Authorization`
|
||
|
||
### 4. 文件不存在（404）
|
||
|
||
**错误信息**: "请求的资源不存在"
|
||
|
||
**可能原因**:
|
||
- 文件记录在数据库中不存在
|
||
- 租户 ID (tid) 不匹配
|
||
- 文件已被标记为删除
|
||
|
||
**解决方案**:
|
||
```sql
|
||
-- 检查文件记录
|
||
SELECT * FROM yz_system_file WHERE id = 320;
|
||
|
||
-- 检查是否被删除
|
||
SELECT * FROM yz_system_file WHERE id = 320 AND delete_time IS NULL;
|
||
```
|
||
|
||
## 监控指标
|
||
|
||
建议监控以下指标：
|
||
|
||
1. **上传成功率**: 成功上传数 / 总上传请求数
|
||
2. **平均上传时间**: 按文件大小分段统计
|
||
3. **磁盘使用率**: uploads 目录大小 / 总磁盘空间
|
||
4. **错误率**: 按错误类型分类统计
|
||
|
||
## 相关文件
|
||
|
||
- `go/controllers/platform_file.go` - 文件上传控制器
|
||
- `go/services/storage_service.go` - 存储服务接口
|
||
- `go/conf/app.conf` - 服务器配置
|
||
- `go/routers/router.go` - 路由和 CORS 配置
|
||
- `go/models/system_file.go` - 文件数据模型
|
||
|
||
## 更新日志
|
||
|
||
- **2026-04-09**:
|
||
- 文件大小限制从 200MB 提升到 2GB
|
||
- 移除服务器超时限制
|
||
- 更新文档
|
||
|
||
## 参考资料
|
||
|
||
- [Beego 文档 - 文件上传](https://beego.vip/docs/mvc/controller/file.md)
|
||
- [Nginx 文件上传配置](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size)
|
||
- [七牛云 Go SDK](https://developer.qiniu.com/kodo/1238/go)
|