S3 Balance

中文 | English

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

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监控

# 克隆仓库
git clone https://github.com/DullJZ/s3-balance.git --depth=1
cd s3-balance/deploy/docker

# 修改配置
vim config.yaml

# 启动服务
docker compose up -d

Docker

# 拉取镜像
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

本地编译运行

# 克隆仓库
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 指标、路径与可选抓取 Token。
• s3api：Access/Secret Key、proxy_mode（true=服务代理，false=重定向）、auth_required（SigV4 校验）、virtual_host（Host-style 路由）。

API & 测试

• 默认监听 http://localhost:8080，支持 GET /health 健康检查、GET /metrics 指标（配置 metrics.token 后需携带 Authorization: Bearer <token>）。
• 可使用 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 清单