# 7.1 文件上传全流程

:::tip 概述
上传采用两段式：SaveTemp 先入临时目录（白名单+大小+图片嗅探校验），表单保存时 SaveFromTemp 移动到正式子目录。未走第二段的 temp 文件由每日 03:30 清理任务过期回收，不污染正式目录。
:::

## 上传接口

```text
POST /api/upload/uploadFile   （sys:upload:file）multipart 字段名 file
POST /api/upload/uploadFiles  （sys:upload:files）多文件
入参 type=image 时按图片规则校验，否则按普通文件
```

multipart 字段约定：`*ghttp.UploadFile` + `p:"file"` 标签。

## 两段式流程图

```text
阶段一（上传时，POST /api/upload/uploadFile）：
 浏览器 ──multipart──▶ SaveTemp
    │ ① 大小 ≤ file.maxSize(MB)
    │ ② 扩展名 ∈ file.fileExt / file.imageExt
    │ ③ type=image：前512B 魔数嗅探须 image/*
    ▼
 落盘 {uploadDir}/temp/{yyyymmdd}/{32位hex}.{ext}
    ▼
 返回 {url:"{domainUrl}/temp/...", path:"temp/.../x.png"(入库形态)} → 前端预览

阶段二（表单保存时，spec.saveTransform / SaveFileField）：
 表单携带 temp URL ──▶ SaveFromTemp(url, saveDir="user")
    │ 剥离 domainUrl → 相对路径
    │ 以 temp/ 开头？──否──▶ 已正式/外站：归一化或原样返回
    │ 是
    ▼
 {uploadDir}/{saveDir}/{yyyymmdd}/{HHmmss}_{4字节hex}.{ext}（Rename，跨卷复制回退）
    ▼
 库中写入相对路径 "user/20261017/153012_ab12.png"
    ▼
 读侧 GetFileUrl：domainUrl + "/" + 相对路径 ──▶ 前端展示
```

## SaveTemp 校验链（第一段）

```text
1) 大小 ≤ file.maxSize（MB，默认 10）
2) 扩展名白名单：file.fileExt（普通）/ file.imageExt（图片）
3) 读取前 512 字节：type=image 时做魔数嗅探（http.DetectContentType 须 image/*），并据文件头嗅探 MIME
落盘：{file.uploadDir}/{file.tempDir}/{yyyymmdd}/{32位随机hex}.{ext}
返回 Result{Url（可预览完整地址）, Path（相对 uploadDir，入库形态）, Name, Size, Ext, Mime}
```

## SaveFromTemp 处理规则（第二段）

| 入参形态 | 处理 |
|---------|------|
| 空值 | 返回 "" |
| 本站 URL（匹配 file.domainUrl 前缀） | 剥离域名得相对路径 |
| 相对路径以 temp/ 开头 | 移动到 {saveDir}/{yyyymmdd}/{HHmmss}_{4字节hex}.{ext}（os.Rename，跨卷回退"复制后删源"）；返回新相对路径（入库形态） |
| 已是正式相对路径 | 归一化后原样返回（幂等） |
| 外站 http(s) URL | 原样返回（不处理外链） |

SaveFromTempMulti：按逗号拆分逐个转正（如 article.images 多图字段）。

## 路径契约

```text
数据库统一存"相对 uploadDir 的路径"（如 tenant/20260923/x.png）
对外访问地址 = GetFileUrl = file.domainUrl + "/" + 相对路径
  （domainUrl 为空时用 /upload/ 相对路径）
静态访问：router SetServerRoot("resource") 提供 /upload/**
Response 中间件对 .svg 强制 attachment + nosniff（防存储型 XSS）
```

## 声明式用法（ModuleSpec）

```go
FileFields: []string{"avatar"} + FileSaveDir: "user"
// 写侧 saveTransform 自动 temp→正式；读侧 readTransform 自动 GetFileUrl 补域名
// MultiFileFields 处理逗号多文件；ContentFields 走富文本流程
```

模块已接入：user(avatar)、article(cover/images/content)、tenant(logo)、example(avatar) 等。

## 临时目录清理（运营闭环）

```text
cmd.go 注册 gcron "0 30 3 * * *"（每日 03:30）→ logic.CleanTemp：
  扫描 {uploadDir}/{tempDir} 下目录名为 yyyymmdd 且早于
  now-file.tempExpireDays（默认 7 天，0=不清理）的日期目录整目录删除
  返回删除数量并记日志
```

## 常见问题

| 症状 | 排查 |
|------|------|
| 上传图片 404 | file.domainUrl 与静态服务根的相对关系；库中存相对路径，展示层必须经 GetFileUrl |
| 上传被拒 | 扩展名不在白名单 / 超 maxSize / 图片魔数嗅探不过（改后缀伪造） |
| temp 文件堆积 | CleanTemp 的 gcron 已注册？file.tempExpireDays > 0？ |
| 跨卷移动失败 | os.Rename 失败自动回退"复制后删源"；检查磁盘空间与权限 |
| 富文本图片不显示 | 读取侧走 Detail/List（基座自动 Expand），不要直接 Struct 输出 |