cql-proxy

镜像概述和主要用途

cql-proxy是一个客户端CQL代理/边车，它监听本地地址并安全转发应用的CQL流量。该镜像主要用于实现不支持的CQL驱动与DataStax Astra集群的通信，同时允许现有Apache Cassandra或DataStax Enterprise (DSE)应用无需代码修改即可迁移至Astra。

!cql-proxy

核心功能和特性

• 本地监听与流量转发：监听本地地址，安全转发应用的CQL流量至目标集群
• 多集群支持：兼容DataStax Astra集群和Apache Cassandra集群
• 灵活认证方式：支持Astra令牌认证、Astra安全连接包认证及传统用户名密码认证
• 配置灵活性：支持通过命令行标志或环境变量进行配置
• 健康检查：提供存活和就绪性检查功能
• 协议版本控制：可配置初始及最大CQL协议版本

使用场景和适用范围

cql-proxy适用于以下场景：

• 需使用不支持DataStax Astra的CQL驱动（如legacy DataStax驱动、gocql、rust-driver等社区驱动）时
• 现有Apache Cassandra或DSE应用需迁移至Astra，且希望避免代码修改时
• 应用需通过本地代理与远程CQL集群通信，确保连接安全性时

注意：新建应用若使用DataStax官方驱动，无需使用cql-proxy，驱动可直接与Astra通信。

快速开始

连接DataStax Astra集群

使用Astra令牌

docker run -p 9042:9042 \
  datastax/cql-proxy:v0.1.2 \
  --astra-token <astra-token> --astra-database-id <astra-database-id>

<astra-token>可通过这些说明生成。

使用Astra安全连接包

需将安全连接包挂载至容器卷：

docker run -v <your-secure-connect-bundle.zip>:/tmp/scb.zip -p 9042:9042 \
--rm datastax/cql-proxy:v0.1.2 \
--astra-bundle /tmp/scb.zip --username <astra-client-id> --password <astra-client-secret>

连接Apache Cassandra集群

docker run -p 9042:9042 \
  datastax/cql-proxy:v0.1.2 \
  --contact-points <集群节点IP或DNS名称> [--username <用户名>] [--password <密码>]

配置说明

命令行标志和环境变量

使用-h或--help标志可查看所有配置标志及其描述和对应的环境变量（以下以$开头的项）：

$ ./cql-proxy -h
Usage: cql-proxy

Flags:
  -h, --help                                              显示上下文相关帮助
  -b, --astra-bundle=STRING                               Astra数据库的安全连接包路径。需配合'--username'和'--password'使用。若使用令牌或联系点选项则忽略 ($ASTRA_BUNDLE)
  -t, --astra-token=STRING                                用于Astra数据库认证的令牌。需配合'--astra-database-id'使用。若使用安全连接包或联系点选项则忽略 ($ASTRA_TOKEN)
  -i, --astra-database-id=STRING                          Astra数据库的数据库ID。需配合'--astra-token'使用 ($ASTRA_DATABASE_ID)
      --astra-api-url="[***]"    Astra API的URL ($ASTRA_API_URL)
  -c, --contact-points=CONTACT-POINTS,...                 集群的联系点。若使用安全连接包或令牌选项则忽略 ($CONTACT_POINTS)
  -u, --username=STRING                                   认证用户名 ($USERNAME)
  -p, --password=STRING                                   认证密码 ($PASSWORD)
  -r, --port=9042                                         连接集群时使用的默认端口 ($PORT)
  -n, --protocol-version="v4"                             连接后端集群时使用的初始协议版本（默认：v4，选项：v3, v4, v5, DSEv1, DSEv2）($PROTOCOL_VERSION)
  -m, --max-protocol-version="v4"                         后端集群支持的最大协议版本（默认：v4，选项：v3, v4, v5, DSEv1, DSEv2）($MAX_PROTOCOL_VERSION)
  -a, --bind=":9042"                                      服务器绑定地址 ($BIND)
  -f, --config=CONFIG                                     YAML配置文件 ($CONFIG_FILE)
      --debug                                             显示调试日志 ($DEBUG)
      --health-check                                      启用存活和就绪性检查 ($HEALTH_CHECK)
      --http-bind=":8000"                                 用于健康检查的HTTP服务器绑定地址 ($HTTP_BIND)
      --heartbeat-interval=30s                            对集群执行心跳检查的间隔 ($HEARTBEAT_INTERVAL)
      --idle-timeout=60s                                  成功心跳后连接被视为无响应并关闭前的持续时间 ($IDLE_TIMEOUT)
      --readiness-timeout=30s                             代理无法连接后端集群后被视为未就绪的持续时间 ($READINESS_TIMEOUT)
      --num-conns=1                                       向后端集群每个节点创建的连接数 ($NUM_CONNS)
      --rpc-address=STRING                                在'system.local'表中'rpc_address'字段公布的地址。配置对等代理时必须设置 ($RPC_ADDRESS)
      --data-center=STRING                                系统表中使用的数据中心 ($DATA_CENTER)
      --tokens=TOKENS,...                                 系统表中使用的令牌。不推荐使用 ($TOKENS)

配置方法示例

使用命令行标志

docker run -p 9042:9042 \
  --rm datastax/cql-proxy:v0.1.2 \
  --astra-token <astra-token> --astra-database-id <astra-database-id>

使用环境变量

docker run -p 9042:9042  \
  --rm datastax/cql-proxy:v0.1.2 \
  -e ASTRA_TOKEN=<astra-token> -e ASTRA_DATABASE_ID=<astra-database-id>