Linux 部署
按系统选择安装方式，初始化单节点集群，再检查就绪与管理入口。
用 APT 或 DNF 安装单节点集群，再通过 systemd 启动。当前 Preview：v3.0.0-beta.24 · amd64/x86_64。
Preview 是预发布通道
请先在非生产环境验证，再承载生产流量。
支持的系统与架构
软件源仅支持 amd64/x86_64。已验证 Ubuntu 24.04、Debian 13、Rocky Linux 9 和 AlmaLinux 9；RHEL 9 可使用同一 EL9 软件源。
1. 安装
选择自己的系统，展开对应命令。
Debian / Ubuntu
APT 安装命令
curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo apt update
sudo apt install -y wukongimRHEL / Rocky / AlmaLinux 9
DNF 安装命令
curl -fsSL https://packages.githubim.com/repo | sudo sh
sudo dnf -y --disablerepo='*' --enablerepo=wukongim-preview makecache --refresh
sudo dnf install -y wukongim应看到： wukongim 和 wkcli 的 version、commit、build_source 一致；此时服务尚未启动。
版本检查与安装目录
同一软件包会安装服务端和统一运维工具；两者的 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，保存只显示一次的管理员密码，再校验配置。默认只监听回环地址；对外开放前先配置防火墙、TLS 和入口策略。
应看到： /etc/wukongim/wukongim.toml 已生成，配置校验通过。
初始化、校验、自动化与 Demo 转发
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. 启动并验证
启动 systemd 服务，检查 /readyz。返回 200 且 ready: true 后才接流量；失败时查看服务日志。
启动、就绪检查与日志命令
sudo systemctl enable --now wukongim
curl --fail http://127.0.0.1:5001/readyz/readyz 成功后再接入流量。启动失败时查看日志：
sudo journalctl -u wukongim -n 100 --no-pager打开 Manager： 在自己电脑建立 SSH 隧道，再访问 127.0.0.1:5301，用 admin 和保存的密码登录。保持 auth_on = true；无需公网开放 5301。
SSH 隧道与多人管理入口
后台管理默认地址是 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 管理后台。