文件存储 API

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

基础路径

/storage/:projectId

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

认证方式

所有端点均需要认证：

JWT Bearer Token 或 API Key：走 combinedAuth 中间件，按既有项目权限检查。
OAuth Access Token（wno-...）：走 route-local oauthAuth + oauthScopeGuard。当前 mobile:full scope 仅允许 POST /storage/:projectId/upload，其他 storage 路由会返回 403 insufficient_scope。

权限说明

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

端点列表

1. 获取文件列表

GET /storage/:projectId/files

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

展示去重：同一内容多次上传会复用物理存储但产生多行逻辑记录，列表返回前会按 (folder_key, content_hash) 去重，同 key 仅保留 created_at 最新一条。content_hash 为空的历史文件和磁盘同步文件（relative_path 非空）不参与去重、原样返回。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Query 参数

参数	类型	必填	说明
`folderKey`	string	否	文件夹 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

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

认证：JWT / API Key，或 OAuth Access Token（需 mobile:full scope）。OAuth 上传仍复用 auth.userId 做项目访问、写权限和文件 owner 归属检查。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（multipart/form-data）

参数	类型	必填	说明
`file`	File	是	上传的文件
`folderKey`	string	否	目标文件夹 key（仅允许字母数字下划线连字符）
`knowledgeBaseTag`	string	否	知识库标签（触发自动向量化）
`source`	string	否	来源标识
`sourceRef`	string	否	来源引用
`fileType`	string	否	文件类型约束：`image` / `audio` / `pdf` / `csv`
`metadata`	string	否	JSON object 字符串（最大 64 KB），解析后整体写入 `files.metadata.deviceMetadata` 安全 namespace（不覆盖 `originalName` / `source` / `sourceRef` / `thumbnailPath` 等系统键）。非法 JSON、非 object 或超限返回 400；不可作为文件部分上传（`-F metadata=@x.json` 会被拒）

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

fileType	最大大小	允许的 MIME 类型
`image`	10 MB	`image/*`
`audio`	50 MB	`audio/*`
`pdf`	20 MB	`application/pdf`
`csv`	10 MB	`text/csv`、`application/vnd.ms-excel` 或 `.csv` 后缀

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

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

响应 200

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "photo.jpg",
  "path": "8fa76c5e-1c2e-4eb7-905b-d0c0971ac7f2/1706284800000_abc123_photo.jpg",
  "signedUrl": "https://storage.supabase.co/object/sign/...",
  "mimeType": "image/jpeg",
  "sizeBytes": 1024000,
  "metadata": { "originalName": "photo.jpg" },
  "folderKey": null,
  "pinned": false,
  "contentHash": "<sha256-hex>"
}

字段为 camelCase（name / mimeType / sizeBytes …）。完整字段见内部文档 docs/features/storage/api.md。 contentHash 是后端对文件内容计算的 SHA-256（hex），可用于客户端上传后对账。仅去重路径（普通项目文件）有值；_disks、ROMP 等非去重路径为 null。请以 contentHash 为准，不要把 path 里 _cas/.../{hash} 形式当作接口契约。传入 metadata 时，文件记录会在 metadata.deviceMetadata 下携带你上传的对象。

错误码

状态码	说明
400	未提供文件、文件大小超限、文件类型不匹配、folderKey 格式无效、fileType 不支持，或 `metadata` 非法 JSON / 非 object / 超过 64 KB
401	未认证，或 OAuth token 无效、过期、撤销
403	无写入权限，或 OAuth token 有效但缺少 `mobile:full` scope（`insufficient_scope`）
404	项目不存在或无权访问
500	上传失败

3. 移动文件到根目录

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

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

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

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

响应 200

json

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

错误码

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

4. 删除文件

DELETE /storage/:projectId/files/:fileId

删除指定文件。

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`fileId`	string	是	文件 ID

响应 200

json

{
  "success": true
}

错误码

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

5. 获取签名下载 URL

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

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

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`fileId`	string	是	文件 ID

响应 200

json

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

错误码

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

5.1 获取单文件信息（2026-06-10 新增）

GET /storage/:projectId/files/:fileId

按 id 返回单个文件的元数据与签名 URL（VFS 存储节点预览使用，避免为单个文件翻整个列表）。

响应 200

json

{
  "id": "uuid",
  "name": "原始文件名.png",
  "mimeType": "image/png",
  "sizeBytes": 102400,
  "createdAt": "2026-06-10T08:00:00.000Z",
  "folderKey": null,
  "url": "https://...signed",
  "thumbnailUrl": "https://...signed"
}

状态码	说明
404	项目不存在或无权访问
500	文件不存在或获取失败

6. 获取预览 URL

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

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

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID
`fileId`	string	是	文件 ID

响应 200

json

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

错误码

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

7. 获取存储限制信息

GET /storage/:projectId/limits

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

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

响应 200

json

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

错误码

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

8. 创建文件夹

POST /storage/:projectId/folders

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

Path 参数

参数	类型	必填	说明
`projectId`	string	是	项目 ID

Body 参数（JSON）

参数	类型	必填	说明
`name`	string	是	文件夹名称
`parentKey`	string	否	父文件夹 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。

文件存储 API ​

基础路径 ​

认证方式 ​

权限说明 ​

端点列表 ​

1. 获取文件列表 ​

2. 上传文件 ​

3. 移动文件到根目录 ​

4. 删除文件 ​

5. 获取签名下载 URL ​

5.1 获取单文件信息（2026-06-10 新增） ​

6. 获取预览 URL ​

7. 获取存储限制信息 ​

8. 创建文件夹 ​

源码 ​

补充端点 ​

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

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

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

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

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

GET /storage/:projectId/files/trash ​

GET /storage/:projectId/folder-stats ​

文件存储 API

基础路径

认证方式

权限说明

端点列表

1. 获取文件列表

2. 上传文件

3. 移动文件到根目录

4. 删除文件

5. 获取签名下载 URL

5.1 获取单文件信息（2026-06-10 新增）

6. 获取预览 URL

7. 获取存储限制信息

8. 创建文件夹

源码

补充端点

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

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

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

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

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

GET /storage/:projectId/files/trash

GET /storage/:projectId/folder-stats