简介：面向Kafka集群的日常运维与管理，资源内含Yahoo开源工具CMAK（Kafka-Manager）2.0.0.2的预编译Zip包，适合需要直观监控多套Kafka集群、管理主题与消费者组的开发和运维人员，也免去了手动编译与JDK版本适配的烦恼。包内共780个文件，以101个JAR运行依赖、604个HTML管理界面和JS/CSS静态资源为主，另有bat启动脚本与config配置样例，其中JAR提供核心运行库，HTML和前端文件构成控制台界面，压缩后约92.38MB，解压即可使用。借助CMAK可查看各节点状态、分区分配与副本分布，创建或删除主题时灵活设置分区数和副本数，实时掌握消费者组消费进度并在线调整配置；同时支持基于角色的访问控制，2.0.0.2版本对不同JDK环境更友好，预编译产物省去构建过程，部署门槛低，适合快速搭建集群监控台。目前已有390人学习下载，适合希望低成本引入Kafka可视化管理的中级运维工程师参考使用。
1. 这个 zip 包是什么，为什么运维要专门找它
如果你手头拿到的是kafka-manager（CMAK）-2.0.0.2.zip，大概率是刚接手一套 Kafka 集群，想找个成熟的管理界面，而不是每次都用命令行去查 topic 列表和消费组偏移量。CMAK 是 Cluster Manager for Apache Kafka 的缩写，它管理 Kafka 的多个集群、展示 topic 分区分布、监控 consumer 延迟，还支持分区重分配和优先副本选举这些平时最不想手搓的操作。2.0.0.2 是使用比较广的发布版本之一，zip 包本身就是解压就能跑的产物。适合已经具备 ZK 和 Kafka 基础、想在十分钟内看到集群拓扑图的运维，也适合需要频繁做分区均衡的人作为可视化操作平台。
2. 部署 kafka-manager（CMAK）2.0.0.2：从解压到给出最小配置
这个 zip 不是源码包，不需要 sbt 编译，解压后配一个文件就能起服务。但很多人栽在第一步：把它当普通 Java 工程直接java -jar，然后发现缺少主类或者报一堆 ClassNotFound。CMAK 的部署路径是跑bin/cmak启动脚本，脚本会自己组装 classpath。
2.1 先看运行时：JDK 版本、内存和端口规划
CMAK 2.0.0.2 对应 Scala 2.12，要求 JDK 1.8 及以上。我一般建议装在独立节点，至少给它 2 个 CPU 和 1G 堆内存；如果你只有一台机器在跑 Kafka，可以把 CMAK 和 Kafka Broker 混部，但 JVM 参数要错开，避免两个进程同时触发 Full GC 造成相互影响。
端口默认是 9000，这个不固定，可以在application.conf里改。建议在部署前先确认 9000 端口没被占用，防火墙放行你浏览器要访问的那台机器 IP。还有一个容易忽略的点：CMAK 服务端要能连到你的 ZooKeeper 和 Kafka Broker 的端口，不是只开 UI 端口就够。最小环境需要两样东西：一个正在运行的 ZooKeeper 集合，一个待管理的 Kafka 集群，版本最好在 0.11 以上。
2.2 解压 zip 与目录结构识别：bin、conf、lib 各管什么
拿到 zip 后先不要急着双击解压，文件名里的全角括号在 Linux shell 里处理起来很别扭，我一般会先统一改成 ASCII 命名。
mv 'kafka-manager（CMAK）-2.0.0.2.zip' kafka-manager-cmak-2.0.0.2.zip unzip kafka-manager-cmak-2.0.0.2.zip cd kafka-manager-2.0.0.2/ ls -la解压后的目录顶层应该有bin/、conf/、lib/、logs/这几个目录。bin/cmak是启动脚本，conf/application.conf是配置文件，lib/下是一堆依赖 jar 包。这里给个提醒：不要跳过lib目录直接看界面，后面添加集群时版本选不了，问题大概率出在这个目录里。
2.3 写出最小 application.conf：ZK 地址是唯二必改项
CMAK 的所有集群元数据都存在 ZooKeeper 里，它自己不像 Kafka 那样需要存储层，所以配置文件里最重要的就是告诉它 ZooKeeper 在哪。打开conf/application.conf，定位到kafka-manager.zkhosts这一行，改成本环境的 ZK 地址。
# CMAK 自身元数据存储的 ZooKeeper 地址，多个用逗号分隔 kafka-manager.zkhosts="zk01:2181,zk02:2181,zk03:2181" # UI 端口，默认 9000 kafka-manager.port="9000" # 监听地址，如果只想让内网访问，改成内网 IP 更安全 kafka-manager.application.hostname="0.0.0.0"如果 Kafka 本身就是这套 ZK 管理，直接写同一组地址即可。如果 ZK 用了 chroot 路径，必须在每个地址后面带路径，格式是host:2181/kafka，这个稍后在第 5 章会单独展开。
提示：不要把
kafka-manager.zkhosts配置里的地址间隔写成空格，逗号分隔才是合法的 ZK 连接串格式。
配置文件里还有kafka-manager.security.basic.enabled这类参数，控制是否启用登录页，默认是开启的，先用默认值跑通再说，密码的事放到下一章。
3. 启动 CMAK 并完成首次登录：日志、密码与 JVM 参数
启动过程比想象中简单，但几个细节能决定你能不能顺利打开页面。很多人第一次启动后浏览器一直转圈，或者页面打开但请求超时，其实不是代码问题，而是启动方式选错了。
3.1 前台启动，从日志确认三类关键信息
我不建议直接nohup后台启动，第一次一定用前台方式跑，方便看日志输出。CMAK 的启动脚本是bin/cmak，老版本叫bin/kafka-manager，你手里是 2.0.0.2，一般已经改名成cmak了。
cd kafka-manager-2.0.0.2/ bin/cmak -Dconfig.file=conf/application.conf看到Starting CMAK和Listening for HTTP on /0.0.0.0:9000之类的输出说明启动成功。启动日志里重点看三个信息：第一，ZK 连接是否建立成功；第二，HTTP 服务监听在哪个端口；第三，有没有Exception或ERROR字样。如果端口被占，把kafka-manager.port换掉再试。
日志输出里如果出现Unable to connect to ZooKeeper，先不要怀疑 CMAK，直接用zkCli.sh连一下 ZK 地址验证连通性。CMAK 对 ZooKeeper 的连接超时默认比较短，ZK 负载高时启动阶段可能报一次错然后重连，不一定是死状态。
3.2 修改默认 admin 账号的登录口令
服务起来后，浏览器访问http://你的IP:9000，会看到一个登录页。默认账号是admin，密码是admin，这是 CMAK 写死在代码里的初始口令，生产环境必须改。修改方式不是在配置里写明文密码，而是登录后进入右上角的用户菜单，在页面里改密码。
这里有个操作陷阱：CMAK 的用户信息存在它连接的 ZooKeeper 里，路径大致在/kafka-manager/users下。如果你之后把kafka-manager.zkhosts指向了另一套 ZK，用户数据是迁移不过去的，需要重新建账号。改完密码后建议立刻登出再登录一次，确认新密码生效。
如果你的环境不允许任何人直接访问 UI，可以在application.conf里关掉登录：
kafka-manager.security.basic.enabled=false关掉后所有人都能访问，只适合内网测试环境，别在生产这么干。
3.3 内存上限与启动翻车的关系
CMAK 默认启动脚本给的内存并不大，在小规模环境下没问题，但如果你管理的集群有几百个 topic、上千个分区，UI 在加载列表时可能卡很久，极端情况直接 OOM。要调就改bin/cmak脚本里的 JVM 参数，找到类似-Xmx的位置：
# 在 bin/cmak 脚本中找到 JVM 参数所在行，改成如下 declare -r java_opts="-Xms256m -Xmx1024m -XX:MaxMetaspaceSize=256m"分配多少取决于你的 topic 数量和 broker 规模。我见过测试环境给 256M 跑得挺好，也见过生产环境 8G 堆仍然在重分配时卡顿。重分配阶段需要把所有分区分配方案加载到内存里计算，建议管理超过 200 个 topic 的集群时，至少给 2G。改完重启进程，用jstat -gc <pid>观察FGC次数，如果十几分钟就有一次 Full GC，说明内存还是小了。
4. 在 CMAK 中添加 Kafka 集群：表单与监控口径
部署 CMAK 本身不复杂，真正决定它好不好用的是你在 UI 里添加集群时填的参数。很多人部署成功后，添加集群这一步反复失败，或者在页面上看到一堆红色告警，本质上是把表单里的字段含义理解错了。
4.1 添加集群表单逐项拆解：版本选择要和 lib 里的包对应
登录后点击Cluster -> Add Cluster，会进入一个表单。必填项有 Cluster Name、Cluster Zookeeper Hosts、Kafka Version，其他像是 JMX 轮询、Logkafka、Security Settings 都是可选项。
Cluster Name 是给你看的别名，随便填，但不要填中文和空格，后续很多 API 调用会把这个名字拼进 URL，出现中文容易出问题。Cluster Zookeeper Hosts 填写集群使用的 ZK 地址，注意这里填的是Kafka 的 ZK 地址，不是 CMAK 自身存储用的 ZK。如果你的 Kafka 和 CMAK 用同一套 ZK，那两者相同。
Kafka Version 下拉列表里通常有 0.11、1.0、1.1、2.0、2.1 这些选项。这里就是第 2 章埋下伏笔的地方：下拉列表里能不能选你想要的版本，取决于lib目录下有没有对应版本的 Kafka 客户端 jar 包。CMAK 2.0.0.2 自带 jar 未必覆盖所有版本，如果你选了列表里存在但实际没有 class 的版本，启动时或保存集群时会报 Kafka 版本相关的异常。等遇到时按第 5 章的方案处理，先确保选一个已知可用的版本。
表单下方的Enable JMX Polling默认是勾选的，但它依赖每个 Broker 开放 JMX 端口，生产环境往往没开，此时先取消勾选，把集群拉起来再说。Enable Logkafka不用管，那是个已经边缘化的日志采集模块。填完保存，等状态变成 Running 而不是 Disconnected。
4.2 开启 JMX 轮询，补上 Broker Metrics 数据
添加完集群后，点进 Cluster 的详情页，你会看到 Topic 列表、Consumer 列表都能正常展示，但 Broker 的Metrics页是空的。这是因为 Kafka Broker 没有开启远程 JMX 端口，CMAK 的轮询请求发不进去。补上 JMX 需要在每一台 Kafka Broker 上配置并重启。
# 在 kafka-server-start.sh 启动前加入以下环境变量 export JMX_PORT=9999 export KAFKA_JMX_OPTS="-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false" bin/kafka-server-start.sh config/server.propertiesJMX_PORT是暴露指标的端口，CMAK 表单里的JMX Port填写这个值；authenticate=false和ssl=false表示不做认证和加密，仅限内网；如果集群启用了安全协议，需要额外配置认证文件，否则连接会拒绝。
配置完成后回到 CMAK 的集群页面，在Broker Metrics标签页点 Run，大概十几秒后会开始统计 broker 的 CPU、网络 IO 和日志落盘速率。JMX 数据在 CMAK 里是拉取模型，不是推送，所以界面不会自动实时刷新，想看最新数据需要手动点刷新按钮。
4.3 Consumer 监控：别只看 Lag，还要看分区分配
Consumer 页面会展示当前消费组和每个分区的 Lag，这是日常监控最常用的入口。但这有个坑：CMAK 对 Java Consumer（新版 KafkaConsumer）和旧版 SimpleConsumer 的兼容程度不同。新版消费者组数据存储在__consumer_offsets这个内部 topic 里，CMAK 依赖 Coordinator 的状态来拉取消费进度，有时候 ZK 和 Coordinator 信息不同步，页面会显示 Consumer 不存在。
这种情况通常不是 CMAK 的 bug，而是消费组本身没有活跃成员。老版消费者通过 ZK 提交 offset，数据实时性反而更高。如果你用的是新版消费者且开启了 group 认证，需要先在 CMAK 的集群配置里把 SASL/JAAS 信息维护好，否则连__consumer_offsets都读不到。遇到这种场景，我一般先用命令行工具确认消费组真实状态，再决定是排查认证还是排查 broker 版本兼容。
5. 部署与使用 CMAK 的五个现实坑
以下问题我基本都在不同环境里遇到过，按现象排查即可。
5.1 版本坑：添加集群时选了 2.0.0，保存后集群连不上
现象：Kafka 实际是 2.0.0，但 CMAK 里选了 2.0.0 后，集群状态频繁 Disconnected，日志出现ClassNotFoundException或Unsupported version。
原因：CMAK 2.0.0.2 的lib目录下默认只带了一套 Kafka 客户端版本，它没法保证兼容所有 Kafka 版本。下拉列表里能显示 2.0.0 不代表 jar 已经就位。
解决：从 Kafka 客户端包中找到对应版本的kafka-clients和核心 jar，手工放入 CMAK 的lib目录：
cd kafka-manager-2.0.0.2/lib ls | grep -i kafka-assembly # 如果只看到 0.11 或 1.1 的包，说明你的版本确实没带全 # 停掉 CMAK，把 kafka_2.12-2.0.0.jar、kafka-clients-2.0.0.jar 复制进来 cp /path/to/kafka_2.12-2.0.0*.jar . bin/cmak -Dconfig.file=conf/application.conf重启后重新进入添加集群页面，选择对应版本再试。判断版本是否匹配最直接的办法是看启动 log 和连接日志，不要靠感觉。
5.2 ZK 地址带 chroot 时的格式陷阱
现象：Kafka 明明在 ZK 上正常，ZK 路径也不是根路径，填zk01:2181加集群后一直 Pending，ZooKeeper 手动连/brokers/ids能看见 broker。
原因：Kafka 的 Broker 注册在 chroot 节点下，比如/kafka/brokers/ids，而 CMAK 如果直接连根路径，它去找/brokers/ids自然找不到。
解决：添加集群时 Cluster Zookeeper Hosts 一栏写完整路径：
zk01:2181/kafka,zk02:2181/kafka,zk03:2181/kafka注意 chroot 路径在地址里只写一次，不要写成zk01:2181/kafka,zk02:2181/kafka这种每台重复路径之外再加一层，那样反而会拼出错路径。同样，CMAK 自身存储的 ZK 地址也可以带独立 chroot，比如配置kafka-manager.zkhosts="zkx:2181/cmak"，但集群添加页面里填的是业务 Kafka 的 chroot。
5.3 启用了 SASL 认证的 Kafka 连不上集群
现象：Kafka 配置了 SASL_PLAINTEXT，CMAK 里能选集群但一直 Connection Refused，日志里报Exception: Client was not authenticated。
原因：CMAK 连接 Kafka 时没有携带 JAAS 认证信息。它自己有一套安全配置入口，很多人没找到。
解决：添加集群时打开Security Settings，填写Security Protocol为SASL_PLAINTEXT，SASL Mechanism为对应的 PLAIN 或 SCRAM-SHA-256，并维护JAAS配置。更省事的办法是把集群改成不使用 SCRAM，而是让 CMAK 所在的机器加入 Kafka 的 JAAS 配置，但那样会扩大认证范围，不建议。通过 CMake 界面配置 JAAS 后，重启集群连接并观察日志，确认没有Authentication failed再信任页面状态。
我踩过最深的坑是忘了为 CMAK 添加kafka-client-jaas.conf的 JVM 参数。这个文件要放到 CMAK 启动脚本：
JAVA_OPTS="-Djava.security.auth.login.config=/opt/kafka/config/kafka_client_jaas.conf"5.4 JMX 页面空空如也，刷新也出不来
现象：集群状态正常，Topic 列表正常，但 Broker Metrics 永远没有数据，Cluster 状态里 JMX 一直显示 No data。
原因：没有开 JMX 端口或端口不通。CMAK 的 JMX Polling 是在添加集群时决定的，如果你当时取消了勾选，后续补开 JMX 还需要去集群配置里重新勾选。另一个可能是 Broker 的 JMX 绑定到了 localhost，外网访问不到。
解决：确认每个 Broker 都配了JMX_PORT且监听地址不是 127.0.0.1。用命令行验证：
telnet <broker-ip> 9999能通再看 CMAK 集群配置，把Enable JMX Polling打开并填上正确的 JMX 端口。一个 broker 对应一个端口，如果有 3 个 broker，只填一个地址是拉不出完整指标的。
5.5 启用了 ZK ACL 导致集群一直 Disconnected
现象：ZooKeeper 开启了 ACL 权限，CMAK 连上去报KeeperException$NoAuthException，但命令行用同一个 ZK 地址直接连没问题。
原因：命令行工具认证后会话有效，CMAK 进程启动时的 ZK Client 没有携带认证信息。CMAK 和 Kafka 共用同一套 ZK ACL 时经常这样。
解决：在application.conf里为 CMAK 启动脚本添加-Dzookeeper.sasl.client=false或在脚本里加载 JAAS。还有一种做法是给 CMAK 单独建一个 ZK chroot 路径并赋给该用户权限，CMAK 自身的存储和集群管理分开认证。这个方案最干净，但需要同时调整 Kafka 的zookeeper.set.acl配置，改动面较大，建议在维护窗口操作。
6. 进阶：用 CMAK 做优先副本选举和分区重分配
当集群运行一段时间后，broker 节点的分区负载可能严重倾斜，比如某台机器磁盘快满，但它的 leader 分区特别多。CMAK 的进阶用法就是把这两件事从命令行搬进界面。
优先副本选举解决的是 leader 分布不均的问题。在Cluster -> Reassign Partitions里选择Generate Preferred Replica Election，CMAK 会找出所有未按首选副本规则运行的分区，生成候选列表后执行。这个操作比手工写 json 文件快得多，但只适合 leader 重新均衡，不能让分区在不同 broker 之间迁移。
分区重分配适合换 broker 或降磁盘水位。操作路径是选择目标 topic，点击Reassign Partitions，勾选要迁移到的 broker，CMAK 会生成一份 json 分配方案，预览确认后再执行。执行过程中注意两点：一是不要在高峰期操作，重分配会占用 broker 的网络和磁盘 IO；二是 CMak 的界面里没有限流参数，如果想限流，需要把生成的 json 导出后用 Kafka 自带脚本执行。
# 从CMA-K页面导出分配方案后，用脚本带限流参数执行 bin/kafka-reassign-partitions.sh \ --zookeeper zk01:2181/kafka \ --reassignment-json-file reassign.json \ --execute--execute执行前建议先-verify跑一遍预期检查，确认条件满足。执行过程卡住时不要慌，重分配是持续进行的过程，可以用-verify反复查询进度，只有出现Data not yet completed才是正常中间态。
我自己的习惯是：优先副本选举放进每月巡检，分区重分配只在新增 broker 或磁盘告警时才做。每次操作前先用 CMAK 导出当前分区分布，操作后对比负载曲线。这个工具不是黑匣子，它生成的所有方案在后台都能找到对应的 Kafka 原生命令，用熟了以后你会更清楚什么时候该信界面，什么时候该回命令行。希望这些踩坑记录能帮你把部署时间从一晚上压缩到一顿饭的功夫，也希望你在生产环境操作前，先在这套方案的最小集群上完整跑一遍。
本文还有配套的精品资源，点击获取