# 文件管理API

1. 目的与范围 #

本文档涵盖了Ragflow-Plus中的文件管理API端点，提供上传、下载、列出和删除文件的功能。这些API处理单文件操作和批量操作，支持大文件的分块上传。文件管理系统与MinIO集成用于对象存储，与MySQL集成用于元数据管理。

有关知识库文档管理，请参阅知识库API。有关管理文件操作，请参阅管理与Admin API。

相关源代码文件：

• api/apps/minio_app.py
• management/server/routes/files/routes.py
• management/server/services/files/document_service.py
• management/server/services/files/file_service.py
• management/server/services/files/service.py
• management/server/services/files/utils.py
• management/server/services/knowledgebases/excel_parser.py
• management/server/utils.py
• web/.env
• web/.umirc.ts
• web/src/components/chunk_image/index.tsx

2. API端点概述 #

文件管理API在管理服务器中实现，为全面的文件操作提供REST端点。所有端点返回标准化的JSON响应，包含code、message和data字段。

2.1 系统架构图 #

相关源代码文件：

• management/server/routes/files/routes.py (17-178行)
• management/server/services/files/service.py (448-736行)

3. 文件上传API #

3.1 单文件上传 #

/upload端点处理单个或多个文件在单个请求中的上传。

端点： POST /upload

请求格式：

• Content-Type: multipart/form-data
• 字段: files (一个或多个文件)

响应格式：

{
  "code": 0,
  "message": "上传成功", 
  "data": [
    {
      "id": "file_uuid",
      "name": "filename.pdf",
      "size": 12345,
      "type": "pdf",
      "status": "success"
    }
  ]
}

实现会验证文件扩展名是否符合ALLOWED_EXTENSIONS，并使用filename_type()函数确定文件类型。文件存储在MinIO中，元数据记录在file表中。

相关源代码文件：

• management/server/routes/files/routes.py (17-27行)
• management/server/services/files/service.py (448-607行)

3.2 分块文件上传 #

对于大文件，API支持使用两阶段过程的分块上传：上传分块，然后合并它们。

端点：

• POST /upload/chunk - 初始化分块上传
• POST /upload/chunk/<upload_id> - 上传单个分块
• POST /upload/merge - 合并所有分块

分块上传流程：

1. 初始化上传

   {
     "filename": "large_file.pdf",
     "total_size": 10485760,
     "chunk_size": 1048576,
     "total_chunks": 10
   }

   响应包含upload_id用于后续分块上传。

2. 上传分块

   • 每个分块包含：chunk_index、chunk_data、upload_id
   • 分块状态存储在Redis中，使用键模式：upload:{upload_id}:chunks

3. 合并分块

   • 验证所有分块已上传
   • 按顺序合并分块
   • 将完整文件上传到MinIO
   • 创建数据库记录

Redis状态管理：

• 键模式：upload:{upload_id}:info、upload:{upload_id}:chunks
• 使用位图操作进行高效的分块跟踪
• 上传会话24小时过期

4. 文件下载API #

端点： GET /<file_id>/download

响应：

• Content-Type: application/octet-stream
• 文件流作为附件下载

实现流程：

1. 从MySQL数据库获取文件元数据
2. 验证文件存在且不是文件夹
3. 从MinIO检索文件对象
4. 返回文件流给客户端

错误处理：

• 404: 文件不存在
• 400: 尝试下载文件夹
• 500: MinIO访问错误

5. 文件管理API #

5.1 列出文件 #

端点： GET /

查询参数：

• parent_id (可选): 父文件夹ID
• page (可选): 页码
• size (可选): 每页大小
• type (可选): 文件类型过滤

响应格式：

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": "file_uuid",
        "name": "document.pdf",
        "parent_id": "parent_uuid",
        "type": "pdf",
        "size": 12345,
        "location": "document.pdf",
        "source_type": "",
        "create_time": 1640995200,
        "create_date": "2022-01-01 12:00:00"
      }
    ],
    "total": 100
  },
  "message": "获取文件列表成功"
}

列表通过过滤WHERE f.type != 'folder'排除文件夹，并使用LIMIT/OFFSET支持分页。

相关源代码文件：

• management/server/routes/files/routes.py (29-48行)
• management/server/services/files/service.py (52-121行)

5.2 删除文件 #

单文件删除： DELETE /<file_id>

批量删除： DELETE /batch

批量请求体：

{
  "ids": ["file_id1", "file_id2", "file_id3"]
}

删除操作会从MinIO存储和数据库表中删除文件。对于有关联文档的文件（通过file2document表），操作还会清理相关的document记录及其MinIO对象。

事务流程：

1. 开始数据库事务
2. 从file表删除
3. 从file2document表删除
4. 删除关联的document记录
5. 提交事务
6. 从MinIO删除对象（非事务性）

相关源代码文件：

• management/server/routes/files/routes.py (87-124行)
• management/server/services/files/service.py (196-446行)

6. 存储集成 #

文件管理系统与多个存储层集成，实现完整的文件生命周期管理。

6.1 MinIO集成 #

MinIO配置：

• 使用parent_id从文件记录命名存储桶
• 使用location字段作为键存储对象
• 需要时自动创建存储桶
• 通过get_minio_client()配置客户端

MinIO客户端配置：

def get_minio_client():
    return Minio(
        settings.MINIO_ADDRESS,
        access_key=settings.MINIO_ACCESS_KEY,
        secret_key=settings.MINIO_SECRET_KEY,
        secure=settings.MINIO_SECURE
    )

6.2 数据库模式 #

file表： 核心文件元数据

• id: 文件UUID
• name: 文件名
• parent_id: 父文件夹ID
• type: 文件类型（FileType枚举）
• size: 文件大小（字节）
• location: MinIO对象路径
• create_time: 创建时间戳

file2document表： 将文件链接到知识库文档

• file_id: 文件ID
• document_id: 文档ID

document表： 知识库文档记录

• 与文件关联的文档元数据

6.3 Redis使用 #

分块上传状态跟踪：

• 键模式：upload:{upload_id}:info、upload:{upload_id}:chunks
• 位图操作用于高效的分块跟踪
• 上传会话24小时过期

相关源代码文件：

• management/server/services/files/service.py (448-736行)
• management/server/services/files/utils.py (7-33行)

7. 文件类型支持 #

系统支持FileType枚举中定义的全面文件类型集：

文件类型检测： filename_type()函数将文件扩展名映射到FileType枚举值。不支持的扩展名默认为FileType.OTHER，在上传时被拒绝。

Excel/CSV处理： Excel和CSV文件通过excel_parser.py接收特殊处理，将表格数据转换为HTML表格格式以用于知识库集成。

相关源代码文件：

• management/server/services/files/service.py (30-50行)
• management/server/services/files/utils.py (7-17行)
• management/server/services/knowledgebases/excel_parser.py (6-49行)

8. 前端集成 #

8.1 图像显示组件 #

前端提供了一个ChunkImage组件，用于显示存储在MinIO中的图像：

// 动态MinIO端点解析
const getMinioUrl = async () => {
  const res = await fetch(api.minio_endpoint);
  const data = await res.json();
  setImgSrc(`${data.url}${id}`);
};

组件从/api/minio/endpoint动态获取MinIO端点，并使用文件ID作为对象路径构建图像URL。

ImageWithPopover组件： 提供图像预览功能，带有弹出覆盖层以增强用户体验。

相关源代码文件：

• web/src/components/chunk_image/index.tsx (13-56行)
• api/apps/minio_app.py (6-12行)

8.2 环境配置 #

MinIO访问通过环境变量配置：

• MINIO_VISIT_HOST: MinIO服务器主机名（默认：localhost）
• MINIO_PORT: MinIO服务器端口（默认：9000）

这些变量被注入到前端构建过程中，用于动态端点解析。

相关源代码文件：

• web/.umirc.ts (51-52行)
• web/.env (1行)

9. 总结 #

文件管理API为Ragflow-Plus提供了完整的文件操作功能，包括：

• 多种上传模式：单文件、多文件和分块上传
• 存储集成：MinIO对象存储和MySQL元数据管理
• 文件类型支持：支持多种文档和图像格式
• 状态管理：使用Redis跟踪分块上传状态
• 前端集成：图像显示和动态端点解析

这些功能共同构成了一个强大且灵活的文件管理系统，能够有效处理各种文件操作需求。