利用 StatefulSet 部署悟空 IM（WuKongIM）分布式三节点集群踩坑记录

引言

在 Kubernetes（K8s）中部署分布式强一致性集群（如基于 Raft 协议的中间件）时，工程师们经常会遭遇各种诡异的启动死锁。

最近，我们在基于容器多阶段构建、无基础 OS（Alpine）的私有镜像上，利用 StatefulSet 部署悟空 IM（WuKongIM）分布式三节点集群。期间踩过了一连串极具代表性的硬核深坑：从 Docker 编译行为的反直觉路径截断，到 Linux 动态链接器断层，再到 K8s 内部 CoreDNS 与有状态服务按序拉起引发的"鸡生蛋、蛋生鸡"网络死锁。

本文将完全还原这场长达数小时的排链、填坑之旅，把这些沉甸甸的底层逻辑和避坑指南分享给大家。

🛠️ 第一阶段：Dockerfile 多阶段构建与文件截断谜案

1. 现象还原

基于标准的 Go 1.23 多阶段构建 Dockerfile 在物理宿主机顺利编译完成（docker build -t ... .）。然而，当将生成的镜像投入 K8s 时，Pod 却疯狂报错闪退：

Plaintext

复制代码

/startup/startup.sh: line 25: /home/app: No such file or directory

令人费解的是，物理进入容器后，发现 /home 文件夹下确实空空如也。

2. 根因拆解

问题出在后端编译命令与多阶段目录拷贝的连锁反应。原编译指令如下：

Dockerfile

复制代码

RUN GIT_COMMIT=$(git rev-parse HEAD) && \
    ...
    CGO_ENABLED=0 GOOS=linux go build -o app ./main.go

Git 变量阻断 ：当我们在非 Git 仓库的纯代码包根目录下执行编译时，git rev-parse HEAD 直接报错返回非 0 状态。由于 && 的链式逻辑，直接导致后面的 go build 被彻底跳过，未生成任何 app 二进制。
多阶段拷贝覆盖陷阱：在第二阶段（生产环境）中，有这样两行：

Dockerfile
复制代码
```
WORKDIR /home
COPY --from=build /go/release/app /home
```
在 Docker 机制中，如果源路径 app 文件因为编译失败压根不存在，部分 Docker 引擎版本在处理此类上下文缓存时，可能直接跳过或保持目标的 /home 为基础镜像默认的空目录。

3. 正确解法

去掉动态抓取 Git 状态的强依赖，或者对 Git 命令进行容错处理，确保 go build 100% 物理执行并产出：

Dockerfile

复制代码

WORKDIR /go/release
ADD . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o app ./main.go

当第二次成功编译出 app 文件后，由于目标的 /home 已经存在并且是个目录，Docker 的 COPY 机制会将其完美送入 /home/app。

🐚 第二阶段：Alpine 镜像解释器断层与极其误导的 "Not Found"

1. 现象还原

好不容易把物理文件打进了镜像，再次通过 K8s 拉起时，依然闪退，但这次报错更让人崩溃：

Plaintext

复制代码

/bin/sh: /startup/startup.sh: not found

明明用 kubectl 查看时，由 ConfigMap 挂载出来的 /startup/startup.sh 脚本稳稳当当地躺在目录里，权限也是 0755，为什么操作系统却坚称 not found？

2. 根因拆解

这是 Linux 环境中极其隐蔽的"内核解释器断层"假象。

看一眼当时我们的 ConfigMap 启动脚本开头：

Bash

复制代码

#!/bin/bash
# ... 各种集群变量初始化

而在 Dockerfile 尾部，为了追求极简和轻量化，生产阶段使用的是 FROM alpine as prod。

Alpine 镜像为了把体积压缩到极致，内部默认只有 /bin/sh，根本就没有安装 bash！

当 K8s 的 StatefulSet 容器主进程通过 /bin/sh -c "/startup/startup.sh" 去引导脚本时，底层 Linux 内核读取了脚本第一行的 Shebang（#!/bin/bash），发现系统里压根没有 bash 这个程序。于是，系统向 Shell 抛出了一个极具误导性的报错------找不到脚本指定的内核解释器 bash，却被 Shell 误报成了"找不到脚本文件本身"。

3. 正确解法

彻底将 ConfigMap 内的 Shebang 降级切换为 Alpine 原生完美支持的标准通用 sh，同时将脚本内部的 [[ ... ]] 语法也同步兼容更正：

YAML

复制代码

data:
  startup.sh: |
    #!/bin/sh
    POD_NAME=${HOSTNAME}
    # 使用纯 sh 兼容的字符串剥离语法获取 Pod 序号
    POD_INDEX=${POD_NAME##*-} 
    ...

🕸️ 第三阶段：CoreDNS 与有状态服务就绪探针的"死锁循环"

解释器和二进制路径终于全部对齐后，3 个 Pod 终于齐刷刷变成了 Running。但是，它们卡在了 0/1 READY 状态，并且开始无休止地重启。

通过捞取上一次崩溃前留下的最后一句话（kubectl logs ... --previous），抓到了底层的核心 Panic 报错：

JSON

复制代码

{"level":"info","msg":"【raft.node】become candidate","term":23}
{"level":"info","msg":"【raft.node】sent vote request","from":1001,"to":1002,"term":23}
{"level":"panic","msg":"【slot.Server】wait all slots ready timeout"}
panic: 【slot.Server】wait all slots ready timeout

1. "无尽拉票"的网络深坑

日志显示：0号节点（1001）在短时间内任期号（term）疯狂飙升，不断变成 Candidate（候选人）并疯狂向 1 号和 2 号节点发拉票请求。然而，它发送出去的选票，在物理网络上没有任何人回应它。 物理钻进容器内部，尝试对兄弟节点进行网络探测，现了原形：

Bash

复制代码

/home # nc -zv agent-intent-wukongim-1.agent-intent-wukongim-headless 11110
nc: bad address 'agent-intent-wukongim-1.agent-intent-wukongim-headless'

bad address 意味着 K8s 内部的 CoreDNS 根本解析不动这个域名！

2. 揭秘"鸡生蛋、蛋生鸡"的有状态集死锁

在 Kubernetes 中，StatefulSet 的分布式 Pod 依赖一个 clusterIP: None 的 Headless Service 来做内网相互寻址。

然而，K8s 默认有一个极为保守的安全铁律：一个 Pod 只有在就绪探针（Readiness Probe）打卡通过、状态变成 1/1 READY 的时候，它的 IP 才会正式注册到 Headless Service 对应的 DNS 列表中。

这就导致了以下闭环死锁：

未就绪不解析 ：因为 3 个节点刚开机，全都是 0/1 READY。
DNS 拒绝广播：Endpoint 认为它们都不可用，直接从 CoreDNS 里抹掉了它们的域名解析。
拉票石沉大海 ：悟空 IM 的 Raft 协议在后台启动，尝试通过域名去和兄弟节点建立 11110 端口的 TCP 握手。因为 bad address，请求全部石沉大海。
无法选主崩溃 ：得不到多数派选票，集群选不出 Leader ➡️ 分布式槽位（Slots）无法初始化 ➡️ 触发超时 Panic 闪退 ➡️ 永远无法进入 1/1 READY。

3. 正确解法

要彻底击碎这个网络死锁，必须强行通知 Kubernetes 破例：这是分布式强一致性集群，不要管它们有没有就绪，哪怕是 0/1 状态，也必须立刻在 CoreDNS 里全量广播它们的内网 IP 路由！

我们在 service.yaml （Headless Service）的 spec 下注入了一行极为关键的黄金开关：publishNotReadyAddresses: true。

YAML

复制代码

apiVersion: v1
kind: Service
metadata:
  name: agent-intent-wukongim-headless
spec:
  clusterIP: None
  # 🌟【终极破锁】允许 Pod 在 0/1 未就绪状态下也能通过内网域名互相寻址
  publishNotReadyAddresses: true
  selector:
    app: wukongim
  ports:
  ...

同时，为了防止有状态集老老实实按序排队（0号不就绪就不创建1号），我们在 statefulset.yaml 中调整了管理策略，让 3 个副本一口气并行启动，在网络中同时现身：

YAML

复制代码

spec:
  serviceName: agent-intent-wukongim-headless
  replicas: 3
  # 🌟【并行拉起】不排队，3 个 Pod 一起动作，在开机瞬间完成网络握手
  podManagementPolicy: Parallel

🏁 终结清洗与凯旋

在将上述所有网络开关、脚本机制和容器路径彻底对齐后，我们通过 cascade=orphan 剥离旧控制器并下发了全新的 Helm 配置：

Bash

复制代码

# 1. 物理铲除旧的、卡死状态的 Headless 服务与控制器
kubectl delete svc agent-intent-wukongim-headless -n agent-intent-system
kubectl delete sts agent-intent-wukongim -n agent-intent-system --cascade=orphan

# 2. 清洗之前多次闪退残留的 Raft 脏元数据卷
kubectl delete pvc -l app=wukongim -n agent-intent-system

# 3. 升级 Helm 刷新全量全新网络配置
helm upgrade agent-intent . -f values-with-internal-db.yaml --namespace agent-intent-system

# 4. 强杀老 Pod 促使并行重建
kubectl delete pod -l app=wukongim -n agent-intent-system --force --grace-period=0

当全新并行的 Pod 拔地而起时，由于 publishNotReadyAddresses: true 全额生效，开机 0.1 秒内各节点便顺利在 11110 端口完成了 TCP 三次握手：

JSON

复制代码

{"level":"info","msg":"【Server】收到连接。。。","from":"1002"}
{"level":"info","msg":"【Server】收到连接。。。","from":"1003"}
{"level":"info","msg":"【raft.node[clusterconfig]】become follower","term":19,"leaderId":1003}

集群在几秒钟内瞬间完成 Raft 分布式选主，彻底击碎了 Slot 超时死锁。

最终的验收结果令人赏心悦目：

Plaintext

复制代码

(base) user@node1:~$ kubectl get pods -n agent-intent-system -l app=wukongim
NAME                      READY   STATUS    RESTARTS   AGE
agent-intent-wukongim-0   1/1     Running   0          74s
agent-intent-wukongim-1   1/1     Running   0          74s
agent-intent-wukongim-2   1/1     Running   0          74s

💡 总结与避坑铁律

多阶段构建时 ：务必注意 COPY 的目标路径如果是已存在的 WORKDIR 目录，文件会以原名原样复制进去；同时，编译命令链条中不要让非核心命令（如 Git 状态抓取）阻塞整个编译产出。
精简镜像（Alpine/Distroless） ：开机引导脚本的 Shebang 头绝对不能盲目写 #!/bin/bash，必须与镜像内存在的实际 Shell 解释器严格对齐。
强一致性分布式集群（Raft/Zookeeper/ETCD） ：在 K8s 中配置 Headless Service 时，务必物理开启 publishNotReadyAddresses: true 开关，否则极易因为"未就绪不解析 DNS"的网络特性把整个集群死死掐灭在摇篮里。