跳转到主要内容
本文档由 AI 自动翻译。如有任何不准确之处,请参考 英文原版。
知识库选用 自定义端点 扫描服务后,Dify 会把上传到该知识库的文件发给你的扫描服务,再根据服务返回的判定结果处理文件:安全的文件照常索引,已感染的文件则被拦截。 端点运行起来后,前往 集成 > 文件安全扫描 > 添加扫描服务 > 自定义端点 添加即可。为知识库开启扫描的方法详见 扫描上传文件中的恶意软件。
这类扫描服务与 集成 中的 自定义端点 板块无关。后者存放的是基于 API 的扩展,请求格式也不同。

接收文件

Dify 为每个文件单独发送一个请求:
自己定一个保密的字符串作为 API 密钥,添加扫描服务时填入 Dify,再让你的服务校验它。密钥不匹配时,返回 401。 表单包含文件本身和 5 个文本字段:
file
待扫描的文件。
string
本次扫描的 ID。Dify 自动重试同一次扫描时会发送相同的 ID,因此你的服务收到重复请求时,可直接返回首次扫描的结果,无需重新扫描。之后在知识库中重试该文档,则会发起新的扫描,ID 也随之更换。
string
文件名,如 report.docx。
string
文件大小,单位为字节,以十进制字符串表示,如 482113。
string
文件的 MIME 类型。Dify 无法确定类型时为空。
string
文件内容的 SHA3-256 哈希值,以十六进制表示,可能为空。如果你的服务每次都需要哈希值,可根据文件内容自行计算。

返回判定结果

返回任意 2xx 状态码和一个 JSON 对象:
string
必填
clean、infected 或 unscannable。
string[]
检测到的威胁名称,会显示在被拦截文档的错误信息中,供用户查看。未提供时,错误信息显示检测到 unknown。Dify 最多保留 20 个名称,每个名称最长 200 个字符,超出部分截断。
string
扫描引擎的名称或版本。Dify 不会在产品中显示该值。
string
服务无法扫描该文件的原因,最多 500 个字符。Dify 不会在产品中显示该值。
服务无法判定某个文件时,该文件是被拦截(默认)还是不经扫描直接放行,取决于知识库的 文件无法扫描时(已加密或过大) 选项。文件被拦截时,用户看到什么错误信息,由你返回的内容决定:
  • 文件过大:返回 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 格式相同的请求:
扫描逻辑就绪后,将该请求发送两次:一次附带安全的文件,一次附带 EICAR 测试文件,并相应修改 file_name、file_size 和 mime_type。端点应对前者返回 clean,对后者返回 infected。
EICAR 测试文件本身无害,但所有杀毒引擎都会把它识别为恶意软件,可从 eicar.org 下载。
另外,再挑一些真实文件发送测试,以便在知识库启用该扫描服务之前发现误报。 Dify 会记住判定结果。在同一工作空间中,同一扫描服务再次检查相同的内容时,Dify 会直接沿用之前的判定结果,不再调用你的端点:
  • infected:永久沿用。如果你的服务把安全文件误判为感染,即使之后修好了扫描服务,这个文件也会一直被拦截。
  • clean:默认沿用 24 小时,由 FILE_SCAN_CLEAN_VERDICT_TTL_HOURS 设置。在此期间,即使你已更新扫描服务、使其能检出该文件,同一文件仍会放行。
保存扫描服务时,以及每次点击 测试 时,Dify 都会发送一个文件来检查连接:
  • file:clean-test.txt,类型为 text/plain
  • scan_id:connectivity-check
  • file_hash:空
只要返回格式正确的判定结果,检查即通过,返回 413 也算通过。只有检查通过,Dify 才会保存扫描服务。 知识库启用该扫描服务后,可在其中 上传 EICAR 测试文件,检查整条链路是否正常。

从示例开始

将以下 Flask 端点中的 my_scanner 替换为你自己的扫描逻辑:
scanner.py
将代码保存为 scanner.py,安装 Flask 后启动端点。启动时使用的 API 密钥,就是要在 Dify 中填写的那个:
最后修改于 2026年11月18日