majiayu000 文件上传与 OSS 管理规范
核心规范
规范1：统一上传接口与 OSS 配置
（详细说明：必须使用若依封装的 SysOssController 或自定义 UploadController 处理文件上传。底层应支持多种存储策略（本地、MinIO、阿里云OSS、腾讯云COS等），通过配置文件 ruoyi.profile 或数据库动态切换。Controller 层需使用 @RepeatSubmit 注解防止重复提交。）
@RestController
@RequestMapping("/system/oss")
public class SysOssController extends BaseController {
@Autowired
private ISysOssService sysOssService;
/**
* 统一文件上传接口
*/
@PreSaCheckPermissionAuthorize("system:oss:upload")
@Log(title = "OSS文件上传", businessType = BusinessType.INSERT)
@RepeatSubmit(interval = 3000) // 3秒内防重复提交
@PostMapping("/upload")
public R<Map<String, String>> upload(@RequestPart("file") MultipartFile file) {
if (file.isEmpty()) {
return R.fail("上传文件不能为空");
}
try {
// 调用Service层上传，返回访问URL和文件ID
SysOss oss = sysOssService.upload(file);
Map<String, String> result = new HashMap<>();
result.put("url", oss.getUrl());
result.put("fileName", oss.getFileName());
result.put("ossId", oss.getOssId().toString());
return R.ok(result);
} catch (Exception e) {
log.error("文件上传失败", e);
return R.fail(e.getMessage());
}
}
}
规范2：文件安全校验与重命名策略
（详细说明：严禁信任用户提交的原始文件名。必须使用 FileUploadUtils 工具类进行文件上传，该工具类内置了后缀白名单校验（防止上传.jsp、.exe等脚本文件）、文件大小限制及UUID重命名逻辑。对于本地存储，需确保上传目录位于WebRoot之外或不可执行路径下。）
@Service
public class SysOssServiceImpl implements ISysOssService {
/**
* 本地文件上传核心逻辑示例
*/
@Override
public SysOss uploadLocal(MultipartFile file) {
// 1. 校验文件扩展名（内部基于白名单机制）
// 2. 校验文件大小（默认配置上限）
String fileName = FileUploadUtils.upload(RuoYiConfig.getUploadPath(), file);
String url = serverConfig.getUrl() + fileName;
SysOss oss = new SysOss();
oss.setFileName(FileUtils.getName(fileName));
oss.setOriginalName(file.getOriginalFilename());
oss.setFileSuffix(FileUtils.getExtension(fileName));
oss.setUrl(url);
// ...保存到数据库
return baseMapper.insert(oss);
}
// 对于OSS上传，同样建议先校验后上传
public void validateFile(MultipartFile file) {
// 校验扩展名
String extension = FileUploadUtils.getExtension(file);
if (!FileUploadUtils.isAllowedExtension(extension, MimeTypeUtils.DEFAULT_ALLOWED_EXTENSION)) {
throw new ServiceException("文件格式不正确，请上传" + Arrays.toString(MimeTypeUtils.DEFAULT_ALLOWED_EXTENSION) + "格式");
}
}
}
禁止事项
- ❌ 禁止直接使用
file.getOriginalFilename()作为服务器存储文件名（必须使用UUID重命名）。 - ❌ 禁止上传可执行文件（如 .exe, .sh, .jsp, .php）到可执行目录，必须在
application.yml中配置allowed-extension黑/白名单。 - ❌ 禁止在文件上传接口中省略文件大小限制，防止恶意大文件攻击导致磁盘溢出。
- ❌ 禁止将文件直接存储在项目
src/main/resources或static目录下（推荐存储在外部目录或OSS）。 - ❌ 禁止在前端URL中携带本地绝对路径，文件访问必须通过服务器流或OSS签名URL。
参考代码
- 文件路径：
ruoyi-admin/src/main/java/com/ruoyi/web/controller/system/SysOssController.java - 文件路径：
ruoyi-common/src/main/java/com/ruoyi/common/utils/file/FileUploadUtils.java - 文件路径：
ruoyi-ui/src/components/ImageUpload/index.vue（前端上传组件）
检查清单
- 是否遵循统一的上传接口标准
- 是否配置了正确的文件后缀白名单
- 是否使用了UUID或时间戳重命名文件
- 是否在接口上添加了防重复提交注解
- 是否限制了单次上传文件的最大大小