模块：KAFKA

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

模块能力

KAFKA 模块当前提供：

• 原生动态 KRaft：不安装 ZooKeeper，也不渲染静态 controller.quorum.voters
• 三种原生角色 combined / broker / controller，支持复合与控制面/数据面分离拓扑
• 新集群随机生成 Cluster ID 与 Controller Directory ID，由最小 Bootstrap Manifest 冻结身份，冲突时失败关闭
• 按实时健康状态自动选路：冷启动/修复、Broker 串行准入、Controller 动态加入或严格单节点滚动
• 滚动前后检查 Controller 多数派与 Voter 追平、Offline Partition、Under Min ISR 与 ISR 追平
• 成员退役与故障节点替换由剧本编排：kafka-rm.yml 真子集退役（含死节点），三条命令完成补换
• 两种安全档位：plaintext 与生产 scram（TLS、SCRAM-SHA-512、Controller mTLS、ACL 与默认拒绝授权）
• 声明式收敛 Topic、用户凭据、ACL 与 Quota，不隐式删除业务 Topic；内部凭据与证书支持保护性轮换
• 完整可观测性：JMX 与协议双 Exporter、19 条 Recording Rule、15 条告警规则、4 个 Grafana Dashboard、日志入 VictoriaLogs

模块架构

KAFKA 模块依赖 NODE 完成节点纳管、仓库与基础监控，依赖 INFRA 提供 VictoriaMetrics、VictoriaLogs、Grafana 与 Alertmanager。

flowchart LR
    admin["Pigsty 管理节点"] -->|"kafka.yml / exact cluster"| kafka["Kafka 4.1+ / 动态 KRaft"]
    kafka --> jmx["每个 Kafka JVM / JMX :9404"]
    kafka --> exporter["最多两个 Broker / kafka_exporter :9308"]
    kafka --> journal["Journald"]
    jmx --> vm["VictoriaMetrics"]
    exporter --> vm
    journal --> vector["Vector"] --> vl["VictoriaLogs"]
    vm --> grafana["Grafana"]
    vl --> grafana
    vm --> alert["Alertmanager"]

    style kafka fill:#70C1B3,stroke:#4f968b,color:#fff
    style vm fill:#E66B7A,stroke:#b84e5c,color:#fff
    style vl fill:#C98367,stroke:#9e634e,color:#fff
    style grafana fill:#F29C64,stroke:#c77845,color:#fff

每个 Kafka JVM 都注入 JMX Exporter 并注册为 job=kafka。协议型 kafka_exporter 只在按 kafka_seq 排序后的前两个 Broker-capable 节点运行；单 Broker 集群只运行一个，纯 Controller 不运行。它们返回的是同一逻辑集群视图，Recording Rule 会先去重再聚合。

文档导航

第一次使用

快速上手 提供一条从零开始、由浅入深的完整路径：单节点开发集群 → 三节点 TLS/SCRAM/ACL 安全集群 → 应用客户端接入 → 参数与资源变更 → 上线检查。

如果您已经熟悉 Kafka 与 Pigsty，可以直接进入 集群配置 或 参数参考。

默认端口

四个端口必须彼此不同，均可通过参数调整。JMX 与协议 Exporter 的 HTTP 端口仍应通过防火墙限制在监控网络内。

当前边界

当前角色提供的是 Kafka 核心部署基线，不替代完整的流平台或托管服务。下列能力仍需显式运行手册或独立组件：

• Broker 扩容后的既有 Partition Reassignment 与副本再均衡（成员的加入/退役/替换已由剧本编排，数据搬迁仍需显式计划）
• 扩容后提升冻结的 default.replication.factor：Kafka 4.3 需要显式数据迁移与静态配置维护窗口
• 已有 Topic 的副本因子变更、Topic 删除与用户删除
• 已格式化集群从 plaintext 在线迁移到 scram
• Kafka 版本升级、Feature Level 终结、数据备份、恢复与灾难演练
• 多 Listener、NAT/公网地址、同一 Broker 多客户端网络、Tiered Storage
• Kafka Connect、Schema Registry、MirrorMaker 2、Cruise Control 与 Web UI

这些边界应在生产方案、审批流程与演练中明确记录，不能用普通清单重跑代替。