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

文件上传与管理 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/9.4-file-upload-and-management-apis

翻译时间：2026-05-27T08:44:20.982Z

翻译模型：deepseek-chat

原文字符数：9237

项目：Dify (dify)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

文件上传与管理 API

相关源文件

以下文件被用作生成此 Wiki 页面的上下文：

• 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 进行存储抽象以及数据库持久化。

方法	用途	来源
upload_file()	校验文件扩展名、检查大小限制、保存到存储并记录到数据库。	api/services/file_service.py:49-118
is_file_size_within_limit()	根据扩展名类别（图片、视频、音频）检查文件大小的静态辅助方法。	api/services/file_service.py:121-131
get_file_preview()	使用 ExtractProcessor 从文档文件中提取文本片段。	api/services/file_service.py:176-193
upload_text()	将原始文本作为 .txt 文件保存到存储中的专用方法。	api/services/file_service.py:143-174

系统请求流程：上传

graph TD
    subgraph "控制器层"
        C_API["Console: /files/upload"]
        S_API["Service: /files/upload"]
        P_API["Plugin: /upload/for-plugin"]
    end

    subgraph "服务层"
        FS["FileService.upload_file()"]
        TFM["ToolFileManager.create_file_by_raw()"]
    end

    subgraph "存储与数据库"
        STR["storage.save()"]
        DB_UF[("models.UploadFile")]
        DB_TF[("models.ToolFile")]
    end

    C_API --> FS
    S_API --> FS
    P_API --> TFM
    FS --> STR
    FS --> DB_UF
    TFM --> STR
    TFM --> DB_TF

来源：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 端点

端点	方法	用途
/files/<uuid:file_id>/file-preview	GET	下载文件流，支持媒体文件的 Range 请求。
/files/<uuid:file_id>/image-preview	GET	（已废弃）专用的图片预览端点。
/tools/<uuid:file_id>.<ext>	GET	下载由工具生成的文件。
/files/<uuid:file_id>/preview	GET	获取文档文件的文本内容片段。

实现细节：对于媒体文件（音频/视频），响应中会包含 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 进行处理。

graph LR
    subgraph "代码实体"
        C["RemoteFileUploadApi"]
        P["ssrf_proxy"]
        FS["FileService"]
    end

    C -- "1. 校验 URL" --> P
    P -- "2. HEAD/GET" --> Remote["远程服务器"]
    P -- "3. 返回内容" --> C
    C -- "4. upload_file()" --> FS

来源：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

---

后端存储与模型

核心数据实体

模型类	用途	来源
UploadFile	用户上传文件的主模型，追踪租户、大小和哈希值。	api/models/model.py
ToolFile	由工具/插件生成的文件的元数据。	api/models/tools.py
StorageType	定义后端存储类型（LOCAL， S3， AZURE 等）的枚举。	api/extensions/storage/storage_type.py:1-10

存储键模式

• 标准上传：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