lunanting/qiangdanxitong
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
qiangdanxitong/S3文件存储系统实现说明.md

7.7 KiB
Raw Blame History

S3文件存储系统实现说明

📋 概述

本系统实现了基于S3兼容存储（MinIO）的文件上传、下载和管理功能，包括：

  1. S3配置管理：支持多配置管理和动态切换
  2. 文件上传：支持多文件上传到S3存储
  3. 文件下载：带登录验证的文件下载
  4. 文件记录：完整的文件上传记录和关联管理

🗄️ 数据库设计

1. S3配置表 (sys_s3_config)

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)

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 中添加：

<!-- 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配置管理标签页：

<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 中修改文件上传逻辑：

// 使用新的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. 文件下载

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. 执行数据库脚本

mysql -uroot -p designhub < database/create_s3_config.sql

2. 更新后端依赖

cd backend
mvn clean install

3. 重启后端服务

systemctl restart designhub-backend

4. 更新前端

cd frontend
pnpm build
# 部署到服务器

🔍 测试验证

1. 测试S3配置

curl -X GET http://localhost:8080/api/s3/config/active \
  -H "Authorization: Bearer YOUR_TOKEN"

2. 测试文件上传

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. 测试文件下载

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. 存储统计：显示存储空间使用情况

✅ 完成清单

  • 数据库表设计
  • 后端实体类和Mapper
  • S3Service核心服务
  • S3ConfigService配置管理
  • FileUploadController上传下载
  • S3ConfigController配置管理
  • 前端S3配置管理页面
  • 前端文件上传组件改造
  • 系统测试和部署