coco/generic-rw-s3

Generic Reader/Writer for S3 镜像文档

镜像概述和主要用途

这是一个用于读写通用负载到Amazon S3的API服务，支持通过UUID标识对数据进行PUT、GET和DELETE操作。该服务可配置从Kafka读取负载并存储到S3，适用于需要将通用格式数据持久化到S3或从Kafka消费数据并存储的场景。

核心功能和特性

• 通用负载处理：支持任意格式的负载数据，通过UUID唯一标识
• S3操作支持：提供PUT（写入）、GET（读取）、DELETE（删除）数据到S3的功能
• Kafka集成：可配置从Kafka主题读取数据并存储到S3
• 灵活的路径结构：支持为S3对象添加前缀路径，优化S3分区管理
• 并发处理：可配置并发下载数和消息并发处理模式
• 哈希校验：支持基于负载哈希的更新控制，避免重复写入

使用场景和适用范围

• 需要将通用数据（如JSON、文本等）持久化到S3的服务
• 从Kafka消费消息并异步存储到S3的数据流处理场景
• 需要通过API接口管理S3中UUID标识数据的应用

详细使用方法和配置说明

环境变量配置

Docker部署示例

基础启动命令

bash
docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e BUCKET_NAME="my-s3-bucket" \
  -e AWS_REGION="eu-west-1" \
  -e AWS_ACCESS_KEY_ID="AKID1234567890" \
  -e AWS_SECRET_ACCESS_KEY="MY-SECRET-KEY" \
  docker.xuanyuan.run/coco/generic-rw-s3

带Kafka集成的启动命令

bash
docker run -d \
  -p 8080:8080 \
  -e PORT=8080 \
  -e BUCKET_NAME="my-s3-bucket" \
  -e AWS_REGION="eu-west-1" \
  -e AWS_ACCESS_KEY_ID="AKID1234567890" \
  -e AWS_SECRET_ACCESS_KEY="MY-SECRET-KEY" \
  -e BUCKET_PREFIX="kafka-data" \
  docker.xuanyuan.run/coco/generic-rw-s3 --source-addresses="kafka-broker:9092" --source-group="consumer-group-1" --source-topic="data-topic"

本地运行方法

1. 安装依赖并编译（需Go环境）：

bash
# 安装dep
curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
# 获取源码
go get github.com/Financial-Times/generic-rw-s3
cd $GOPATH/src/github.com/Financial-Times/generic-rw-s3
# 安装依赖
dep ensure -v -vendor-only
# 编译
go install

2. 配置环境变量并启动：

bash
# 设置必填环境变量
export PORT=8080
export BUCKET_NAME="my-s3-bucket"
export AWS_REGION="eu-west-1"
# 配置AWS凭证（或通过~/.aws/credentials文件）
export AWS_ACCESS_KEY_ID="AKID1234567890"
export AWS_SECRET_ACCESS_KEY="MY-SECRET-KEY"
# 可选配置
export BUCKET_PREFIX="data-prefix"
export WORKERS=20
export SRC_CONCURRENT_PROCESSING=true

# 启动服务
$GOPATH/bin/generic-rw-s3

3. 带Kafka读取功能启动：

bash
$GOPATH/bin/generic-rw-s3 --port=8080 --bucketName="my-s3-bucket" --source-addresses="kafka-broker:9092" --source-group="consumer-group" --source-topic="data-topic"

服务端点说明

核心数据操作端点

PUT /UUID

通过UUID写入负载到S3，请求头需指定Content-Type（将作为S3对象的Content-Type存储）。
示例：

bash
curl -H "Content-Type: application/json" -X PUT -d '{"key":"value"}' http://localhost:8080/bcac6326-dd23-4b6a-9dfa-c2fbeb9737d9

S3对象路径格式：<bucket_prefix>/<uuid前8位>/<uuid中间4位>/<uuid中间4位>/<uuid中间4位>/<uuid后12位>（如prefix/123e4567/e89b/12d3/a456/426655440000）

GET /UUID

读取指定UUID对应的S3对象，返回存储的负载数据。若不存在返回404。
示例：

bash
curl http://localhost:8080/bcac6326-dd23-4b6a-9dfa-c2fbeb9737d9

DELETE /UUID

删除指定UUID对应的S3对象，成功返回204。
示例：

bash
curl -X DELETE http://localhost:8080/bcac6326-dd23-4b6a-9dfa-c2fbeb9737d9

工具端点

GET /

流式返回存储桶中所有负载数据。

GET /__ids

流式返回存储桶中所有UUID列表，每行一个JSON对象。
示例响应：

json
{"ID":"dcfa65d6-3849-445e-ac6a-15bc5a17e954"}
{"ID":"2136f8ad-e94e-45cb-b616-336f38533214"}

管理端点

• 健康检查：http://localhost:8080/__health
• 构建信息：http://localhost:8080/__build-info 或 http://localhost:8080/build-info
• 就绪检查：http://localhost:8080/__gtg

其他配置说明

哈希更新控制

服务会在S3对象元数据中存储负载的哈希值。当ONLY_UPDATES_ENABLED环境变量设为true时，会对比新负载与存储哈希：

• 哈希不同（内容更新）：执行写入，返回200
• 哈希相同（内容未变）：不执行写入，返回304 Not Modified
  可通过请求头X-Ignore-Hash: true绕过哈希检查，强制写入。

S3存储桶权限策略

需确保AWS凭证对目标S3存储桶有读写权限，推荐策略配置：

json
{
  "Version": "2012-10-17",
  "Id": "PolicyForS3RW",
  "Statement": [
    {
      "Sid": "AllowFullAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<AWS账户ID>:user/<IAM用户名>"
      },
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::<BUCKET_NAME>",
        "arn:aws:s3:::<BUCKET_NAME>/*"
      ]
    }
  ]
}

构建与部署信息

• Docker镜像地址：https://hub.docker.com/r/coco/generic-rw-s3/
• CI/CD：通过CircleCI构建（https://circleci.com/gh/Financial-Times/generic-rw-s3%EF%BC%89
• 代码覆盖率：由Coveralls提供（https://coveralls.io/github/Financial-Times/generic-rw-s3%EF%BC%89