附件

HamsterBase Tasks 支持为任务和项目添加文件附件。文件会被存储在 S3 兼容 的对象存储服务中，由 你自己 提供和管理——应用本身不会代理你的文件，也不会经过任何 HamsterBase 服务器。

使用前请阅读

• 附件存储在你自己的 S3 服务上，而不是 HamsterBase 的服务器上。 桶的创建、账单与凭据安全都由你负责。
• 附件文件内容不是端到端加密的。 原始文件会直接上传到你的桶中，能读取该桶的人都可以读到这些文件。请通过桶级别的访问控制来保护它们。
• S3 配置仅保存在当前设备本地。 不会同步到其他设备。每一台需要上传、下载或预览附件的设备都需要单独配置。
• 只有附件的 元数据（文件名、大小、MIME 类型、S3 对象 key）会在你的设备之间同步。没有 S3 凭据的设备依然能看到附件列表，但无法读取文件。

你需要准备

任意 S3 兼容的存储都可以使用，常见选择：

• Amazon S3
• Cloudflare R2
• Backblaze B2（S3 兼容端点）
• MinIO（自部署）
• 其他 S3 兼容服务 —— 腾讯云 COS、阿里云 OSS、Wasabi、Garage、SeaweedFS 等

对于要使用的桶，你需要知道：

项	示例
Endpoint URL	https://s3.amazonaws.com、https://<account>.r2.cloudflarestorage.com、http://192.168.1.10:9000
Bucket	my-tasks-attachments
Region	us-east-1、auto（R2）等
Access Key ID	来自 S3 提供商的 IAM / API 凭据页面
Secret Access Key	对应的密钥
Key Prefix（可选）	hamsterbase-tasks/ —— 将所有对象限定在一个前缀下
Force Path Style	MinIO 与许多自部署服务需要开启，详见下文

S3 凭据至少需要对该桶有 put、get、head 对象的权限（以及桶本身的 HeadBucket 权限，连接测试会用到）。

配置

附件配置是 按数据库 维护的。如果你有多个数据库，每个数据库都有自己独立的 S3 配置，保存在当前设备本地。

1. 打开 设置。
2. 进入 附件（Attachments） 标签页。
3. 页面顶部会显示当前配置所属的数据库。如果想配置其它数据库，请先切换到对应数据库。
4. 点击 配置（Configure）（若已存在配置则显示 编辑（Edit））。
5. 填写表单：
   • Endpoint URL —— 含协议头的完整 URL。AWS S3 用 https://s3.amazonaws.com；R2 使用账户专属的 endpoint；MinIO 用你的服务器地址。
   • Bucket —— 桶名（需要事先创建好）。
   • Region —— 桶所在区域。R2 使用 auto。
   • Access Key ID / Secret Access Key —— 具有 put / get / head 权限的凭据。
   • Key Prefix （可选） —— 应用写入对象时统一加上的前缀。如果该桶被多个工具共享，建议设置一个独立前缀。如果你没写结尾的 /，应用会自动补上。
   • Force Path Style （开关） —— 见下文 Force Path Style。
6. 点击 Test Connection（测试连接）。应用会对你的桶调用 HeadBucket，成功时显示 ✓ Connection successful。
7. 点击 Save（保存）。

Force Path Style

默认情况下，S3 客户端使用 虚拟主机风格（virtual-hosted-style） 的 URL：https://<bucket>.<endpoint>/<key>。一些服务无法处理这种格式，需要 路径风格（path-style） ：https://<endpoint>/<bucket>/<key>。

以下情况建议打开此开关：

• MinIO —— 几乎总是需要
• 自部署的 Garage / SeaweedFS / Ceph RGW —— 通常需要
• 任何使用 <bucket>.<endpoint> 形式时报 DNS 或证书错误的 S3 兼容服务

以下情况保持关闭：

• Amazon S3
• Cloudflare R2
• Backblaze B2
• 大多数商用 S3 兼容服务

不确定的话，先关着试一次。如果连接测试或上传报 DNS / TLS 相关错误，再打开重试。

清除配置

点击已保存配置旁边的垃圾桶图标会从当前设备清除配置。已经上传到 S3 的文件不会被删除。 在你重新配置可以访问同一个桶和 key prefix 的 S3 凭据之前，这些附件在应用中将无法访问。要真正删除文件，请直接到 S3 服务里删除。

文件如何存储

每个从 HamsterBase Tasks 上传的附件都会写入到你的桶里这样一个确定的 key：

{keyPrefix}{databaseId}/attachments/{attachmentId}.{ext}

• keyPrefix —— 你在表单中设置的 Key Prefix，若没有结尾的 / 会自动补上；没设置就是空字符串。
• databaseId —— 任务或项目所属的 HamsterBase 数据库 ID。每个数据库都对应前缀下独立的一个目录，因此一个桶可以安全地承载多个数据库。
• attachmentId —— 本地生成的随机唯一 ID。不会 用原始文件名作为 key，所以同名文件不会冲突，应用内重命名也不会移动 S3 中的对象。
• ext —— 原始文件扩展名（小写）。没有扩展名的文件就只用裸 key。

举例。 若 Key Prefix 为 hamsterbase-tasks/，数据库 ID 为 db_abc123，文件名为 Q2-report.pdf：

hamsterbase-tasks/db_abc123/attachments/V1StGXR8_Z5jdHi6B-myT.pdf

缩略图

对于图片附件（SVG 除外），应用会在上传时本地生成一个小尺寸的 JPEG 缩略图，并以 .thumb.jpg 作为后缀写到原对象旁边：

hamsterbase-tasks/db_abc123/attachments/V1StGXR8_Z5jdHi6B-myT.pdf.thumb.jpg

缩略图是“尽力而为”的——即便生成或上传失败，原文件依然会被保存，应用会自动回退到通用文件图标。

删除

应用中的删除是 软删除：元数据被标记为已删除、UI 中隐藏，但 S3 中的对象会保留。要真正释放存储空间，请自己到 S3 中删除对应对象（在 attachments/ 前缀上配置生命周期规则是个方便的做法）。

上传与预览

配置好 S3 之后，每个任务和项目的详情面板都会出现 附件（Attachments） 区域。

• 点击拖拽区域或将文件拖入即可 添加 附件。
• 单台设备最多同时上传 3 个 文件，其余会排队等待。
• 切换数据库或退出登录时，正在进行的上传会被取消。
• 图片附件会显示缩略图，点击后在预览浮层中查看。
• 其他类型的文件可以通过下载按钮下载。

任务和项目的附件数量会作为标签的一部分显示在列表项中。

故障排查

连接测试报 Access Denied 或 403。 凭据没有该桶的 s3:HeadBucket 权限，或桶名 / 区域不对。检查 IAM 策略是否包含目标桶。

连接测试报 DNS 或 TLS 错误。 Endpoint 无法以 <bucket>.<endpoint> 的形式访问。打开 Force Path Style 重试。

上传成功但预览打不开。 通常是 CORS 问题。应用是直接在浏览器中调用 GetObject 读文件的，桶需要允许应用所在的来源（origin）。对自部署 S3，配置一份较宽松的 CORS 策略；对 R2 / S3，添加允许 GET、PUT、HEAD 的 CORS 规则。

换设备后附件全部不可访问。 S3 配置是按设备保存的。在新设备的 设置 → 附件 中重新填写相同的 S3 凭据即可。