From 6e416fcfd02aca7a46289cc5b59caa4d0cab4f5b Mon Sep 17 00:00:00 2001
From: richjohnrambo <richjohnrambo@gmail.com>
Date: Sun, 27 Sep 2026 00:24:28 +0800
Subject: [PATCH] docs: add machine B pressure test instructions

---
 loadtest/im-pressure/MACHINE-B.md | 149 ++++++++++++++++++++++++++++++
 loadtest/im-pressure/README.md    |   4 +-
 2 files changed, 152 insertions(+), 1 deletion(-)
 create mode 100644 loadtest/im-pressure/MACHINE-B.md

diff --git a/loadtest/im-pressure/MACHINE-B.md b/loadtest/im-pressure/MACHINE-B.md
new file mode 100644
index 0000000..de90af0
--- /dev/null
+++ b/loadtest/im-pressure/MACHINE-B.md
@@ -0,0 +1,149 @@
+# 机器 B 压测执行手册
+
+## 给机器 B 上 AI 的指令
+
+你当前操作的是 **机器 B**，代码与机器 A 完全相同。你的职责只有：核验运行文件、启动 `agent -machine b`、观察运行状态、把结果留给机器 A。不要执行 `prepare`、`coordinator` 或 `merge`，不要修改账号分片。
+
+机器 B 固定模拟 `ltb0001` 至 `ltb1000` 共 1000 个用户。测试场景和统一开始时间由机器 A 的 coordinator 下发。
+
+## 运行前向机器 A 获取
+
+开始前必须拿到以下信息：
+
+- `MACHINE_A_IP`：机器 A 的内网 IP。
+- `RUN_ID`：本轮唯一标识，例如 `p2p-20260927-01`。
+- `config.json`：两台机器使用同一份配置。
+- `manifest.json`：由机器 A 执行 `prepare` 生成，包含账号 Token 和 Topic。
+- `IM_API_KEY`、`IM_LOAD_PASSWORD`：通过安全方式提供，不写进代码或结果文件。
+- 机器 A 已启动 coordinator 的确认。
+
+同一份代码不代表运行时 manifest 会自动同步。如果本机没有最新的 `manifest.json`，必须让机器 A 传过来；机器 B 不得自行执行 `prepare`。
+
+## 第一步：进入仓库并构建
+
+把 `/absolute/path/to/im_server` 换成本机仓库绝对路径：
+
+```bash
+cd /absolute/path/to/im_server
+git rev-parse HEAD
+go build -o loadtest/im-pressure/im-pressure ./loadtest/im-pressure
+ulimit -n 100000
+```
+
+将 `git rev-parse HEAD` 的结果发给机器 A，确认两边代码版本一致。
+
+## 第二步：放置运行文件
+
+机器 A 应把文件放到：
+
+```text
+loadtest/im-pressure/config.json
+loadtest/im-pressure/manifest.json
+```
+
+检查并保护 manifest：
+
+```bash
+test -s loadtest/im-pressure/config.json
+test -s loadtest/im-pressure/manifest.json
+chmod 600 loadtest/im-pressure/manifest.json
+```
+
+## 第三步：设置环境变量并核验
+
+```bash
+export IM_API_KEY='由机器A提供'
+export IM_LOAD_PASSWORD='由机器A提供'
+export MACHINE_A_IP='机器A内网IP'
+export RUN_ID='由机器A提供的本轮run-id'
+
+./loadtest/im-pressure/im-pressure verify \
+  -config loadtest/im-pressure/config.json \
+  -manifest loadtest/im-pressure/manifest.json
+```
+
+`verify` 必须成功后才能继续。它只读核验 2000 个账号、P2P Topic 和 2000 人群，不会开始压测。
+
+## 第四步：检查机器 A 协调器
+
+```bash
+curl -fsS "http://${MACHINE_A_IP}:8090/v1/status"
+```
+
+如果连接失败，停止操作并让机器 A 检查 coordinator、内网 IP、防火墙和 `8090` 端口。不要改为本机启动 coordinator。
+
+## 第五步：启动机器 B agent
+
+```bash
+mkdir -p "loadtest/im-pressure/results/${RUN_ID}"
+
+./loadtest/im-pressure/im-pressure agent \
+  -config loadtest/im-pressure/config.json \
+  -manifest loadtest/im-pressure/manifest.json \
+  -machine b \
+  -coordinator "http://${MACHINE_A_IP}:8090" \
+  -metrics-listen :9105 \
+  -output "loadtest/im-pressure/results/${RUN_ID}/agent-b-summary.json"
+```
+
+启动后会依次发生：
+
+1. 机器 B 建立 1000 条 WebSocket 连接并订阅对应 P2P Topic 和群 Topic。
+2. agent 向机器 A coordinator 报告 READY。
+3. 如果机器 A 尚未 READY，当前命令会等待，这是正常现象。
+4. coordinator 下发 `run_id`、场景和统一 UTC 开始时间。
+5. agent 完成发送、WS 到达统计、drain 和历史持久化回查。
+6. agent 写出 summary、上报 coordinator，然后正常退出。
+
+机器 B 不需要传场景参数。`p2p`、`group` 或 `mixed` 由机器 A coordinator 决定。
+
+## 第六步：检查并回传结果
+
+```bash
+test -s "loadtest/im-pressure/results/${RUN_ID}/agent-b-summary.json"
+```
+
+将以下文件路径和运行是否成功告知机器 A：
+
+```text
+loadtest/im-pressure/results/<RUN_ID>/agent-b-summary.json
+```
+
+如果机器 A 无法直接读取机器 B 文件，由机器 A 使用 `scp` 拉取，或从机器 B 推送：
+
+```bash
+scp "loadtest/im-pressure/results/${RUN_ID}/agent-b-summary.json" \
+  user@机器A内网IP:/absolute/path/to/im_server/loadtest/im-pressure/results/${RUN_ID}/
+```
+
+## 运行中观察
+
+另开一个终端可以查看本机 agent 指标：
+
+```bash
+curl -fsS http://127.0.0.1:9105/metrics | \
+  grep -E 'im_load_agent_(ready_connections|publish|received|duplicates|out_of_order|disconnects)'
+```
+
+关键判断：
+
+- `im_load_agent_ready_connections` 应到达 `1000`。
+- `disconnects_total`、`duplicates_total`、`out_of_order_total` 期望为 `0`。
+- agent 进程退出前不要关闭终端或停止网络。
+
+## 常见问题
+
+- `coordinator connection refused`：机器 A coordinator 未启动、IP 错误或 `8090` 被拦截。
+- 一直等待开始：通常是另一台 agent 尚未达到 1000 个 READY，查看机器 A coordinator 状态。
+- 登录返回 `401`：确认本机设置了正确的 `IM_LOAD_PASSWORD`，并让机器 A 重新同步最新 manifest。
+- `listen :9105 address already in use`：换成空闲端口，例如 `-metrics-listen :9106`，并通知机器 A 修改采集地址。
+- `ready connections` 不足 1000：不要继续压测，检查 WS 地址、文件描述符限制、Ingress 和网络连接限制。
+- `verify` 失败：停止，不要绕过；让机器 A 核对数据准备结果和本机运行文件版本。
+
+## 机器 B 禁止事项
+
+- 禁止运行 `prepare`，避免重复创建或改变测试数据。
+- 禁止运行 `coordinator`，全场只能使用机器 A 的 coordinator。
+- 禁止把参数改成 `-machine a`。
+- 禁止自行改变 `RUN_ID`、config 或 manifest。
+- 禁止提交或传播包含 Token 的 manifest。
diff --git a/loadtest/im-pressure/README.md b/loadtest/im-pressure/README.md
index 1334482..6401216 100644
--- a/loadtest/im-pressure/README.md
+++ b/loadtest/im-pressure/README.md
@@ -2,6 +2,8 @@
 
 该工具按商户 `006` 的固定模型运行：两台压测机各承载 1000 个 WebSocket 用户，共 2000 个用户、1000 对好友和一个 2000 人群。
 
+机器 B 上的 AI 或操作人请直接阅读 [MACHINE-B.md](./MACHINE-B.md)。该文件不重复讲方案，只给出机器 B 从核验到启动、观察和回传结果的完整命令。
+
 ## 两台机器的固定分工
 
 当前仓库所在机器固定作为 **机器 A**。两台机器不要交换 `-machine` 参数，否则账号分片和结果归属会混乱。
@@ -21,7 +23,7 @@
 
 ### 机器 B 最短操作清单
 
-把本 README 放到机器 B 后，机器 B 操作人只需完成以下事项：
+机器 B 的完整命令见 [MACHINE-B.md](./MACHINE-B.md)。机器 B 操作人只需完成以下事项：
 
 1. 检出与机器 A 相同的 Git 提交并构建 `im-pressure`。
 2. 接收机器 A 生成的 `config.json` 和 `manifest.json`，不要自行运行 `prepare`。