做用户上传功能时加了一道扫描:文件落盘先算哈希,连上下载地址一起丢给病毒查询接口,命中就拦、不命中就放。写了不到一个月,接口开始时不时返回一个 503 开头的错误码,写着本地病毒特征库未初始化。值班同学的第一反应是把这道检查跳过,理由是「反正是个附加功能」。
下面拿数据鱼API的「病毒与恶意链接查询」服务当例子。它只有一个
query端点,收hash与url两个参数,也正好用来说明「依赖不可用」该怎么处理。
hash 和 url 都标了必填。这不太常见——多数查询接口会允许二选一。两个都要,意思是你得同时给出「这个文件是什么」和「它从哪儿来」:同一个文件从不同来源下载,风险不一样;同一个地址下发的文件也可能被替换。
所以调用方要做的事很具体:文件落盘算一遍哈希(SHA-256 就够),同时把来源地址一并记下,两个字段一起提交。数据鱼这个端点把两项都设为必填,等于要求你把「样本是什么」和「样本从哪来」当成一组信息来看。
GET /api/virus/query这里最常见的实现错误是只传哈希、地址留空,然后抱怨接口报 4001。必填就是必填,别指望它能替你推断。
那次报错的信息量很大:本地病毒特征库未初始化,表不存在。直白到几乎不像生产环境的错误提示,但它说明了一件事——这个端点的判定依赖一张本地特征库表,表不在,整个判定链路就跑不起来。
关键在于接口的选择:它返回 5031,而不是返回「未命中」或者「安全」。
这两者的差别,决定了你的系统在故障时是安全的还是危险的。如果它返回「未命中」,你的代码会放行,用户上传的可能是恶意文件;它返回 5031,你有机会选择「暂缓处理」。文档里其余错误码的说明也写了同一句话:上游不可用时不会返回伪造数据。这句话应该被当作契约来读。
返回 | 含义 | 你的正确动作 |
|---|---|---|
0 + 命中 | 已知恶意样本 | 阻断,记录证据 |
0 + 未命中 | 特征库正常,未命中 | 放行,保留抽样 |
5031 / 5032 | 判定无法完成 | 暂缓,不进「安全」分支 |
4001 / 4002 | 参数问题 | 修调用,别重试 |
我们最后定的是三态,不是两态:安全、恶意、未知。未知的文件进隔离区,不对外提供下载,后台按 5 分钟、30 分钟、2 小时退避重试,恢复后自动补判。
这条规则写起来简单,落地时最容易被产品挑战:「用户上传完看不到文件,体验很差。」我们的回答是:体验差和被当成传播渠道,选一个。后来加了个折中——隔离期间前端显示「安全检测中,预计几分钟」,比直接报错友好,也没破坏安全边界。
技术上还有两个细节。第一,重试要有上限,超过 24 小时仍未判定的,转人工。第二,重试期间同一哈希不要再走一次完整上传流程,缓存中间状态,避免用户重复上传。
大多数接口的健康检查是免鉴权的,方便运维探活。这个接口的 ping 明确标注「需鉴权」,用的还是独立的 Key。
这意味着你的探活脚本不能照抄别处的写法——不带 Key 直接探,会拿到 4011,然后监控误报服务不可用。数据鱼这个接口把 ping 也放在鉴权之后,探活配置就得跟业务调用分开维护,Key 独立存放,日志里只记状态码,不记 Key。
顺带说一句 Key 的用法:推荐走请求头,查询参数只作旧客户端兼容。区别在于查询参数会进访问日志,密钥一旦落进日志,就等于在服务器上留了一份明文副本。
病毒查询这类能力,边界很清楚:它只告诉你「这个样本在已知特征库里有没有记录」,不保证没记录的就是安全的,也不替你做沙箱行为分析。把它当成过滤器的一道,而不是安全体系的全部。这类能力仅用于自有业务的防护场景。
以上关于
query的两个必填参数、5031错误码语义与ping鉴权要求的说明,整理自数据鱼API「病毒与恶意链接查询」接口的公开文档与错误提示;文中故障场景为虚构示例,安全判定请结合多种检测手段综合判断。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。