332 lines
7.7 KiB
Markdown
332 lines
7.7 KiB
Markdown
# S3文件存储系统实现说明
|
||
|
||
## 📋 概述
|
||
|
||
本系统实现了基于S3兼容存储（MinIO）的文件上传、下载和管理功能，包括：
|
||
|
||
1. **S3配置管理**：支持多配置管理和动态切换
|
||
2. **文件上传**：支持多文件上传到S3存储
|
||
3. **文件下载**：带登录验证的文件下载
|
||
4. **文件记录**：完整的文件上传记录和关联管理
|
||
|
||
---
|
||
|
||
## 🗄️ 数据库设计
|
||
|
||
### 1. S3配置表 (`sys_s3_config`)
|
||
|
||
```sql
|
||
CREATE TABLE `sys_s3_config` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT,
|
||
`endpoint` varchar(255) NOT NULL COMMENT 'S3服务端点',
|
||
`bucket` varchar(100) NOT NULL COMMENT '存储桶名称',
|
||
`access_key_id` varchar(255) NOT NULL,
|
||
`secret_access_key` varchar(255) NOT NULL,
|
||
`region` varchar(50) DEFAULT 'us-east-1',
|
||
`public_domain` varchar(255),
|
||
`enable_path_style` tinyint(1) DEFAULT 1,
|
||
`file_path` varchar(255) DEFAULT '/',
|
||
`is_active` tinyint(1) DEFAULT 1,
|
||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP,
|
||
`update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
`deleted` tinyint(1) DEFAULT 0,
|
||
PRIMARY KEY (`id`)
|
||
);
|
||
```
|
||
|
||
### 2. 文件上传记录表 (`sys_file_upload`)
|
||
|
||
```sql
|
||
CREATE TABLE `sys_file_upload` (
|
||
`id` bigint NOT NULL AUTO_INCREMENT,
|
||
`original_name` varchar(255) NOT NULL,
|
||
`stored_name` varchar(255) NOT NULL,
|
||
`file_path` varchar(500) NOT NULL,
|
||
`file_url` varchar(500) NOT NULL,
|
||
`file_size` bigint NOT NULL,
|
||
`file_type` varchar(100),
|
||
`uploader_id` bigint NOT NULL,
|
||
`uploader_name` varchar(100),
|
||
`related_type` varchar(50),
|
||
`related_id` bigint,
|
||
`create_time` datetime DEFAULT CURRENT_TIMESTAMP,
|
||
`update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
`deleted` tinyint(1) DEFAULT 0,
|
||
PRIMARY KEY (`id`),
|
||
KEY `idx_uploader` (`uploader_id`),
|
||
KEY `idx_related` (`related_type`, `related_id`)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 后端实现
|
||
|
||
### 1. Maven依赖
|
||
|
||
在 `pom.xml` 中添加：
|
||
|
||
```xml
|
||
<!-- AWS SDK for S3 -->
|
||
<dependency>
|
||
<groupId>software.amazon.awssdk</groupId>
|
||
<artifactId>s3</artifactId>
|
||
<version>2.20.26</version>
|
||
</dependency>
|
||
|
||
<!-- Apache Commons IO -->
|
||
<dependency>
|
||
<groupId>commons-io</groupId>
|
||
<artifactId>commons-io</artifactId>
|
||
<version>2.11.0</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2. 核心服务
|
||
|
||
#### S3Service
|
||
- `uploadFile()`: 上传文件到S3
|
||
- `getFileUploadById()`: 获取文件记录
|
||
- `getFilesByRelated()`: 获取关联文件列表
|
||
|
||
#### S3ConfigService
|
||
- `getActiveConfig()`: 获取激活的配置
|
||
- `createConfig()`: 创建新配置
|
||
- `updateConfig()`: 更新配置
|
||
- `activateConfig()`: 激活指定配置
|
||
|
||
### 3. API接口
|
||
|
||
#### S3配置管理 (`/api/s3/config`)
|
||
|
||
- `GET /active` - 获取激活的配置
|
||
- `GET /list` - 获取所有配置
|
||
- `GET /{id}` - 获取指定配置
|
||
- `POST /` - 创建配置
|
||
- `PUT /{id}` - 更新配置
|
||
- `DELETE /{id}` - 删除配置
|
||
- `PUT /{id}/activate` - 激活配置
|
||
|
||
#### 文件管理 (`/api/file`)
|
||
|
||
- `POST /upload` - 上传文件（需要登录）
|
||
- 参数：`files` (MultipartFile[]), `relatedType`, `relatedId`
|
||
- 返回：文件URL列表
|
||
|
||
- `GET /download/{id}` - 下载文件（需要登录，验证token）
|
||
- 自动重定向到S3文件URL
|
||
|
||
- `GET /{id}` - 获取文件信息
|
||
- `GET /list` - 获取关联文件列表
|
||
|
||
---
|
||
|
||
## 🎨 前端实现
|
||
|
||
### 1. S3配置管理页面
|
||
|
||
在 `Settings.vue` 中添加S3配置管理标签页：
|
||
|
||
```vue
|
||
<template>
|
||
<a-tab-pane key="s3" tab="S3存储配置">
|
||
<!-- S3配置表单 -->
|
||
<a-form :model="s3ConfigForm">
|
||
<a-form-item label="服务端点">
|
||
<a-input v-model:value="s3ConfigForm.endpoint" />
|
||
</a-form-item>
|
||
<a-form-item label="存储桶">
|
||
<a-input v-model:value="s3ConfigForm.bucket" />
|
||
</a-form-item>
|
||
<!-- ... 其他配置项 ... -->
|
||
<a-button @click="saveS3Config">保存配置</a-button>
|
||
</a-form>
|
||
</a-tab-pane>
|
||
</template>
|
||
```
|
||
|
||
### 2. 文件上传组件
|
||
|
||
在 `CreateTask.vue` 中修改文件上传逻辑：
|
||
|
||
```typescript
|
||
// 使用新的S3上传接口
|
||
const handleUpload = async (file: File) => {
|
||
const formData = new FormData();
|
||
formData.append('files', file);
|
||
formData.append('relatedType', 'task');
|
||
|
||
const response = await axios.post('/api/file/upload', formData, {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'multipart/form-data'
|
||
}
|
||
});
|
||
|
||
return response.data.data; // 返回文件URL数组
|
||
};
|
||
```
|
||
|
||
### 3. 文件下载
|
||
|
||
```typescript
|
||
const downloadFile = (fileId: number) => {
|
||
const token = localStorage.getItem('token');
|
||
window.open(`/api/file/download/${fileId}`, '_blank');
|
||
// 浏览器会自动携带token（如果在请求头中）
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 安全特性
|
||
|
||
### 1. 登录验证
|
||
- 所有文件上传需要有效的JWT token
|
||
- 文件下载需要验证登录状态
|
||
- token验证失败返回401错误
|
||
|
||
### 2. 敏感信息保护
|
||
- API返回时自动隐藏`secretAccessKey`
|
||
- 前端更新时支持保留原密钥
|
||
|
||
### 3. 权限控制
|
||
- 只有管理员可以配置S3
|
||
- 普通用户只能上传和下载自己有权限的文件
|
||
|
||
---
|
||
|
||
## 📝 使用流程
|
||
|
||
### 1. 配置S3存储
|
||
|
||
1. 登录系统，进入**系统设置** > **S3存储配置**
|
||
2. 填写S3配置信息：
|
||
- 服务端点：`https://s3.1080p.hk`
|
||
- 存储桶：`jsxiangche`
|
||
- AccessKey和SecretKey
|
||
- 公共域名：`https://s3.1080p.hk/jsxiangche`
|
||
- 文件路径前缀：`由壹点AI/`
|
||
3. 点击保存并激活
|
||
|
||
### 2. 上传文件
|
||
|
||
1. 在创建任务页面选择文件
|
||
2. 文件自动上传到S3
|
||
3. 系统生成文件URL并保存到数据库
|
||
4. 任务中显示附件链接
|
||
|
||
### 3. 下载文件
|
||
|
||
1. 在任务卡片或详情中点击附件链接
|
||
2. 系统验证登录状态
|
||
3. 自动跳转到S3文件下载
|
||
|
||
---
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 执行数据库脚本
|
||
|
||
```bash
|
||
mysql -uroot -p designhub < database/create_s3_config.sql
|
||
```
|
||
|
||
### 2. 更新后端依赖
|
||
|
||
```bash
|
||
cd backend
|
||
mvn clean install
|
||
```
|
||
|
||
### 3. 重启后端服务
|
||
|
||
```bash
|
||
systemctl restart designhub-backend
|
||
```
|
||
|
||
### 4. 更新前端
|
||
|
||
```bash
|
||
cd frontend
|
||
pnpm build
|
||
# 部署到服务器
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 测试验证
|
||
|
||
### 1. 测试S3配置
|
||
|
||
```bash
|
||
curl -X GET http://localhost:8080/api/s3/config/active \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 2. 测试文件上传
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/file/upload \
|
||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||
-F "files=@test.pdf" \
|
||
-F "relatedType=task" \
|
||
-F "relatedId=1"
|
||
```
|
||
|
||
### 3. 测试文件下载
|
||
|
||
```bash
|
||
curl -X GET http://localhost:8080/api/file/download/1 \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
---
|
||
|
||
## 📌 注意事项
|
||
|
||
1. **S3配置安全**：
|
||
- AccessKey和SecretKey存储在数据库中，需要加密存储（可选）
|
||
- 管理界面只对管理员开放
|
||
|
||
2. **文件大小限制**：
|
||
- 需要在Nginx和Spring Boot中配置文件大小限制
|
||
- 建议单文件不超过100MB
|
||
|
||
3. **文件命名**：
|
||
- 使用时间戳+UUID避免文件名冲突
|
||
- 保留原始文件名用于显示
|
||
|
||
4. **错误处理**：
|
||
- S3服务不可用时给出友好提示
|
||
- 上传失败后清理临时文件
|
||
|
||
5. **性能优化**：
|
||
- 使用S3的预签名URL实现直传（可选）
|
||
- 大文件使用分片上传（可选）
|
||
|
||
---
|
||
|
||
## 🎯 后续优化建议
|
||
|
||
1. **直传优化**：前端直接上传到S3，后端只生成签名
|
||
2. **CDN加速**：配置CloudFlare等CDN加速文件访问
|
||
3. **图片处理**：集成图片压缩和格式转换
|
||
4. **文件预览**：支持PDF、图片等文件在线预览
|
||
5. **批量操作**：支持批量删除和批量下载
|
||
6. **存储统计**：显示存储空间使用情况
|
||
|
||
---
|
||
|
||
## ✅ 完成清单
|
||
|
||
- [x] 数据库表设计
|
||
- [x] 后端实体类和Mapper
|
||
- [x] S3Service核心服务
|
||
- [x] S3ConfigService配置管理
|
||
- [x] FileUploadController上传下载
|
||
- [x] S3ConfigController配置管理
|
||
- [ ] 前端S3配置管理页面
|
||
- [ ] 前端文件上传组件改造
|
||
- [ ] 系统测试和部署
|