Docker部署Kafka集群需先创建专用网络（如kafka-net）并确保ZooKeeper与Kafka容器均加入该网络，正确配置KAFKA_ADVERTISED_LISTENERS区分内外地址，ZooKeeper使用3节点高可用模式，Java客户端通过host.docker.internal（Mac/Win）或宿主机IP（Linux）连接，避免localhost和默认bridge网络。
Java 应用要对接 Kafka 集群，前提是底层 Kafka 和 ZooKeeper 必须稳定、可发现、网络互通。Docker 部署分布式集群不是简单跑几个容器，而是要确保节点间能互相识别、选举、同步元数据——尤其对 Java 客户端（如 KafkaProducer/KafkaConsumer）而言，advertised listeners 和 network 隔离策略 是最容易出错的两个环节。
必须先创建专用 Docker 网络
ZooKeeper 集群节点之间、Kafka 节点与 ZooKeeper 之间、Java 应用与 Kafka 之间，都需要可靠内网通信。不能依赖默认 bridge 网络或 host 模式。
- 执行：
docker network create --driver bridge --subnet 172.20.0.0/16 --gateway 172.20.0.1 kafka-net - 所有容器（ZooKeeper、Kafka、甚至你的 Java 应用容器）都必须显式加入该网络，例如：
--network kafka-net - 避免使用
localhost或127.0.0.1作为服务地址——它们在容器间不互通
ZooKeeper 集群配置要点（3 节点）
单节点 ZooKeeper 仅适合开发验证；生产级 Java 应用依赖 ZooKeeper 的高可用和 leader 选举能力，至少部署 3 节点。
- 每个节点需唯一
ZOO_MY_ID（1/2/3），且ZOO_SERVERS列表必须完全一致、包含全部节点地址 - 推荐使用官方镜像
zookeeper:3.8.2或confluentinc/cp-zookeeper:7.4.0，避免老旧版本兼容问题 - 关键环境变量示例（zoo1）：
ZOO_MY_ID=1ZOO_SERVERS=server.1=zoo1:2888:3888;2181 server.2=zoo2:2888:3888;2181 server.3=zoo3:2888:3888;2181 - 端口映射只暴露客户端端口（2181），内部选举端口（2888/3888）无需对外暴露，但必须在自定义网络内可达
Kafka 集群与 Java 客户端连通性关键设置
Kafka 节点必须正确广播自身地址，否则 Java 客户端拿到错误 host/port，连接 broker 失败或消费中断。
立即学习“Java免费学习笔记（深入）”；
-
KAFKA_ADVERTISED_LISTENERS必须区分「内部通信」和「外部接入」：PLAINTEXT://kafka1:9092,PLAINTEXT_HOST://host.docker.internal:9092
其中kafka1是容器 hostname（用于集群内通信），host.docker.internal是 Docker Desktop 提供的宿主机别名（供本地 Java 进程连接） -
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP和KAFKA_INTER_BROKER_LISTENER_NAME需严格匹配，否则 broker 间无法同步元数据 - Java 客户端配置
bootstrap.servers应指向host.docker.internal:9092（Mac/Windows）或172.20.0.1:9092（Linux 宿主机 IP），而非容器 IP - 若 Java 应用也运行在 Docker 中（如 Spring Boot 容器），则
bootstrap.servers直接填kafka1:9092,kafka2:9092,kafka3:9092
验证集群状态与 Java 连通性
部署后不能只看容器 running，要确认 ZooKeeper 节点角色和 Kafka broker 注册状态。
- 进入任意 ZooKeeper 容器：
docker exec -it zoo1 sh→ 执行echo stat | nc localhost 2181，检查 Mode 是否为 leader/follower - 进入 Kafka 容器：
docker exec -it kafka1 sh→ 运行：./bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092
成功返回 API 版本列表，说明 broker 正常响应 - 在 Java 工程中运行一个最小消费者（订阅任意 topic），观察是否能拉取到消息；若超时或报
UnknownHostException，大概率是 advertised listener 或网络配置错误
