7.2 上传配置详解
概述
上传行为全部由 config.yaml 的 file.* 配置块控制：物理目录、访问域名、扩展名白名单、大小上限、临时保留天数。本节逐键说明与调优建议。
配置全貌
yaml
file:
uploadDir: "upload" # 物理根目录（相对项目根或绝对路径）
domainUrl: "" # 文件访问域名，为空时使用 /upload/ 相对路径
tempDir: "temp" # 临时目录名，位于 uploadDir 下
imageExt: "gif,jpg,jpeg,png,bmp,webp,svg" # 允许的图片扩展名
fileExt: "gif,jpg,jpeg,png,bmp,webp,svg,doc,docx,xls,xlsx,ppt,pptx,pdf,zip,rar,txt,csv,mp3,mp4,sql,js,css" # 允许的文件扩展名
maxSize: 10 # 单文件大小上限（MB）
tempExpireDays: 7 # 临时目录保留天数，超期自动清理，0 表示不清理逐键说明
| 键 | 作用 | 调优建议 |
|---|---|---|
| uploadDir | 上传物理根目录 | 容器部署挂独立卷（跨卷 Rename 回退复制）；权限最小化 |
| domainUrl | 文件访问域名 | 空 = /upload/ 相对路径（同域反代场景）；CDN/独立文件域名时配置完整 origin；SaveFromTemp 按此前缀识别"本站 URL" |
| tempDir | 临时目录名 | 保持默认；位于 uploadDir 下，CleanTemp 按它定位 |
| imageExt | 图片白名单 | 按需增减；svg 在白名单时由 Response 中间件附件化兜底 |
| fileExt | 普通文件白名单 | 对公网用户开放上传时建议收紧——当前含 js/css/sql，公开场景应移除 |
| maxSize | 单文件上限 MB | 表单上传场景 10 足够；大文件场景配合同步调 Nginx client_max_body_size |
| tempExpireDays | temp 保留天数 | 0=不清理（不建议）；默认 7 天覆盖正常"上传→提交表单"周期 |
domainUrl 的三种部署形态
text
形态一：同域反代（推荐）
domainUrl: ""（空）
前端经 Nginx 同域访问 /upload/**，SaveFromTemp 以 /temp/ 前缀识别
形态二：独立文件域名/CDN
domainUrl: "https://files.example.com"
上传返回 https://files.example.com/temp/...；
SaveFromTemp 匹配此前缀剥离域名后转正
形态三：后端直出
domainUrl: "http://backend:8000"
静态访问由 SetServerRoot("resource") 提供domainUrl 一致性
domainUrl 决定"本站 URL"的判定——库里存相对路径、展示层拼域名。改 domainUrl 后旧数据无需迁移（相对路径不变），但外链判定/转正识别以新前缀为准。
安全链与配置的关系
text
大小限制 ← maxSize
扩展名白名单 ← fileExt / imageExt
图片魔数嗅探 ← type=image 时强制（配置不可关）
随机文件名 ← 固定行为（32hex / HHmmss_4hex，防猜路径/覆盖）
两段式 ← 固定行为（未过校验不进正式目录）
svg 加固 ← Response 中间件固定行为（attachment+nosniff）
temp 清理 ← tempExpireDays + 每日 03:30 gcron生产加固建议
text
1. fileExt 按业务收紧：纯图片业务 fileExt=imageExt 即可
2. maxSize 与 Nginx client_max_body_size 对齐（防绕过）
3. uploadDir 挂独立卷并限制执行权限（防上传 js 被解析执行——
静态服务只应返回文件内容）
4. domainUrl 走 CDN 时配置防盗链（CDN 侧）
5. tempExpireDays 保持 ≤7（缩短未转正文件暴露窗口）验证配置生效
sh
# 上传超限 → 拒绝并提示大小
# 上传白名单外扩展名 → 拒绝
# 上传后检查：
ls upload/temp/$(date +%Y%m%d)/ # 阶段一落盘
ls upload/user/$(date +%Y%m%d)/ # 表单保存后转正
# temp 清理验证：改小 tempExpireDays 观察 03:30 清理日志