# 模块：KAFKA

> 使用 Pigsty 部署、保护与监控 Apache Kafka 4.1+ 动态 KRaft 集群。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

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

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


--------

## 模块能力

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`](/docs/node) 完成节点纳管、仓库与基础监控，依赖 [`INFRA`](/docs/infra) 提供 VictoriaMetrics、VictoriaLogs、Grafana 与 Alertmanager。

```mermaid
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 会先去重再聚合。


--------

## 文档导航

| 文档                           | 内容                                    |
|:-----------------------------|:--------------------------------------|
| [快速上手](/docs/kafka/start)    | 从单节点到三节点安全集群、客户端接入、参数修改与上线检查          |
| [集群配置](/docs/kafka/config)   | 拓扑、动态 KRaft、网络、存储、安全与资源声明             |
| [参数参考](/docs/kafka/param)    | 15 项持久公开参数及临时运维变量                     |
| [日常管理](/docs/kafka/admin)    | 状态检查、Topic、消息、Consumer Group 与拓扑变更    |
| [预置剧本](/docs/kafka/playbook) | `kafka.yml` 生命周期、任务标签、轮换与清理保护         |
| [监控告警](/docs/kafka/monitor)  | 指标链路、Dashboard、日志查询与告警规则              |
| [指标定义](/docs/kafka/metric)   | JMX、协议 Exporter 与 Recording Rule 指标字典 |
| [常见问题](/docs/kafka/faq)      | 角色、身份、安全、Exporter 与扩缩容答疑              |
{.full-width}


--------

## 第一次使用

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

如果您已经熟悉 Kafka 与 Pigsty，可以直接进入 [集群配置](/docs/kafka/config) 或 [参数参考](/docs/kafka/param)。


--------

## 默认端口

|   端口   | 服务               | 部署范围                   | `plaintext` | `scram`                  |
|:------:|:-----------------|:-----------------------|:------------|:-------------------------|
| `9092` | Kafka Broker     | Broker-capable 节点      | PLAINTEXT   | SASL_SSL + SCRAM-SHA-512 |
| `9093` | KRaft Controller | Controller-capable 节点  | PLAINTEXT   | 双向 TLS                   |
| `9308` | kafka_exporter   | 最多两个 Broker-capable 节点 | HTTP 指标     | HTTP 指标，后端使用 TLS/SCRAM   |
| `9404` | JMX Exporter     | 所有 Kafka 节点            | HTTP 指标     | HTTP 指标                  |
{.full-width}

四个端口必须彼此不同，均可通过参数调整。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

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

---

本节页面：

- [快速上手](/zh/docs/kafka/start/): 从零部署单节点与三节点 Kafka，完成安全接入、参数调整和上线检查。
- [集群配置](/zh/docs/kafka/config/): 规划 Kafka 动态 KRaft 拓扑、身份、网络、存储、安全与声明式资源。
- [参数参考](/zh/docs/kafka/param/): KAFKA 模块 15 项持久公开参数与临时受保护运维变量。
- [日常管理](/zh/docs/kafka/admin/): Kafka 集群的状态检查、Topic 与用户管理、配置变更、扩容缩容、故障节点替换与安全轮换。
- [预置剧本](/zh/docs/kafka/playbook/): 使用 kafka.yml 与 kafka-rm.yml 执行动态 KRaft 生命周期、严格滚动、资源收敛、轮换与下线。
- [监控告警](/zh/docs/kafka/monitor/): Kafka 指标采集、Grafana Dashboard、日志查询与告警规则。
- [指标定义](/zh/docs/kafka/metric/): Kafka JMX、协议 Exporter 与 Recording Rule 指标字典。
- [常见问题](/zh/docs/kafka/faq/): Pigsty Kafka 4.1+ 动态 KRaft 模块常见问题与故障排查。