对象存储
接入对象存储、上传第一个头像，并检查资产列表。
配置存储后可上传头像并使用账号资产管理。Web 使用 S3 兼容对象存储与签名 URL。
开始前准备
准备已运行应用和测试账号。准备 bucket、API endpoint、限定权限的凭据与头像公开读地址。开发与生产资源分开，凭据仅存服务端。
1. 接入存储
S3 兼容 Bucket
在所选 S3 兼容服务商创建 bucket，获取 endpoint 和限定权限的凭据，填写 apps/web/.env.local：
S3_ENDPOINT="https://YOUR_S3_ENDPOINT"
S3_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
S3_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
S3_REGION="auto"
S3_AVATARS_BUCKET="avatars"
S3_AVATARS_PROXY_URL="https://YOUR_PUBLIC_READ_BASE"region 使用服务商实际要求。S3_AVATARS_BUCKET 必须是已创建 bucket 的名称，avatars 只是默认值。读地址是相对对象 key 可以访问的 URL 前缀，不一定与 S3 API endpoint 相同。
浏览器通过签名 URL 直传。配置 bucket CORS，允许开发 origin（http://localhost:3000）和生产 origin，以及上传流程需要的方法。使用公开预览前缀时，另行配置对象公开读权限或读代理。
2. 上传第一个头像
配置完成后重启本地服务。登录并打开 /app/settings/general，选择图片，完成裁剪和上传。然后访问 /app/settings/storage，检查文件列表与用量，下载自己的文件，并删除不再需要的测试资产。
确认结果
- 头像出现在个人资料中，刷新后仍能显示。
- Storage 设置页列出文件，可以下载。
- 删除测试资产后，列表与用量更新。
- 其他用户无法下载或删除你受会话保护的资产。
常见问题
| 问题 | 处理方式 |
|---|---|
Node 返回 503 STORAGE_ENV_MISSING | 检查必需 S3 凭据，重启服务 |
| 签名上传被浏览器拦截 | 检查 bucket CORS 与实际开发/生产 origin |
| 上传成功但预览失败 | 检查读地址和对象读取权限；API endpoint 不一定是公开读 URL |
自定义上传参考
src/server/storage.ts 选择应用 driver。资产 API 在 src/backend/api/routes/assets/，UI 在 src/modules/settings/components/assets/。
| API | 用途 |
|---|---|
GET /api/assets | 文件分页，默认 50、最大 100 |
GET /api/assets/usage | 对象数与字节数，最多聚合 10,000 对象 |
POST /api/assets/download-url | 签名下载 URL（900 秒） |
POST /api/assets/delete | 最多 200 个 key，返回逐项结果 |
对象 key 限定在认证用户下。扩展时保留所有权校验，以及列表/用量缓存刷新。