243 lines
8.5 KiB
Markdown
243 lines
8.5 KiB
Markdown
# 管理端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
|
||
```bash
|
||
curl -X POST "https://your-api.com/admin/auth/login" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"admin","password":"password"}'
|
||
```
|
||
|
||
### 2. 生成上传签名
|
||
```bash
|
||
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
|
||
```bash
|
||
# 使用返回的签名信息上传到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配置
|
||
```yaml
|
||
# 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}
|
||
```
|
||
|
||
### 支持的文件格式
|
||
```java
|
||
// 图片格式
|
||
.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
|
||
|
||
### 文件安全
|
||
- **类型白名单**: 严格的文件类型验证，防止恶意文件上传
|
||
- **大小限制**: 可配置的文件大小限制，防止过大文件占用存储
|
||
- **目录隔离**: 支持子目录分类，便于文件管理
|
||
- **操作审计**: 完整的操作日志，支持追溯
|
||
|
||
## 📖 使用文档
|
||
|
||
- 📚 [完整API文档](./admin-oss-upload-api.md) - 详细的接口文档和参数说明
|
||
- 💻 [使用示例](./admin-oss-upload-examples.md) - JavaScript/Vue/React等框架的使用示例
|
||
- 🔧 [错误排查指南](#错误排查) - 常见问题和解决方案
|
||
|
||
## 🚨 注意事项
|
||
|
||
### 重要提醒
|
||
1. **目录统一**: 管理端和用户端文件存储在同一根目录 `user_img/` 下
|
||
2. **权限必需**: 所有管理端接口都需要有效的管理员JWT Token
|
||
3. **文件命名**: 建议使用时间戳+随机数避免文件名冲突
|
||
4. **大小限制**: 注意文件大小限制，避免上传失败
|
||
5. **网络超时**: 大文件上传注意设置合适的超时时间
|
||
|
||
### 最佳实践
|
||
1. **错误处理**: 做好网络异常和服务器错误的异常处理
|
||
2. **进度显示**: 大文件上传时显示进度，提升用户体验
|
||
3. **重试机制**: 对于网络不稳定情况，实现上传重试
|
||
4. **文件校验**: 上传完成后可进行文件完整性校验
|
||
5. **清理机制**: 定期清理失效或无用的文件
|
||
|
||
## 🔍 错误排查
|
||
|
||
### 常见错误及解决方案
|
||
|
||
| 错误代码 | 错误信息 | 可能原因 | 解决方案 |
|
||
|---------|---------|---------|---------|
|
||
| 401 | 未授权访问 | JWT Token无效或过期 | 重新登录获取新Token |
|
||
| 403 | 权限不足 | 不是管理员或工作人员 | 确认账号权限 |
|
||
| 400 | 不支持的文件类型 | 文件格式不在白名单中 | 检查文件格式是否支持 |
|
||
| 400 | 文件大小超限 | 文件超过大小限制 | 压缩文件或选择更小的文件 |
|
||
| 500 | OSS签名生成失败 | OSS配置错误 | 检查OSS配置参数 |
|
||
|
||
### 调试技巧
|
||
```javascript
|
||
// 开启调试模式
|
||
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操作
|
||
- ✅ 权限验证和安全控制
|
||
- ✅ 支持多种文件格式和大文件上传
|
||
|
||
## 🤝 技术支持
|
||
|
||
如果在使用过程中遇到问题，请按以下步骤排查：
|
||
|
||
1. **检查Token**: 确认管理员JWT Token有效
|
||
2. **验证权限**: 确认当前用户有管理员/工作人员权限
|
||
3. **文件格式**: 确认文件格式在支持列表中
|
||
4. **大小限制**: 确认文件大小在限制范围内
|
||
5. **网络连接**: 确认网络连接正常
|
||
6. **OSS配置**: 确认OSS相关配置正确
|
||
|
||
---
|
||
|
||
*最后更新: 2024-12-25*
|
||
*版本: v1.0.0*
|