Stargate with Apache Cassandra 4.0 镜像文档

⚠️ 警告

此镜像适用于 Stargate v1。对于 Stargate v2，请参考 stargateio/coordinator-4_0 镜像。

一、镜像概述与主要用途

镜像概述

本镜像为 Stargate v1 版本，针对 Apache Cassandra 4.0 后端，提供开源 API 框架支持。Stargate 作为数据网关部署于客户端应用与数据库之间，以可扩展性为核心设计理念，通过插件机制支持新 API、数据类型及访问方式，简化不同应用 workload 对数据库的使用。

主要用途

• 为 Apache Cassandra 4.0 数据库提供多 API 访问能力（如 CQL、REST）
• 作为数据访问中间层，统一请求处理、路由及认证逻辑
• 简化客户端应用与 Cassandra 数据库的交互，降低“手册阅读疲劳”及数据库选型复杂度

二、核心功能与组件

Stargate 包含三大核心服务组件，协同实现数据网关功能：

1. API 服务（API Services）

负责 API 定义、请求处理与转换、结果返回，支持以下接口：

• cql：Cassandra Query Language (CQL) API 实现，提供原生 CQL 访问能力
• restapi：REST API 实现，通过 REST 接口暴露 Cassandra 数据，支持 CRUD 操作

2. 持久化服务（Persistence Services）

实现协调层，将 API 服务的请求转发至底层数据存储实例：

• persistence-api：持久化服务接口
• persistence-common：持久化服务共享工具类
• persistence-cassandra-3.11：Cassandra 协调层实现（注：文档中虽提及 3.11，但镜像针对 4.0 后端），作为仅协调节点（不存储数据）加入 Cassandra 集群，模拟系统表以支持原生驱动集成，通过 CQL QueryHandler/QueryProcessor 执行请求，并将 Cassandra 结果集转换为 Stargate 数据存储对象

3. 认证服务（Authentication Services）

负责 Stargate 访问认证：

• auth-api：生成认证令牌的 REST 服务
• auth-table-based-service：数据库中存储令牌的服务
• authentication：认证提供器接口

三、使用场景与适用范围

适用场景

• 开发与测试环境：通过开发者模式快速启动，无需单独部署 Cassandra 实例
• 多 API 访问需求：需同时支持 CQL 原生访问及 REST API 访问 Cassandra 的应用
• 数据访问层统一：需要标准化数据访问流程（认证、请求路由、结果转换）的场景

限制

• 开发者模式仅适用于开发测试，生产环境需部署独立 Cassandra 集群
• 本镜像为 Stargate v1 版本，如需使用 v2 请参考对应镜像

四、使用方法

1. 开发者模式

开发者模式无需单独部署 Cassandra 实例，适用于本地开发测试。

启动命令

docker run --name stargate \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-4_0:{stargate-docker-tag}

参数说明

• 端口映射：
  • 8081：REST 认证服务端口（令牌生成）
  • 8082：REST API 端口（CRUD 操作）
  • 9042：CQL 服务端口（本地回环地址绑定，避免与外部 Cassandra 冲突）
• 环境变量：
  • CLUSTER_NAME：集群名称（开发者模式下自定义）
  • CLUSTER_VERSION：后端版本（开发者模式下填 3.11）
  • DEVELOPER_MODE：启用开发者模式（true）
• {stargate-docker-tag}：替换为具体版本标签（如 v1.0.0）

2. Docker Compose 部署

适用于模拟生产环境的多节点部署，需配合 Cassandra 集群。官方提供多种后端的 Compose 示例：

核心配置说明

environment 部分配置对 Stargate 正常运行至关重要：

environment:
  # 集群名称必须与后端集群名称一致
  - CLUSTER_NAME=backend
  # 版本必须与后端版本匹配（如 3.11 / 4.0）
  - CLUSTER_VERSION=4.0
  # 至少配置一个种子节点（后端集群种子节点地址）
  - SEED=backend-1
  # 机架和数据中心名称必须与后端匹配（注意：Cassandra 与 DSE 默认值不同）
  - RACK_NAME=rack1
  - DATACENTER_NAME=dc1

启动方法

由于后端（Cassandra/DSE）容器启动后需时间初始化，直接启动可能导致 Stargate 因后端未就绪而失败，建议使用官方提供的 wrapper 脚本确保启动顺序：

# 示例：Cassandra 4.0 后端启动脚本
git clone [***]
cd docker-images/examples/cassandra-4.0
./start_cass40.sh

如需手动启动 Compose 文件：

docker-compose --file <compose-file.yml> up

五、配置参数说明

参考链接

• Stargate 官方文档：stargate.io
• 社区参与：stargate.io/community
• Docker Compose 示例：stargate/docker-images/examples