# 大文件上传配置说明

## 概述

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

## 配置修改

### 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)