📚 课程目录第4章环境搭建与Kafka集群部署

4. 环境搭建与Kafka集群部署：单机与集群模式选择、Docker Compose快速部署方案、关键配置参数

在回测标签口径校准系统中，Kafka 作为事件流与标签数据的核心传输总线，其部署模式直接影响开发效率、测试可靠性以及生产环境的吞吐能力。本章将围绕单机与集群模式的选择依据、基于 Docker Compose 的快速部署方案以及关键配置参数展开，为后续的 Topic 设计与流处理作业提供稳定的基础设施。

4.1 单机模式 vs 集群模式：选型对比

Kafka 的部署模式主要分为单机（Standalone）与集群（Cluster）两种。在回测标签口径校准的场景下，两种模式各有适用阶段：

对比维度	单机模式	集群模式
适用阶段	本地开发、单元测试、小规模回测验证	集成测试、预发布、生产环境
节点数量	1 个 Broker	3 个或更多 Broker
数据冗余	无副本，单点故障即丢失数据	副本因子 ≥ 2，支持故障转移
吞吐能力	受限于单机磁盘与网络 I/O	水平扩展，分区负载均衡
ZooKeeper / KRaft	可依赖单节点 ZooKeeper 或 KRaft 内置	需独立 ZooKeeper 集群或 KRaft 共识
运维复杂度	低，适合快速迭代	中高，需监控 Broker 与 Controller 状态

推荐策略： 在课程案例中，本地原型验证阶段使用单机模式；当需要验证多消费者组并行消费、标签数据重平衡或故障恢复场景时，切换到 3 节点集群模式。

4.2 Docker Compose 快速部署方案

为降低环境搭建门槛并保证跨平台一致性，本课程采用 Docker Compose 作为容器化部署工具。以下方案同时支持单机与集群两种模式，通过 docker-compose.yml 中的服务数量控制切换。

4.2.1 单机模式部署（开发环境）

version: '3.8'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    ports:
      - "2181:2181"

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1

4.2.2 集群模式部署（3 节点，集成测试环境）

version: '3.8'
services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000
    ports:
      - "2181:2181"

  kafka1:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 2
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 3

  kafka2:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9093:9093"
    environment:
      KAFKA_BROKER_ID: 2
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9093
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 2
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 3

  kafka3:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    ports:
      - "9094:9094"
    environment:
      KAFKA_BROKER_ID: 3
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9094
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9094
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 3
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 2
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 3

  启动命令：

  单机模式：docker-compose -f docker-compose-standalone.yml up -d

  集群模式：docker-compose -f docker-compose-cluster.yml up -d

  验证集群状态：docker exec -it kafka1 kafka-broker-api-versions --bootstrap-server localhost:9092

4.3 关键配置参数详解

Kafka 的性能、可靠性与数据一致性高度依赖配置参数的调优。以下列出回测标签口径校准场景中最关键的参数及其推荐值：

参数名称	推荐值	说明
`num.partitions`	3 ~ 6	标签 Topic 的分区数，影响并行消费粒度；建议与消费者组内最大并行度对齐
`default.replication.factor`	3（集群）/ 1（单机）	副本因子，保证数据冗余与高可用
`min.insync.replicas`	2	最小同步副本数，配合 acks=all 防止数据丢失
`log.retention.hours`	72	标签数据保留时间，回测场景通常需要保留 3~7 天
`log.segment.bytes`	1073741824 (1GB)	日志段大小，影响文件清理与索引效率
`message.max.bytes`	10485760 (10MB)	单条消息最大字节，标签载荷通常较小，但需预留空间
`compression.type`	lz4	生产者端压缩，降低网络带宽与磁盘占用
`auto.create.topics.enable`	false	关闭自动创建 Topic，避免口径校准过程中意外生成脏数据

注意： 在回测标签口径校准场景中，auto.create.topics.enable 务必设置为 false。所有 Topic 应通过管理脚本或 Kafka Admin Client 预先创建，并指定分区数与副本因子，防止因消费者自动创建 Topic 导致分区数不匹配或副本因子不足。

4.4 部署架构示意

下图展示了基于 Docker Compose 的 3 节点 Kafka 集群与 ZooKeeper 的部署关系，以及回测标签数据流的写入与消费路径：

bootstrap.servers 指定任意 Broker 即可发现集群 • 消费者组内各实例自动分配分区，无需手动干预

4.5 部署后验证清单

完成 Docker Compose 启动后，建议按以下步骤验证环境可用性：

检查容器状态： docker-compose ps 确认所有服务均为 Up 状态。
测试 ZooKeeper 连通性： echo ruok | nc localhost 2181 应返回 imok。
列出 Kafka Broker 版本： docker exec kafka1 kafka-broker-api-versions --bootstrap-server localhost:9092。
创建测试 Topic： docker exec kafka1 kafka-topics --create --topic test-tag-calibration --partitions 3 --replication-factor 3 --bootstrap-server localhost:9092。
生产与消费验证： 使用 kafka-console-producer 与 kafka-console-consumer 发送并接收一条消息，确认端到端通路正常。

快速验证脚本（bash）：

#!/bin/bash
# 验证 Kafka 集群可用性
BOOTSTRAP="localhost:9092"
echo "=== 1. 检查 Broker 列表 ==="
docker exec kafka1 kafka-broker-api-versions --bootstrap-server $BOOTSTRAP | head -5
echo "=== 2. 创建测试 Topic ==="
docker exec kafka1 kafka-topics --create --topic verify-topic --partitions 3 --replication-factor 3 --bootstrap-server $BOOTSTRAP --if-not-exists
echo "=== 3. 发送测试消息 ==="
echo '{"tag":"口径校准测试","value":0.95}' | docker exec -i kafka1 kafka-console-producer --topic verify-topic --bootstrap-server $BOOTSTRAP
echo "=== 4. 消费测试消息 ==="
docker exec kafka1 kafka-console-consumer --topic verify-topic --from-beginning --bootstrap-server $BOOTSTRAP --max-messages 1
echo "=== 验证完成 ==="

4.6 环境清理与重置

在回测标签口径校准的迭代过程中，经常需要重置环境以清除历史数据。Docker Compose 提供了便捷的清理方式：

# 停止并移除容器、网络
docker-compose -f docker-compose-cluster.yml down

# 删除持久化数据卷（谨慎操作）
docker volume prune -f

# 重新启动
docker-compose -f docker-compose-cluster.yml up -d

数据持久化建议： 在 docker-compose.yml 中为 Kafka 与 ZooKeeper 挂载命名卷（如 kafka-data1、zookeeper-data），避免每次 down 后丢失 Topic 元数据。仅在需要完全重置回测环境时执行 docker volume prune。

通过本章的环境搭建，你已经拥有了一个可随时切换单机/集群模式的 Kafka 基础设施。下一阶段将基于此环境创建回测标签 Topic，并配置口径校准所需的序列化与分区策略。