在运行中的 Kafka 集群渐进式启用安全零停机实战手册（KRaft/Broker 通用）

1. 为什么要"分阶段、滚动式"启用安全？

对生产集群"一步到位"切换安全协议，极易造成客户端与 broker 协议不匹配而中断。官方建议采用 incremental bounce（滚动重启）分阶段推进：

1. 第一轮滚动 ：在每台 broker 上新增安全端口 （例如 SSL 或 SASL_SSL），保留 PLAINTEXT。
2. 客户端切换：将客户端改为使用新开的安全端口与协议（SSL 或 SASL_SSL）。
3. 第二轮滚动 ：为 broker--broker（内网复制、控制路径）启用安全协议 （例如 security.inter.broker.protocol=SSL）。
4. 最终滚动 ：关闭 PLAINTEXT 端口，完成加固。

关键点：始终保留一个 PLAINTEXT 端口直到所有客户端、以及 broker--broker 都已经完成迁移与验证，否则会出现连接断裂。

2. 安全方案与端口规划

根据你的目标不同，有两种常见形态：

方案 A：全 SSL 加密（broker--client 与 broker--broker 都使用 SSL）

• 目标：仅加密，无额外认证（或认证由证书完成）。

• 监听规划（示例）：

  • PLAINTEXT://broker1:9091（迁移期间保留）
  • SSL://broker1:9092（新开）

方案 B：客户端 SASL+SSL ，broker--broker 仅 SSL

• 目标：对外（client--broker）既加密（SSL），又认证（SASL），而 broker--broker 内部仅加密。

• 监听规划（示例）：

  • PLAINTEXT://broker1:9091（迁移期间保留）
  • SSL://broker1:9092（broker--broker）
  • SASL_SSL://broker1:9093（client--broker）

注：SSL/SASL 配置细节见前文 7.3（SSL）与 7.4（SASL）。本文聚焦"运行中切换"的调度与步骤。

3. 滚动重启（incremental bounce）运行手册

通用前置：变更窗口与健康门槛

• 优雅停止 ：使用 SIGTERM 停止 broker。
• ISR 等待 ：每个节点拉起后，等待分区副本回到 ISR 再处理下一台。
• 业务窗口：选择低峰期；观察客户端重连成功率、吞吐与延迟。

A. 目标：全 SSL 加密

第 1 轮：为每台 broker 打开 SSL 端口（保留 PLAINTEXT）

server.properties（每台）：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092
# 证书等 SSL 细节按 7.3 配置

执行：逐台 broker 滚动：SIGTERM → 启动 → 等待 ISR 恢复。

客户端切换为 SSL

客户端（Producer/Consumer）应用配置（示例）：

bootstrap.servers=[broker1:9092,...]
security.protocol=SSL
# 其他 SSL 客户端参数同 7.3

推进策略：优先切换非关键业务与批处理客户端，逐步扩大范围，观察错误率。

第 2 轮：启用 broker--broker 使用 SSL

server.properties（每台）：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092
security.inter.broker.protocol=SSL

执行：逐台滚动，确认控制面与复制链路健康。

最终轮：关闭 PLAINTEXT 端口

listeners=SSL://broker1:9092
security.inter.broker.protocol=SSL

执行：逐台滚动；关闭后验证所有客户端仍可连通。

B. 目标：客户端 SASL+SSL，broker--broker 仅 SSL

第 1 轮：为每台 broker 打开 SSL 与 SASL_SSL 端口（保留 PLAINTEXT）

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093
# 配置 SSL（7.3）与 SASL（7.4）细节

客户端切换为 SASL+SSL

bootstrap.servers=[broker1:9093,...]
security.protocol=SASL_SSL
# sasl.mechanism=PLAIN / SCRAM / GSSAPI 等
# 其余凭据按 7.4

第 2 轮：启用 broker--broker 使用 SSL（复用 9092）

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL

最终轮：关闭 PLAINTEXT 端口

listeners=SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL

4. 变更步骤（可直接用作 Runbook）

对每一台 broker（按机架/副本分布顺序）执行：

1. 预检查

   • 控制器健康、ISR 稳定、请求队列正常；客户端错误率基线已记录。
   • 证书链、SASL 凭据、JAAS 文件、server.properties 已下发并校验。

2. 变更配置

   • 添加目标 listeners；未到最终轮前保留 PLAINTEXT。
   • 仅在对应阶段设置 security.inter.broker.protocol=SSL。

3. 优雅重启

   • kill -TERM <pid> 或 systemd/service 脚本。
   • 拉起后检查：kafka-broker-api-versions.sh、日志无 SSL/SASL 握手错误。

4. 健康验证

   • 分区副本回 ISR（Controller 日志、/metrics、运维面板）。
   • 业务读写无报错；客户端连接逐步切换、灰度放量。

5. 推进下一台

   • 周期性观测 3--10 分钟（按负载而定）再继续。

客户端统一切换阶段：与业务团队沟通窗口；优先无状态与幂等写入者；重点关注老旧 SDK。

5. 验证清单：连通性、握手与权限

• 端口监听 ：目标端口 LISTEN；openssl s_client -connect broker1:9092 -tls1_2 验证证书链。
• 客户端连接数：新端口建立，旧端口下降（直到最终关闭）。
• 生产/消费 ：写入 TPS、消费延迟、重试/超时指标；无 SSLHandshakeException、SaslAuthenticationException。
• 集群内部 ：控制器选举稳定；复制无滞后；inter.broker.listener.name（如使用）与 security.inter.broker.protocol 一致。

6. 常见坑位与规避

• 过早关闭 PLAINTEXT ：客户端尚未全部迁移即关闭 → 瞬时不可用。务必最后一轮才关。
• 证书主机名不匹配 ：CN/SAN 与 bootstrap.servers 不符；建议使用 SAN 通配或统一域名。
• SASL 机制不一致 ：broker 与客户端 sasl.mechanism/JAAS 配置不一致导致认证失败。
• 忘记滚动所有节点：导致同一集群存在不同安全形态，引发复制/控制面异常。
• 缺少 ISR 等待：重启过快，副本未恢复即继续，风险叠加。

7. 回滚策略（必须预置）

• 配置回退 ：恢复到上一个成功状态的 listeners 与 security.inter.broker.protocol。
• 端口回开 ：若已关闭 PLAINTEXT 而出现大量客户端失败，第一时间恢复 PLAINTEXT 并广播客户端迁移回退通知。
• 逐台回滚：同样采用滚动方式，保证 ISR 与客户端稳定。

8. 参考示例（与官方流程完全对齐）

A. 全 SSL（官方示例复刻）

第 1 轮：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092

客户端切换：

bootstrap.servers=[broker1:9092,...]
security.protocol=SSL

第 2 轮：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092
security.inter.broker.protocol=SSL

最终轮：

listeners=SSL://broker1:9092
security.inter.broker.protocol=SSL

B. SASL+SSL（客户端）+ SSL（内网）

第 1 轮：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093

客户端切换：

bootstrap.servers=[broker1:9093,...]
security.protocol=SASL_SSL
# sasl.mechanism 与凭据按 7.4 配置

第 2 轮：

listeners=PLAINTEXT://broker1:9091,SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL

最终轮：

listeners=SSL://broker1:9092,SASL_SSL://broker1:9093
security.inter.broker.protocol=SSL

9. 总结

在运行中的 Kafka 集群启用安全的关键是：分阶段、可回滚、可观测 。通过增量滚动重启，先打开安全端口 、再迁移客户端 、随后切换内网 broker--broker ，最后关闭 PLAINTEXT，即可在不打断业务的前提下完成整体加固。配合证书与 SASL 的正确配置、严格的 ISR 等待与健康校验，整个过程将变得可预测、可控且安全。