86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# 7.2 上传配置详解
|
||
|
||
:::tip 概述
|
||
上传行为全部由 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") 提供
|
||
```
|
||
|
||
::: warning 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 清理日志
|
||
```
|