用 Docker 搭建 Kafka 分布式环境需以 ZooKeeper（或 KRaft）协调为核心，通过 docker-compose.yml 定义自定义网络、正确 advertised.listeners、持久化卷及健康检查，启动后须验证 topic 创建与消息收发，确保集群真正可用。
选对模式：ZooKeeper 还是 KRaft？
Kafka 3.3+ 支持无 ZooKeeper 的 KRaft 模式，但目前（2026年）多数生产环境和镜像生态仍以 ZooKeeper 协调为主，稳定性与工具链更成熟。
- 新手或测试环境推荐 ZooKeeper 模式：镜像丰富（如
wurstmeister/kafka、confluentinc/cp-kafka）、文档全、排错资料多 - 新项目且用 Kafka 3.8+ 可试 KRaft：省去 ZooKeeper 维护，但需注意官方镜像对 KRaft 的默认支持仍在完善中（例如部分镜像需显式启用
KAFKA_PROCESS_ROLES和KAFKA_NODE_ID）
写好 docker-compose.yml：四要素缺一不可
一个可用的分布式 Kafka 集群至少包含 1 个协调服务（ZooKeeper 或 KRaft controller）+ 3 个 Broker 节点。配置必须明确：
-
网络驱动：定义自定义 bridge 网络（如
kafka-net），确保容器间 DNS 可解析（如broker1:9092） -
主机名与 advertised.listeners：每个 Broker 必须通过
hostname和environment中的KAFKA_ADVERTISED_LISTENERS告诉客户端“从外部怎么连你”，常见写法：PLAINTEXT://host.docker.internal:9092（Mac/Win）或PLAINTEXT://宿主机IP:9092（Linux） -
持久化卷：为 ZooKeeper 的
/data和每个 Kafka 的/kafka挂载命名卷（如kafka-data-1），避免容器重启丢数据 -
资源限制与健康检查：加
mem_limit防止 OOM；用healthcheck判断 Broker 是否真正就绪（不只是端口通）
启动与验证：别只看容器是否 running
容器起来 ≠ 集群可用。关键验证步骤：
- 执行
docker-compose ps确认所有服务状态为healthy（非 justUp） - 进任意 Broker 容器：
docker-compose exec broker1 bash，运行kafka-topics.sh --bootstrap-server localhost:9092 --list查看 topic 列表（首次应为空） - 创建 topic 测试：
kafka-topics.sh --create --topic test --partitions 3 --replication-factor 3 --bootstrap-server localhost:9092，成功说明副本同步正常 - 用
kafka-console-producer.sh和kafka-console-consumer.sh发送/接收消息，确认端到端通路
后续可扩展点：让环境真正“分布式”起来
单机 Docker Compose 是分布式逻辑的模拟，但已具备横向扩展基础：
- 增加 Broker 数量：复制 service 块，改 hostname、port 映射、卷名、
KAFKA_BROKER_ID，再docker-compose up -d - 接入外部客户端：只要宿主机防火墙放行 9092 等端口，并确保
advertised.listeners指向宿主机可访问地址，Java/Python 生产者就能直连 - 加管控组件：在 compose 文件里追加
kafdrop（轻量 Web UI）或confluent-control-center（企业级），共享同一网络即可自动发现集群
