KAFKA on Pigsty v5.0

模块：KAFKA

Mon, 01 Jan 0001 00:00:00 +0000

Kafka 是一个分布式事件流平台。Pigsty 的 KAFKA 模块使用 RPM/DEB 软件包，在纳管节点上部署 Apache Kafka 4.1+ 动态 KRaft 集群，并统一管理安全、资源、生命周期与可观测性。

当前状态：Beta 模块

当前 Kafka 模块处于 Beta 状态。用于严肃生产环境前请务必充分测试，确保满足业务需求。包括动态 KRaft、严格滚动、TLS/SCRAM/ACL、声明式 Topic/User、凭据与证书轮换，以及完整监控链路。

快速上手

Mon, 01 Jan 0001 00:00:00 +0000

本教程从一个最小单节点集群开始，完成 Topic 创建与消息读写；随后部署一套独立的三节点安全集群，配置应用用户、ACL、Quota 和生产 Topic；最后演示核心参数修改、客户端接入、监控验证与上线检查。

集群配置

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块使用 15 项持久公开参数表达集群意图，其余拓扑、监听器、存储子目录、复制安全、授权与 Exporter 放置由角色统一推导。首次部署建议先完成快速上手；完整字段见参数参考。

先规划，后格式化

kafka_seq 会写入 KRaft node.id；新集群的随机 Cluster ID、初始 Controller Identity、安全模式与初始复制策略会写入 Bootstrap Manifest。存储格式化后，不要随意修改身份、安全模式或 Controller 集合。角色会验证现场与 Manifest 并在冲突时失败关闭，不会自动覆盖或重新格式化数据。

参数参考

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 角色刻意只公开 15 项持久参数。拓扑、Listener、安全实现、存储子目录、复制安全与 Exporter 放置等细节由角色统一推导，不能作为额外持久变量覆盖。

参数概览

参数	层级	默认值	说明
`kafka_cluster`	集群	必填	Kafka 集群身份
`kafka_seq`	实例	必填	集群内唯一 KRaft `node.id`
`kafka_role`	实例	`combined`	`combined`、`broker` 或 `controller`
`kafka_cluster_id`	集群	未设置	接管/恢复断言；新集群随机生成
`kafka_data`	实例	`/data/kafka`	角色自有数据根目录
`kafka_heap_opts`	实例	`-Xms1G -Xmx1G`	Kafka JVM Heap
`kafka_port`	实例	`9092`	Broker/client 端口
`kafka_controller_port`	实例	`9093`	KRaft Controller 端口
`kafka_rack`	实例	未设置	Broker 故障域标签
`kafka_parameters`	集群/实例	`{}`	非角色自有 Broker 参数
`kafka_jmx_exporter_port`	实例	`9404`	JMX Exporter HTTP 端口
`kafka_exporter_port`	实例	`9308`	协议 Exporter HTTP 端口
`kafka_security`	集群	`plaintext`	`plaintext` 或生产 `scram` 档位
`kafka_users`	集群	`[]`	用户凭据、ACL 与 Quota
`kafka_topics`	集群	`[]`	声明式 Topic

kafka_cluster 与 kafka_seq 必须定义；kafka_role 有真实默认值。集群角色要么全部省略，要么全部显式声明。

日常管理

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块把 Kafka 安装在 /opt/kafka，使用 Systemd 管理服务，并把持久意图保存在 pigsty.yml。节点上的生成文件不应手工修改。

以下 Kafka CLI 示例都使用角色生成的 /etc/kafka/admin.properties。即使当前是 plaintext 也建议始终保留 --command-config：切换到 scram 管理通道时命令结构不变。将 <broker>:9092 替换为可达的 inventory_hostname 与端口。

预置剧本

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块提供两个剧本：kafka.yml 用于部署 Apache Kafka 4.1+ 动态 KRaft 集群并收敛其安全、资源与监控状态；kafka-rm.yml 用于下线集群或移除成员。

集群完整性约束

每个被选中的 kafka_cluster 必须包含其全部成员：部分选择会在写入前失败；选择一个集群、多个完整集群或不加 -l 裸跑全部集群都是允许的。先对完全相同的目标执行 --check；真实运行前仍需人工核验备份/重建意图、容量、业务窗口、回退方案与变更批准。

监控告警

Mon, 01 Jan 0001 00:00:00 +0000

Pigsty 为 KAFKA 模块提供指标、日志、Dashboard 与告警一体化的可观测能力。监控同时覆盖 Kafka JVM 内部状态与 Kafka 协议视角，避免只看到进程存活而看不到 Partition、ISR 与 Consumer Lag，也避免只看到集群元数据而看不到 JVM、请求队列与 KRaft Controller 健康。

指标定义

Mon, 01 Jan 0001 00:00:00 +0000

KAFKA 模块使用两类指标源，都注册在同一 job=kafka 采集任务下：JMX 目标（带 role 标签）采集每个 JVM 的内部状态；协议 Exporter 目标（无 role 标签）通过 Kafka 协议采集逻辑集群、Topic、Partition 与 Consumer Group 状态。协议 Exporter 只放在 kafka_seq 最小的至多两个 Broker-capable 节点上，单 Broker 集群只运行一个。

常见问题

Mon, 01 Jan 0001 00:00:00 +0000

当前 KAFKA 模块是什么成熟度？

当前角色已实现生产级 v1 基线：动态 KRaft、完整集群护栏、冷启动/修复、Broker 串行准入与 Controller 动态加入、成员退役（含死节点）、故障节点三步替换、严格滚动、TLS/SCRAM/ACL、Topic/User 声明式收敛、内部凭据/证书轮换以及完整监控链路。