wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-09 File Storage 基础版 #9

New Issue
Open
opened 2026-05-22 21:00:15 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:15 +08:00
Owner
Copy Link

目标

设计知习后端文件存储模块，为全系统提供统一的对象存储访问能力，封装 COS 上传签名、objectKey 管理、文件元数据和解析结果回写。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习的用户上传资料（PDF/DOCX/图片等）需要存储在腾讯云 COS 上，解析后的 parsed.md 也需要回写到 COS。服务器只做临时拉取处理，不长期存储用户文件。

File Storage 模块负责统一管理所有文件的外部存储访问，业务模块不需要知道 COS SDK 的细节，只管"我要上传一个文件"或"我要获取一个文件的下载地址"。

模块职责

  1. 本模块负责：

    • COS 上传签名生成（临时授权，服务端签名）
    • objectKey 生成规则（按用户/知识库/文件类型组织路径）
    • 文件元数据管理（大小、类型、MD5、上传时间）
    • 解析结果（parsed.md）回写到 COS
    • 文件下载（生成临时访问 URL）
    • 文件删除（软删除 + COS 异步清理队列）
    • 备份文件上传

  2. 本模块不负责：

    • 文件内容解析（走 Ingestion Module）
    • 文件上传后的业务处理流程（走 Ingestion Module）
    • 用户可用的存储空间额度管理（走 Quota Module）
    • 数据备份策略（走 Backup Module）

候选数据对象

  • File（文件元数据）
  • FileObject（COS 上的对象记录）
  • StorageObject
  • CosUploadSession（上传会话）
  • FileCleanupJob（文件清理任务）

基础设施依赖判断

  • MySQL：是（文件元数据）
  • Redis：否（或用于上传会话临时状态）
  • BullMQ：是（文件异步删除队列）
  • Qdrant：否
  • AI Gateway：否
  • COS：是（核心存储依赖）
  • Config：是（COS 配置、bucket 名称等）

API 设计

  1. CAPI：

    • 获取上传签名（/api/files/upload-signature）
    • 确认上传完成（/api/files/upload-complete）

  2. AAPI：

    • 文件列表（按用户/知识库筛选）
    • 文件详情
    • 手动触发文件删除/清理

  3. IAPI：

    • 内部文件下载（供 Ingestion/Worker 使用）
    • 批量文件状态查询

Domain Event 设计

  • FileUploaded：文件上传完成
  • FileDeleted：文件删除
  • FileCleanupCompleted：文件清理完成

Admin 视图设计

  1. 文件管理页：
    • 文件列表（文件名、大小、类型、上传者、关联知识库、上传时间）
    • 文件详情（COS 路径、MD5、状态）
    • 手动清理操作

安全设计

  • 上传签名必须有有效期和用户绑定
  • 禁止 C 端直接访问其他用户的文件
  • 文件删除需软删除标记 + 异步 COS 清理

交付检查

  • 路由归属：CAPI + AAPI + IAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：需判断
  • 是否需要 BullMQ：是
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：是（上传文件需经过内容审核）
  • 是否需要 Cost 记录：是（存储空间消耗）
  • 是否需要 AuditLog：是（手动删除操作）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. COS 上传签名生成方案
  2. objectKey 命名规则设计
  3. File / FileObject Prisma schema
  4. 文件上传完整流程设计（获取签名 → 客户端上传 → 确认完成）
  5. parsed.md 回写方案
  6. 文件删除和 COS 清理方案
  7. Admin 文件管理视图设计
  8. 集成测试覆盖上传/下载/删除流程

禁止事项

  • 禁止服务器长期存储用户文件（应存 COS，服务器仅临时拉取处理）
  • 禁止上传签名不设有效期
  • 禁止上传签名不绑定用户身份
  • 禁止文件物理删除同步执行（应先软删除标记，异步清理 COS）
  • 禁止业务模块直接调用 COS SDK（必须走 File Storage）

不建议当前阶段实现

  • 多存储后端支持（先只做 COS）
  • 文件版本管理
  • 文件秒传（基于 MD5 去重）
  • CDN 加速配置
## 目标 设计知习后端文件存储模块，为全系统提供统一的对象存储访问能力，封装 COS 上传签名、objectKey 管理、文件元数据和解析结果回写。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习的用户上传资料（PDF/DOCX/图片等）需要存储在腾讯云 COS 上，解析后的 parsed.md 也需要回写到 COS。服务器只做临时拉取处理，不长期存储用户文件。 File Storage 模块负责统一管理所有文件的外部存储访问，业务模块不需要知道 COS SDK 的细节，只管"我要上传一个文件"或"我要获取一个文件的下载地址"。 ## 模块职责 1. 本模块负责： - COS 上传签名生成（临时授权，服务端签名） - objectKey 生成规则（按用户/知识库/文件类型组织路径） - 文件元数据管理（大小、类型、MD5、上传时间） - 解析结果（parsed.md）回写到 COS - 文件下载（生成临时访问 URL） - 文件删除（软删除 + COS 异步清理队列） - 备份文件上传 2. 本模块不负责： - 文件内容解析（走 Ingestion Module） - 文件上传后的业务处理流程（走 Ingestion Module） - 用户可用的存储空间额度管理（走 Quota Module） - 数据备份策略（走 Backup Module） ## 候选数据对象 - File（文件元数据） - FileObject（COS 上的对象记录） - StorageObject - CosUploadSession（上传会话） - FileCleanupJob（文件清理任务） ## 基础设施依赖判断 - MySQL：是（文件元数据） - Redis：否（或用于上传会话临时状态） - BullMQ：是（文件异步删除队列） - Qdrant：否 - AI Gateway：否 - COS：是（核心存储依赖） - Config：是（COS 配置、bucket 名称等） ## API 设计 1. CAPI： - 获取上传签名（/api/files/upload-signature） - 确认上传完成（/api/files/upload-complete） 2. AAPI： - 文件列表（按用户/知识库筛选） - 文件详情 - 手动触发文件删除/清理 3. IAPI： - 内部文件下载（供 Ingestion/Worker 使用） - 批量文件状态查询 ## Domain Event 设计 - FileUploaded：文件上传完成 - FileDeleted：文件删除 - FileCleanupCompleted：文件清理完成 ## Admin 视图设计 1. 文件管理页： - 文件列表（文件名、大小、类型、上传者、关联知识库、上传时间） - 文件详情（COS 路径、MD5、状态） - 手动清理操作 ## 安全设计 - 上传签名必须有有效期和用户绑定 - 禁止 C 端直接访问其他用户的文件 - 文件删除需软删除标记 + 异步 COS 清理 ## 交付检查 - [ ] 路由归属：CAPI + AAPI + IAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：需判断 - [ ] 是否需要 BullMQ：是 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：是（上传文件需经过内容审核） - [ ] 是否需要 Cost 记录：是（存储空间消耗） - [ ] 是否需要 AuditLog：是（手动删除操作） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. COS 上传签名生成方案 2. objectKey 命名规则设计 3. File / FileObject Prisma schema 4. 文件上传完整流程设计（获取签名 → 客户端上传 → 确认完成） 5. parsed.md 回写方案 6. 文件删除和 COS 清理方案 7. Admin 文件管理视图设计 8. 集成测试覆盖上传/下载/删除流程 ## 禁止事项 - 禁止服务器长期存储用户文件（应存 COS，服务器仅临时拉取处理） - 禁止上传签名不设有效期 - 禁止上传签名不绑定用户身份 - 禁止文件物理删除同步执行（应先软删除标记，异步清理 COS） - 禁止业务模块直接调用 COS SDK（必须走 File Storage） ## 不建议当前阶段实现 - 多存储后端支持（先只做 COS） - 文件版本管理 - 文件秒传（基于 MD5 去重） - CDN 加速配置
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:15 +08:00
wangdl self-assigned this 2026-05-22 21:00:15 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#9
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?