file_system/README.md

# 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 服务)

### 安装运行

```bash
# 克隆项目
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.`

### 使用示例

```bash
# 列出所有存储桶
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 密钥，将返回：

```json
{
  "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`，主要配置项：

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

## 开发指南

### 编译项目

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

### 运行测试

```bash
go test ./...
```

### 生成 Swagger 文档

```bash
swag init -g cmd/server/main.go
```

## 部署

### Docker 部署

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

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

### Docker Compose 部署

```bash
docker-compose up -d
```

## 文档

- [API 授权使用指南](docs/AUTH_GUIDE.md)
- [Swagger API 文档](http://localhost:8080/swagger/index.html)

## 更新日志

### v1.1 (最新)
- ✨ 添加 API 授权中间件，所有接口需要密钥验证
- 📝 完善项目文档
- 🔧 优化配置管理

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

## 许可证

MIT License

## 联系方式

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