工具执行手册

本页是运维现场的执行步骤，从收到交付包开始。 配置怎么定、包怎么打，属于交付准备阶段，不在本页范围内。 仅需了解方法论的读者阅读基本概念即可。

执行由两个工具接力完成：先造数，再压测。 两者都以自包含压缩包交付，在无开发环境、无外网的客户内网中解压即可运行。

图中位置表示在哪台机器上运行，配色表示属于哪个工具： 橙色为造数工具，绿色为压测工具，灰色为被测系统本身（不是性能测试的执行方）。 虚线框表示该步骤可选。

三个步骤分处两台机器，位置不能互换：

步骤	运行位置	原因
① 造数	ONES 应用服务器	需直连数据库批量写入，走 kubectl exec 进入服务容器执行
② 发压	压测机	独立机器，避免压测进程与被测服务争抢 CPU，否则测的不是系统真实表现
③ 采集服务端资源 （可选）	ONES 应用服务器	脚本本身是压测工具链的产物，但必须在被压节点本地执行，原因见下

③ 画成虚线框，因为它是可选的

服务端 CPU / 内存有两种取法：用交付包里的 COLLECT.sh 采， 或从已开启的 ONES 可观测性系统读。取其一即可。

两者都没有时服务端资源数据缺失，「CPU 使用率 ≤ 70%」这类验收线无法判定， soak 也只能得出「客户端观测没变慢」，证明不了没有内存泄漏。

具体操作见三、压测。

一、前置条件

项	要求
目标环境	已完成部署并通过环境检测
环境规格	满足部署配置要求，且按目标数据量级留足余量
压测机位置	应与被测环境同机房。经由公网时测得的主要是网络耗时而非服务端能力，附件上传下载类链路尤其明显
账号	具备目标团队管理权限的账号
交付包	造数包与压测包各一个，由交付工程师按该客户打好。每个包都附 SHA-256 校验文件，两个文件都要收到

收到交付包后先验

sha256sum -c <包名>.tar.gz.sha256      # 校验完整性
tar xzf <包名>.tar.gz && cd <解压目录>

uname -sm          # 目标机架构
bin/k6 version     # 包里的 k6 能否在这台机器上跑（仅压测包）

架构不匹配是最常见的现场问题

包里的 k6 按目标机架构预置（x86 或 ARM），开发机上无法验证跨架构的二进制， 必须在目标机上实跑。不匹配时退回交付工程师按正确架构重新打包。

数据量级越高，对内存的要求越高

写入百万级数据时，率先成为瓶颈的通常是搜索索引层（TiKV）的内存，而非数据库。 容器内存上限不足将触发 OOMKilled，进而导致同步服务反复重启、聚合视图降级报错。

实测链路：150 万工作项重建索引 → TiKV 超出 6Gi 内存上限被 OOM 重启 → 同步服务进入崩溃循环 → 聚合与分组视图降级报错。

该层内存与数据库同属「目标环境需满足部署配置要求」的范畴， 应在造数前确认，避免写入过程中才发现。

二、造数

目的：使测试环境的数据量级接近客户真实环境。 省略此步则后续性能数据不成立——空环境的查询无需扫描，与真实场景不具可比性。

数据规格与规划量级

下表为单个团队内已验证的推荐规模。超出该范围的需求需单独评估： 更大量级会先触及环境自身的资源上限（见上述内存警告）。

数据域	实体	规划量级
账号	成员	6,000（可上探万级）
	部门	~500，树深 ≤ 4
	用户组	数个~数十个，单组 ≤ 1,000 成员
知识库	页面组	150 组（单组可达 ~8 万页）
	页面	150 万页，树深 ≤ 5
项目	项目	100 个
	工作项	150 万条
	评论 / 工时 / 关注人	每工作项平均 3 / 2 / 3
测试	用例库 / 用例 / 测试计划	按需配置

数据分布贴近真实场景（含大小不一的实体），按团队维度生成，可精确清理且不影响既有数据。

执行顺序

账号 → 知识库 → 测试 → 项目，顺序不可调整。

账号必须先生成且不可跳过：后三类数据均需引用真实成员—— 工作项的负责人、页面的作者、用例的执行人均从已授权成员中选取， 无成员则无法生成。后三类按配置生成，未配置则跳过。

执行：解压交付包后两步

交付包为自包含 tar，客户内网无需 Go、git 或编译环境。解压后目录里已按该客户填好参数， 两个入口脚本的路径也已写死，无需再传参数文件。

tar xzf <客户>-datagen-<架构>.tar.gz
cd <解压目录>

./PREVIEW.sh                        # 第一步：预览将写入多少数据，不连接环境
TEAM=<8 位 team_uuid> ./RUN.sh      # 第二步：执行写入

预览阶段不应省略

最常见的参数失误是将「每个项目的工作项数」误作「工作项总数」， 两者相差项目个数的倍数。

预览可立即发现该类问题；跳过则需在写入数小时后才发现量级偏差， 且必须先清理数据再重新执行。

TEAM 不传则取库里第一个 team。中断后重跑加 RESUME=1，从断点续，不会重复写入：

RESUME=1 ./RUN.sh

预览这一步不应省略

最常见的参数失误是将「每个项目的工作项数」误作「工作项总数」，两者相差项目个数的倍数。

预览可立即发现该类问题；跳过则需在写入数小时后才发现量级偏差，且必须先清理数据再重新执行。 如果预览出的量级与约定不符，不要自行改参数，退回交付工程师重新打包—— 参数在打包时已固化，现场改容易改漏。

造完之后：需要运维手动重建索引

造数工具默认会关闭 binlog 同步（scripts/*/run.sh 默认 FAST_UNSAFE=1， 造数期间执行 SET GLOBAL sync_binlog=0，退出时恢复），目的是把写入速度提升约一倍。

代价是：搜索索引的同步服务依赖 binlog 捕获数据变更，binlog 关闭期间这条链路不生效， 造出来的数据不会进入搜索索引。

因此造数完成后，需要运维同事手动重建索引，否则：

• 搜索类链路查不到数据；
• 聚合与分组视图（项目分组、按状态聚合的计数、带状态分类的筛选）可能报错。

索引没重建就开压，搜索类链路的结论不成立

场景列表里的 project-search-workitem、wiki-search 这类链路直接查搜索索引。索引里没有数据时，测出来的是「空索引上的查询」， 比真实情况快得多，且与客户环境完全不可比。

开压前先确认索引条数与写入条数一致。 核对方法见索引时长。

例外：显式关闭提速时索引会自动同步

若以 FAST_UNSAFE=0 执行造数，binlog 保持开启，搜索索引会由同步服务自动追平， 无需重建——实测 10,000 条在写入完成后 36.6 秒全量可被检索，同步速率约 280 条/秒。

代价是造数耗时约翻倍。数据量大时通常仍选择默认提速 + 事后重建索引。 详见索引时长。

三、压测

压测包是自包含 tar，客户目录、负载模型、k6 二进制、现场脚本都已固化在包内。 校验与解压见前置条件。

1. 配置目标环境与账号

make env

依次询问环境地址、账号与密码，随后实际登录目标环境，拉取可选的团队、项目与知识库供选择， 菜单会标注每个项目的工作项数与每个知识库的页面数。

做成选择而非手工填写，是因为这些值原需从浏览器地址栏抄录 UUID， 抄错一位不会报错，只会静默压测到别的对象上。

不应选择数据量过小的项目

仅含少量数据的项目响应必然很快，该数据不具备参考价值，无法作为交付依据。

2. 冒烟验证

以 1 个 VU 执行数次，确认认证、请求路径与测试数据均正确。该步骤不采集性能结论。

make smoke CUSTOMER=<客户> INSECURE=1

INSECURE=1 跳过 HTTPS 证书校验，仅用于自签证书的测试环境，不得用于生产。

3. 执行

包里的 RUN-PLAN.sh 按该客户约定的模式、顺序与间隔跑完整轮。

放进 screen 或 tmux 里跑，不要直接在 SSH 会话中执行

./RUN-PLAN.sh

跑哪几种模式由客户配置决定（共七种：smoke / baseline / load / soak / spike / stress / throughput），各自的适用场景见压测模式。

轮次之间的间隔不要手工缩短

上一轮的负载会在系统里留余温（缓存、连接池、GC 状态）， 紧接着跑下一轮测到的不是该轮的真实表现。RUN-PLAN.sh 已按此内置间隔。

4. 采集服务端资源（可选）

k6 只看得见 HTTP 响应，采不到服务端的 CPU 与内存。缺这份数据时， 「CPU 使用率 ≤ 70%」这类验收线无法判定，soak 也只能得出「客户端观测没变慢」， 证明不了没有内存泄漏。

两种取法，二选一：

取法	适用
环境已开启 ONES 可观测性系统	压测后直接从中读取，本节可跳过。要求 ONES ≥ 6.5.0 或 6.1 LTS ≥ 6.1.94，底座 K3s
用交付包里的 COLLECT.sh	环境未开启可观测性系统时，按下述步骤采集

执行位置

在被压的 ONES 应用服务器上运行，不能从压测机远程执行。 把包里的 COLLECT.sh 拷到该服务器上。

远程执行会漏掉短时突增

实测同一组容器：从压测机远程发起每轮约 40 秒，在被压节点本地只需 3 秒， 差一个数量级。spike 这类十几秒的突增，40 秒采样一轮根本看不到。

时机

采集要包住整个压测过程——在第 3 步之前起、之后停。

时机	命令
压测前（配置阶段即可做）	./COLLECT.sh probe
压测开始前 1 分钟	./COLLECT.sh start
压测进行中（按需查看）	./COLLECT.sh status
压测结束后	./COLLECT.sh stop

probe 用于提前探权限，缺什么会当场说清；报权限不足时， 包里的 docs/server-metrics-rbac.yaml 是所需的最小权限，交给客户集群管理员应用即可。

采集范围与采样间隔在打包时已固化，现场不传参数。

回传

stop 会打印要回传哪两个文件。把 server-metrics.csv 与 server-metrics.meta.json 放进压测机的报告目录，再生成解读报告——两侧数据在同一时间轴上对齐后才能一起判读。

四、交付产物

每轮执行生成一个独立目录，可整体打包交付客户， 其中同时包含供技术人员使用的原始数据与面向客户的中文解读报告。

文件	内容
report.html	完整图表报告，自包含、可离线打开
report-guide.html	中文解读报告，共八章，不熟悉 k6 亦可读懂
summary.txt	汇总表纯文本，可直接引用于邮件
metrics-breakdown.json	分接口与分链路明细，供二次分析
server-metrics.csv	服务端 CPU / 内存采样原始数据
timeline.json	时间锚点，用于与客户监控图对齐
summary.json	聚合指标全量
execution.log	运行日志与末尾汇总表
profile.yaml / customer-config.yaml	本轮实际生效的配置副本，供归档

中文解读报告共八章，从阈值判定、时间线、分阶段与服务端资源， 到重点慢接口、本轮问题与建议的排查复测顺序。

报告目录自包含，可直接拷贝

常见做法是在服务器上执行压测，再将整个报告目录拷回本地生成解读报告。 目录中保存了本轮实际使用的配置副本，因此本地无需该客户的配置即可还原正确的时间线。

与客户监控图对齐时间轴使用 timeline.json

单轮压测存在三个不同的起始时刻：命令启动时刻、压测引擎启动时刻， 以及实际开始加压的时刻（此前需完成登录等准备工作，最长可达 300 秒）。

统计窗口的零点为第三个时刻。 直接使用 timeline.json 中的时间圈定 客户 Grafana 的查询范围即可对齐，无需运行本工具链的任何组件。

五、相关问题

问题	参考
数据写入后多久可被检索	索引时长
客户给出的并发数如何换算	并发公式
环境自身异常（服务未启动、数据库故障等）	故障排查