tests/stress/README.md

PDF 导出压力测试工具

用于测量 PDF 导出后端 (/api/generate_pdf) 的并发承载能力（同时能有多少用户导出 PDF）。

文件

文件	说明
payload-generator.js	生成确定性的仿真 PDF HTML 负载（文本 + Shiki 代码块 + base64 图片）
run-stress-test.js	主压力测试脚本：按并发梯度打请求，统计成功率/延迟/吞吐
monitor-docker.js	并行监控 docker 容器 CPU/内存，与压力测试结果关联
verify-pdf-output.js	生成一份 PDF 保存到磁盘，验证输出为真实 PDF（%PDF-1.x 魔数）
test-widget-batch.js	批量 widget 渲染验证（模拟 PDF/DOCX 导出的 render_charts 调用）
results/	测试报告 JSON + 监控 JSON

用法

# 基线/优化后对比测试（medium 负载）
node tests/stress/run-stress-test.js \
  --base http://localhost:17861 \
  --concurrency 1,2,4,6,8 \
  --total 8 \
  --profile medium \
  --settle-ms 3000 \
  --tag opt-pool4

# 并行监控 docker 资源（在另一个终端运行）
node tests/stress/monitor-docker.js \
  --containers pdf-test,pdf-prod \
  --interval 2000 \
  --duration 240000 \
  --out tests/stress/results/monitor-x.json

# 校验 PDF 输出质量
node tests/stress/verify-pdf-output.js

# 验证批量 widget 渲染
node tests/stress/test-widget-batch.js

参数

参数	默认值	说明
--base	http://localhost:17861	后端地址（17861=测试容器，7860=生产容器）
--concurrency	1,2,4,6,8	并发梯度（逗号分隔，每个梯度跑 --total 个请求）
--total	20	每个并发梯度下总请求数
--profile	medium	负载规格：small(62KB) / medium(375KB+3图) / large(1.24MB+10图)
--settle-ms	10000	每个梯度之间的冷却时间，让内存回落
--tag	``	报告文件名后缀，用于区分基线/优化
--timeout-ms	180000	单请求超时

报告解读

• throughputPerMin 基于墙钟时间（该梯度内实际完成的请求数/分钟），反映系统真实吞吐。
• latencyMs 是每个请求从发起到收到响应的耗时（含排队等待）。
• 失败分类：500=服务端错误，conn/...=连接层错误。

重要提示

1. 本机 docker 不能完全模拟 Hugging Face：HF 免费版 = 2 vCPU / 16GB；本机 docker 为 16 核。本机测出的并发上限是 HF 的上界，HF 上需按 PDF_POOL_SIZE=2 部署。
2. 测试前确认 pdf-test 容器已用最新代码重建。
3. 机器上还跑着其他系统（如 xianzhi-*），测试不要设置过大的并发，避免干扰。