Topic 主题是什么
Topic 是消息的逻辑分类，也是 Kafka 里所有配置的落点：分区数、副本因子、保留时长、清理策略、单条消息大小上限都以主题为单位定义。生产者写主题、消费者订主题，分区只是主题内部为并行而做的拆分。
配置分两级
主题级配置覆盖 Broker 级默认值。查配置时先看主题级覆盖（可能只有一两项），其余取集群默认。大多数配置可以在线修改并对新写入的消息立即生效，不需要重启 Broker，因此调整保留时长、大小上限属于常规运维动作。
基本信息
| 组成 | 名称 + 分区数 + 副本因子 + 主题级配置覆盖 |
|---|---|
| 命名约定 | 业务域.环境.实体，全小写，避免特殊字符与中文 |
| 常用配置 | retention.ms、cleanup.policy、max.message.bytes、min.insync.replicas |
| 生效方式 | 多数主题配置可在线修改，无需重启 |
| 管理工具 | kafka-topics.sh（结构）与 kafka-configs.sh（配置） |
典型使用场景
- 新建主题时定分区与副本，并显式覆盖保留策略而不是吃集群默认值
- 日志类主题延长保留以支持下游重放补数
- 账务类主题缩短保留以满足合规要求，同时保留足够重放窗口
- 大消息场景上调 max.message.bytes，避免生产端被拒绝
- 配置审计：用 --topics-with-overrides 找出被手工改过配置的主题
主题级配置查询与修改
主题级配置查询与修改
# 查看主题的覆盖配置（只列出被显式修改过的项）
kafka-configs.sh --bootstrap-server localhost:9092 \
--entity-type topics --entity-name orders --describe
# 延长保留到 3 天
kafka-configs.sh --bootstrap-server localhost:9092 \
--entity-type topics --entity-name orders \
--alter --add-config retention.ms=259200000
# 删除覆盖配置，恢复为集群默认值（不是关闭该功能）
kafka-configs.sh --bootstrap-server localhost:9092 \
--entity-type topics --entity-name orders \
--alter --delete-config retention.ms常用主题配置读法
| 配置 | 作用 | 取值建议 |
|---|---|---|
| retention.ms | 消息保留时长 | 按下游重放需求定，默认 7 天 |
| retention.bytes | 单分区保留容量上限 | 磁盘紧张时与时间保留取较小者生效 |
| cleanup.policy | 清理策略：delete 或 compact | 事件流用 delete，状态类主题用 compact |
| max.message.bytes | 单条消息大小上限 | 默认约 1MB，大消息需上调并核验生产端 |
| min.insync.replicas | 写成功所需最少同步副本 | 与 acks=all 配套，副本为 3 时设 2 |
命名建议用「业务域.环境.实体」的小写形式：全小写加点和连字符能兼容绝大多数监控与权限工具，中文或空格会在 ACL、脚本与可视化环节反复出问题。
内部主题（__consumer_offsets、__transaction_state）承载消费位点与事务状态，不要手工改它们的配置或清理数据，交由集群参数管理。