# 7.2 上传配置详解

:::tip 概述
上传相关配置集中在 `config.yaml` 的 file 节。关键概念：**物理路径**（服务器磁盘）与**访问 URL**（对外域名）分离，`file.domainUrl` 是两者的桥。
:::

## 配置项

```yaml
file:
  uploadDir: 'E:\...\upload'      # 物理根目录（绝对路径；容器经 env 覆盖）
  domainUrl: "http://file.gin.elevue"  # 访问域名（样例值；为空时挂应用开发回退）
  tempDir: "temp"                  # 临时目录名（uploadDir 下）
  imageExt: "gif,jpg,jpeg,png,bmp,webp,svg"
  fileExt: "gif,jpg,...,pdf,zip,rar,txt,csv,mp3,mp4,sql,js,css"
  maxSize: 10                      # 单文件上限（MB）
  tempExpireDays: 7                # 临时文件保留天数（0=不清理；每日 03:30 清理任务消费）
```

## domainUrl 的三种形态

| 配置 | 行为 | 适用 |
|---|---|---|
| 具体域名（推荐） | 访问 URL = 域名 + 相对路径，nginx 直供 | 生产 |
| 为空 | 应用挂 `/upload/*` 开发回退（封禁 temp + SafeJoin） | 本地开发 |
| https 域名 | 同第一种，配合 TLS | 生产标准形态 |

**契约**：访问 URL = 域址 + "/" + 入库路径，**不含 upload 段**——nginx root 直接指向 upload 目录内部结构。

## nginx 配套（deploy/nginx.conf）

```nginx
root /data/upload;
client_max_body_size 10m;          # 与 file.maxSize 对齐
location ^~ /temp/ { return 404; } # 临时目录封禁
location ~* \.svg$ {               # SVG 强制附件 + nosniff
    add_header Content-Disposition "attachment";
    add_header X-Content-Type-Options "nosniff";
}
```

## 容器部署

docker-compose 把 upload 目录挂为卷（应用写、nginx 只读），并经环境变量覆盖：

```text
APP_FILE_UPLOADDIR=/data/upload
APP_FILE_DOMAINURL=${FILE_DOMAIN_URL}
```

## 容量与清理

- temp 超过 `tempExpireDays` 自动清理
- 正式目录按 `{模块}/{yyyymmdd}` 分桶，便于按日期归档
- 备份策略：upload 卷纳入备份清单（[11.9 备份与恢复](/zh/deploy/backup.html)）

## 常见问题

| 现象 | 检查 |
|---|---|
| 上传成功但 URL 404 | domainUrl 与 nginx root 是否同构；相对路径是否含 upload 段 |
| 图片裂图 | domainUrl 协议（http/https 混合内容） |
| 超大文件失败 | maxSize 与 nginx client_max_body_size 两边对齐 |
| 本地 temp 可访问 | 不应发生——开发回退封禁 temp，检查是否绕过了应用直接访问 |

## 下一步

→ [7.3 富文本处理](/zh/tools/rich-text.html)