文件上传和存储功能

现行接口

1. 内部上传

接口：POST /upms/file/upload
用途：登录后的后台、商城、App 等内部业务上传
请求参数：

参数	必填	说明
`file`	是	上传文件
`dir`	是	相对存储目录，可多级，如 `material/`、`mall/user/`
`fileType`	是	文件类型，`image`/`img` 表示图片，其他类型按普通文件处理

2. 对外白名单场景上传

接口：POST /upms/file/upload/out
用途：只给少量必须匿名访问的页面使用
请求参数：

参数	必填	说明
`file`	是	上传文件
`dir`	是	白名单场景码，不再接受旧 `dir` 别名，也不允许任意目录
`fileType`	是	公开上传目前只允许 `image`/`img`

`/upms/file/upload/out` 当前白名单场景

场景码	典型用途	是否必须登录	允许类型	大小上限	固定落盘目录
`tenantApply`	租户申请图片上传	否	图片	`5MB`	`0/out/tenantapply/yyyyMM/`
`supplierApplyLicense`	供应商入驻资质图片上传	否	图片	`5MB`	`0/out/supplierapply/license/yyyyMM/`

对外白名单场景使用说明

请求方式：multipart/form-data
返回结果：成功后返回 JSON，实际文件地址在 link 字段
dir 必须传场景码，不能再传旧目录名，也不能自行拼新的上传目录

示例：

POST /upms/file/upload/out?fileType=image&dir=tenantApply
Content-Type: multipart/form-data

POST /upms/file/upload/out?fileType=image&dir=supplierApplyLicense
Content-Type: multipart/form-data

如果传入未定义场景码，服务端会直接拒绝请求。

服务端校验规则

公共规则

上传目录参数会先做规范化处理
禁止包含 ..、控制字符、: * ? " < > | 等非法字符
上传临时文件在处理结束后会自动删除

图片规则

内部上传图片最大 10MB
对外白名单图片最大 5MB
仅允许 jpg、jpeg、png、gif、bmp
会同时校验扩展名、Content-Type，并实际解析图片内容，防止伪装文件

登录后上传说明

/upms/file/upload/out 只保留匿名申请类图片上传
IM、素材库、用户头像等登录后上传统一走受保护的 /upms/file/upload

如何新增对外白名单场景

新增场景时，不是让前端直接换一个新的 dir，而是按下面步骤处理：

先确认该业务是否真的需要匿名上传；只要能要求登录，就应该继续使用 /upms/file/upload
在 joolun-upms-admin 的 UploadFileController.PUBLIC_UPLOAD_SCENES 中新增场景码，并绑定固定存储目录
明确该场景允许的文件类型、大小上限；如果不是现有图片规则，必须在后端显式补充校验，不能直接放宽全局限制
前端或外部调用方改为传新的场景码到 dir 参数
同步更新本文档和对外暴露说明，确保场景用途、限制和责任边界可追踪

示例：

private static final Map<String, PublicUploadPolicy> PUBLIC_UPLOAD_SCENES = Map.of(
    "tenantApply", new PublicUploadPolicy("tenantapply", PUBLIC_IMAGE_MAX_SIZE),
    "supplierApplyLicense", new PublicUploadPolicy("supplierapply/license", PUBLIC_IMAGE_MAX_SIZE),
    "demoScene", new PublicUploadPolicy("demo/scene", PUBLIC_IMAGE_MAX_SIZE)
);

说明：

仅新增场景码时，继续复用 /upms/file/upload/out，不需要额外新增匿名接口路径
如果新增的是全新的匿名接口，而不是复用现有上传接口，才需要重新评估 release-urls 白名单

水印与存储配置

如果文件存储配置里设置了水印内容，图片上传后会自动加水印
上传前必须先在后台配置文件存储，否则接口会直接报错

后台配置位置：

平台管理 -> 平台系统配置 -> 平台文件存储配置
系统管理 -> 文件存储配置

Spring Boot 配置

全局上传大小限制由 application-dev.yml 或对应环境配置控制：

spring:
  servlet:
    multipart:
      location: /data/tmp
      max-file-size: 10MB
      max-request-size: 100MB

生产环境注意事项

Nginx 需要同步配置上传大小限制
OSS、COS、MinIO 等对象存储按业务需要配置访问权限
不要再通过新增任意 dir 的方式扩展公开上传；如需新增公开上传能力，应新增白名单场景并明确限制文件类型和目录

集成SKD

阿里OSS
七牛云
minio
腾讯cos

配置

阿里OSS、腾讯cos、七牛云请去相应官网申请账号
注意：必须设为公共读并配置跨域
在后台【平台管理】-【平台系统配置】-【平台文件存储配置】配置平台文件存储，平台存储用于保存非租户的公共图片，比如系统管理员头像
在后台【系统管理】-【文件存储配置】配置租户文件存储，租户的文件存储配置都是相互独立的，所以每个租户都需单独配置，租户存储用于保存租户的私有图片，如店铺、商品图片