Kafka Consumer 长期稳定运行需避开默认配置陷阱：poll() 卡住或跳过新消息源于 fetch buffer 机制；max_poll_records 与 max_poll_interval_ms 联动不当会触发 rebalance；须手动提交 offset 并绑定业务事务；多 topic 优先用 subscribe()；退出前必须 close() 确保 offset 提交。
直接用 KafkaConsumer 循环拉取消息就能跑起来，但真要长期稳定运行、不丢消息、不重复、不卡死，得绕开几个默认配置的坑。
为什么 consumer.poll() 会“卡住”或“跳过新消息”
这不是 bug，是 poll() 的语义决定的：它只返回当前 fetch buffer 里已缓存的消息，不是实时触发一次 broker 查询。如果 max_poll_records 设太小（默认 500），而单条消息处理慢，buffer 很快被清空，后续调用就返回空；如果设太大，又可能拖长单次处理时间，触发 group rebalance。
-
max_poll_interval_ms（默认 300000ms）必须大于单次poll()+ 全部消息处理的耗时，否则 consumer 会被踢出 group，offset 不再提交 -
session_timeout_ms（默认 10000ms）控制心跳超时，和heartbeat_interval_ms（默认 3000ms）配合——心跳发太慢，也会被误判为失联 - 别依赖
auto_offset_reset='latest'去“监听未来消息”，它只在无 committed offset 时生效；真正想“持续追新”，靠的是持续poll()+ 正确提交 offset
如何避免 offset 提交失败导致重复消费
手动提交（enable_auto_commit=False）比自动提交更可控，但容易漏调 consumer.commit() 或在异常路径下没兜住。更稳妥的做法是：把 commit 和业务逻辑绑定在同一事务边界内，哪怕只是“处理完一条就 commit 一条”。
- 用
try/except/finally包裹消息处理块，在finally里调consumer.commit()，确保无论成功失败都推进 offset（前提是业务可幂等） - 若业务本身不可幂等，改用
consumer.commit(offsets={...})显式提交上一条成功消息的 offset + 1，避免“多提交” - 禁用
auto_commit_interval_ms，防止后台线程在你还没处理完时偷偷提交了旧 offset
消费多个 topic 时订阅方式选 subscribe 还是 assign
绝大多数场景该用 subscribe()，它支持动态分区分配、rebalance 和 offset 自动管理；只有当你需要精确控制每个 partition 的起始位置（比如从某个固定 offset 回溯）、或绕过 group 协调器做“无状态读取”时，才用 assign()。
立即学习“Python免费学习笔记（深入）”；
-
subscribe([t1, t2])：consumer 加入 group，Kafka 自动分配 partitions，offset 从 group coordinator 读取 -
assign([TopicPartition(t1, 0), TopicPartition(t2, 1)])：完全 bypass group，不参与 rebalance，也不提交 offset 到 coordinator，适合离线扫描类任务 - 混用危险：
subscribe()后再assign()会清空之前订阅关系，且不会报错，只默默失效
脚本退出前必须显式 close()，否则可能丢最后一批 offset
consumer.close() 不只是释放 socket，它还会触发一次最终 commit（如果 enable_auto_commit=True）或 flush 当前 pending offset（如果手动 commit）。没这步，程序被 kill 时未提交的 offset 就丢了。
- 用
atexit.register(consumer.close)或with语句（需封装成上下文管理器）确保执行 - 捕获
KeyboardInterrupt和SystemExit，不要只靠 finally——信号中断可能跳过 finally 块 - 注意：close() 是阻塞操作，如果网络卡住，可能 hang 住整个退出流程；加 timeout 更安全：
consumer.close(timeout=5)
最常被忽略的是 max_poll_records 和 max_poll_interval_ms 的联动关系——它们共同决定了“单次 poll 能吃多少、多久必须吃完”，这个窗口一旦压不住，consumer 就会在后台静默掉线，而日志里往往只显示 “Rebalancing” 或 “Not a leader for partition”，根本看不出是自己没处理完。
