RustFS 文件存储系统

基于 RustFS S3 兼容存储的高性能文件服务系统，提供文件上传、下载、分片上传、存储桶管理等完整功能。

功能特性

• ✅ 文件操作: 上传、下载、删除、列表、预览
• ✅ 分片上传: 支持大文件分片上传，提高上传成功率
• ✅ 存储桶管理: 创建、列表、删除存储桶
• ✅ API 授权: 所有 API 接口都需要密钥验证，保证安全性
• ✅ Swagger 文档: 完整的 API 文档支持
• ✅ Web UI: 提供简洁的 Web 界面

技术栈

• 框架: Gin (Go Web Framework)
• 存储: RustFS S3 (AWS S3 Compatible)
• API 文档: Swagger
• 架构模式: CQRS + Mediator

快速开始

环境要求

• Go 1.23.2+
• Docker (用于运行 RustFS 服务)

安装运行

# 克隆项目
git clone http://192.168.1.154:8888/root/file_service.git
cd file_service

# 启动 RustFS 服务
docker-compose up -d

# 编译并运行服务
go run cmd/server/main.go

服务将在 http://localhost:8080 启动

访问地址

• Web UI: http://localhost:8080/web
• API 文档: http://localhost:8080/swagger/index.html

API 授权

安全性

所有 API 接口都需要通过授权验证才能访问。每个请求必须在请求头中包含有效的 API 密钥。

授权信息

• 请求头: X-API-Key
• 密钥值: xn001624.

使用示例

# 列出所有存储桶
curl -X GET http://localhost:8080/buckets \
  -H "X-API-Key: xn001624."

# 上传文件
curl -X POST http://localhost:8080/files/upload \
  -H "X-API-Key: xn001624." \
  -F "file=@/path/to/file.txt" \
  -F "bucket=my-bucket" \
  -F "path=/uploads/"

# 下载文件
curl -X GET "http://localhost:8080/files/download?bucket=my-bucket&path=/uploads/file.txt" \
  -H "X-API-Key: xn001624." \
  -o downloaded_file.txt

错误响应

如果未提供或提供了无效的 API 密钥，将返回：

{
  "code": 401,
  "message": "未授权：请在请求头中提供有效的API密钥",
  "error": "Missing or invalid API key"
}

API 接口

文件操作

接口	方法	描述
/files/upload	POST	上传文件
/files/download	GET	下载文件
/files/list	GET	列出文件
/files/preview	GET	获取文件预览URL
/files/delete	DELETE	删除文件

分片上传

接口	方法	描述
/files/multipart/init	POST	初始化分片上传
/files/multipart/part	PUT	上传分片
/files/multipart/complete	POST	完成分片上传

存储桶操作

接口	方法	描述
/buckets	POST	创建存储桶
/buckets	GET	列出存储桶
/buckets	DELETE	删除存储桶

项目结构

file_service/
├── cmd/
│   └── server/
│       └── main.go              # 程序入口
├── internal/
│   ├── api/
│   │   ├── endpoints/           # API 端点定义
│   │   ├── handlers/            # 请求处理器
│   │   └── validators/          # 请求验证器
│   ├── common/                  # 公共配置和工具
│   ├── domain/
│   │   └── repository/          # 数据仓储接口
│   ├── infrastructure/
│   │   ├── mediator/            # CQRS Mediator 实现
│   │   └── s3/                  # S3 客户端实现
│   └── middleware/
│       └── auth.go              # 授权中间件
├── docs/
│   └── AUTH_GUIDE.md            # 授权使用指南
├── web/                         # Web UI 资源
├── docker-compose.yml           # Docker 编排配置
├── Dockerfile                   # Docker 镜像构建
└── .gitlab-ci.yml               # CI/CD 配置

配置

配置文件位于 internal/common/config.go，主要配置项：

type Config struct {
    ServerPort      string  // 服务端口
    RustFSEndpoint  string  // RustFS S3 端点
    RustFSAccessKey string  // RustFS 访问密钥
    RustFSSecretKey string  // RustFS 秘密密钥
    RustFSRegion    string  // S3 区域
    RustFSUseSSL    bool    // 是否使用 SSL
}

开发指南

编译项目

go build -o file-service ./cmd/server/main.go

运行测试

go test ./...

生成 Swagger 文档

swag init -g cmd/server/main.go

部署

Docker 部署

# 构建镜像
docker build -t file-service:latest .

# 运行容器
docker run -p 8080:8080 file-service:latest

Docker Compose 部署

docker-compose up -d

文档

• API 授权使用指南
• Swagger API 文档

更新日志

v1.1 (最新)

• ✨ 添加 API 授权中间件，所有接口需要密钥验证
• 📝 完善项目文档
• 🔧 优化配置管理

v1.0

• 🎉 初始版本发布
• ✨ 实现基础文件操作功能
• ✨ 实现分片上传功能
• ✨ 实现存储桶管理功能

许可证

MIT License

联系方式

如有问题或建议，请提交 Issue 或 Merge Request。