mirror of
https://github.com/DullJZ/s3-balance.git
synced 2026-06-27 14:01:23 +08:00
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# S3 Balance
|
||
|
||
中文 | [English](./README_EN.md)
|
||
|
||
S3 Balance 是一个用 Go 编写的 S3 兼容负载均衡器，可在多套对象存储之间自动选择最佳目标桶，向上提供完整 S3 API。项目支持多种后端（AWS S3、MinIO、OSS 等）、可插拔负载策略、健康检查与统计采集、代理/重定向两种传输模式，以及简易认证和虚拟主机访问。
|
||
|
||
## 关键特性
|
||
|
||
- **标准 S3 API**：桶与对象操作、分片上传、预签名 URL 均与原生 S3 一致。
|
||
- **多桶调度**：支持轮询、剩余空间、加权和一致性哈希等策略，可热切换。
|
||
- **健康监控**：周期性探活与容量统计，Prometheus 指标暴露在 `/metrics`。
|
||
- **虚拟桶映射**：对外只暴露虚拟桶名称，真实桶在后端透明调度。
|
||
- **代理或重定向模式**：可选择由服务转发数据，或返回302重定向让客户端直连。
|
||
- **SigV4 认证**：配置 `s3api.auth_required` 后，通过 `github.com/DullJZ/s3-validate` 校验 AWS Signature Version 4 请求。
|
||
|
||
## 快速开始
|
||
|
||
### Docker Compose
|
||
|
||
#### 仅S3 Balance服务
|
||
|
||
```yaml
|
||
services:
|
||
s3-balance:
|
||
image: dulljz/s3-balance:latest
|
||
container_name: s3-balance
|
||
ports:
|
||
- "8080:8080"
|
||
volumes:
|
||
- ./config.yaml:/app/config/config.yaml
|
||
- ./data:/app/data
|
||
environment:
|
||
- TZ=Asia/Shanghai
|
||
restart: unless-stopped
|
||
command: ["/app/s3-balance", "-config", "/app/config/config.yaml"]
|
||
```
|
||
#### 含Prometheus & Grafana监控
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/DullJZ/s3-balance.git --depth=1
|
||
cd s3-balance/deploy/docker
|
||
|
||
# 修改配置
|
||
vim config.yaml
|
||
|
||
# 启动服务
|
||
docker compose up -d
|
||
```
|
||
|
||
### Docker
|
||
```bash
|
||
# 拉取镜像
|
||
docker pull dulljz/s3-balance:latest
|
||
# 准备配置与数据目录
|
||
mkdir -p ~/s3-balance/config ~/s3-balance/data
|
||
wget https://raw.githubusercontent.com/DullJZ/s3-balance/refs/heads/main/config/config.example.yaml -O ~/s3-balance/config/config.yaml
|
||
vim ~/s3-balance/config/config.yaml # 设置后端桶、数据库、S3 API 选项
|
||
# 运行
|
||
docker run -d --name s3-balance -p 8080:8080 -v ~/s3-balance/config:/app/config -v ~/s3-balance/data:/app/data dulljz/s3-balance:latest
|
||
```
|
||
|
||
### 本地编译运行
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://github.com/DullJZ/s3-balance.git --depth=1
|
||
cd s3-balance
|
||
|
||
# 安装依赖
|
||
go mod tidy
|
||
|
||
# 准备配置
|
||
cp config/config.example.yaml config/config.yaml
|
||
vim config/config.yaml # 设置后端桶、数据库、S3 API 选项
|
||
|
||
# 运行
|
||
go run cmd/s3-balance/main.go -config config/config.yaml
|
||
# 或构建：
|
||
go build -o s3-balance cmd/s3-balance/main.go
|
||
./s3-balance -config config/config.yaml
|
||
|
||
```
|
||
|
||
## 配置要点
|
||
|
||
- `server`：监听地址与超时时间。
|
||
- `database`：GORM 支持 sqlite/mysql/postgres，并存储对象元数据、分片会话等。
|
||
- `buckets`：列出真实与虚拟桶。`virtual: true` 的条目会对外暴露，真实桶为 `virtual: false`。可设置 `path_style` 与 `max_size`。
|
||
- `balancer`：策略 (`round-robin`|`least-space`|`weighted`)、健康检查周期、重试次数与延迟。
|
||
- `metrics`：是否启用 Prometheus 指标及路径。
|
||
- `s3api`：Access/Secret Key、`proxy_mode`（true=服务代理，false=重定向）、`auth_required`（SigV4 校验）、`virtual_host`（Host-style 路由）。
|
||
|
||
## API & 测试
|
||
|
||
- 默认监听 `http://localhost:8080`，支持 `GET /health` 健康检查、`GET /metrics` 指标。
|
||
- 可使用 AWS CLI、s3cmd、MinIO Client 或 `python3 test_virtual_bucket_s3.py` 验证兼容性；脚本运行前需修改 endpoint 与凭据。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
cmd/s3-balance/ # 服务入口
|
||
internal/api/ # S3 路由、对象/分片处理
|
||
internal/bucket/ # 桶客户端 & 健康监控
|
||
internal/balancer/ # 策略实现与指标
|
||
internal/middleware/ # SigV4、虚拟主机等中间件
|
||
internal/storage/ # GORM 模型与服务
|
||
pkg/presigner/ # 预签名 URL 工具
|
||
config/ # 示例配置与部署清单
|
||
deploy/ # Docker/Kubernetes/Helm 清单
|
||
```
|