首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >查不到不等于没毒:病毒库未就绪时该怎么降级|数据鱼API

查不到不等于没毒:病毒库未就绪时该怎么降级|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-18 21:41:54
发布于 2026-11-18 21:41:54
100
举报
文章被收录于专栏:小技术小技术技术手册

做用户上传功能时加了一道扫描:文件落盘先算哈希,连上下载地址一起丢给病毒查询接口,命中就拦、不命中就放。写了不到一个月,接口开始时不时返回一个 503 开头的错误码,写着本地病毒特征库未初始化。值班同学的第一反应是把这道检查跳过,理由是「反正是个附加功能」。

下面拿数据鱼API的「病毒与恶意链接查询」服务当例子。它只有一个 query 端点,收 hash 与 url 两个参数,也正好用来说明「依赖不可用」该怎么处理。

两个参数都必填,本身就是个设计信号

hash 和 url 都标了必填。这不太常见——多数查询接口会允许二选一。两个都要,意思是你得同时给出「这个文件是什么」和「它从哪儿来」:同一个文件从不同来源下载,风险不一样;同一个地址下发的文件也可能被替换。

所以调用方要做的事很具体:文件落盘算一遍哈希(SHA-256 就够),同时把来源地址一并记下,两个字段一起提交。数据鱼这个端点把两项都设为必填,等于要求你把「样本是什么」和「样本从哪来」当成一组信息来看。

代码语言:javascript
复制
GET /api/virus/query

这里最常见的实现错误是只传哈希、地址留空,然后抱怨接口报 4001。必填就是必填,别指望它能替你推断。

5031 不是超时,是「依赖没准备好」

那次报错的信息量很大:本地病毒特征库未初始化,表不存在。直白到几乎不像生产环境的错误提示,但它说明了一件事——这个端点的判定依赖一张本地特征库表,表不在,整个判定链路就跑不起来。

关键在于接口的选择:它返回 5031,而不是返回「未命中」或者「安全」。

这两者的差别,决定了你的系统在故障时是安全的还是危险的。如果它返回「未命中」,你的代码会放行,用户上传的可能是恶意文件;它返回 5031,你有机会选择「暂缓处理」。文档里其余错误码的说明也写了同一句话:上游不可用时不会返回伪造数据。这句话应该被当作契约来读。

返回

含义

你的正确动作

0 + 命中

已知恶意样本

阻断,记录证据

0 + 未命中

特征库正常,未命中

放行,保留抽样

5031 / 5032

判定无法完成

暂缓,不进「安全」分支

4001 / 4002

参数问题

修调用,别重试

降级策略:把「未知」当成第三种状态

我们最后定的是三态,不是两态:安全、恶意、未知。未知的文件进隔离区,不对外提供下载,后台按 5 分钟、30 分钟、2 小时退避重试,恢复后自动补判。

这条规则写起来简单,落地时最容易被产品挑战:「用户上传完看不到文件,体验很差。」我们的回答是:体验差和被当成传播渠道,选一个。后来加了个折中——隔离期间前端显示「安全检测中,预计几分钟」,比直接报错友好,也没破坏安全边界。

技术上还有两个细节。第一,重试要有上限,超过 24 小时仍未判定的,转人工。第二,重试期间同一哈希不要再走一次完整上传流程,缓存中间状态,避免用户重复上传。

ping 需要鉴权,这个差异要记住

大多数接口的健康检查是免鉴权的,方便运维探活。这个接口的 ping 明确标注「需鉴权」,用的还是独立的 Key。

这意味着你的探活脚本不能照抄别处的写法——不带 Key 直接探,会拿到 4011,然后监控误报服务不可用。数据鱼这个接口把 ping 也放在鉴权之后,探活配置就得跟业务调用分开维护,Key 独立存放,日志里只记状态码,不记 Key。

顺带说一句 Key 的用法:推荐走请求头,查询参数只作旧客户端兼容。区别在于查询参数会进访问日志,密钥一旦落进日志,就等于在服务器上留了一份明文副本。

病毒查询这类能力,边界很清楚:它只告诉你「这个样本在已知特征库里有没有记录」,不保证没记录的就是安全的,也不替你做沙箱行为分析。把它当成过滤器的一道,而不是安全体系的全部。这类能力仅用于自有业务的防护场景。

以上关于 query 的两个必填参数、5031 错误码语义与 ping 鉴权要求的说明,整理自数据鱼API「病毒与恶意链接查询」接口的公开文档与错误提示;文中故障场景为虚构示例,安全判定请结合多种检测手段综合判断。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 两个参数都必填,本身就是个设计信号
  • 5031 不是超时,是「依赖没准备好」
  • 降级策略:把「未知」当成第三种状态
  • ping 需要鉴权,这个差异要记住
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档