在Node.js文件上传中集成ClamAV扫描的详细步骤

文件上传一直是应用安全里最容易被忽视的攻击面。用户上传的东西，可能表面上是个PDF，底层却藏着恶意脚本、ZIP冲击波，甚至只是改了个后缀名的可执行文件。很多Node.js项目只做扩展名白名单检查——说实话，这跟没检查区别不大。

这里要聊的 pompelmi 是一个轻量级的 Node.js 库，它的设计思路很实在：在文件真正落盘之前就完成病毒扫描，返回一个类型化的 verdict symbol。不依赖任何第三方运行时，也不需要额外安装复杂的杀毒引擎——当然，ClamA V 本身还是得装的。

工作原理

核心逻辑简单到可以用三句话讲清楚：

1. 验证传入参数是否为字符串，以及文件是否存在
2. 通过 child_process 调用 clamscan，直接读取退出码
3. 把退出码映射成预定义的 Symbol

没有 stdout 解析，没有正则匹配，没有隐式状态。简洁，但足够可靠。

安装

前提条件：Node.js 和 ClamA V。先装依赖包：

npm install pompelmi

然后安装 ClamA V，不同系统的命令略有差异：

# macOS
brew install clama v && freshclam
# Debian / Ubuntu
sudo apt-get install -y clama v clama v-daemon && sudo freshclam
# Windows
choco install clama v -y

基本用法

调用 scan 函数后得到一个 verdict，通过比较 Verdict 枚举值来决定下一步动作：

const { scan, Verdict } = require('pompelmi');

const result = await scan('/path/to/file.zip');

switch (result) {
  case Verdict.Clean:
    // 文件安全，继续处理
    break;
  case Verdict.Malicious:
    throw new Error('检测到恶意软件，文件已拒绝');
  case Verdict.ScanError:
    // 扫描未完成，按不可信文件处理
    console.warn('扫描失败，拒绝文件');
    break;
}

返回值与 ClamA V 退出码的对应关系如下表：

在 Express 中集成

实际项目里最常见的场景就是配合 Express + Multer 做上传接口。代码结构很清晰：先扫描临时文件，根据 verdict 决定是保留还是删除并返回错误。注意，扫描失败和检测到恶意软件都返回 422，但语义不同，客户端可以根据 error 信息区分。下面是一个完整的示例：

const express = require('express');
const multer  = require('multer');
const { scan, Verdict } = require('pompelmi');
const path = require('path');
const fs   = require('fs');

const app    = express();
const upload = multer({ dest: 'tmp/' });

app.post('/upload', upload.single('file'), async (req, res) => {
  const filePath = path.resolve(req.file.path);
  try {
    const result = await scan(filePath);
    if (result === Verdict.Malicious) {
      fs.unlinkSync(filePath);
      return res.status(422).json({ error: '文件包含恶意软件' });
    }
    if (result === Verdict.ScanError) {
      fs.unlinkSync(filePath);
      return res.status(422).json({ error: '扫描失败，文件已拒绝' });
    }
    // Verdict.Clean — 继续保存文件
    return res.status(200).json({ verdict: 'clean' });
  } catch (err) {
    fs.unlinkSync(filePath);
    return res.status(500).json({ error: err.message });
  }
});

远程扫描（Docker）

如果你的 ClamA V 运行在容器或远程服务器上，可以通过 TCP socket 连接。只需要在 scan 的第二个参数中传入 host 和 port：

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

API 签名完全不变，verdict 类型也保持一致——底层会自动切换到远程 clamd 协议。

错误处理

库的异常处理比较直接，抛出的错误信息基本能一眼看出问题所在：

try {
  const result = await scan(path.resolve(filePath));
  return result;
} catch (err) {
  // filePath 不是字符串      → 'filePath must be a string'
  // 文件不存在               → 'File not found: '
  // clamscan 不在 PATH 中    → ENOENT
  // 未知退出码               → 'Unexpected exit code: N'
  console.error('扫描异常:', err.message);
  return null;
}

特性

• 零运行时依赖，仅仅使用 Node.js 内置的 child_process
• 不解析 stdout，直接读取退出码，性能干净利落
• 支持 TypeScript，verdict 为 Symbol 类型，不会因拼写错误导致 bug
• 既支持本地 clamscan，也支持远程 clamd TCP socket
• 跨平台：macOS、Linux、Windows 均可使用