go-platform/docs/大文件上传配置.md

大文件上传配置说明

概述

为支持大型软件安装包（如桌面客户端安装程序）的上传，系统已调整文件上传限制和超时配置。

配置修改

1. 文件大小限制

文件位置: go/controllers/platform_file.go

修改内容:

// 修改前
const fileUploadMaxMB = 200 // 200MB

// 修改后
const fileUploadMaxMB = 2048 // 2GB，适用于大型软件安装包

2. 服务器超时配置

文件位置: go/conf/app.conf

新增配置:

# 服务器超时配置（支持大文件上传）
# 0 表示不设置超时限制
ServerTimeOut = 0
# 最大请求体大小（字节），0 表示不限制
MaxMemory = 0

CORS 配置

文件位置: go/routers/router.go

当前 CORS 配置允许跨域请求：

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 设置为具体的前端域名：

// 开发环境
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 作为反向代理，需要调整以下配置：

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. 磁盘空间监控

大文件上传需要足够的磁盘空间：

# 检查磁盘空间
df -h

# 监控 uploads 目录大小
du -sh uploads/

# 设置磁盘空间告警（推荐使用监控工具）

3. 数据库优化

对于频繁的文件查询，建议添加索引：

-- 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) 不匹配
• 文件已被标记为删除

解决方案:

-- 检查文件记录
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 文档 - 文件上传
• Nginx 文件上传配置
• 七牛云 Go SDK