EMQX 在 K8s 重启失败：从死锁到自愈的完整配置指南

为什么写这篇

前段时间遇到一个棘手问题：EMQX 在 Kubernetes 环境里崩了之后，怎么都起不来。Pod 一直卡在 CrashLoopBackOff，日志里全是连接超时。我对 K8s 和 EMQX 都不算熟，排查过程踩了不少坑。

这篇文章不是写给专家看的，是写给和我一样”能用但不精通”的人。我会用最直白的类比解释那些术语，然后给出能直接用的配置文件。你不需要完全理解底层原理，但看完应该能知道”为什么会挂”和”怎么防止再挂”。

故障现场

症状：
– EMQX Pod 反复重启，退出码 137（OOM 被杀）
– 重启后卡在启动阶段，日志显示 waiting for Mnesia to start...
– 双节点集群，一个挂了另一个也跟着不工作

根本原因（后来才搞清楚的）：
1. 内存爆了：数据桥接的缓冲队列（ReplayQ）用的是内存模式，下游 Kafka 慢了之后消息全堆在内存里，最后被 Linux 内核强杀
2. 重启死锁：Pod 重启后读到旧硬盘里残留的旧 IP 地址，一直尝试连接已经不存在的节点，陷入无限等待
3. 集群规模不够：只有 2 个节点，挂掉 1 个后剩下那个无法形成”多数派”，自愈机制失效

名词映射表：把复杂术语翻译成人话

在开始配置之前，先理解几个关键概念。我把它们分成”基础设施层（K8s）”和”应用层（EMQX）”两部分。

K8s 基础设施层

把 K8s 想象成一个五星级酒店大楼：

EMQX 应用层

EMQX 是基于 Erlang 的 MQTT 消息中间件：

故障相关核心概念

解决方案一：StatefulSet + 持久化存储

为什么需要 StatefulSet

如果用 Deployment 部署 EMQX，就像让员工住临时工位——每次重启后名字和位置都是随机的。Mnesia 数据库里记录的节点名称（如 emqx-0）和新启动的 Pod 名称（如 emqx-7a8b9c）对不上，集群就认不出来。

StatefulSet 保证三件事：
1. Pod 名称固定（emqx-0, emqx-1, emqx-2）
2. 重启后能找回原来的 PVC（持久化硬盘）
3. 启动顺序可控（虽然我们会改成并行启动）

完整配置文件

apiVersion: v1
kind: Service
metadata:
  name: emqx-headless
  namespace: emqx
spec:
  clusterIP: None  # Headless Service，用于生成稳定的 FQDN
  selector:
    app: emqx
  ports:
  - name: mqtt
    port: 1883
  - name: dashboard
    port: 18083
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: emqx
  namespace: emqx
spec:
  serviceName: emqx-headless
  replicas: 3  # 至少 3 个节点，保证多数派
  podManagementPolicy: Parallel  # 并行启动，避免顺序依赖
  selector:
    matchLabels:
      app: emqx
  template:
    metadata:
      labels:
        app: emqx
    spec:
      # ========== Init Container：启动前清理旧数据 ==========
      initContainers:
      - name: cleanup-stale-mnesia
        image: busybox:1.36
        command:
        - /bin/sh
        - -c
        - |
          MNESIA_DIR="/opt/emqx/data/mnesia"
          CURRENT_NODE="emqx@$(hostname).emqx-headless.emqx.svc.cluster.local"

          if [ -d "$MNESIA_DIR" ]; then
            echo "检查 Mnesia 目录: $MNESIA_DIR"
            # 删除所有不匹配当前节点名的目录（清理旧 IP 残留）
            find $MNESIA_DIR -maxdepth 1 -type d ! -name "*$(hostname)*" -exec rm -rf {} + 2>/dev/null || true
            echo "清理完成，当前节点: $CURRENT_NODE"
          fi
        volumeMounts:
        - name: emqx-data
          mountPath: /opt/emqx/data

      # ========== 主容器 ==========
      containers:
      - name: emqx
        image: emqx/emqx:5.4.0
        env:
        # 使用 FQDN 作为节点名（关键配置）
        - name: EMQX_NODE_NAME
          value: "emqx@$(HOSTNAME).emqx-headless.$(POD_NAMESPACE).svc.cluster.local"
        - name: HOSTNAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace

        # 集群发现配置
        - name: EMQX_CLUSTER__DISCOVERY_STRATEGY
          value: "k8s"
        - name: EMQX_CLUSTER__K8S__SERVICE_NAME
          value: "emqx-headless"
        - name: EMQX_CLUSTER__K8S__ADDRESS_TYPE
          value: "hostname"  # 使用主机名而非 IP
        - name: EMQX_CLUSTER__K8S__NAMESPACE
          value: "emqx"

        # 资源限制（QoS Guaranteed）
        resources:
          requests:
            memory: "2Gi"
            cpu: "1000m"
          limits:
            memory: "2Gi"  # 和 requests 一致，防止被优先杀掉
            cpu: "2000m"

        volumeMounts:
        - name: emqx-data
          mountPath: /opt/emqx/data
        - name: emqx-config
          mountPath: /opt/emqx/etc/emqx.conf
          subPath: emqx.conf

      volumes:
      - name: emqx-config
        configMap:
          name: emqx-config

  # ========== 持久化存储声明模板 ==========
  volumeClaimTemplates:
  - metadata:
      name: emqx-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: "standard"  # 根据你的集群修改
      resources:
        requests:
          storage: 10Gi

关键配置解释

解决方案二：ReplayQ 磁盘模式 + 内存保护

为什么会 OOM

这次故障的直接原因是 ReplayQ 用内存模式存消息。当下游 Kafka 慢了或者挂了，消息全堆在内存里，最后把 2GB 内存吃光，被 Linux 内核强杀（Exit Code 137）。

形象化类比：
– Memory 模式：快递全堆在办公桌上，桌子堆满了就崩了
– Disk 模式：快递放进仓库（PVC），桌上只留几个待处理的

EMQX 配置文件（emqx.conf）

创建 ConfigMap 挂载到 /opt/emqx/etc/emqx.conf：

apiVersion: v1
kind: ConfigMap
metadata:
  name: emqx-config
  namespace: emqx
data:
  emqx.conf: |
    # ========== 节点配置 ==========
    node {
      name = "emqx@${HOSTNAME}.emqx-headless.${POD_NAMESPACE}.svc.cluster.local"
      cookie = "emqx_cluster_secret"  # 集群认证密钥，所有节点必须一致
    }

    # ========== 集群配置 ==========
    cluster {
      discovery_strategy = k8s
      k8s {
        service_name = "emqx-headless"
        address_type = hostname
        namespace = "emqx"
      }
    }

    # ========== 内存保护配置 ==========
    # 强制垃圾回收：每处理 8000 条消息清理一次内存
    force_gc {
      count = 8000
      bytes = 16MB
    }

    # 离线消息队列限制：单个客户端最多存 500 条
    mqtt {
      max_mqueue_len = 500
    }

    # 会话过期时间：1 小时后自动清理僵尸连接
    zone.external {
      session_expiry_interval = 1h
    }

    # 内存过载保护：内存水位超过 85% 时拒绝新连接
    sysmon {
      os {
        mem_check_interval = 60s
        sysmem_high_watermark = 85%
      }
    }

    # ========== 数据桥接配置（关键）==========
    # 示例：Kafka 桥接
    bridges.kafka.my_kafka_bridge {
      enable = true
      servers = "kafka.default.svc.cluster.local:9092"

      # ReplayQ 磁盘模式配置
      resource_opts {
        buffer_mode = volatile_offload  # 关键：启用磁盘缓冲
        buffer_seg_bytes = 100MB        # 每个段文件 100MB
        max_buffer_bytes = 2GB          # 最大缓冲 2GB（写入 PVC）

        # 过载保护
        health_check_interval = 15s
        request_ttl = 45s

        # 工作线程
        worker_pool_size = 4
        max_queue_bytes = 2GB
      }
    }

关键参数解释

为什么磁盘模式不会拖慢性能

你可能会担心”写磁盘会不会很慢”。实际上：
1. 只在下游阻塞时才写磁盘：正常情况下消息直接转发，不经过磁盘
2. 顺序写入：磁盘顺序写入速度接近内存（现代 SSD 可达 500MB/s）
3. 异步刷盘：不会阻塞主线程

解决方案三：集群规模 + 多数派机制

为什么 2 节点不够

分布式系统有个”多数派”原则：超过半数的节点存活，集群才能做决定。

推荐配置：
– 生产环境：至少 3 个 Core 节点
– 高可用场景：5 个 Core 节点 + N 个 Replicant 节点

Core vs Replicant 架构

如果你的集群主要处理连接（而非写数据），可以用这种架构：

# Core 节点（负责写 Mnesia）
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: emqx-core
spec:
  replicas: 3  # 固定 3 个
  template:
    spec:
      containers:
      - name: emqx
        env:
        - name: EMQX_NODE__DB_ROLE
          value: "core"
---
# Replicant 节点（只处理连接）
apiVersion: apps/v1
kind: Deployment  # 可以用 Deployment，因为不需要持久化
metadata:
  name: emqx-replicant
spec:
  replicas: 10  # 可以随意扩缩容
  template:
    spec:
      containers:
      - name: emqx
        env:
        - name: EMQX_NODE__DB_ROLE
          value: "replicant"

优势：
– Core 节点稳定（3 个就够），负责数据一致性
– Replicant 节点可以根据连接数动态扩缩容
– Replicant 挂了不影响集群决策

验证和排查

部署后检查清单

# 1. 检查 Pod 状态
kubectl get pods -n emqx -o wide

# 期望输出：
# NAME      READY   STATUS    RESTARTS   AGE
# emqx-0    1/1     Running   0          5m
# emqx-1    1/1     Running   0          5m
# emqx-2    1/1     Running   0          5m

# 2. 检查集群状态
kubectl exec -n emqx emqx-0 -- emqx ctl cluster status

# 期望输出：
# Cluster status: #{running_nodes =>
#     ['emqx@emqx-0.emqx-headless.emqx.svc.cluster.local',
#      'emqx@emqx-1.emqx-headless.emqx.svc.cluster.local',
#      'emqx@emqx-2.emqx-headless.emqx.svc.cluster.local']}

# 3. 检查 PVC 绑定
kubectl get pvc -n emqx

# 期望输出：
# NAME              STATUS   VOLUME    CAPACITY   STORAGECLASS
# emqx-data-emqx-0  Bound    pvc-xxx   10Gi       standard
# emqx-data-emqx-1  Bound    pvc-yyy   10Gi       standard
# emqx-data-emqx-2  Bound    pvc-zzz   10Gi       standard

# 4. 检查内存使用
kubectl top pods -n emqx

# 期望输出：内存使用应该稳定在 1.5GB 以下

常见问题排查

模拟故障测试

验证配置是否生效的最好方法是主动制造故障：

# 1. 删除一个 Pod，看能否自动恢复
kubectl delete pod emqx-1 -n emqx

# 观察：
# - 新 Pod 应该在 30 秒内启动
# - 集群状态应该自动恢复到 3 节点
# - 不应该出现 CrashLoopBackOff

# 2. 模拟下游阻塞（如果有 Kafka 桥接）
# 停掉 Kafka，观察 EMQX 内存是否稳定
kubectl scale deployment kafka -n default --replicas=0

# 观察：
# - 内存应该稳定在 2GB 以下
# - 日志应该显示 "buffer offloaded to disk"
# - 不应该出现 OOM

# 3. 恢复 Kafka，检查消息是否补发
kubectl scale deployment kafka -n default --replicas=3

# 观察：
# - 磁盘缓冲的消息应该逐步发送到 Kafka
# - 内存使用应该回落

核心配置总结

把上面的方案整合一下，关键配置点：

写在最后

这次故障排查让我学到几个教训：

1. 分布式系统不要凭直觉：2 节点看起来有冗余，实际上挂 1 个就全废。多数派机制是硬性要求，不是可选项。

2. 内存模式是定时炸弹：ReplayQ 默认用内存，在测试环境可能没问题，但生产环境下游一慢就爆炸。磁盘模式应该是默认选项。

3. IP 地址不可靠：K8s 环境下 Pod 重启 IP 必然变，用 FQDN 才是正道。这个坑不只 EMQX 有，所有有状态服务都要注意。

4. Init Container 是救命稻草：启动前清理旧数据，能避免 90% 的重启死锁问题。这个模式可以推广到其他有状态应用。

如果你也在用 K8s 跑 EMQX（或其他 Erlang 集群），希望这篇文章能帮你少踩点坑。配置文件可以直接拿去用，记得改 namespace 和 storageClassName。