radarbase/radar-gateway

RADAR-Gateway

镜像概述和主要用途

RADAR-Gateway是Apache Kafka的REST网关，功能类似Confluent提供的REST代理，额外集成了认证授权、内容验证和按需数据解压能力。它支持Avro格式数据的JSON序列化及二进制序列化，可作为Docker镜像部署，适用于需要通过REST API安全、合规地向Kafka集群提交数据的场景。

核心功能和特性

• REST代理功能：提供与Kafka集群交互的REST API接口，支持主题管理和数据生产，兼容Confluent REST Proxy核心规范。
• 认证与授权：基于RADAR-Auth库实现用户认证，通过JWT令牌验证权限，确保仅授权用户可提交数据。
• 内容验证：强制使用Avro格式数据（JSON序列化），验证消息key和value是否符合预定义schema，确保数据结构合规。
• 数据解压：自动处理GZIP（Content-Encoding: gzip）和Apple LZFSE（Content-Encoding: lzfse）编码的压缩数据。
• 二进制数据摄入：支持基于RecordSet schema的二进制Avro格式（application/vnd.radarbase.avro.v1+binary），提升数据传输效率。

使用场景和适用范围

适用于需通过REST API向Kafka集群提交数据的场景，尤其适合：

• 物联网设备、移动应用的数据采集，需通过REST接口安全上传至Kafka。
• 对数据格式有严格要求的场景，需确保提交数据符合Avro schema规范。
• 高吞吐量数据传输场景，通过二进制格式和压缩编码减少网络带宽占用。
• 多源数据接入平台，需统一认证授权和数据验证流程。

配置说明

认证与授权通过[RADAR-Auth]库实现，具体配置选项请参考其官方文档。该库负责处理OAuth2 JWT令牌验证、权限范围检查及数据源授权管理。

使用方法

启动服务

使用docker-compose启动RADAR-Gateway及依赖组件：

shell
docker-compose up -d --build

创建Kafka主题

待kafka-1服务就绪后，创建数据提交所需的Kafka主题：

shell
TOPIC=test
docker-compose exec kafka-1 kafka-topics --create --topic $TOPIC --bootstrap-server kafka-1:9092

服务访问地址

• 网关接口：http://localhost:8090/radar-gateway/
• ManagementPortal（用于生成访问令牌）：http://localhost:8080/managementportal/

生成访问令牌

通过ManagementPortal生成JWT访问令牌，令牌需满足：

• 包含MEASUREMENT.CREATE作用域（scope），资源为res_gateway
• 包含sources数组声明，列出允许提交数据的sourceId
• sub字段需与数据key中的userId一致

访问网关API

获取主题列表

使用令牌查询可用主题：

shell
TOKEN=<从ManagementPortal获取的访问令牌>
curl -H "Authorization: Bearer $TOKEN" http://localhost:8090/radar-gateway/topics

提交压缩数据

提交GZIP压缩的Avro数据（需指定媒体类型和压缩头）：

shell
curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.kafka.avro.v2+json" \
  -H "Content-Encoding: gzip" \
  --data-binary @data.json.gz \
  http://localhost:8090/radar-gateway/topics/test

提交二进制Avro数据

使用二进制Avro格式提交数据（基于RecordSet schema）：

shell
curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/vnd.radarbase.avro.v1+binary" \
  --data-binary @record_set_data.avro \
  http://localhost:8090/radar-gateway/topics/test

客户端配置

• Java客户端启用GZIP压缩：通过radar-commons库配置：

  java
  RestClient.Builder.gzipCompression(true);
  

• 启用二进制模式：通过radar-commons的RestSender配置：

  java
  RestSender.Builder.useBinaryContent(true);
  

参考链接

• [REST Proxy文档]：[***]
• [RADAR-Auth]：https://github.com/RADAR-base/ManagementPortal/tree/master/radar-auth
• [ManagementPortal]：https://github.com/RADAR-base/ManagementPortal
• [RecordSet schema]：https://github.com/RADAR-base/RADAR-Schemas/blob/master/commons/kafka/record_set.avsc