---
url: /docs/recipes/file-uploads.md
---
# 文件上传

## 当前实现

私有文件 API 与定时清理已通过本地 Workers 验收；文件工作台和两个生成站的完整流程仍待 I2，云端资源未部署。配置、请求格式、迁移、错误代码及排查以[私有文件存储教程](../agentbuff-stack/files-storage)为准。

```mermaid
flowchart LR
  U[登录账号发送二进制] --> V[服务端检查来源、身份、格式与大小]
  V --> Q[事务预留数量和字节]
  Q --> S[通过私有 R2 绑定写对象]
  S --> M[标记元数据可读取]
  M --> D[会话授权读取或下载]
  M --> C[定时批次清理与配额释放]
```

元数据使用 tRPC，二进制使用 Hono。服务端原生 R2 绑定负责读写，当前无需 S3 访问密钥、浏览器直传许可或桶 CORS。文件名与客户端 MIME 只作提示，实际内容需通过检查。

## 扩展新类型

先确认真实产品是否需要服务器保存文件；纯客户端处理可以避免上传。增加 PDF、SVG、视频或其他输入时，在 `apps/api/lib/files/validation.ts` 增加实际格式检查，明确最大大小、可执行内容的下载方式和保留策略，再补前端与真实样例验收。仅添加 MIME 字符串或上传控件不能构成安全支持。

首版文件归个人所有，切换组织不改变所有权。团队共享需另定义真实成员授权；异步任务的文件引用、删除与结果保留在 I4 接入，当前不能将正在执行的任务当成已有功能。外部 URL 输入还需独立实现网络范围、重定向、大小和超时限制。

## 故障与验证

数据库与 R2 之间使用显式补偿，不能共同事务提交。失败上传不可下载，确认对象删除后才释放额度；失败删除保留占用，由定时批次重试。孤立对象扫描只处理本站前缀并使用持久化游标，未知对象保留至少一小时。

运行 `bun files:validate` 验证真实本地 Worker 的四种类型、下载字节、摘要、跨账号拒绝、过期拒绝、删除和定时清理。并发配额与故障恢复另由实际迁移及 R2 测试覆盖。云端绑定、触发和限制需要真实环境单独验收。