ShowDocs
搜索文章Ctrl K

外观

← 返回Kafka列表
知识专题

Kafka：KRaft 起步与命令 ​

本轮仅静态审阅，以下命令与练习均未执行；预期结果不是本轮运行证据。早期真实服务验证仅为历史记录，不能代替当前环境验证。

实验环境 ​

本课程从能连接的日志服务开始。需要 Docker Engine、Compose v2、Python 3.12 和可用的本机 29092 端口；Windows PowerShell 与 Linux shell 都从仓库根目录执行。Docker Desktop 在 Windows 承载的是 Linux 容器，不能称为 Windows 原生 Kafka 安装。本课程固定 Apache Kafka 4.1.2，不追随 latest；这是可复现实验基线，不表示最新版本或生产选型建议。完整镜像 digest 见配置。

Kafka 4.x 使用 KRaft 管理集群元数据，不需要 ZooKeeper。本实验只有一个节点，同时担任 broker 和 controller，数据副本数为 1，服务停止就整体不可用，没有高可用保证。PLAINTEXT 只绑定本机演示，生产需要认证、TLS、容量和多节点方案。

yaml
services:
  init:
    image: apache/kafka:4.1.2@sha256:5cc2a2fd93fa2687b44015eee04fb2c3edd9e526bd64bf8bec5ff1e268772e0e
    container_name: showdocs-m4b-kafka-init
    user: '0:0'
    entrypoint: ['sh', '-c', 'chown 1000:0 /var/lib/kafka/data']
    volumes: ['data:/var/lib/kafka/data']
  broker:
    image: apache/kafka:4.1.2@sha256:5cc2a2fd93fa2687b44015eee04fb2c3edd9e526bd64bf8bec5ff1e268772e0e
    container_name: showdocs-m4b-kafka-broker
    depends_on:
      init:
        condition: service_completed_successfully
    ports: ['127.0.0.1:29092:29092']
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: INTERNAL://:9092,EXTERNAL://:29092,CONTROLLER://:9093
      KAFKA_ADVERTISED_LISTENERS: INTERNAL://broker:9092,EXTERNAL://127.0.0.1:29092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: INTERNAL:PLAINTEXT,EXTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@broker:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_LOG_DIRS: /var/lib/kafka/data
    volumes: ['data:/var/lib/kafka/data']
volumes:
  data:
    name: showdocs-m4b-kafka-data
sh
docker compose -p showdocs-m4b-kafka -f examples/kafka/compose.yaml up -d
docker exec showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-topics.sh --bootstrap-server broker:9092 --list

第二条命令成功退出才表示 Kafka 管理请求可达；容器显示 running 还不足够。第一次启动可能要重试，超过 80 秒应查日志，不靠固定等待推断就绪。

CLI 创建与读取 ​

Kafka 自带 kafka-topics.sh、kafka-console-producer.sh、kafka-console-consumer.sh。下面只创建教学 topic，不依赖自动创建；名称重复会报告已存在，不应把它当服务故障。

sh
docker exec showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-topics.sh --bootstrap-server broker:9092 --create --topic first-orders --partitions 3 --replication-factor 1
docker exec showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-topics.sh --bootstrap-server broker:9092 --describe --topic first-orders

发送一条后用独立组读取。PowerShell 的管道字符串和 Linux 的 printf 都把内容写到标准输入：

powershell
'order-001' | docker exec -i showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server broker:9092 --topic first-orders
sh
printf 'order-001\n' | docker exec -i showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-console-producer.sh --bootstrap-server broker:9092 --topic first-orders
docker exec showdocs-m4b-kafka-broker /opt/kafka/bin/kafka-console-consumer.sh --bootstrap-server broker:9092 --topic first-orders --group first-reader --from-beginning --max-messages 1 --timeout-ms 10000 --property print.partition=true --property print.offset=true

只执行当前平台的一条发送命令。预期读取 order-001，并显示 Partition 和 Offset；重复发送会得到新 offset。--from-beginning 只影响没有有效已提交位移的分区，不会强行覆盖消费组提交。

地址与 metadata ​

metadata 地址不可达时，先区分连接入口与返回的地址。bootstrap.servers 是发现入口。客户端随后使用 broker 返回的 advertised.listeners 地址，因此 TCP 握手成功不等于后续生产成功。Windows 客户端使用 127.0.0.1:29092；同一 Compose 网络内使用 broker:9092。INTERNAL 与 EXTERNAL 两个 listener 返回各自可达的地址，不能把容器里的 localhost 误当宿主机地址。

kafkacat 是 kcat 的历史命令名，本课程使用发行包自带 CLI 和明确锁定的 Python 驱动；旧别名说明仍保留为历史查阅，不假定系统装有 kcat。

来源与版本边界 ​

英文主来源：Apache 4.1 Docker、Kafka 4.1 设计、Confluent Python API。中文交叉核对：阿里云消费位点。云产品的默认保留时间和控制台命令不等于本地 Apache Kafka 的配置；本课程不照搬云默认值。驱动支持 Kafka 协议协商，本包曾有 Windows Python 与容器 CLI 的历史运行结果；本轮仅核对源码，不把历史结果当作当前环境或其他平台兼容证明。

学习顺序：本页观察 topic 后进入 分区与组；使用 Python 命令前先完成 项目依赖。排错见 诊断，练习与分开答案见 复习。

本篇的机制与失败分支可按综合练习书面推演；提示与参考答案分开提供，无需执行示例。

继续阅读