wkcli

使用一个运维工具完成在线操作、压测、离线数据库传输与 v2 到 v3 迁移。

wkcli 是 WuKongIM 的统一运维工具。在线操作通过 HTTP 和 WKProto 入口执行，db 和 migrate 处理离线数据。从 v3.0.0-beta.12 起，官方 Linux/macOS 归档和 Linux 原生安装包均包含同一版本的 wkcli 与 wukongim。

安装与版本核对

Linux amd64 按 Linux 部署通过 APT 或 DNF 安装 wukongim 软件包，即可同时获得 wkcli。Linux arm64 或 macOS 从 GitHub Releases下载对应系统与架构的归档，按发布的校验文件核对摘要，再解压两个程序。当前文档版本为 v3.0.0-beta.21。将解压目录加入 PATH，或在该目录使用 ./wkcli 和 ./wukongim。

wukongim version --output json
wkcli version --output json
wkcli bench --help
wkcli db --help
wkcli migrate --help

配套发布的两个程序应返回相同的 version、commit 和 build_source。以上命令无需启动服务，也不会执行压测或迁移。下文默认 wkcli 已在 PATH 中；源码构建方式见工具总览。

命令边界

命令	作用	风险类别
`bench`	分布式负载、worker、容量测试与报告	产生真实流量
`db`	离线查询、REPL、导入、导出与比较	import 写入目标存储
`migrate`	原版 v2 到 v3 迁移	创建全新离线 v3 数据
`context`	保存和选择一组 WuKongIM HTTP API 地址	只写本机用户配置目录
`top`	读取并聚合一个或多个节点的 `/top/v1/snapshot`	在线只读
`node ls` / `node diagnose`	读取动态节点与有界根因证据	Manager 只读
`node activate` / `node onboarding` / `node scale-in`	推进动态节点生命周期	Manager 受控写入
`bench send`	进行轻量 SEND/SENDACK 检查	产生真实连接与消息
`sim`	准备测试元数据并持续产生真实群消息流量	受控模拟环境专用

wkcli node 不启动或停止服务进程，也不直接写 Controller 或 Slot 状态。Manager 的权限、审计和安全门槛仍然生效。

旧调用 wkbench …、wkdb …、wkmigrate … 分别改为 wkcli bench …、wkcli db …、wkcli migrate …。旧独立入口已移除；各命令的参数、输出格式和退出码约定保持不变。数据库全局参数仍须放在具体操作之前。

配置命名上下文

wkcli context add dev \
  --server http://127.0.0.1:5001 \
  --server http://127.0.0.1:5002 \
  --description "development cluster" \
  --select

wkcli context ls
wkcli context show
wkcli context current

--server 可以重复或使用逗号分隔，地址必须是绝对 http:// 或 https:// API URL。上下文保存的是目标地址，不会把“选择了 production”变成操作审批；执行前仍要核对集群身份和凭据范围。

使用 Top

wkcli top --context dev --once
wkcli top --context dev --once --json
wkcli top --context dev --interval 2s --max-refresh 5
wkcli top --context dev --alerts

Top 读取节点本地有界历史，不依赖 Prometheus。默认持续刷新，脚本和事件证据应使用 --once 或 --max-refresh 限定时间。聚合结果仍应与 /readyz、Manager 和 Prometheus 交叉验证。

读取动态节点证据

wkcli node ls --context dev
wkcli node diagnose 4 --context dev
wkcli node diagnose 4 --context dev --json
wkcli node scale-in status 4 --context dev

保留输出中的健康新鲜度、控制修订、blocked_reasons、safe_to_remove、网关排空计数以及有界任务、审计和 Slot 证据。缺失信息保持未知，不要用空值推断健康。

节点写操作

wkcli node activate 4 --context dev
wkcli node onboarding start 4 --context dev --max-slot-moves 1
wkcli node scale-in start 4 --context dev
wkcli node scale-in drain 4 --context dev --draining=true
wkcli node scale-in remove 4 --context dev

这些命令必须放在明确的扩容与缩容流程中。动态节点加入后不会自动获得 Slot 副本或 Leader；Controller voter 变化也是单独的显式决策。缩容删除必须等待权威状态给出 safe_to_remove=true，命令行诊断建议不能替代这个门槛。

轻量发送检查

wkcli bench send \
  --gateway 127.0.0.1:5100 \
  --clients 8 \
  --msgs 1000 \
  --channels 10 \
  --channel-prefix check-g \
  --channel-type group \
  --size 128B

bench send 用于快速检查 WKProto SEND 吞吐与 SENDACK 延迟，不替代完整 wkcli bench 场景。它会创建真实会话和消息；先限制客户端、消息、频道和运行时间，并使用专用测试身份与频道。

长期模拟

sim 通过 /bench/v1/* 准备群元数据，通过真实 WKProto 网关维持用户在线并发送 SEND -> SENDACK 流量。目标必须显式启用 Benchmark API，并发布可访问的网关地址。

wkcli sim \
  --server http://127.0.0.1:5001 \
  --users 100 \
  --groups 50 \
  --group-members 10 \
  --rate 0.25/s \
  --max-runtime 30s

--rate 是每个群的发送率，总提供速率随群数增加。仅在隔离的开发或压测集群运行，结束后关闭 Benchmark API 并清理生成数据。需要完整验证、容量搜索和报告时使用 wkcli bench。

安全停止

目标身份、Manager 权限或权威状态不清楚时不要执行节点写命令。
写请求超时后先读取任务状态，不要盲目重复。
Top、发送检查和模拟达到时间/流量预算时立即停止。
退出后确认没有遗留模拟器、临时上下文、开放的 Benchmark API 或未完成节点任务。

wkcli

本页内容