必须用 statefulset+headless service 或 rocketmq operator 部署 broker；deployment 会导致注册混乱、主从失联、扩容失败，因其 pod 名称随机、ip 不固定、无法 dns 反解，且无法绑定 brokerid 与持久化存储。
直接上生产环境的 RocketMQ 高可用集群，必须用 RocketMQ Operator 或至少基于 StatefulSet + Headless Service；裸用 Deployment 启多个 Broker 会导致注册混乱、主从失联、扩容失败——这是最常踩的坑。
为什么不能用 Deployment 部署 RocketMQ Broker
RocketMQ 的 Broker 必须有稳定网络标识（如 broker-a-0.broker-a-headless.default.svc.cluster.local）供 NameServer 和其他 Broker 识别角色与拓扑。Deployment 生成的 Pod 名称随机、IP 不固定、无法反向 DNS 解析，导致：
-
broker-a启动后注册到 NameServer 的地址是10.244.1.15:10911，但下次重启变成10.244.1.16，NameServer 不感知，客户端查不到路由 - 主从之间靠
brokerName+brokerId+ 网络域名协商复制关系，Deployment下无法保证brokerId=0（Master）和brokerId=1（Slave）严格绑定到固定 Pod 实例 - Broker 持久化路径（
/home/rocketmq/store）若挂emptyDir，Pod 重建即丢消息；挂PVC又因无序重建导致 PVC 绑定错乱
StatefulSet 配置关键字段必须显式声明
以双主双从同步模式为例，Broker StatefulSet 必须设置以下参数，缺一不可：
-
serviceName: broker-a-headless：确保 Headless Service 正确关联，让 DNS 解析出broker-a-0.broker-a-headless这类可预测域名 -
podManagementPolicy: OrderedReady：强制按序启动（0→1→2…），避免 Slave 在 Master 尚未注册完成时就尝试连接 -
revisionHistoryLimit: 5：保留足够旧版本 Revision，防止滚动更新时误删 PVC -
volumeClaimTemplates中的storageClassName必须指向支持ReadWriteOnce且具备拓扑感知的存储（如local-path、rook-ceph），NFS 多数场景不满足同步刷盘一致性要求
示例片段（Broker-A Master）：
spec:
serviceName: "broker-a-headless"
podManagementPolicy: "OrderedReady"
volumeClaimTemplates:
- metadata:
name: store
spec:
accessModes: ["ReadWriteOnce"]
storageClassName: "local-path"
resources:
requests:
storage: 50Gi
RocketMQ Operator 是生产首选，但要注意 CRD 初始化顺序
Operator 并非“装完就自动跑通”，它依赖一组自定义资源（CRD）先于 Controller 启动。常见失败现象：kubectl get rocketmqclusters 报 error: the server doesn't have a resource type "rocketmqclusters"。
针对 Kubernetes 仪表板和 Web UI 的浏览器自动化。适用于与 Kubernetes Dashboard、Grafana、ArgoCD UI 或其他 Web 界面交互。需要设置 MCP_BROWSER_ENABLED=true。
- 必须先执行
kubectl apply -f config/crd/bases/（含nameservices.rocketmq.apache.org、brokers.rocketmq.apache.org等 CRD 文件） - 再部署 Operator Controller（
make deploy或helm install），否则自定义资源无法被识别 - 创建
RocketMQCluster前，确认kubectl get crd | grep rocketmq输出至少 4 行，包括nameservices、brokers、console、topics - Operator 默认拉取镜像
apache/rocketmq:4.9.4，若内网无外网代理，需提前docker pull并kind load docker-image或改写imagePullPolicy: IfNotPresent+image字段
NameServer 和 Broker 的端口暴露策略要分离
对外提供服务时，NameServer 和 Broker 的访问路径完全不同，混用 Service 类型会引发连接超时：
-
NameServer只需 ClusterIP（默认9876端口），客户端通过namesrvAddr=ns-svc:9876注册，无需暴露到集群外 -
Broker的10911（非 VIP）必须通过 NodePort / LoadBalancer 暴露，否则外部生产者/消费者连不上；但10909（VIP 通道）可禁用，除非你明确在客户端设置了useTLS=false且走 VIP 路由 - 切勿给 Broker Service 设置
clusterIP: None（即 Headless）再配 Ingress——Ingress 不转发 TCP 流量，10911是纯 TCP 协议，必须用NodePort或LoadBalancer
验证方式：
kubectl exec -it rocketmq-console-xx -- curl -s http://rocketmq-nameserver:9876/namesrv/queryRouteInfo?topic=test | jq '.status'
返回 OK 表示 NameServer 可达；再从集群外 telnet <node-ip> 30911</node-ip>（NodePort 映射值）能通，才说明 Broker 对外链路正常。
真正卡住人的从来不是 YAML 写几行，而是 Broker 启动后日志里反复出现 registerBrokerToNamesrv failed 却死活查不到原因——大概率是 StatefulSet 的 serviceName 拼错、Headless Service 缺失、或 NameServer 的 clusterIP 被误设为 None。这些地方没对齐，后面所有扩缩容、主从切换全失效。
