文件防病毒扫描

Discuse 会在文件到达你的用户之前扫描其中的恶意软件。有两种调用方式：在 POST /api/v2/check 上启用 check_antivirus，以便在执行其他检查的同时扫描文档 URL；或者使用专用的 POST /api/v2/scan 端点扫描单个文件，并获取包含威胁名称和 SHA-256 哈希在内的完整报告。

为什么要扫描上传的文件？

文件上传是一种常见的攻击途径。通过你的平台传播恶意软件，会危及用户数据、你的声誉以及你自己的基础设施。在存储或提供文件访问之前逐一扫描，可以堵住这个安全缺口。

扫描是如何工作的？

当你提交文件 URL 时，Discuse 会将文件下载到隔离环境中进行扫描，并返回是否发现威胁。相同文件会被缓存，因此重复扫描会很快。

选项 1：在 /check 请求中扫描文件

在 content.document_urls 中传入文档 URL，并启用 check_antivirus。当你正在审核一条同时带有附件的消息时，这就是合适的调用方式。

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "document_urls": ["https://example.com/uploaded-file.pdf"]
    },
    "settings": {
      "check_antivirus": true
    }
  }'

单个请求最多可接受 5 个文档 URL。

响应

{
  "has_violations": true,
  "cached": false,
  "message": "Malware detected in file",
  "results": {
    "hits": true,
    "antivirus": {
      "status": "FOUND",
      "hit": true,
      "details": [
        {
          "type": "malware",
          "details": "Trojan.GenericKD.12345678",
          "result": true
        }
      ]
    }
  }
}

results.antivirus 下的防病毒结果包含三个字段：status、hit 和一个 details 数组。每个 details 条目都包含 type、details（威胁名称或消息）、confidence 和 result。

选项 2：使用 /api/v2/scan 扫描单个文件

专用扫描端点会为一个文件返回更丰富的报告，包括威胁名称、文件哈希和扫描耗时。

curl -X POST https://api.discuse.com/api/v2/scan \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "file_url": "https://example.com/uploaded-file.pdf",
    "file_name": "uploaded-file.pdf"
  }'

响应

{
  "hit": true,
  "status": "FOUND",
  "description": "Trojan.GenericKD.12345678",
  "file_name": "uploaded-file.pdf",
  "file_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "scan_time_ms": 1250
}

/api/v2/scan 请求字段

字段	类型	说明
`api_key`	string	请求体中可选；也可以改为发送 `X-API-Key`
`file_url`	string	要扫描的文件 URL
`file_name`	string	报告中使用的可选文件名

请提供 file_url。Base64 file_data 已在 schema 中定义，但尚不支持——如果请求中只有 file_data，会返回错误，提示你使用 file_url。

/api/v2/scan 响应字段

字段	类型	描述
`hit`	boolean	检测到恶意软件时为 True
`status`	string	`OK`（干净）、`FOUND`（恶意软件）或 `ERROR`
`description`	string	威胁名称，或错误消息
`file_name`	string	已扫描的文件名
`file_hash`	string	文件的 SHA-256 哈希
`scan_time_ms`	number	扫描耗时，单位为毫秒

使用限制

防病毒扫描仅适用于付费套餐。每扫描一个文件都会计入一次配额。

套餐	每月扫描次数	超额费率
Basic	不可用	-
Gold	500	$0.001/次扫描
Platinum	1,500	$0.00085/次扫描（15% 折扣）
Ultimate	3,000	$0.00075/次扫描（25% 折扣）

如果项目没有有效订阅，防病毒扫描将被拒绝。

最佳实践

存储前先扫描

在永久存储文件之前先扫描，这样受感染的文件就不会进入你的系统：

async function handleFileUpload(fileUrl, fileName) {
  const result = await scanFile(fileUrl, fileName);

  if (result.hit) {
    throw new Error('Infected file detected: ' + result.description);
  }
  await storeFile(fileUrl);
}

根据状态分流处理

区分干净文件和扫描失败的情况：

const result = await scanFile(fileUrl, fileName);

switch (result.status) {
  case 'FOUND': await rejectAndNotify(fileUrl, result.description); break;
  case 'ERROR': await quarantineForReview(fileUrl); break;
  case 'OK':    await storeFile(fileUrl); break;
}

复用一致的 URL

相同文件会被缓存。使用稳定的文件 URL，可以让重复扫描从缓存返回，而无需重新下载。

集成示例

Node.js（专用扫描端点）

async function scanFile(fileUrl, fileName) {
  const response = await fetch('https://api.discuse.com/api/v2/scan', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({ file_url: fileUrl, file_name: fileName })
  });

  return response.json();
}

Python（专用扫描端点）

import os
import requests

def scan_file(file_url, file_name=None):
    response = requests.post(
        'https://api.discuse.com/api/v2/scan',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={'file_url': file_url, 'file_name': file_name}
    )
    return response.json()