文件管理模块

概述

文件管理模块提供完整的文件存储和管理功能，支持多存储后端（本地/OSS/MinIO/Azure）、分块上传、秒传、临时访问令牌、AI OCR 识别等能力。

模块路径：backend-fastapi/core/file_manager/

API 前缀：/api/core/file_manager

数据模型

FileManager（文件/文件夹）

python

class FileManager(BaseModel):
    __tablename__ = "core_file_manager"

    name: str               # 文件/文件夹名称
    type: str               # 类型（file/folder）
    parent_id: str          # 父文件夹 ID
    path: str               # 完整路径
    size: int               # 文件大小（字节）
    file_ext: str           # 文件扩展名
    mime_type: str          # MIME 类型
    storage_type: str       # 存储类型
    storage_path: str       # 存储路径
    url: str                # 访问 URL
    thumbnail_url: str      # 缩略图 URL
    md5: str                # 文件 MD5（用于秒传）
    is_public: bool         # 是否公开
    is_system: bool         # 是否系统文件夹
    source: str             # 来源模块
    download_count: int     # 下载次数

FileAccessToken（临时访问令牌）

python

class FileAccessToken(BaseModel):
    __tablename__ = "core_file_access_token"

    token: str              # 访问令牌（唯一）
    file_id: str            # 文件 ID
    expires_at: datetime    # 过期时间
    user_id: str            # 创建用户
    ip_address: str         # 客户端 IP
    user_agent: str         # 客户端 UA

存储类型 (storage_type)

值	说明
`local`	本地存储
`oss`	阿里云 OSS
`minio`	MinIO
`azure`	Azure Blob Storage

服务层

FileManagerService

继承 BaseService，提供以下方法：

文件操作

方法	说明
`get_list(db, page, page_size, filters)`	获取文件列表（文件夹排前）
`get_folder_tree(db)`	获取文件夹树
`create_folder(db, name, parent_id)`	创建文件夹（同名检查）
`upload_file(db, file, parent_id, source)`	上传文件
`rename_item(db, id, new_name)`	重命名（递归更新子路径）
`move_items(db, ids, target_folder_id)`	移动文件（循环依赖检查）
`delete_item(db, id)`	删除（递归删除子项+存储文件）
`batch_delete(db, ids)`	批量删除

文件查询

方法	说明
`get_by_storage_path(db, path)`	根据存储路径获取
`get_by_md5(db, md5)`	根据 MD5 获取（秒传）
`has_children(db, folder_id)`	检查是否有子项
`get_parent(db, file_id)`	获取父文件夹
`increment_download_count(db, file_id)`	增加下载次数

文件内容

方法	说明
`get_file_content(db, file_id)`	获取文件内容（bytes）
`get_file_as_base64(db, file_id)`	获取 Base64 编码
`get_file_as_data_url(db, file_id)`	获取 Data URL
`get_file_text_content(db, file_id, max_length)`	提取文本内容

文件自动归类

方法	说明
`get_or_create_source_folder(db, source)`	获取/创建来源文件夹

来源映射：

source	文件夹名称
`announcement`	公告附件
`workflow`	工作流附件
`chat`	聊天文件
`form`	表单附件
`avatar`	头像
`ai_platform`	AI平台文件

AI 能力

方法	说明
`recognize_image_with_ocr(db, file_id)`	图片 OCR（qwen-vl-ocr）
`recognize_file_with_function_calling(db, file_id, schema)`	结构化提取

FileAccessTokenService

临时访问令牌服务：

方法	说明
`create_token(db, file_id, expires_in, user_id)`	创建令牌
`verify_token(db, token)`	验证令牌
`revoke_token(db, token)`	撤销令牌
`cleanup_expired_tokens(db)`	清理过期令牌

存储后端

抽象基类 StorageBackend：

python

class StorageBackend:
    def save(self, file_content, filename) -> str: ...
    def delete(self, storage_path) -> bool: ...
    def exists(self, storage_path) -> bool: ...
    def get_url(self, storage_path) -> str: ...
    def get_size(self, storage_path) -> int: ...
    def calculate_md5(self, file_content) -> str: ...

实现类

类	说明
`LocalStorageBackend`	本地存储（media/file_manager）
`OSSStorageBackend`	阿里云 OSS
`MinioStorageBackend`	MinIO（支持预签名 URL）
`AzureBlobStorageBackend`	Azure Blob Storage

API 接口

文件操作

方法	路径	说明
POST	`/upload`	上传文件
POST	`/folder`	创建文件夹
GET	`/`	获取文件列表
GET	`/tree`	获取文件夹树
GET	`/{file_id}`	获取文件详情
PUT	`/{id}/rename`	重命名
PUT	`/{id}/public`	设置公开状态
PUT	`/move`	移动文件
DELETE	`/{id}`	删除文件
POST	`/batch/delete`	批量删除

文件访问

方法	路径	说明
GET	`/url/{file_id}`	获取文件 URL
GET	`/batch/urls`	批量获取 URL
GET	`/stream/{file_id}`	流式访问（需 token）
GET	`/proxy/{file_id}`	代理访问（需 token）
GET	`/file/download`	下载文件

分块上传

方法	路径	说明
POST	`/chunk/init`	初始化（含秒传检查）
POST	`/chunk/upload`	上传分块
GET	`/chunk/status`	查询进度
POST	`/chunk/merge`	合并分块
DELETE	`/chunk/cancel`	取消上传

临时令牌

方法	路径	说明
POST	`/access-token`	创建令牌
GET	`/access-token/url/{file_id}`	获取带令牌的 URL
DELETE	`/access-token/{token}`	撤销令牌
POST	`/access-token/cleanup`	清理过期令牌

AI 识别

方法	路径	说明
POST	`/ocr/recognize`	OCR 识别

存储配置

方法	路径	说明
GET	`/storage/config`	获取存储配置
PUT	`/storage/config`	更新存储配置

请求/响应示例

上传文件

请求：

POST /api/core/file_manager/upload
Content-Type: multipart/form-data

file: (binary)
parentId: folder001
source: form
isPublic: false

响应：

json

{
  "id": "file001",
  "name": "document.pdf",
  "file_type": "file",
  "file_size": 1024000,
  "file_ext": "pdf",
  "mime_type": "application/pdf",
  "storage_type": "local",
  "is_public": false,
  "source": "form"
}

初始化分块上传

请求：

json

POST /api/core/file_manager/chunk/init
{
  "filename": "large-video.mp4",
  "totalSize": 104857600,
  "chunkSize": 5242880,
  "fileHash": "abc123..."
}

响应：

json

{
  "uploadId": "upload001",
  "chunkSize": 5242880,
  "totalChunks": 20,
  "uploadedChunks": [],
  "fileExists": false,
  "fileId": null
}

OCR 识别

请求：

json

POST /api/core/file_manager/ocr/recognize
{
  "fileId": "file001",
  "outputSchema": {
    "name": "string",
    "amount": "number"
  },
  "prompt": "提取发票信息"
}

响应：

json

{
  "success": true,
  "rawText": "发票内容...",
  "extractedData": {
    "name": "商品名称",
    "amount": 100.00
  }
}

文件访问控制

公开文件

is_public=true 的文件可直接通过 /stream/{file_id} 访问。

私有文件

需要临时访问令牌：

调用 /access-token 创建令牌（默认 1 小时有效）
使用 /stream/{file_id}?token={token} 访问

与其他模块的关系

表单模块：表单附件上传时 source=form
工作流模块：流程附件上传时 source=workflow
AI 平台：AI 对话文件上传时 source=ai_platform
用户模块：头像上传时 source=avatar

文件管理模块 ​

概述 ​

数据模型 ​

FileManager（文件/文件夹） ​

FileAccessToken（临时访问令牌） ​

存储类型 (storage_type) ​

服务层 ​

FileManagerService ​

文件操作 ​

文件查询 ​

文件内容 ​

文件自动归类 ​

AI 能力 ​

FileAccessTokenService ​

存储后端 ​

实现类 ​

API 接口 ​

文件操作 ​

文件访问 ​

分块上传 ​

临时令牌 ​

AI 识别 ​

存储配置 ​

请求/响应示例 ​

上传文件 ​

初始化分块上传 ​

OCR 识别 ​

文件访问控制 ​

公开文件 ​

私有文件 ​

与其他模块的关系 ​

文件管理模块

概述

数据模型

FileManager（文件/文件夹）

FileAccessToken（临时访问令牌）

存储类型 (storage_type)

服务层

FileManagerService

文件操作

文件查询

文件内容

文件自动归类

AI 能力

FileAccessTokenService

存储后端

实现类

API 接口

文件操作

文件访问

分块上传

临时令牌

AI 识别

存储配置

请求/响应示例

上传文件

初始化分块上传

OCR 识别

文件访问控制

公开文件

私有文件

与其他模块的关系