Linux 部署

用 deb/rpm 预览包或源码安装 WuKongIM，并通过安全初始化和 systemd 托管集群节点。

Linux 路径适合希望直接控制主机、文件系统、网络和服务生命周期的团队。仓库现在能够构建 deb/rpm 预览包，独立的 WuKongIM/packages 仓库也已在完成验证的 HTTPS 地址 packages.githubim.com 建立 fail-closed bootstrap；但签名密钥和 APT/YUM 索引尚未启用，因此该地址还不能用于安装。不要把下面的本地预览包当作已签名的正式发布渠道。

首批预览支持 Linux amd64，并在 Ubuntu 24.04、Debian 12、Rocky Linux 9 和 AlmaLinux 9 上执行安装契约检查。

1. 构建并安装本地预览包

仓库要求 Go 1.25.11，打包配置固定按 GoReleaser v2.18.0 校验：

git rev-parse HEAD
go version
goreleaser release --snapshot --clean \
  --config .goreleaser.packages.yaml
(cd dist && sha256sum --check checksums.txt)

Debian/Ubuntu 安装生成的 .deb：

sudo apt install ./dist/wukongim_*_linux_amd64.deb

Rocky/AlmaLinux 安装生成的 .rpm：

sudo dnf install ./dist/wukongim_*_linux_amd64.rpm

安装包会安装 /usr/bin/wukongim 和加固的 wukongim.service，创建 wukongim 系统账号以及 /etc/wukongim、/var/lib/wukongim、/var/log/wukongim、/run/wukongim。它不会生成活动配置，也不会启用、启动或重启服务。

用下面的命令确认二进制身份：

wukongim version
wukongim version --output json

2. 安全初始化配置

交互式初始化会生成单节点集群配置、随机 Cluster ID、Join Token、Manager JWT Secret 和管理员密码；生成的管理员密码只显示一次：

sudo wukongim config init \
  --config /etc/wukongim/wukongim.toml

自动化环境必须从标准输入提供至少 12 个字符的管理员密码，命令不会回显它：

sudo wukongim config init \
  --config /etc/wukongim/wukongim.toml \
  --admin-password-stdin < /secure/path/manager-password

初始化默认只让 TCP、WebSocket、API、Manager 和节点 Transport 监听回环地址。只有确认主机防火墙、TLS 终止和入口策略后，才可在首次初始化时添加 --gateway-public；该选项只将客户端 TCP/WebSocket Gateway 改为监听所有接口，不会公开 Manager 或节点 Transport。

生成器拒绝覆盖现有文件，并在原子发布前完成与服务启动相同的配置校验。以 root 运行且 wukongim 组存在时，文件权限为 root:wukongim 0640；其他情况使用 0600。随后检查外部地址、节点 ID、挂载和网络策略，再显式校验：

sudo wukongim config validate \
  --config /etc/wukongim/wukongim.toml

配置错误返回退出码 78。systemd 单元把这个退出码列入 RestartPreventExitStatus，避免错误配置形成重启风暴。配置加载器也会拒绝未知 TOML 键和未知 WK_* 环境变量。

3. 启动并验证

sudo systemctl enable --now wukongim
sudo systemctl status wukongim
sudo journalctl -u wukongim -n 100 --no-pager

curl --fail http://127.0.0.1:5001/readyz

进程收到 SIGTERM 后会按配置的集群停止预算执行优雅停止，服务单元给出 30 秒的外部上限。若 /healthz 成功而 /readyz 返回 503，不要把节点加入负载均衡；先检查返回的 reason 和服务日志。

同时确认持久化挂载、目录所有者和从目标客户端网络可达的外部地址，并在服务重启后再次检查 /readyz。

包生命周期

安装不创建活动配置，也不启用或启动服务。
升级替换包文件，但不自动重启正在运行的节点；先验证兼容性和配置，再在计划窗口中显式重启。
卸载会停止并禁用服务，但保留配置、数据、日志和服务账号。
服务进程在创建运行时前执行同一套配置校验；配置错误以 78 退出且不会自动重启。单元只允许写入包管理的状态、日志和运行时目录。

升级前先在非生产环境验证目标提交、制品、配置、备份和恢复路径。只有目标版本明确声明支持与当前版本混跑时，才能逐节点滚动升级；否则使用全体维护窗口。完整边界见升级与迁移。

从源码安装

公共软件源启用前，也可以直接构建二进制：

GOWORK=off go build -trimpath -o ./bin/wukongim ./cmd/wukongim
sha256sum ./bin/wukongim

源码部署仍应复用仓库中的 packaging/systemd/wukongim.service、sysusers/tmpfiles 定义和安全初始化命令，不要从移动分支在每台生产节点上分别构建，也不要把根目录中的开发示例配置直接复制成活动生产配置。

多节点配置继续阅读多节点集群。