8.5 KiB
8.5 KiB
管理端OSS文件上传功能
📋 功能概述
基于用户端OSS上传接口 /user/oss/post-signature 实现的管理端文件上传功能，提供了更强大的文件管理能力，同时与用户端文件存储在同一目录下，便于统一管理。
✅ 已实现功能
核心接口
- ✅
POST /admin/oss/post-signature- 生成OSS POST签名 - ✅
DELETE /admin/oss/file- 删除单个文件 - ✅
POST /admin/oss/batch-delete- 批量删除文件 - ✅
GET /admin/oss/file-info- 获取文件信息 - ✅
GET /admin/oss/upload-config- 获取上传配置
技术实现
- ✅ DTO类设计: AdminOssUploadRequest、AdminOssUploadResponse
- ✅ 服务层: AdminOssService接口 + AdminOssServiceImpl实现
- ✅ 控制器: AdminOssController，包含完整的CRUD操作
- ✅ 权限验证: 使用@RequireAdminOrStaff注解，确保只有管理员可访问
- ✅ 统一目录: 与用户端共享
user_img/目录
功能特性
- ✅ 更大文件: 支持最大500MB文件上传（用户端10MB）
- ✅ 更多格式: 支持图片、文档、音视频、压缩包等全格式
- ✅ 更长有效期: 2小时有效期（用户端1小时）
- ✅ 完整管理: 支持文件删除、批量删除、信息查询
- ✅ 灵活配置: 支持自定义子目录、文件大小限制
- ✅ 操作记录: 完整的操作日志记录
📁 目录结构
项目根目录/
├── src/main/java/com/dora/
│ ├── dto/
│ │ ├── AdminOssUploadRequest.java # 管理端上传请求DTO
│ │ └── AdminOssUploadResponse.java # 管理端上传响应DTO
│ ├── service/
│ │ ├── AdminOssService.java # 管理端OSS服务接口
│ │ └── impl/
│ │ └── AdminOssServiceImpl.java # 管理端OSS服务实现
│ └── controller/
│ └── AdminOssController.java # 管理端OSS控制器
├── docs/
│ ├── admin-oss-upload-api.md # 完整API文档
│ ├── admin-oss-upload-examples.md # 使用示例
│ └── admin-oss-upload-readme.md # 本文件
└── ...
🔗 存储路径
统一存储规则
- 基础目录:
user_img/(配置在OssConfig.userImgFolder) - 用户端文件:
user_img/{用户上传的文件} - 管理端文件:
user_img/{指定子目录}/{管理端上传的文件}
推荐子目录
user_img/
├── banners/ # Banner图片 (管理端)
├── images/ # 通用图片 (管理端)
├── documents/ # 文档文件 (管理端)
├── videos/ # 视频文件 (管理端)
├── audios/ # 音频文件 (管理端)
├── uploads/ # 默认目录 (管理端)
└── {用户文件} # 用户端直接上传的文件
🚀 快速使用
1. 获取管理员Token
curl -X POST "https://your-api.com/admin/auth/login" \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"password"}'
2. 生成上传签名
curl -X POST "https://your-api.com/admin/oss/post-signature" \
-H "Authorization: Bearer {admin_token}" \
-H "Content-Type: application/json" \
-d '{
"fileName": "banner.jpg",
"directory": "banners",
"maxSizeMB": 50
}'
3. 上传文件到OSS
# 使用返回的签名信息上传到OSS
curl -X POST "{返回的host}" \
-F "key={返回的dir}文件名" \
-F "policy={返回的policy}" \
-F "OSSAccessKeyId={返回的accessKeyId}" \
-F "x-oss-signature-version={返回的version}" \
-F "x-oss-credential={返回的x_oss_credential}" \
-F "x-oss-date={返回的x_oss_date}" \
-F "signature={返回的signature}" \
-F "success_action_status=200" \
-F "file=@/path/to/your/file.jpg"
📊 功能对比
| 特性 | 用户端接口 | 管理端接口 | 说明 |
|---|---|---|---|
| 接口路径 | /user/oss/post-signature |
/admin/oss/post-signature |
路径不同 |
| 权限验证 | 无需认证 | 需要管理员Token | 安全级别不同 |
| 文件大小 | 最大10MB | 最大500MB | 管理端支持更大文件 |
| 文件格式 | 基础格式 | 全格式支持 | 管理端支持更多格式 |
| 有效期 | 1小时 | 2小时 | 管理端有效期更长 |
| 存储目录 | user_img/ |
user_img/{subdir}/ |
同一根目录 |
| 管理功能 | 仅上传 | 完整CRUD | 管理端功能更全 |
🔧 配置说明
OSS配置
# application.yml
aliyun:
oss:
endpoint: https://oss-cn-hangzhou.aliyuncs.com
bucket-name: oss-1818ai-user-img
region: cn-hangzhou
user-img-folder: user_img/ # 统一存储目录
expiration-seconds: 3600
access-key-id: ${ALIYUN_OSS_ACCESS_KEY_ID}
access-key-secret: ${ALIYUN_OSS_ACCESS_KEY_SECRET}
支持的文件格式
// 图片格式
.jpg, .jpeg, .png, .gif, .bmp, .webp, .svg, .ico, .tiff
// 文档格式
.pdf, .txt, .md, .json, .xml, .csv, .doc, .docx, .xls, .xlsx, .ppt, .pptx
// 压缩包格式
.zip, .rar, .7z, .tar, .gz, .bz2, .xz
// 音频格式
.mp3, .wav, .flac, .aac, .ogg, .wma
// 视频格式
.mp4, .avi, .mov, .wmv, .flv, .mkv, .webm
// 其他格式
.html, .css, .js, .sql, .log
🛡️ 安全特性
权限控制
- 接口级别:
@RequireAdminOrStaff注解确保只有管理员/工作人员可访问 - AspectJ切面: 自动验证JWT Token有效性和用户权限
- 身份记录: 自动记录操作者的管理员ID
文件安全
- 类型白名单: 严格的文件类型验证，防止恶意文件上传
- 大小限制: 可配置的文件大小限制，防止过大文件占用存储
- 目录隔离: 支持子目录分类，便于文件管理
- 操作审计: 完整的操作日志，支持追溯
📖 使用文档
🚨 注意事项
重要提醒
- 目录统一: 管理端和用户端文件存储在同一根目录
user_img/下 - 权限必需: 所有管理端接口都需要有效的管理员JWT Token
- 文件命名: 建议使用时间戳+随机数避免文件名冲突
- 大小限制: 注意文件大小限制，避免上传失败
- 网络超时: 大文件上传注意设置合适的超时时间
最佳实践
- 错误处理: 做好网络异常和服务器错误的异常处理
- 进度显示: 大文件上传时显示进度，提升用户体验
- 重试机制: 对于网络不稳定情况，实现上传重试
- 文件校验: 上传完成后可进行文件完整性校验
- 清理机制: 定期清理失效或无用的文件
🔍 错误排查
常见错误及解决方案
| 错误代码 | 错误信息 | 可能原因 | 解决方案 |
|---|---|---|---|
| 401 | 未授权访问 | JWT Token无效或过期 | 重新登录获取新Token |
| 403 | 权限不足 | 不是管理员或工作人员 | 确认账号权限 |
| 400 | 不支持的文件类型 | 文件格式不在白名单中 | 检查文件格式是否支持 |
| 400 | 文件大小超限 | 文件超过大小限制 | 压缩文件或选择更小的文件 |
| 500 | OSS签名生成失败 | OSS配置错误 | 检查OSS配置参数 |
调试技巧
// 开启调试模式
localStorage.setItem('debug', 'true');
// 查看详细错误信息
console.log('Upload error details:', error);
// 测试Token有效性
fetch('/admin/oss/upload-config', {
headers: { 'Authorization': `Bearer ${token}` }
})
.then(r => r.json())
.then(result => console.log('Token test:', result));
🔄 版本历史
v1.0.0 (2024-12-25)
- ✅ 实现基础的管理端OSS上传功能
- ✅ 支持与用户端统一目录存储
- ✅ 完整的文件管理CRUD操作
- ✅ 权限验证和安全控制
- ✅ 支持多种文件格式和大文件上传
🤝 技术支持
如果在使用过程中遇到问题，请按以下步骤排查：
- 检查Token: 确认管理员JWT Token有效
- 验证权限: 确认当前用户有管理员/工作人员权限
- 文件格式: 确认文件格式在支持列表中
- 大小限制: 确认文件大小在限制范围内
- 网络连接: 确认网络连接正常
- OSS配置: 确认OSS相关配置正确
最后更新: 2024-12-25
版本: v1.0.0