Node.js文件上传集成ClamAV扫描：pompelmi库落盘前检测恶意文件

脚本专家

文件上传是Web应用常见的安全攻击面，用户上传的文件可能包含恶意软件、ZIP炸弹或伪造MIME类型。大多数Node.js项目仅做文件扩展名检查，远远不够。pompelmi是一个Node.js库，它能在文件落盘之前完成ClamAV扫描，返回类型化的verdict symbol，不依赖第三方运行时。

工作原理

pompelmi通过Node.js内置的child_process调用clamscan，直接读取退出码并将其映射为Symbol类型的结果。没有stdout解析，没有正则匹配，没有隐式状态，干净利落。

安装依赖

首先安装Node.js库：

2. npm install pompelmi

复制代码

然后在操作系统上安装ClamAV：
- macOS:

2. brew install clamav && freshclam

复制代码

- Debian/Ubuntu:

2. sudo apt-get install -y clamav clamav-daemon && sudo freshclam

复制代码

- Windows:

2. choco install clamav -y

复制代码

基本用法

导入模块并扫描文件：

2. const { scan, Verdict } = require('pompelmi');
3. const result = await scan('/path/to/file.zip');
5. switch (result) {
6.   case Verdict.Clean:
7.     // 文件安全，继续处理
8.     break;
9.   case Verdict.Malicious:
10.     throw new Error('检测到恶意软件，文件已拒绝');
11.   case Verdict.ScanError:
12.     // 扫描未完成，按不可信文件处理
13.     console.warn('扫描失败，拒绝文件');
14.     break;
15. }

复制代码

返回值映射关系：
- Verdict.Clean：ClamAV退出码0，未发现威胁
- Verdict.Malicious：退出码1，匹配到已知病毒签名
- Verdict.ScanError：退出码2，扫描本身失败，文件状态未知

在Express中集成

使用multer处理文件上传，在保存前调用pompelmi扫描：

2. const express = require('express');
3. const multer = require('multer');
4. const { scan, Verdict } = require('pompelmi');
5. const path = require('path');
6. const fs = require('fs');
8. const app = express();
9. const upload = multer({ dest: 'tmp/' });
11. app.post('/upload', upload.single('file'), async (req, res) => {
12.   const filePath = path.resolve(req.file.path);
13.   try {
14.     const result = await scan(filePath);
15.     if (result === Verdict.Malicious) {
16.       fs.unlinkSync(filePath);
17.       return res.status(422).json({ error: '文件包含恶意软件' });
18.     }
19.     if (result === Verdict.ScanError) {
20.       fs.unlinkSync(filePath);
21.       return res.status(422).json({ error: '扫描失败，文件已拒绝' });
22.     }
23.     // Verdict.Clean — 继续保存文件
24.     return res.status(200).json({ verdict: 'clean' });
25.   } catch (err) {
26.     fs.unlinkSync(filePath);
27.     return res.status(500).json({ error: err.message });
28.   }
29. });

复制代码

扫描失败或检测到恶意文件时，立即删除临时文件并返回422状态码。

远程扫描（Docker环境）

当ClamAV运行在容器中时，通过TCP socket连接：

2. const result = await scan('/path/to/file.zip', {
3.   host: '127.0.0.1',
4.   port: 3310,
5. });

复制代码

API保持不变，verdict类型不变，无缝切换。

错误处理

scan函数可能抛出以下异常：
- filePath不是字符串 → 'filePath must be a string'
- 文件不存在 → 'File not found: <path>'
- clamscan不在PATH中 → ENOENT
- 未知退出码 → 'Unexpected exit code: N'

建议在try/catch中处理：

2. try {
3.   const result = await scan(path.resolve(filePath));
4.   return result;
5. } catch (err) {
6.   console.error('扫描异常:', err.message);
7.   return null;
8. }

复制代码

特性总结

- 零运行时依赖，仅使用Node.js内置child_process
- 不解析stdout，直接读取退出码，性能可靠
- 支持TypeScript，verdict为Symbol类型，防止拼写错误
- 支持本地clamscan和远程clamd TCP socket
- 跨平台：macOS、Linux、Windows

通过pompelmi库，开发者可以用最少的代码在文件上传流程中集成ClamAV病毒扫描，提升应用安全性，避免用户上传恶意文件造成危害。

热心网友7

这个方案很实用，特别是“落盘前扫描”的思路，比事后扫描安全不少。pompelmi 直接读退出码不解析 stdout，确实干净，避免了正则解析带来的各种坑。 有个实际场景想请教一下：当并发上传请求较多时，每次调用 `child_process` 执行 `clamscan`，会不会有性能瓶颈？比如频繁 fork 进程导致 CPU 飙升，或者有没有内置的连接池机制来复用远程 clamd 的 TCP 连接？ 另外，`freshclam` 的更新策略通常怎么配合比较合理？如果用户上传文件时候病毒库还是旧的，可能会漏报。建议在文档里加一段定时更新数据库的示例，或者检查 `clamscan --version` 的数据库日期。