9.4 · 文件上传与管理 API（File Upload and Management APIs）

文件上传与管理 API

文件上传与管理 API

相关源文件

本章引用的主要源码文件：

• api/controllers/common/errors.py
• api/controllers/console/files.py
• api/controllers/console/remote_files.py
• api/controllers/files/__init__.py
• api/controllers/files/image_preview.py
• api/controllers/files/tool_files.py
• api/controllers/files/upload.py
• api/controllers/inner_api/__init__.py
• api/controllers/inner_api/app/__init__.py
• api/controllers/inner_api/mail.py
• api/controllers/inner_api/plugin/plugin.py
• api/controllers/inner_api/workspace/workspace.py
• api/controllers/mcp/__init__.py
• api/controllers/service_api/__init__.py
• api/controllers/service_api/app/file.py
• api/controllers/web/__init__.py
• api/controllers/web/files.py
• api/controllers/web/remote_files.py
• api/core/plugin/backwards_invocation/base.py
• api/services/errors/file.py
• api/services/file_service.py
• api/tasks/mail_inner_task.py
• api/tests/test_containers_integration_tests/services/test_file_service.py
• api/tests/unit_tests/controllers/console/test_files.py
• api/tests/unit_tests/controllers/console/test_files_security.py
• api/tests/unit_tests/controllers/inner_api/app/__init__.py
• api/tests/unit_tests/core/datasource/test_file_upload.py
• api/tests/unit_tests/fields/test_file_fields.py
• api/tests/unit_tests/services/test_file_service.py

本文档涵盖了 Dify 中的文件上传与管理 API，包括用于上传文件、检索文件内容以及将文件集成到消息流中以实现多模态 AI 能力的 HTTP 端点。

范围：本页面主要介绍 Service API 端点（/files/upload， /files/:file_id/preview）、底层的 FileService 实现，以及文件如何在不同的层级（Console、Web 和 Tool 生态系统）之间传递。

文件上传 API 架构

文件上传系统使用户能够上传文件，这些文件可以在后续的消息请求中被引用，从而支持多模态理解和知识库（检索增强生成（RAG））的入库。

核心实现：FileService

FileService 类是文件生命周期管理的核心。它负责处理校验、通过 OpenDAL 进行存储抽象以及数据库持久化。

系统请求流程：上传

来源：api/services/file_service.py:89-113， api/controllers/console/files.py:85-91， api/controllers/service_api/app/file.py:59-64， api/controllers/files/upload.py:100-107

文件预览与检索

Dify 提供了多个用于检索文件内容的端点，包括针对图片和通用文件的签名预览。访问权限通过 HMAC 签名进行保护。

HTTP 端点

实现细节：对于媒体文件（音频/视频），响应中会包含 Accept-Ranges: bytes 和 Content-Length 请求头，以支持网页播放器中的拖拽定位。 来源：api/controllers/files/image_preview.py:115-130， api/controllers/files/tool_files.py:73-80， api/controllers/console/files.py:103-113

签名验证

为防止未授权访问，预览 URL 会进行签名。系统会验证 timestamp、nonce 和 sign 参数。 来源：api/controllers/files/image_preview.py:55-66， api/core/tools/signature.py:12-31

远程文件管理

Dify 支持从远程 URL 获取文件。当用户提供 remote_url 而非 local_file 时，会使用此功能。

远程文件流程

1. 元数据检查：系统通过 ssrf_proxy 发起 HEAD 请求（失败时回退到 GET 请求），以确定文件大小和类型。
2. SSRF 防护：所有远程请求都通过 ssrf_proxy 路由，以防止内部网络扫描。
3. 上传：如果文件大小在限制范围内，则会被下载并作为标准的 UploadFile 进行处理。

来源：api/controllers/console/remote_files.py:58-85， api/controllers/web/remote_files.py:115-137， api/core/helper/ssrf_proxy.py:1-40

工具与插件文件处理

工具和插件拥有由 ToolFileManager 管理的专用文件生命周期。这些文件通常是代码执行或工具调用的临时输出。

插件文件上传

插件通过 /upload/for-plugin 端点上传文件。此端点需要一个由 verify_plugin_file_signature 验证的签名。 来源：api/controllers/files/upload.py:88-97， api/core/tools/tool_file_manager.py:100-107

工具文件访问

工具文件通过一个特定的路由进行访问，该路由在从存储中流式传输文件之前，会验证工具专用的签名。 来源：api/controllers/files/tool_files.py:52-59

在消息 API 中的集成

Dify 在聊天/补全/工作流 API 中支持三种主要的文件传递方式：

1. local_file：引用通过 /files/upload 创建的 UploadFile ID。
2. remote_url：一个直接的 URL，由服务器在运行时获取。
3. tool_file：（内部使用）引用在执行期间生成的 ToolFile ID。

文件引用结构

在请求中传递文件时，使用以下模式：

{
  "type": "image",
  "transfer_method": "local_file",
  "upload_file_id": "72fa9618-8f89-4a37-9b33-7e1178a24a67"
}

来源：api/controllers/service_api/app/file.py:17-21， api/services/file_service.py:95-109

后端存储与模型

核心数据实体

存储键模式

• 标准上传：upload_files/{tenant_id}/{uuid}.{extension}
• 文本上传：upload_files/{tenant_id}/{uuid}.txt

来源：api/services/file_service.py:89-89， api/services/file_service.py:148-148