---
name: file-upload
when: '文件上传, 上传文件, 文件存储, OSS, 图片上传, 附件上传, multipart, 文件下载, 对象存储'
scope:
  - backend
products:
  - '*'
id: ka-pattern-file-upload
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 文件上传
  - 上传文件
  - 文件存储
  - OSS
  - 图片上传
  - 附件上传
  - multipart
  - 文件下载
  - 对象存储
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 文件必须存储到对象存储（OSS/MinIO/S3），禁止存本地磁盘
- 必须校验文件类型白名单（禁止 .exe/.sh/.jsp 等）
- 必须限制文件大小（默认 10MB）
- 禁止使用原始文件名，必须 UUID 重命名防路径遍历
- 上传接口必须校验文件 MIME 类型和扩展名双重验证
- 图片类上传必须校验实际文件头（magic bytes），不能只依赖扩展名
- 必须配置上传文件总容量限制（单个用户/租户），防止存储滥用
- 下载链接必须使用签名 URL 或一次性 token，禁止永久公开 URL
- 禁止上传目录有执行权限（chmod -x），防止上传的脚本被服务器执行
- 文件上传必须异步处理（先上传再后台扫描），大文件必须支持断点续传
- 必须记录文件上传/下载审计日志（操作人、时间、文件名、大小）

## 验收项
- [AC-01] 文件类型白名单校验
- [AC-02] 文件大小限制（默认 10MB）
- [AC-03] UUID 重命名文件
- [AC-04] 存储在对象存储而非本地磁盘
- [AC-05] 文件头 magic bytes 校验
- [AC-06] 用户/租户存储容量限制
- [AC-07] 下载链接签名或一次性 token
- [AC-08] 上传目录无执行权限
- [AC-09] 上传/下载审计日志
