> ## Documentation Index
> Fetch the complete documentation index at: https://wukong.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 多节点部署

> 使用 Helm 在 Kubernetes 集群中部署 WuKongIM 多节点集群

在 Kubernetes 集群中部署 WuKongIM 多节点集群，提供高可用性、容灾能力和负载均衡。

## 部署特点

**优点**：

* 高可用性和容灾能力强
* 支持在线扩容
* 多副本间实时自动备份
* 负载均衡，无需手动配置
* 快速伸缩

**适用场景**：

* 对数据安全要求高的应用
* 大型应用
* 企业级生产环境

<Warning>
  **注意**：当前 WuKongIM 支持热扩容，暂不支持热缩容！
</Warning>

## 前提条件

* Kubernetes 集群 1.19+
* kubectl 已配置并能访问集群
* Helm 3.0+
* 至少 3 个工作节点，每个节点 4GB+ 内存和 2 CPU 核心

## 部署步骤

### 1. 添加 Helm 仓库

```bash theme={null}
helm repo add wukongim https://wukongim.github.io/helm/
```

### 2. 更新 Helm 仓库

```bash theme={null}
helm repo update
```

### 3. 搜索可用的 Chart

```bash theme={null}
helm search repo wukongim
```

### 4. 部署 WuKongIM 多节点集群

```bash theme={null}
# 多节点部署（副本数为 3）
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=3
```

**可选参数**：

* `replicaCount=3`：副本数量（默认为 2）
* `externalIP=<IP地址>`：外部 IP 地址

### 5. 查看安装状态

```bash theme={null}
helm status wkim -n wukongim
```

### 6. 验证部署

```bash theme={null}
# 检查 Pod 状态
kubectl get pods -n wukongim

# 检查服务状态
kubectl get svc -n wukongim

# 查看集群状态
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/cluster/nodes
```

## 访问服务

### 端口转发访问

```bash theme={null}
# API 服务
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim

# WebSocket 服务
kubectl port-forward svc/wkim-wukongim 5200:5200 -n wukongim

# Demo 界面
kubectl port-forward svc/wkim-wukongim 5172:5172 -n wukongim

# 管理界面
kubectl port-forward svc/wkim-wukongim 5300:5300 -n wukongim
```

### 访问地址

* **API 端点**：[http://localhost:5001](http://localhost:5001)
* **WebSocket**：ws\://localhost:5200
* **Demo 界面**：[http://localhost:5172](http://localhost:5172)
* **管理界面**：[http://localhost:5300](http://localhost:5300)

## 配置选项

### 常用 Helm 参数

```bash theme={null}
# 完整配置示例
helm install wkim wukongim/wukongim \
  -n wukongim \
  --create-namespace \
  --version 0.1.0 \
  --set replicaCount=3 \
  --set image.tag=v2.0.0 \
  --set service.type=LoadBalancer \
  --set persistence.enabled=true \
  --set persistence.size=50Gi \
  --set resources.requests.memory=4Gi \
  --set resources.requests.cpu=2000m
```

### 主要配置参数

| 参数                    | 描述       | 默认值         |
| --------------------- | -------- | ----------- |
| `replicaCount`        | 副本数量     | `2`         |
| `image.tag`           | 镜像版本     | `latest`    |
| `service.type`        | 服务类型     | `ClusterIP` |
| `persistence.enabled` | 启用持久化存储  | `true`      |
| `persistence.size`    | 存储大小     | `10Gi`      |
| `externalIP`          | 外部 IP 地址 | `""`        |

## 扩容操作

### 扩容集群

```bash theme={null}
# 扩容到 5 个副本
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version 0.1.0 \
  --set replicaCount=5
```

### 验证扩容

```bash theme={null}
# 检查 Pod 数量
kubectl get pods -n wukongim

# 检查集群状态
kubectl port-forward svc/wkim-wukongim 5001:5001 -n wukongim &
curl http://localhost:5001/cluster/nodes

# 查看集群节点信息
curl http://localhost:5001/cluster/nodes | jq '.'
```

## 故障排除

### 常见问题

**Pod 启动失败**：

```bash theme={null}
# 查看 Pod 状态
kubectl get pods -n wukongim

# 查看详细信息
kubectl describe pod <pod-name> -n wukongim

# 查看日志
kubectl logs <pod-name> -n wukongim
```

**集群节点无法通信**：

```bash theme={null}
# 检查网络连通性
kubectl exec -it <pod-name> -n wukongim -- ping <other-pod-ip>

# 检查集群端口
kubectl exec -it <pod-name> -n wukongim -- netstat -tulpn | grep 11110

# 查看集群状态
kubectl logs <pod-name> -n wukongim | grep cluster
```

**服务无法访问**：

```bash theme={null}
# 检查服务状态
kubectl get svc -n wukongim

# 检查端点
kubectl get endpoints -n wukongim

# 测试服务连通性
kubectl exec -it <pod-name> -n wukongim -- wget -qO- http://localhost:5001/health
```

### 日志查看

```bash theme={null}
# 查看实时日志
kubectl logs -f deployment/wkim-wukongim -n wukongim

# 查看所有副本日志
kubectl logs -l app.kubernetes.io/name=wukongim -n wukongim

# 查看历史日志
kubectl logs deployment/wkim-wukongim -n wukongim --previous
```

## 升级和维护

### 升级版本

```bash theme={null}
# 更新 Helm 仓库
helm repo update

# 搜索新版本
helm search repo wukongim

# 升级到新版本
helm upgrade wkim wukongim/wukongim \
  -n wukongim \
  --version <新版本号>
```

### 备份数据

```bash theme={null}
# 创建数据快照
kubectl exec -n wukongim deployment/wkim-wukongim -- \
  tar czf /tmp/backup-$(date +%Y%m%d).tar.gz /data

# 复制备份文件到本地
kubectl cp wukongim/<pod-name>:/tmp/backup-$(date +%Y%m%d).tar.gz \
  ./wukongim-backup-$(date +%Y%m%d).tar.gz
```

## 卸载

```bash theme={null}
# 卸载 WuKongIM
helm uninstall wkim -n wukongim

# 删除命名空间（可选）
kubectl delete namespace wukongim
```

## 下一步

<CardGroup cols={2}>
  <Card title="单节点部署" icon="cube" href="/zh/installation/k8s/single-node">
    了解单节点部署方式
  </Card>

  <Card title="服务器配置" icon="gear" href="/zh/server/configuration">
    详细配置选项
  </Card>

  <Card title="Docker 部署" icon="docker" href="/zh/installation/docker/multi-node">
    Docker 多节点部署
  </Card>

  <Card title="API 文档" icon="code" href="/zh/api/introduction">
    开始使用 API
  </Card>
</CardGroup>