签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/tools/upload-config.md

@@ -0,0 +1,85 @@
+# 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 清理日志
+```