09. 测试策略与生产上线清单

ZIP 功能不能只用一个正常压缩包测试。它同时涉及不可信输入、流、磁盘、CPU、网络中断和异步清理；很多问题只会出现在损坏 ZIP 或失败路径中。

1. 测试分层

建议分成三层：

单元测试
  路径、大小、文件类型、清单等纯逻辑

Service 集成测试
  真正使用 yauzl/archiver 读写临时 ZIP

HTTP 集成测试
  Multer + Express Route + 下载响应

不要所有测试都经过 HTTP。路径规范化和 Entry 限制可以作为纯函数快速覆盖；只有库和流的真实行为才需要创建 ZIP。

2. 正常功能用例

至少覆盖：

• 单个入口 Markdown；
• 多个 Markdown，并按约定选择入口；
• Markdown 引用相对图片；
• 多层资源目录；
• 中文文件名和空格；
• 空目录；
• 已经压缩的 PNG/JPEG；
• 最终 ZIP 能被重新打开；
• ZIP 内 index.html 和资源路径正确；
• HTML 内容已经过预期净化。

测试不要只检查 HTTP 200，还应重新用 yauzl 打开返回 ZIP，检查内部 Entry：

expect(entryNames).toEqual(
  expect.arrayContaining([
    "index.html",
    "assets/architecture.png",
  ]),
);

这叫“验证产物”，比只看状态码可靠。

3. 恶意和异常 ZIP 用例

路径类

• ../outside.txt；
• ../../.env；
• /absolute/path.txt；
• C:\\app\\server.ts；
• \\server\\share\\file.txt；
• 混合 / 和 \；
• 超深目录；
• 超长文件名；
• Unicode 规范化后重名。

容量类

• Entry 数量超过上限；
• 单文件解压大小超过上限；
• 所有 Entry 总大小超过上限；
• 极高压缩比；
• 压缩包自身超过 Multer 上限；
• 解压过程中超过实际磁盘配额。

格式类

• 不是 ZIP 却使用 .zip 后缀；
• Central Directory 损坏；
• ZIP 被截断；
• Entry 声明大小与实际数据不一致；
• 不支持的压缩方式；
• 加密 ZIP；
• 符号链接 Entry；
• 重复文件名；
• 文件和目录同名冲突。

内容类

• 没有 Markdown；
• 出现不允许的扩展名；
• Markdown 含脚本和危险 URL；
• SVG 含脚本或外部引用；
• HTML 文件伪装为图片；
• Markdown 引用 ZIP 外部的相对路径。

4. 故障注入

单元测试中的正常假数据很难暴露资源泄漏。可以有意识地制造失败：

• yauzl 打开时报错；
• 读取到第 N 个 Entry 时报错；
• 输出 WriteStream 中途失败；
• Markdown 渲染函数抛错；
• archiver warning 或 error；
• finalize() 失败；
• 临时目录无写权限；
• 磁盘空间不足；
• 客户端上传中止；
• 客户端下载一半后断开；
• 服务触发 timeout；
• 清理目录第一次失败。

每个失败用例除了断言错误码，还应验证：

ZipFile 已关闭
流已销毁或结束
archiver 已停止
没有发送第二个响应
临时目录最终不存在
日志不包含密码、Token 或原始敏感内容

5. HTTP 集成测试示意

使用 Supertest 上传正常文件：

const response = await request(app)
  .post("/api/markdown/export")
  .attach("archive", fixturePath)
  .expect(200)
  .expect("Content-Type", /application\/zip/)
  .expect("Content-Disposition", /attachment/);

默认解析器可能不适合二进制响应，可以注册 Buffer parser：

function binaryParser(
  response: NodeJS.ReadableStream,
  callback: (error: Error | null, body?: Buffer) => void,
): void {
  const chunks: Buffer[] = [];

  response.on("data", (chunk: Buffer) => {
    chunks.push(chunk);
  });

  response.on("end", () => {
    callback(null, Buffer.concat(chunks));
  });

  response.on("error", callback);
}

测试文件应放在明确的 fixtures 目录。小型恶意 ZIP 可以在测试中使用 archiver 或专用脚本生成；不要把来源不明的真实恶意样本放进开发者常用目录并随意解压。

6. 测试资源上限本身

不要只测试“超限会报错”，还要测试边界：

maxEntries - 1  → 成功
maxEntries      → 成功（若规则是 <=）
maxEntries + 1  → 拒绝

大小、路径深度、名称长度和压缩比都应该有边界测试。还应确认计数使用的是所有 Entry 还是只使用文件 Entry，这个业务定义必须固定。

7. 并发和资源测试

单个 20 MiB ZIP 能成功，不代表 30 个同时上传也能成功。观察：

• Node.js RSS 和 heap；
• Event Loop 延迟；
• CPU 使用率；
• 临时磁盘使用量；
• 打开的文件描述符数量；
• 同时运行的导出数；
• P95/P99 转换耗时；
• 客户端断开后资源下降速度。

对 CPU 较重的 Markdown 高亮、图片处理和压缩，可以限制并发或转到任务队列/Worker。PM2 cluster 增加进程后，总并发限制也要重新计算，不能只看单个进程。

8. 建议监控的业务指标

日志中建议携带 requestId/jobId，但不要记录完整 Markdown 内容、Token、Cookie 或服务器敏感路径。

9. Nginx、Multer 和业务层各自的限制

Nginx client_max_body_size
  公网入口的请求体硬上限

Multer limits.fileSize / files / fields
  multipart 上传层限制

yauzl Entry 限制
  ZIP 内部数量、大小、路径和压缩比

任务并发限制
  控制 CPU、内存和磁盘总消耗

这些限制不是重复。越靠外层越早拒绝明显异常流量，越靠内层越了解 ZIP 的真实结构。

10. 生产上线清单

上传入口

• 必须认证的接口已经先认证，再执行 Multer；
• 对高成本导出设置用户级限流或并发配额；
• Nginx 和 Multer 都限制请求体大小；
• 只在明确上传 Route 使用 Multer，不全局使用 .any()；
• 上传文件存入不可被 Nginx 直接访问的隔离目录。

yauzl 导入

• 使用 lazyEntries: true 控制处理节奏；
• 启用合适的 Entry size 验证；
• 每个 Entry 都先校验路径，再创建文件；
• 同时限制 Entry 数、单文件大小和总解压大小；
• 限制压缩比、路径深度和名称长度；
• 拒绝绝对路径、路径穿越和符号链接；
• 定义重复路径、大小写冲突和 Unicode 冲突策略；
• 不信任扩展名、mimetype 和原始文件名。

Markdown 与 HTML

• 明确入口 Markdown 的选择规则；
• 资源引用不能逃出项目根目录；
• 禁止或安全处理外部资源 URL；
• 对生成 HTML 执行符合业务要求的净化；
• SVG、HTML、PDF/Office 等主动内容有单独策略；
• 输出目录只包含允许返回的产物。

archiver 导出

• 先注册 warning、error 和目标流监听，再 finalize()；
• 对 warning 分类，不无条件忽略；
• 添加完所有 Entry 后调用 finalize()；
• 等待目标 Writable 完成，而不只等待 finalize()；
• 使用 Express res.attachment() 设置下载名；
• 已发送响应后不再尝试返回 JSON。

中止与清理

• 客户端断开会触发 AbortController；
• 中止时关闭 ZipFile、销毁 Entry 流并 archive.abort()；
• 所有失败路径都会进入 finally；
• 每个请求使用独立临时目录；
• 递归删除只针对服务器创建并验证过的目录；
• 有定时任务兜底清理过期孤儿目录；
• 清理失败会记录日志和监控指标。

运维

• 已设置同时转换任务上限；
• 已监控 CPU、内存、事件循环和临时磁盘；
• 已测试客户端上传和下载中断；
• 已测试损坏 ZIP、Zip Slip 和 ZIP 炸弹；
• 错误响应不暴露堆栈和服务器路径；
• 日志不记录认证信息和敏感文件内容。

11. 新人上线的最小安全版本

如果清单看起来很多，第一次上线至少完成：

1. Nginx 与 Multer 限制上传大小；
2. 使用 yauzl lazyEntries；
3. 阻止路径穿越和符号链接；
4. 限制 Entry 数、单项大小和总解压大小；
5. 每请求独立临时目录；
6. 先生成结果 ZIP，成功后再 res.download()；
7. finally 清理，并测试失败路径；
8. 限制接口并发，记录耗时和清理失败。

然后再逐步增加压缩比、Unicode 冲突、主动内容扫描、后台任务和更完整的监控。

复盘题

1. 为什么 ZIP 接口测试不能只断言 HTTP 200？
2. 路径攻击、容量攻击和格式损坏分别应有哪些测试样例？
3. 故障注入后，除了错误响应还应验证哪些资源状态？
4. 为什么单请求压力测试不能代替并发测试？
5. Nginx、Multer 与 yauzl 的大小限制各解决什么问题？
6. 为什么要监控临时目录清理失败次数？
7. PM2 cluster 增加实例后，为什么需要重新评估总并发？
8. 如果只能完成八项措施，新人最小安全版本应包括哪些内容？

官方参考

• yauzl 官方 README
• Archiver 官方文档
• Multer 官方文档
• Express 5 API
• Node.js Test Runner
• Node.js Stream API