001|Kafka 快速上手:核心概念与第一条消息

罗兴波发布于
文章摘要

用固定版本的 Kafka 与 Python SDK 跑通一发一收,认识 Topic、Partition、Offset 和消费组,明确发送确认、手动提交及重复处理的最小边界。

这是消息队列专题第 1 篇,也是 Kafka 小专题第 1 篇。先跑通一条消息,再理解它为什么这样工作。下一篇讨论存储与消息清理。

先看结论、场景与前提

Kafka 可以先理解成一组按分区追加、允许不同业务独立读取的事件日志。“订单已创建”写入一次,通知服务和分析服务可以分别读取;消费者读过以后,记录通常还在,直到触发保留或清理策略。官方概念说明

本篇适合第一次把 Python 程序接入 Kafka 的开发者。完成标准只有三个:创建一个三分区 Topic;收到一次生产者发送确认;消费者处理后提交进度。这里没有连接业务数据库,打印仅代表示例处理动作,不能直接替换为未经设计的扣款或库存变更。

服务端与 SDK 固定为 Apache Kafka 4.4.0、confluent-kafka 2.16.1,Python 使用 3.10 及以上版本,命令面向 macOS/Linux 的 Bash 或 Zsh,Windows 可在 WSL2 中按相同路径操作。Kafka 的 Python SDK 版本不需要与服务端版本数字相同。服务端发布记录与SDK 固定版本页面均已核对。

下面是依据官方资料编写的可复现示例;本文未实际启动 Broker,输出描述是预期行为,不是实测记录。只使用本机回环地址、无认证单节点,适用于学习。生产部署需要另行设计多副本、身份认证、TLS、数据卷与监控。

先认识六个对象

  • Broker:接收、保存和提供消息读取的 Kafka 服务进程。
  • Topic:业务事件的命名集合,例如订单事件。
  • Partition:Topic 的一个分区,每个分区内部有自己的记录顺序。
  • Offset:记录在分区内的逻辑位置;不同分区的 Offset 不能直接比大小。
  • Producer:把事件发送到 Topic 的客户端。
  • Consumer group:使用同一个 group.id 协作读取分区的一组消费者;另一个组拥有自己的读取进度。
Python Producer
      |
      v
Topic: mq-demo-events
  Partition 0: [offset 0][offset 1]...
  Partition 1: [offset 0][offset 1]...
  Partition 2: [offset 0][offset 1]...
      |
      v
Consumer group: mq-demo-workers
      |
      v
业务处理成功 -> 提交“下次从哪里继续读”

不要把一个 Topic 想成所有消费者共同争抢、取走即消失的单一列表。这个区别会影响后面的扩容和重放设计。本系列使用普通 Consumer 的经典消费组模型,不覆盖 Share Groups。

第一步:准备目录与依赖

安装并启动 Docker Desktop,或安装 Docker Engine 与 Compose 插件,可参照 Docker 官方安装入口。以下检查应能返回版本及服务端信息;只有 Docker CLI 而后台未运行时,先启动 Docker。

docker version
docker compose version
python3 --version
mkdir kafka-demo
cd kafka-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'confluent-kafka==2.16.1'

本文固定 SDK 已在 Python 3.10 隔离环境完成安装与导入;其他 Python 版本仍需在实际平台确认对应发行包。若当前平台没有对应 wheel、pip 转为源码构建并提示缺少 librdkafka,不要反复改系统库,先使用有对应发行包的 Python 版本和平台;源码构建按客户端维护方说明单独处理。

第二步:启动一个本地 Kafka

把下面内容保存为 compose.yaml:

services:
  kafka:
    image: apache/kafka:4.4.0
    container_name: mq-demo-kafka
    hostname: kafka
    ports:
      - "127.0.0.1:19092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: INTERNAL://:29092,EXTERNAL://:9092,CONTROLLER://:9093
      KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:29092,EXTERNAL://127.0.0.1:19092
      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@kafka:9093
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
      KAFKA_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_LOG_DIRS: /tmp/mq-demo-kafka-logs
      KAFKA_LOG_RETENTION_CHECK_INTERVAL_MS: 5000

这里把一个进程同时作为 Broker 和 KRaft Controller,使用固定单节点仲裁成员,学习环境不需要 ZooKeeper。没有配置持久化卷:容器停止后再启动通常仍保留容器内数据,但删除容器会丢失本例日志。

端口要分清两条路径:主机上的 Python 使用 127.0.0.1:19092,容器内命令使用 kafka:29092。advertised.listeners 是 Broker 告诉客户端“接下来连这里”的地址,不能只把端口映射改成 19092,却仍对主机客户端通告容器地址。配置方式参考 Kafka Docker 文档和官方单节点示例。

docker compose up -d
docker compose logs --tail=80 kafka
docker exec mq-demo-kafka /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server kafka:29092 --list

最后一个命令成功返回、即使列表为空,也说明已经可以执行管理请求。启动中的连接失败可稍后重试;若持续失败,先检查日志。不要用“容器状态是 Up”代替 Kafka 已就绪。

第三步:明确创建 Topic

docker exec mq-demo-kafka /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server kafka:29092 --create --if-not-exists \
  --topic mq-demo-events --partitions 3 --replication-factor 1 \
  --config cleanup.policy=delete --config retention.ms=600000

docker exec mq-demo-kafka /opt/kafka/bin/kafka-topics.sh \
  --bootstrap-server kafka:29092 --describe --topic mq-demo-events

预期能看到 PartitionCount 为 3、副本数为 1。重复命令不会重建已有 Topic;如果同名 Topic 曾按别的参数创建,要以 describe 的真实配置为准。这是专用学习名称,不要拿现有业务 Topic 来试。

保留十分钟是为了方便观察,不保证消费者有十分钟之外的恢复机会。单副本则意味着没有第二台 Broker 帮它保留数据;此时 acks=all 也不能创造副本。

第四步:发送一条 JSON 事件

保存为 producer.py:

import argparse
import json
import uuid

from confluent_kafka import Producer


parser = argparse.ArgumentParser()
parser.add_argument("--topic", default="mq-demo-events")
parser.add_argument("--partition", type=int, choices=(0, 1, 2), default=0)
args = parser.parse_args()

producer = Producer({
    "bootstrap.servers": "127.0.0.1:19092",
    "client.id": "mq-demo-producer",
    "enable.idempotence": True,
    "acks": "all",
    "message.timeout.ms": 10000,
})
result = {"delivered": False, "error": None}


def on_delivery(error, message):
    # 回调确认发送结果;produce() 返回只代表进入客户端队列。
    if error is not None:
        result["error"] = str(error)
        return
    result["delivered"] = True
    print(
        f"发送确认 topic={message.topic()} "
        f"partition={message.partition()} offset={message.offset()}",
        flush=True,
    )


event = {
    "event_id": str(uuid.uuid4()),
    "order_id": "demo-order-1001",
    "event_type": "order.created",
}
producer.produce(
    args.topic,
    key=event["order_id"].encode("utf-8"),
    value=json.dumps(event, ensure_ascii=False).encode("utf-8"),
    partition=args.partition,
    on_delivery=on_delivery,
)
# flush 会驱动回调;超时后仍排队的消息不能当作发送成功。
remaining = producer.flush(15)
if remaining or result["error"] or not result["delivered"]:
    raise SystemExit(
        f"未确认成功:remaining={remaining}, error={result['error']};"
        "消息可能已写入,请先核对,勿把超时等同于未发送。"
    )

运行:

python producer.py

预期收到带 Topic、Partition、Offset 的“发送确认”。为了方便对照,本例显式写入分区 0;真实业务通常由分区策略结合 key 决定去向,不要照搬这种固定分区方式。新建空 Topic 的首条普通消息通常从 Offset 0 开始,重复实验时数字会继续增长。

produce() 把数据放入客户端队列后就返回,不能在下一行直接打印“消息发送成功”。回调由 poll() 或 flush() 驱动;示例等待 flush,并同时检查未完成数量与回调错误。flush 等待的是客户端投递完成,不是要求 Broker 执行磁盘 fsync。Python 客户端发送说明

第五步:消费并提交进度

另开终端,进入同一个 kafka-demo 目录并激活 .venv,把下面内容保存为 consumer.py:

import json
import os
import sys

from confluent_kafka import Consumer, KafkaError, KafkaException


consumer = Consumer({
    "bootstrap.servers": "127.0.0.1:19092",
    "client.id": f"mq-demo-consumer-{os.getpid()}",
    "group.id": os.getenv("GROUP_ID", "mq-demo-workers"),
    "group.protocol": "classic",
    "enable.auto.commit": False,
    "enable.auto.offset.store": False,
    "auto.offset.reset": "earliest",
})
exit_code = 0
try:
    consumer.subscribe([os.getenv("TOPIC", "mq-demo-events")])
    while True:
        message = consumer.poll(1.0)
        if message is None:
            continue
        if message.error():
            if message.error().code() == KafkaError._PARTITION_EOF:
                continue
            raise KafkaException(message.error())
        event = json.loads(message.value().decode("utf-8"))
        # 示例用打印代表处理;真实业务应等数据库事务等动作成功。
        print(
            f"处理成功 pid={os.getpid()} partition={message.partition()} "
            f"offset={message.offset()} event={event}",
            flush=True,
        )
        # 第 3 篇的故障实验使用;失败后退出,不能继续提交更大位点。
        if os.getenv("FAIL_BEFORE_COMMIT") == "1":
            raise RuntimeError("模拟业务完成、位点提交前退出")
        committed = consumer.commit(message=message, asynchronous=False)
        for partition in committed or []:
            if partition.error is not None:
                raise KafkaException(partition.error)
except KeyboardInterrupt:
    print("停止消费", flush=True)
except Exception as error:
    exit_code = 1
    print(f"消费停止,当前消息未确认完成:{error}", file=sys.stderr, flush=True)
finally:
    # 已关闭自动提交,close() 不会把失败消息的位点自动提交。
    consumer.close()
sys.exit(exit_code)
source .venv/bin/activate
python consumer.py

预期看到刚才的事件;Ctrl+C 停止。再以相同 group.id 启动,若提交成功且没有新记录,程序会等待,而不会从头打印所有历史。earliest 仅在没有有效已提交位点、或位点越界等需要重置的情况下决定起点,不是每次启动都回到开头。

示例使用“业务处理后同步提交”,并检查逐分区提交错误。失败后停止,避免继续处理同一分区的后续消息、再把进度推进到失败记录之后。关闭自动提交后,close() 不会替失败消息提交进度。Consumer API

这条链路最少要记住的失败边界

  • 生产端超时可能只是确认没回来,消息也可能已经写入。贸然把同一业务再次发送,会产生重复事件。
  • enable.idempotence 处理客户端协议范围内的重复发送问题,不会替业务判断“两次下单请求其实是同一笔订单”。真实业务需要稳定的 event_id 和消费幂等处理;本例每次运行生成新 event_id,因此重新运行表示发送一个新事件。
  • 打印或数据库更新成功后、进度提交前退出,重启可能再次处理同一事件。示例不承诺业务只执行一次。

没收到消息时按这条顺序检查

先看生产端有没有发送确认,再 describe Topic,确认客户端连接的是主机 19092。随后检查消费者 group.id:同组的另一个实例可能已经处理并提交;需要独立观察时,可临时使用 GROUP_ID=mq-demo-observer python consumer.py,但只能读到仍被保留的消息。不要因为本地看不到输出,就直接删除 Topic 或重置现有消费组位点。

完成后用 docker compose stop 暂停学习环境。docker compose down 会删除容器,本例无数据卷,之后重新创建会丢失学习数据。

官方参考与核对范围

核对日期:2026-10-31。版本、配置与 API 已按官方资料检查;固定 SDK 已在 Python 3.10 隔离环境完成安装与导入。镜像启动、一发一收和故障实验仍需真实 Broker 验证。

记录过程,也留下判断。

← 继续阅读其他文章