Linux 部署

当前 Preview 软件源发布 v3.0.0-beta.21，仅支持 amd64/x86_64。已验证 Ubuntu 24.04、Debian 13、Rocky Linux 9 和 AlmaLinux 9；RHEL 9 可使用同一 EL9 软件源。

1. 安装

Debian / Ubuntu

curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo apt update
sudo apt install -y wukongim

RHEL / Rocky / AlmaLinux 9

curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo dnf -y --disablerepo='*' --enablerepo=wukongim-preview makecache --refresh
sudo dnf install -y wukongim

同一软件包会安装服务端和统一运维工具；两者的 version、commit、build_source 应一致。命令用法见 wkcli。若找不到 wkcli 或版本不一致，先用 command -v wkcli 排查 PATH 中的旧程序，再更新为配套的软件包。

wukongim version --output json
wkcli version --output json

软件包会创建服务账号、systemd 服务以及 /etc/wukongim、/var/lib/wukongim 和 /var/log/wukongim，但不会生成配置或启动服务。

2. 初始化配置

sudo wukongim init
# 自动化环境：
sudo wukongim init \
  --admin-password-stdin < /secure/path/manager-password

保存只显示一次的管理员密码。旧自动化也可继续使用 wukongim config init --config /etc/wukongim/wukongim.toml。然后校验配置：

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

默认只监听回环地址。对外开放服务前，请先配置防火墙、TLS 和入口策略。

初始化的 WebSocket 监听地址为 127.0.0.1:5200，/route 会保留该具体地址。按快速开始转发 5001、5200 和 5301 后即可从自己电脑体验 Demo，无需配置 api.external_ws_addr。如果改为通配监听，默认公网路由可按请求主机名补全；非默认外部端口、独立域名及 TLS 代理仍需显式对外地址，见 Docker 部署中的地址规则。

3. 启动并验证

sudo systemctl enable --now wukongim
curl --fail http://127.0.0.1:5001/readyz

/readyz 成功后再接入流量。启动失败时查看日志：

sudo journalctl -u wukongim -n 100 --no-pager

后台管理默认地址是 http://127.0.0.1:5301，使用 admin 和初始化时保存的密码登录。保持 auth_on = true；远程访问时在自己的电脑执行下面的命令，并保持终端运行，然后打开同一个浏览器地址：

ssh -N -L 127.0.0.1:5301:127.0.0.1:5301 <user>@<server-ip>

无需在公网放行 5301。多人运维使用管理内网或 VPN，并通过 HTTPS 代理访问；配置见 Manager 管理后台。

多节点部署继续阅读多节点集群，升级前阅读升级与迁移。