WaiNao.AI

主题

文件存储 API ​

管理项目文件的上传、下载、删除和预览，支持文件夹管理和存储限制查询。

基础路径 ​

/storage/:projectId

注意：存储 API 的基础路径是 /storage，与其他项目 API 的 /projects 前缀不同。

认证方式 ​

所有端点均需要 JWT Bearer Token 或 API Key 认证（combinedAuth 中间件）。

权限说明 ​

  • 读取操作（GET）：需要项目访问权限（项目所属团队成员）
  • 写入操作（POST / DELETE / PATCH）：额外检查写入权限（write / admin，或团队成员默认读写权限）

端点列表 ​

1. 获取文件列表 ​

GET /storage/:projectId/files

获取项目的文件列表，支持按文件夹过滤。

Path 参数

参数类型必填说明
projectIdstring是项目 ID

Query 参数

参数类型必填说明
folderKeystring否文件夹 key。不传=全部文件，空字符串=根目录文件，有值=指定文件夹内的文件

响应 200

json
{
  "files": [
    {
      "id": "uuid",
      "file_name": "photo.jpg",
      "mime_type": "image/jpeg",
      "size": 1024000,
      "folder_key": "",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

错误码

状态码说明
401未认证
404项目不存在或无权访问
500获取文件列表失败

2. 上传文件 ​

POST /storage/:projectId/upload

上传文件到项目存储。支持文件类型校验、大小限制检查和知识库工作流触发。

Path 参数

参数类型必填说明
projectIdstring是项目 ID

Body 参数（multipart/form-data）

参数类型必填说明
fileFile是上传的文件
folderKeystring否目标文件夹 key（仅允许字母数字下划线连字符）
knowledgeBaseTagstring否知识库标签（触发自动向量化）
sourcestring否来源标识
sourceRefstring否来源引用
fileTypestring否文件类型约束：image / audio / pdf / csv

文件类型限制（当指定 fileType 时）

fileType最大大小允许的 MIME 类型
image10 MBimage/*
audio50 MBaudio/*
pdf20 MBapplication/pdf
csv10 MBtext/csv、application/vnd.ms-excel 或 .csv 后缀

未指定 fileType 时，按订阅计划的文件大小限制检查。

知识库自动向量化：当同时提供 knowledgeBaseTag 且文件 MIME 类型受支持时（文本、图片、视频、PDF、Word），自动触发知识库工作流。

响应 200

json
{
  "id": "uuid",
  "path": "projects/xxx/files/photo.jpg",
  "file_name": "photo.jpg",
  "mime_type": "image/jpeg",
  "size": 1024000
}

错误码

状态码说明
400未提供文件、文件大小超限、文件类型不匹配、folderKey 格式无效或 fileType 不支持
401未认证
403无写入权限
404项目不存在或无权访问
500上传失败

3. 移动文件到根目录 ​

PATCH /storage/:projectId/files/move-to-root

将指定文件夹下的文件移到根目录。

Path 参数

参数类型必填说明
projectIdstring是项目 ID

Body 参数（JSON）

参数类型必填说明
folderKeysstring[]是要移动文件的文件夹 key 数组（非空）

响应 200

json
{
  "success": true,
  "movedCount": 5
}

错误码

状态码说明
400folderKeys 为空数组
401未认证
403无写入权限
404项目不存在或无权访问
500移动文件失败

4. 删除文件 ​

DELETE /storage/:projectId/files/:fileId

删除指定文件。

Path 参数

参数类型必填说明
projectIdstring是项目 ID
fileIdstring是文件 ID

响应 200

json
{
  "success": true
}

错误码

状态码说明
401未认证
403无写入权限
404项目不存在或无权访问
500删除失败

5. 获取签名下载 URL ​

GET /storage/:projectId/files/:fileId/signed-url

获取文件的签名下载 URL（临时有效）。

Path 参数

参数类型必填说明
projectIdstring是项目 ID
fileIdstring是文件 ID

响应 200

json
{
  "url": "https://storage.example.com/signed/..."
}

错误码

状态码说明
401未认证
404项目不存在或无权访问
500获取下载链接失败

6. 获取预览 URL ​

GET /storage/:projectId/files/:fileId/preview-url

获取文件的预览 URL。优先返回缩略图 URL，如果没有缩略图则返回原图签名 URL。

Path 参数

参数类型必填说明
projectIdstring是项目 ID
fileIdstring是文件 ID

响应 200

json
{
  "url": "https://storage.example.com/preview/...",
  "isThumbnail": true
}

错误码

状态码说明
401未认证
404项目不存在或无权访问
500获取预览链接失败

7. 获取存储限制信息 ​

GET /storage/:projectId/limits

获取项目的存储限制信息（基于订阅计划）。

Path 参数

参数类型必填说明
projectIdstring是项目 ID

响应 200

json
{
  "maxFileSize": 52428800,
  "usedStorage": 10485760,
  "maxStorage": 1073741824
}

错误码

状态码说明
401未认证
404项目不存在或无权访问
500获取存储限制失败

8. 创建文件夹 ​

POST /storage/:projectId/folders

创建文件夹占位符。实际文件夹数据由前端通过 projectStore 更新 storageFolder 管理，此端点返回生成的 key。

Path 参数

参数类型必填说明
projectIdstring是项目 ID

Body 参数（JSON）

参数类型必填说明
namestring是文件夹名称
parentKeystring否父文件夹 key

响应 200

json
{
  "key": "folder-1709123456-abc123",
  "label": "文件夹名称"
}

错误码

状态码说明
400文件夹名称为空
401未认证
403无写入权限
404项目不存在或无权访问
500创建文件夹失败

源码 ​

  • 路由：apps/backend/src/routes/storage.ts
  • 服务：apps/backend/src/services/storage/
  • 参考文档：文件存储指南

补充端点 ​

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

DELETE /storage/:projectId/files/:fileId/permanent ​

永久删除文件

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID
fileId文件 ID

请求：通常无请求体；删除类接口通过路径参数定位资源，部分接口会执行软删除、释放绑定或撤回流程。

响应：成功时返回 { "success": true } 或等价删除结果；资源不存在、无权限或存在依赖时返回 4xx。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

PATCH /storage/:projectId/files/:fileId/pin ​

置顶文件

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID
fileId文件 ID

请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /storage/:projectId/files/:fileId/restore ​

恢复文件

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID
fileId文件 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

PATCH /storage/:projectId/files/:fileId/unpin ​

取消置顶

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID
fileId文件 ID

请求：请求体为 JSON，传入需要变更的字段；未传字段保持不变。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /storage/:projectId/files/batch-signed-urls ​

批量获取项目文件的临时签名访问 URL。

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回创建或更新后的资源对象，或 { "success": true }。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /storage/:projectId/files/trash ​

回收站列表

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回列表数据，通常包含 items / data / rows 与分页或统计字段。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /storage/:projectId/folder-stats ​

文件夹统计

认证：JWT Bearer Token 或 API Key（combinedAuth）。写入类操作需要项目写权限。 路径参数

参数说明
projectId项目 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

AI Workflow Editor

Copyright 2024-present WaiNao.AI