fix: prepare native cluster deployment

2026-09-21 13:52:34 +08:00
parent 5f717c2162
commit 407842db91
7 changed files with 754 additions and 18 deletions
@@ -0,0 +1,430 @@
+# IM 原生 Cluster 运维部署说明
+
+## 1. 目标
+
+本文给运维说明 IM Server 如何部署才能真正启用 Tinode 原生 Cluster。
+
+目标效果：
+
+- 多个 IM Pod 组成同一个 Tinode Cluster，不再是 standalone。
+- 每个 Pod 拥有稳定、唯一的节点名。
+- 节点之间通过 `cluster_config.nodes.addr` 建立内部 TCP RPC 通信。
+- Topic 请求可以路由到唯一 Topic master，由 master 处理 Topic 内状态机、顺序和实时下发。
+
+如果部署后日志仍出现：
+
+```text
+Cluster: running as a standalone server.
+```
+
+说明原生 Cluster 没有启用，跨 Pod Topic 状态机不会生效。
+
+## 2. 原生 Cluster 启用条件
+
+必须同时满足以下条件：
+
+1. `cluster_self` 非空。
+2. `cluster_self` 的值必须等于 `cluster_config.nodes` 中某个节点的 `name`。
+3. `cluster_config.nodes` 必须包含所有 IM 节点，包括当前节点。
+4. 每个节点的 `addr` 必须是其他 Pod 可访问的内部地址。
+5. 每个节点必须监听自己的 `addr` 端口。
+6. 节点之间网络策略、安全组、Service 必须放通 cluster 内部端口。
+7. 至少 2 个节点才算有效 Cluster，生产建议 3 个节点起。
+
+当前代码启动参数由 `docker/tinode/entrypoint.sh` 传入：
+
+```bash
+./tinode --config=${CONFIG} --static_data=$STATIC_DIR --cluster_self=$CLUSTER_SELF --pprof_url=$PPROF_URL
+```
+
+所以运维侧必须确保每个 Pod 的环境变量 `CLUSTER_SELF` 有值，并且值稳定。
+
+## 3. 推荐部署形态
+
+推荐使用 Kubernetes `StatefulSet`，不要用普通 `Deployment` 直接滚动多个副本。
+
+原因：
+
+- 原生 Cluster 依赖稳定节点名，例如 `im-server-0`、`im-server-1`、`im-server-2`。
+- 原生 Cluster 依赖稳定 DNS，例如 `im-server-0.im-server-cluster.default.svc.cluster.local`。
+- 普通 Deployment 的 Pod 名会变化，不适合作为 `cluster_self`。
+- StatefulSet 配合 Headless Service 可以给每个 Pod 提供固定网络身份。
+
+推荐结构：
+
+```text
+Headless Service: im-server-cluster
+StatefulSet:      im-server
+Pod DNS:
+  im-server-0.im-server-cluster.<namespace>.svc.cluster.local
+  im-server-1.im-server-cluster.<namespace>.svc.cluster.local
+  im-server-2.im-server-cluster.<namespace>.svc.cluster.local
+```
+
+## 4. 端口规划
+
+至少需要区分三类端口：
+
+| 端口 | 用途 | 是否对公网暴露 | 说明 |
+| --- | --- | --- | --- |
+| `6060` | HTTP/WebSocket/API | 通过 Ingress/SLB 暴露 | 客户端连接入口。 |
+| `16060` | Tinode gRPC 客户端端口 | 通常不对公网暴露 | 管理或内部 gRPC 客户端使用。 |
+| `12000` | 原生 Cluster 内部 RPC | 不对公网暴露，只在 Pod 间放通 | `cluster_config.nodes.addr` 使用。 |
+
+注意：`cluster_config.nodes.addr` 使用的是原生 Cluster 内部 TCP RPC 地址，不是 `grpc_listen` 的 `16060`。
+
+建议统一所有 Pod 的 cluster 监听端口为 `12000`，通过 Pod DNS 区分节点：
+
+```json
+{
+  "name": "im-server-0",
+  "addr": "im-server-0.im-server-cluster.default.svc.cluster.local:12000"
+}
+```
+
+不要沿用 docker compose 示例里的 `tinode-0:12000`、`tinode-1:12001`、`tinode-2:12002`，除非是在同一主机或 docker compose 网络里部署。
+
+## 5. 配置文件要求
+
+`server/tinode.conf` 默认配置是：
+
+```json
+"cluster_config": {
+  "self": "",
+  "nodes": [],
+  "failover": {
+    "enabled": false
+  }
+}
+```
+
+这个配置不会启用 Cluster。
+
+生产或测试环境需要提供完整配置。建议 3 节点配置如下：
+
+```json
+"cluster_config": {
+  "self": "",
+  "nodes": [
+    {
+      "name": "im-server-0",
+      "addr": "im-server-0.im-server-cluster.default.svc.cluster.local:12000"
+    },
+    {
+      "name": "im-server-1",
+      "addr": "im-server-1.im-server-cluster.default.svc.cluster.local:12000"
+    },
+    {
+      "name": "im-server-2",
+      "addr": "im-server-2.im-server-cluster.default.svc.cluster.local:12000"
+    }
+  ],
+  "failover": {
+    "enabled": true,
+    "heartbeat": 100,
+    "vote_after": 8,
+    "node_fail_after": 16
+  }
+}
+```
+
+说明：
+
+- `self` 可以保持为空，由启动参数 `--cluster_self=$CLUSTER_SELF` 覆盖。
+- `CLUSTER_SELF` 必须分别为 `im-server-0`、`im-server-1`、`im-server-2`。
+- `nodes` 必须所有 Pod 完全一致。
+- `addr` 必须能被其他 Pod 访问。
+- 3 节点建议开启 failover；2 节点不建议开启 failover。
+
+## 6. Kubernetes 示例
+
+以下示例只展示 Cluster 相关关键配置，实际部署时需要合并现有镜像、环境变量、Secret、资源限制、探针、Ingress 和业务配置。
+
+### 6.1 Headless Service
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: im-server-cluster
+  namespace: default
+spec:
+  clusterIP: None
+  selector:
+    app: im-server
+  ports:
+    - name: cluster
+      port: 12000
+      targetPort: 12000
+    - name: http
+      port: 6060
+      targetPort: 6060
+    - name: grpc
+      port: 16060
+      targetPort: 16060
+```
+
+### 6.2 客户端入口 Service
+
+客户端入口可以继续使用普通 Service 或 Ingress，负载到所有 Pod：
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: im-server
+  namespace: default
+spec:
+  selector:
+    app: im-server
+  ports:
+    - name: http
+      port: 6060
+      targetPort: 6060
+```
+
+### 6.3 StatefulSet
+
+```yaml
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+  name: im-server
+  namespace: default
+spec:
+  serviceName: im-server-cluster
+  replicas: 3
+  selector:
+    matchLabels:
+      app: im-server
+  template:
+    metadata:
+      labels:
+        app: im-server
+    spec:
+      containers:
+        - name: im-server
+          image: <im-server-image>
+          ports:
+            - name: http
+              containerPort: 6060
+            - name: grpc
+              containerPort: 16060
+            - name: cluster
+              containerPort: 12000
+          env:
+            - name: CLUSTER_SELF
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.name
+            - name: EXT_CONFIG
+              value: /etc/tinode/tinode.conf
+          volumeMounts:
+            - name: tinode-config
+              mountPath: /etc/tinode
+              readOnly: true
+      volumes:
+        - name: tinode-config
+          configMap:
+            name: im-server-tinode-conf
+```
+
+重点：
+
+- `serviceName` 必须指向 Headless Service。
+- `CLUSTER_SELF` 直接取 Pod 名，StatefulSet 下会稳定为 `im-server-0`、`im-server-1`、`im-server-2`。
+- ConfigMap 中的 `cluster_config.nodes.name` 必须和 Pod 名一致。
+- ConfigMap 中的 `cluster_config.nodes.addr` 建议使用 StatefulSet Pod DNS。
+
+## 7. NetworkPolicy / 安全组要求
+
+如果集群启用了 NetworkPolicy，需要允许 IM Pod 之间访问 cluster 端口：
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: im-server-cluster-allow
+  namespace: default
+spec:
+  podSelector:
+    matchLabels:
+      app: im-server
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - podSelector:
+            matchLabels:
+              app: im-server
+      ports:
+        - protocol: TCP
+          port: 12000
+  egress:
+    - to:
+        - podSelector:
+            matchLabels:
+              app: im-server
+      ports:
+        - protocol: TCP
+          port: 12000
+```
+
+如果没有 NetworkPolicy，可以跳过此项，但仍要确认云厂商安全组、服务网格策略没有拦截 Pod 间 TCP `12000`。
+
+## 8. 启动顺序
+
+建议：
+
+1. 先部署 ConfigMap、Headless Service、普通入口 Service。
+2. 再部署 StatefulSet。
+3. 第一个 Pod 可以执行数据库初始化和升级。
+4. 其他 Pod 设置 `NO_DB_INIT=true`，避免多 Pod 同时初始化数据库。
+5. 等所有 Pod Ready 后再接入客户端流量。
+
+如果当前镜像沿用 `docker/tinode/entrypoint.sh` 的逻辑：
+
+- 第一个 Pod 可以保留 `NO_DB_INIT=false`。
+- 其他 Pod 建议设置 `NO_DB_INIT=true`。
+- 如果所有 Pod 同时启动，要确认数据库初始化脚本具备幂等能力，否则建议改成 init Job 单独执行。
+
+## 9. 发布步骤建议
+
+### 9.1 灰度前检查
+
+执行：
+
+```bash
+kubectl -n default get pod -l app=im-server -o wide
+kubectl -n default get svc im-server-cluster
+kubectl -n default exec im-server-0 -- sh -c 'echo $CLUSTER_SELF'
+kubectl -n default exec im-server-1 -- sh -c 'echo $CLUSTER_SELF'
+kubectl -n default exec im-server-2 -- sh -c 'echo $CLUSTER_SELF'
+```
+
+期望：
+
+```text
+im-server-0
+im-server-1
+im-server-2
+```
+
+验证节点 DNS：
+
+```bash
+kubectl -n default exec im-server-0 -- sh -c 'nc -vz im-server-1.im-server-cluster.default.svc.cluster.local 12000'
+kubectl -n default exec im-server-0 -- sh -c 'nc -vz im-server-2.im-server-cluster.default.svc.cluster.local 12000'
+```
+
+### 9.2 启动后日志检查
+
+查看日志：
+
+```bash
+kubectl -n default logs im-server-0 | grep -i cluster
+kubectl -n default logs im-server-1 | grep -i cluster
+kubectl -n default logs im-server-2 | grep -i cluster
+```
+
+不能出现：
+
+```text
+Cluster: running as a standalone server.
+```
+
+如果出现该日志，优先检查：
+
+- `CLUSTER_SELF` 是否为空。
+- `CLUSTER_SELF` 是否不在 `cluster_config.nodes.name` 中。
+- 配置文件是否确实被容器读取。
+- `EXT_CONFIG` 是否指向了正确文件。
+- `cluster_config.nodes` 是否为空。
+
+如果出现节点连接失败，优先检查：
+
+- `cluster_config.nodes.addr` DNS 是否能解析。
+- 端口 `12000` 是否监听。
+- Pod 间 NetworkPolicy 是否放通。
+- Service `targetPort` 是否正确。
+
+### 9.3 功能验收
+
+至少验证：
+
+1. A、B 两个账号分别连到不同 Pod，P2P 消息实时互达。
+2. A、B 分别连到不同 Pod，语音通话 `ringing`、`accept`、`hang-up` 状态实时互达。
+3. 同一个账号多端连接不同 Pod，`recv/read` 回执正常。
+4. 群聊成员分布在不同 Pod，群消息实时下发正常。
+5. 重启任意一个 Pod 后，客户端能重连，Topic 可重新订阅。
+6. 日志无持续 cluster unreachable、proxy timeout、dial timeout。
+
+## 10. 与 Redis Fanout 的关系
+
+启用原生 Cluster 后，Redis 仍然保留，但职责要收敛：
+
+- 保留：全局 presence、session control、踢端、同平台挤旧端、大群在线缓存、热点缓存、限流、幂等、补偿。
+- 收敛或关闭：Topic data/info/pres 的 Redis topic fanout。
+- 收敛或关闭：通话 `call_event/topic` 的 Redis fanout。
+
+否则会出现同一个 Topic 事件既由 Cluster 下发、又由 Redis Fanout 下发，导致重复 data/info/pres/call event。
+
+对应职责边界参考：
+
+- `docs/IM-原生Cluster与RedisFanout职责边界.md`
+
+## 11. 常见问题
+
+### 11.1 日志仍然是 standalone
+
+原因通常是 `cluster_self` 为空或配置文件里的 `nodes` 为空。
+
+处理：
+
+1. 确认 Pod 环境变量 `CLUSTER_SELF`。
+2. 确认启动参数包含 `--cluster_self=$CLUSTER_SELF`。
+3. 确认容器读取的是带完整 `cluster_config.nodes` 的配置。
+
+### 11.2 Pod 能启动，但跨 Pod 消息还是不通
+
+原因通常是 cluster 内部端口不通，或节点地址写错。
+
+处理：
+
+1. 从任意 Pod `nc -vz <peer-pod-dns> 12000`。
+2. 检查 Headless Service selector 是否匹配 Pod label。
+3. 检查 NetworkPolicy 是否放通 egress/ingress。
+4. 检查 `cluster_config.nodes.addr` 是否写成了只在 docker compose 里可用的短域名。
+
+### 11.3 扩缩容后部分 Topic 异常
+
+原生 Cluster 的 Topic master 基于节点集合计算。扩缩容会改变节点集合，可能触发 Topic 重新路由。
+
+建议：
+
+- 生产先固定 3 节点。
+- 不要频繁自动扩缩容 IM Server。
+- 扩缩容必须配合完整压测和重连验证。
+- 如果要从 3 节点扩到 5 节点，先更新所有 Pod 的 `cluster_config.nodes`，再按发布计划滚动。
+
+### 11.4 2 节点能不能用
+
+2 节点可以启用基础 Cluster，但不建议开启 failover，也不建议生产使用。
+
+生产推荐 3 节点起，便于 leader 心跳和故障判断。
+
+## 12. 运维上线检查清单
+
+- [ ] 使用 StatefulSet，不使用普通 Deployment 承载 Cluster 节点身份。
+- [ ] 创建 Headless Service。
+- [ ] 每个 Pod 的 `CLUSTER_SELF` 等于 Pod 名。
+- [ ] `cluster_config.nodes` 包含所有 Pod。
+- [ ] 所有 Pod 使用同一份 `cluster_config.nodes`。
+- [ ] 每个 `nodes.addr` 可从其他 Pod 访问。
+- [ ] 放通 cluster 内部 TCP 端口 `12000`。
+- [ ] 普通 HTTP/WebSocket 入口仍通过 Service/Ingress 负载到所有 Pod。
+- [ ] 只有一个入口负责数据库初始化，或数据库初始化已改为独立 Job。
+- [ ] 启动日志不再出现 `Cluster: running as a standalone server.`。
+- [ ] 跨 Pod P2P、群聊、read/recv、通话状态已验收。
+- [ ] 原生 Cluster 启用后，Topic 相关 Redis Fanout 已按职责边界关闭或降级。