7.2 上传配置详解

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

配置项

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）

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 只读），并经环境变量覆盖：

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

容量与清理

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

常见问题

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

下一步

→ 7.3 富文本处理

2.5 KiB Raw Blame History Unescape Escape