部署
先确定集群目标和运行介质，再按统一门槛验证 WuKongIM 部署。
从两个问题开始：是否接受单点故障？谁负责运行节点？ 前者决定拓扑，后者决定 Docker、Linux 或 Kubernetes。运行介质不会自动带来高可用。
每个部署都是集群
单节点部署是单节点集群，仍然经过 Controller、Slot、Channel、路由和存储路径。不存在绕过集群语义的独立模式。
只想先体验 WuKongIM？使用快速开始。部署章节面向需要持久化、可观测、可重复发布的环境。
1. 选择拓扑
| 目标 | 拓扑 | 下一步 |
|---|---|---|
| 开发、验证或明确接受单点故障 | 单节点集群 | 选择 Docker 或 Linux |
| 跨节点复制和故障处理 | 多节点集群 | 先完成多节点设计 |
单节点集群只有一个 Slot/Channel 副本，节点或磁盘故障会中断服务。多节点只有分布在独立磁盘、电源或可用区时才形成有效故障域；三个容器共享一块磁盘不等于三个独立副本。
三节点、三副本没有节点余量。失去任一节点后，剩余节点可能仍有 Raft 多数，但 /readyz 会因副本候选不足返回 503。需要失去一台后仍保留三个副本候选时，至少准备四个合格数据节点。
2. 选择运行介质
| 介质 | 适合 | 由谁负责 |
|---|---|---|
| Docker | 已有容器构建和运行能力 | 镜像、Volume、网络、Secret 与容器生命周期 |
| Linux | 直接管理主机和 systemd | 二进制、目录权限、防火墙与服务单元 |
| Kubernetes（Beta） | 已有成熟有状态工作负载平台 | 最终清单、PVC、Secret、NetworkPolicy 与发布证据 |
仓库根目录的三节点 Compose 只用于开发验证。官方版本容器镜像记录在 Docker 页面；当前文档仍不承诺官方安装包、Helm Chart 或生产 Kubernetes 清单。
3. 按同一顺序实施
- 冻结制品：所有节点来自同一已审阅提交，记录工具链和摘要。
- 完成配置：从配置入口确认 TOML、
WK_*覆盖、节点身份和客户端广告地址。 - 准备状态：每个节点使用独立数据目录或磁盘，并为日志、插件状态和指标设置容量边界。
- 启动节点：显式传入
-config /path/to/wukongim.toml，不要依赖工作目录。 - 验证平台：确认持久化挂载、外部地址、
/healthz和/readyz。 - 验证集群：多节点继续验证成员身份、路由、端到端消息、重连同步和故障恢复。
- 生产切流：完成生产检查清单。
共享运行合同
- 每个节点使用唯一的节点 ID、数据目录和可达 Transport 地址。
- 物理 Hash Slot 数保持
256；副本数必须匹配可用节点和故障目标。 0.0.0.0只能用于监听，不能作为节点或客户端广告地址。- Manager、指标、Debug、Benchmark、诊断和 Transport 使用受控网络边界。
- DNS、证书、产品 HTTP 外部鉴权、云资源、密钥分发和生产切流由部署平台负责。
用 /readyz 接收流量
curl --fail http://127.0.0.1:5001/healthz
curl --fail http://127.0.0.1:5001/readyz/healthz 只说明进程能响应。集群写路由未就绪或处于恢复维护时，/readyz 会返回 503；负载均衡、发布门禁和切流判断必须使用 /readyz。
平台页面通过不等于生产可上线。只有多节点验证和生产清单也具备负责人、证据和回退方式时，才进入生产流量。