wkcli bench

wkcli bench 是 WuKongIM 的黑盒基准驱动器。它通过公开 HTTP、Benchmark HTTP 和 WKProto 网关与运行中的集群交互，不导入服务端内部包，也不绕过集群语义。单节点目标仍然是单节点集群。

完整工作流通常需要目标开放：

• /healthz 与 /readyz；
• /bench/v1/capabilities、/bench/v1/capacity-target 和 /bench/v1/snapshot；
• Benchmark 用户、频道和订阅者准备接口；
• 从运行机可访问的 WKProto 网关发布地址。

在受控环境显式启用 Benchmark API：

[bench]
api_enable = true

/bench/v1/* 不是公开业务集成 API，不得暴露到公共网络。capacity message-event 是例外：它使用 WuKongIM 的 /channel、/message/send、/message/event 和 /metrics，不需要 Benchmark API，但仍会写入生成的频道和消息，因此也必须使用受控目标。

先安装 wkcli。以下命令使用已安装的程序，无需源码仓库或 Go。在工作目录下载配置：

mkdir -p ./tmp/docs-wkbench
for file in target workers scenario; do
  curl --fail --location "https://docs.githubim.com/examples/wkbench/${file}.yaml" \
    --output "./tmp/docs-wkbench/${file}.yaml"
done

在 target.yaml 中填写隔离测试集群的 API、Gateway 和指标地址。示例默认测试节点、Worker 和协调器都在同一主机；分开部署时，每个地址都必须能从对应进程访问。

在 Worker 和协调器两个终端设置相同的控制 Token；协调器的 API Token 必须与测试节点的 bench.api_token 相同。节点还需开启 bench.api_enable 和 observability.metrics_enable。不要在这些命令中使用生产凭据。

终端 A，启动 Worker：

export WK_BENCH_WORKER_TOKEN='replace-with-test-worker-secret'
wkcli bench worker \
  --listen 127.0.0.1:19090 \
  --work-dir ./tmp/docs-wkbench/worker

终端 B，配置本次运行。每次更换 WK_BENCH_RUN_ID，不要复用已有运行标识：

export WK_BENCH_WORKER_TOKEN='replace-with-test-worker-secret'
export WK_BENCH_API_TOKEN='replace-with-test-api-secret'
export WK_BENCH_RUN_ID="docs-smoke-$(date -u +%Y%m%dT%H%M%SZ)"
wkcli bench validate \
  --target ./tmp/docs-wkbench/target.yaml \
  --workers ./tmp/docs-wkbench/workers.yaml \
  --scenario ./tmp/docs-wkbench/scenario.yaml

validate 不访问网络。成功后执行预检；预检失败就修正目标、Token 或地址，不继续运行负载：

wkcli bench doctor \
  --target ./tmp/docs-wkbench/target.yaml \
  --workers ./tmp/docs-wkbench/workers.yaml \
  --scenario ./tmp/docs-wkbench/scenario.yaml

预检通过，再执行有界负载：

wkcli bench run \
  --target ./tmp/docs-wkbench/target.yaml \
  --workers ./tmp/docs-wkbench/workers.yaml \
  --scenario ./tmp/docs-wkbench/scenario.yaml

示例将任意连接、发送确认、接收校验或 Worker 错误视为失败，也会把超过 P99 阈值判为失败。结束后检查命令退出码和报告，再用 Ctrl+C 停止终端 A 的 Worker。cleanup.strategy=keep_data 会保留生成的用户、群和消息；只在隔离测试环境中按保留计划处理这些数据，不要删除集群数据目录来清理一次运行。

• 使用接近真实的在线用户数、频道基数、频道类型、群成员数、消息大小、收发确认与重连行为；
• 将连接爬升、预热、测量和冷却分开，预热计数不能混入测量窗口；
• 分开测试高频道基数、单热点频道、消息事件和连接压力，不要用一个 QPS 数字概括所有瓶颈；
• 为 100,000 成员群组、高消息率、许多频道和大量在线用户显式评估 CPU、内存、分配、锁竞争、有界队列、背压和扇出；
• 固定随机种子或生成规则，并保留场景 YAML、工具/服务版本、硬件、拓扑和配置。

wkcli bench capacity send \
  --api http://127.0.0.1:5001 \
  --profile mixed \
  --start-qps 100 \
  --max-qps 5000 \
  --stable-p99 200ms \
  --duration 30s \
  --group-members 10

capacity send 发现网关、启动临时本地 worker，并在给定门槛内搜索稳定接入速率；它不会启动/停止集群、构建镜像或清理数据。热点频道、Channel runtime 基数和消息事件需要各自的 capacity 子命令。

“最大稳定”只对本次版本、硬件、拓扑、场景和门槛成立。实际规划必须低于首次失败点并保留资源余量；低于提供 QPS 的实际 QPS、尾延迟、错误率、队列、磁盘和恢复时间都属于结果，不能只保留最高数字。

报告至少应保留：

• Git 修订、二进制摘要、配置与集群拓扑；
• 目标/worker/scenario 文件和完整命令；
• prepare、connect、warmup、run、cooldown 各阶段时间与状态；
• offered/actual QPS、吞吐、p50/p95/p99、操作错误分类与超时；
• 每节点 CPU、内存、Goroutine、FD、网络、磁盘 IO、队列和副本/Leader 偏斜；
• 运行前后 /readyz、积压恢复时间、生成数据位置和清理结果。

任一硬门槛、目标就绪、磁盘余量、错误率、尾延迟或 worker 状态失败时停止，不要为了得到更高数字提高上限。诊断过程见诊断能力。

在 run.report_dir 指定的报告目录中，先读 summary.md 和 report.json，再用保存的配置、plan.json 与 metrics/ 解释结果。比较两个结果前，另行记录服务端版本或摘要、SDK/工具版本、每节点 CPU/内存/磁盘类型、节点数、副本数和网络条件；工具报告不会自动代替完整的硬件清单。

下面是假设数据的阅读示例，不是实测报告：背景为相同服务端与工具版本、一个 4 vCPU / 8 GiB / SSD 单节点集群、默认 256 Hash Slots，运行上面的冒烟场景。

JSON 中 Go time.Duration 字段以纳秒表示；例如 180 ms 为 180000000。阅读延迟时优先使用 summary.md 的格式化值。只有足量测量窗口、期望吞吐、错误与尾延迟、接收范围、队列恢复和资源余量共同满足目标，才进入更高一级负载验证。