本文档由 AI 自动翻译。如有任何不准确之处,请参考 英文原版。知识库选用 自定义端点 扫描服务后,Dify 会把上传到该知识库的文件发给你的扫描服务,再根据服务返回的判定结果处理文件:安全的文件照常索引,已感染的文件则被拦截。 端点运行起来后,前往 集成 > 文件安全扫描 > 添加扫描服务 > 自定义端点 添加即可。为知识库开启扫描的方法详见 扫描上传文件中的恶意软件。
这类扫描服务与 集成 中的 自定义端点 板块无关。后者存放的是基于 API 的扩展,请求格式也不同。
接收文件
Dify 为每个文件单独发送一个请求:401。
表单包含文件本身和 5 个文本字段:
本次扫描的 ID。Dify 自动重试同一次扫描时会发送相同的 ID,因此你的服务收到重复请求时,可直接返回首次扫描的结果,无需重新扫描。之后在知识库中重试该文档,则会发起新的扫描,ID 也随之更换。
返回判定结果
返回任意2xx 状态码和一个 JSON 对象:
检测到的威胁名称,会显示在被拦截文档的错误信息中,供用户查看。未提供时,错误信息显示检测到
unknown。Dify 最多保留 20 个名称,每个名称最长 200 个字符,超出部分截断。- 文件过大:返回
413。错误信息会提示文件超出扫描服务的大小上限。 - 已加密、格式不受支持或其他任何原因:返回
unscannable。无论实际原因是什么,错误信息都会提示扫描服务不支持该文件。
选择合适的状态码
Dify 根据你返回的状态码和响应体决定如何处理文件。遇到重试一次即可缓解的短暂过载时,返回
503,不要返回 429。在超时前响应
每个请求都需在 2 分钟内响应。在 Docker Compose 部署中,Dify 的请求会经过一个代理,请求超过 2 分钟仍未收到响应,代理就会将其关闭。 不经过该代理时,时限取决于 Dify 自身的超时设置:默认 300 秒,由FILE_SCAN_REQUEST_TIMEOUT_SECONDS 设置。详见 环境变量。
超时的请求会重新发送,默认最多尝试 3 次。因此端点响应慢时,文档可能要等待约 6 分钟(3 × 2 分钟),之后才会按知识库的 扫描服务不可用时 选项处理。
如果你的服务确定无法及时扫描完某个文件,应立即返回 413 或 unscannable,不要等到请求超时。
确保端点可访问
在 Dify 中,将端点的完整 URL(含路径)填入 端点 URL,如http://scanner.example.internal:8000/scan。填写的地址必须是 Dify 能访问到的,不能使用 localhost。
在 Docker Compose 部署中,Dify 发出的请求都要经过代理,代理默认还会拦截内网地址。如果你的端点使用内网地址,在放行该地址之前,Dify 既无法访问端点,也无法保存该扫描服务:
- 端点 URL 使用 IP 地址时:将
SSRF_PROXY_ALLOW_PRIVATE_IPS设为该地址。 - 端点 URL 使用主机名时:将
SSRF_PROXY_ALLOW_PRIVATE_DOMAINS设为该主机名。
https 请求,该代理只放行 443 端口。除非部署环境将 HTTP_REQUEST_NODE_SSL_VERIFY 设为 false,否则 Dify 会校验 https 端点的 TLS 证书。
保存前先测试
在端点所在的机器上,向它发送一个与 Dify 格式相同的请求:file_name、file_size 和 mime_type。端点应对前者返回 clean,对后者返回 infected。
EICAR 测试文件本身无害,但所有杀毒引擎都会把它识别为恶意软件,可从 eicar.org 下载。
infected:永久沿用。如果你的服务把安全文件误判为感染,即使之后修好了扫描服务,这个文件也会一直被拦截。clean:默认沿用 24 小时,由FILE_SCAN_CLEAN_VERDICT_TTL_HOURS设置。在此期间,即使你已更新扫描服务、使其能检出该文件,同一文件仍会放行。
file:clean-test.txt,类型为text/plainscan_id:connectivity-checkfile_hash:空
413 也算通过。只有检查通过,Dify 才会保存扫描服务。
知识库启用该扫描服务后,可在其中 上传 EICAR 测试文件,检查整条链路是否正常。
从示例开始
将以下 Flask 端点中的my_scanner 替换为你自己的扫描逻辑:
scanner.py
scanner.py,安装 Flask 后启动端点。启动时使用的 API 密钥,就是要在 Dify 中填写的那个: