对象存储

配置存储后可上传头像并使用账号资产管理。Web Cloudflare 使用 R2_BUCKET 绑定访问原生 R2，不需要 S3 密钥。

开始前准备

准备已运行应用和测试账号。创建开发用 R2 bucket。开发与生产资源分开，凭据仅存服务端。

1. 接入存储

原生 R2

创建 R2 bucket，在 apps/web-cloudflare/wrangler.jsonc 设置绑定：

{
  "r2_buckets": [
    { "binding": "R2_BUCKET", "bucket_name": "your-bucket-name" }
  ]
}

将片段合并进现有文件。保留 R2_BUCKET 绑定名，替换 bucket 名称。绑定变化后运行 pnpm cf:typegen。头像经应用需要会话的 /files/avatars/* 读写，不需要公开 R2 域名或 S3 凭据。用 pnpm cf:preview 检查构建后的 Worker，见 Cloudflare 部署。

2. 上传第一个头像

配置完成后重启本地服务。登录并打开 /app/settings/general，选择图片，完成裁剪和上传。然后访问 /app/settings/storage，检查文件列表与用量，下载自己的文件，并删除不再需要的测试资产。

Workers 头像路由接受应用生成的 PNG 头像命名格式，内容非空且不超过 5 MiB。任意文件上传应另外开发专用流程，设置校验与权限。

确认结果

• 头像出现在个人资料中，刷新后仍能显示。
• Storage 设置页列出文件，可以下载。
• 删除测试资产后，列表与用量更新。
• 其他用户无法下载或删除你受会话保护的资产。

常见问题

自定义上传参考

src/server/storage.ts 选择应用 driver。资产 API 在 src/backend/api/routes/assets/，UI 在 src/modules/settings/components/assets/。

对象 key 限定在认证用户下。扩展时保留所有权校验，以及列表/用量缓存刷新。