Spaces:

XWX-AI
/

api-server

Running

File size: 9,540 Bytes

24a2ddf

# PDF 导出并发压力测试与性能优化报告

**日期**: 2026-08-03
**测试环境**: 本机 Docker（`pdf-test` 容器，16 核 / 32GB，Docker 可见 ~15.5GB）
**对比目标**: Hugging Face 免费版（CPU Basic = 2 vCPU / 16GB）
**工具**: `backend-service/tests/stress/`（README 见 `tests/stress/README.md`）

---

## 一、结论摘要

| 指标 | 优化前 | 优化后 | 提升 |
|------|--------|--------|------|
| 单请求延迟 (medium, 并发1) | 4906ms | **1572ms** | **3.1x** |
| 单请求延迟 (small, 并发1) | 3380ms | **926ms** | **3.7x** |
| 吞吐 (medium, 并发1) | ~12/min | **38/min** | **3.2x** |
| 吞吐峰值 (medium) | ~10/min（并发4） | **83/min**（并发8） | **8x** |
| 并发承载（无失败） | 6 并发即延迟飙升至 8.9s | **8 并发全部成功，延迟 3.6s** | 稳定 |
| 内存峰值 | 每请求新建浏览器（泄漏僵尸进程） | **4 个常驻浏览器，峰值 0.91GiB** | 受控 |

**核心答案**: 优化后本机 docker 上 **4 个用户可同时导出 PDF**（=浏览器池大小），更多并发用户自动排队，不会雪崩。Hugging Face 免费版（2 vCPU）建议 `PDF_POOL_SIZE=2`，即 **2 个用户同时导出**，超出排队。

---

## 二、根因分析（为什么原来并发差）

### 2.1 每个 PDF 请求启动一个全新 Chromium（最大瓶颈）

`server.js` 原代码在 `/api/generate_pdf` 中**每次请求都 `puppeteer.launch()`**：

- 启动一个 Chromium 耗时 ~0.3–1.5s、占用 ~200–300MB
- 并发 N 个请求 = N 个 Chromium 进程同时竞争 CPU/内存
- 请求结束 `browser.close()` 还会在容器里留下**僵尸进程**（`chrome_crashpad`/`chromium <defunct>` 累积）
- 实测 6 并发时延迟从 4.9s 飙到 8.9s，吞吐反而下降

> 行业共识（见参考资料）：`page.pdf()` 是 CPU 密集操作，**并发数≈CPU 核数**，永远不要每请求启动浏览器。

### 2.2 setContent 的 networkidle0 等待浪费 ~2s

用临时实验程序（`temp/setcontent-wait-experiment.js`，在容器内实测）：

| waitUntil 策略 | 耗时 |
|----------------|------|
| `setContent(load)` | **3–7ms** |
| `setContent(load + networkidle0)` | **~1970ms** |
| `setContent(load) + waitForNetworkIdle(500)` | ~505ms |
| 原代码两者都做 | **~2470ms** |

原代码既在 `setContent` 里 `networkidle0`，又在后面 `waitForNetworkIdle(500)`，对一个无外链资源的纯本地 HTML 白白等待 ~2.5s。

### 2.3 Widget 渲染每个 widget 启动一个浏览器

`renderWidgetPuppeteer()` / `_renderFullHtml()` 原代码**每个 widget 都 launch 一个新 Chromium**。一次导出 15 个 widget = 15 次浏览器启动。`WidgetRenderer._widgetBrowser` 单例存在但从未被使用（死代码）。

### 2.4 事件循环被同步操作阻塞

- 大 HTML 临时文件的 `fs.writeFileSync` / `fs.unlinkSync` 同步阻塞主线程
- 优化后改为 `fs.promises` 异步版本

### 2.5 响应被错误 JSON 序列化（我引入后立即修复）

`page.pdf()` 在 Puppeteer 24 返回 **`Uint8Array` 而非 Buffer**。`res.send(u8array)` 时 Express 不识别为二进制，会 `JSON.stringify` 成 `{"0":37,"1":80,...}`（约 13 倍体积）。原代码 `Buffer.from(pdfBuffer)` 正是为此。**任何修改都不能去掉这一步**。

---

## 三、实施的优化

### 3.1 新增 `browser-pool.js` — PDF 浏览器池

- 常驻 `PDF_POOL_SIZE` 个 Chromium（默认 4，env 可配）
- 每次请求 `acquire()` 一个浏览器 → 创建 page → 渲染 → 关闭 page → `release()` 归还
- 浏览器在 N 个任务后回收重建（`PDF_RECYCLE_AFTER=30`），防止 Chromium 长期运行内存膨胀
- 浏览器崩溃自动重建；池满时请求排队（`PDF_ACQUIRE_TIMEOUT_MS=120s`）
- 池大小 = 最大并发 PDF 数

### 3.2 Widget 渲染复用单例浏览器

`renderWidgetPuppeteer()` 与 `_renderFullHtml()` 改为使用 `getWidgetBrowser()` 共享浏览器（每个 widget 独立 page，渲染后只关 page 不关浏览器），并加了竞态保护与崩溃自动重建。

### 3.3 等待策略优化

- `setContent` / `goto`：`networkidle0` → `'load'`（每个请求省 ~2s）
- `waitForNetworkIdle`：idleTime 500 → 300（保留作为安全网）
- Widget 渲染同样处理

### 3.4 其他

- 大文件读写改异步 `fs.promises`
- 恢复 `res.send(Buffer.from(pdfBuffer))`（关键，见 2.5）
- 补上 `page.on('dialog')` 自动关弹窗（解决方案备忘录 24 的兜底，防止 XSS/异常 HTML 卡死）
- 配置全部 env 化：`PDF_POOL_SIZE` / `PDF_RECYCLE_AFTER` / `WIDGET_MAX_CONCURRENT`（docker-compose.yml 已配置：生产 2，测试 4）

---

## 四、压力测试数据

### 4.1 medium 负载（375KB 文本 + 3 张 base64 图）

| 并发 | 优化前 avg | 优化后 avg | 优化后 p95 | 优化后吞吐/min | 成功率 |
|------|-----------|-----------|-----------|---------------|--------|
| 1 | 4906ms | **1572ms** | 1843ms | 38 | 100% |
| 2 | 5283ms | **1882ms** | 2131ms | 62 | 100% |
| 4 | 5918ms | **2433ms** | 3752ms | 67 | 100% |
| 6 | 8919ms | **2758ms** | 4163ms | 81 | 100% |
| 8 | 未测 | **3569ms** | 5763ms | 83 | 100% |

### 4.2 small 负载（62KB，纯文本）

| 并发 | 优化前 avg | 优化后 avg | 优化后吞吐/min |
|------|-----------|-----------|---------------|
| 1 | 3380ms | **926ms** | 65 |
| 4 | — | **1513ms** | 117 |
| 8 | — | **2521ms** | 118 |

### 4.3 large 负载（1.24MB + 10 图，走临时文件路径）

| 并发 | 优化后 avg | 优化后吞吐/min | 成功率 |
|------|-----------|---------------|--------|
| 1 | 4988ms | 12 | 100% |
| 4 | 7748ms | 20 | 100% |

### 4.4 资源监控（optimized, medium, 4 浏览器常驻）

- CPU 峰值 ~392%（4 个浏览器同时渲染 ≈ 4 核忙）
- 内存峰值 **0.91GiB**，空闲 0.57GiB（4 个常驻浏览器 + Node）
- 相比优化前每请求新建浏览器、僵尸进程累积，资源完全受控

### 4.5 Widget 渲染

- 5 个 widget（4 chart + 1 mermaid）批量渲染：**7.03s，5/5 成功**，日志确认只启动 **1 次**浏览器（优化前每 widget 1 次）
- 单次 PDF 校验：输出为真实 PDF（`%PDF-1.4` 魔数，~113 页，1.6MB）

---

## 五、对 Hugging Face 免费版（2 vCPU）的预测

本机 16 核 docker 测出的容量是 **HF 的上界**，不能直接套用。按行业经验（每 page.pdf() 约占满 1 核）：

- **HF 建议 `PDF_POOL_SIZE=2`**（docker-compose 已配置）→ 2 个用户同时导出，超出排队
- 单请求延迟在 HF 上会比本机高（CPU 弱），medium 预计 ~3–4s
- 吞吐预计 ~20–30/min（HF 2 核，CPU 是瓶颈）
- **结论**：当前 1000 用户规模绰绰有余；若未来用户数大幅增长，HF 免费版 2 vCPU 会成为瓶颈，需升级 `CPU Upgrade`（8 vCPU/32GB，$0.03/时）或使用 GPU Space

> ⚠️ **Docker 不能完全模拟 HuggingFace 机器**：CPU 核数（16 vs 2）差异巨大，PDF 渲染是 CPU 密集任务，因此本机测试结果只能作为相对对比（优化前后提升倍数），绝对并发数在 HF 上需按 2 vCPU 重新评估。

---

## 六、验证过的兼容性（避免复杂问题重现）

对照解决方案备忘录逐项确认优化未破坏：

| 备忘录 | 关注点 | 验证 |
|--------|--------|------|
| 24 (Puppeteer 超时/XSS) | dialog 卡死 setContent | ✅ 补回 `page.on('dialog')` 自动关闭 |
| 32 (Widget 渲染性能) | CDN 本地化失败、缓存方案 | ✅ 未重蹈 `setServerInterception` 覆辙；widget 单例浏览器按备忘录原设计实现 |
| 31 (表格串行 bug) | 前端导出流程 | ✅ 后端响应格式未变 |
| 05/06/26 (PDF/图表) | Shiki 高亮、Mermaid 版本固定 | ✅ 相关逻辑未改动，实测 PDF 与 widget 输出正确 |

---

## 七、后续建议（如需进一步优化）

1. **Shiki 高亮移入 Worker 线程**：大 HTML（>1MB）大量代码块时主线程阻塞；可放入 `worker_threads`。当前 medium/small 负载下 <100ms，非瓶颈。
2. **Node.js 多进程（cluster/PM2）**：充分利用多核处理主线程工作。注意每个 worker 需独立浏览器池。
3. **外部图片加载超时优化**：非 base64 图片失败时会等 15s 兜底（备忘录 03/04 相关）。可考虑对 http 图片缩短等待或降级。
4. **widget 渲染缓存**：备忘录 32 提到 CDN 响应内存缓存可提升 28%（此前实现丢失，本次未恢复，因为 `setServerInterception` 开销曾被证明为负收益；如需恢复需重新验证）。
5. **大规模扩展**：超过单机能力后，将 PDF 服务拆分为独立可水平扩展的服务（参考 medium 文章的直接 CDP + 队列架构）。

---

## 八、参考资料（行业最佳实践）

- [Puppeteer PDF: Common Problems and How to Fix](https://blog.pdfloom.com/puppeteer-pdf-problems/) — 浏览器池模式、内存 150-300MB/实例、并发限制
- [Optimizing Puppeteer PDF generation](https://www.codepasta.com/2024/04/19/optimizing-puppeteer-pdf-generation) — 并发数≈核数，队列限流
- [Designing a High-Performance HTML-to-PDF Service](https://medium.com/@harishrawat93/designing-a-high-performance-html-to-pdf-service-for-production-1a70099e3ccb) — 浏览器/页面池 + 队列架构
- [How to Fix Puppeteer Memory Leaks](https://www.grabbit.live/blog/puppeteer-memory-leak) — 浏览器按 N 任务回收（disposable Chromium）
- Hugging Face Spaces 免费版规格：CPU Basic = **2 vCPU / 16GB**（[spaces-overview](https://huggingface.co/docs/hub/en/spaces-overview)）