S3 存储配置笔记（Garage 自建 / Cloudflare R2）

归档日期：2026-10-11

一、自建 Garage（2026-10-10 部署，2026-10-11 下线）

环境

• Debian 云服务器（2C2G），podman
• 镜像：dxflrs/garage v2.4.1，单节点，sqlite 元数据
• 部署文件曾位于服务器 /data/garage/（已删除）

核心配置

• 启动参数 --single-node --default-bucket：自动完成 layout 初始化、创建 bucket、生成 S3 key
• 按 2GB 内存做调优（小内存机必需）
• 3900 端口只绑定宿主机回环，不直接暴露公网；Caddy HTTPS 反代
• 容器组网 znet，Caddy 以容器名 garage:3900 反代
• 对外域名：zpmuses3.zhaopeng.site（阿里 ESA + Caddy 反代 3900）

S3 参数

• endpoint：https://zpmuses3.zhaopeng.site
• bucket：muse
• region：garage（强制校验，签名时必须用这个值）
• 密钥位置：/data/garage/podman-compose.yml 的 environment（GARAGE_DEFAULT_ACCESS_KEY / GARAGE_DEFAULT_SECRET_KEY）

rclone 配置

[garage]
type = s3
provider = Other
access_key_id = <GARAGE_DEFAULT_ACCESS_KEY>
secret_access_key = <GARAGE_DEFAULT_SECRET_KEY>
endpoint = https://zpmuses3.zhaopeng.site
region = garage
force_path_style = true

挂载：

rclone mount garage:muse /data/markmap/docs/muse --daemon

目录缓存

• --dir-cache-time 默认 5m：经 S3 API 上传的新对象，最长 5 分钟后才在挂载目录可见
• 低频场景保持默认；需要实时可见时重挂加 --dir-cache-time 10s（每次列目录多一次 LIST 请求）

下线步骤（2026-10-11 已执行）

fusermount -u /data/markmap/docs/muse
rclone config delete garage
cd /data/garage && podman-compose down -v -t 0
rm -rf /data/garage
# Caddyfile 删除 zpmuses3 反代段并 reload；ESA 删除 DNS 解析

二、Cloudflare R2（2026-10-11 起在用）

免费额度

• 每月 10GB 标准存储 + 100 万次 A 类操作 + 1000 万次 B 类操作
• 出站流量免费
• 免费额度只覆盖标准存储类，不频繁访问类会产生费用

建桶

• R2 → 创建存储桶，存储类选「标准」
• bucket：zmus3，位置：亚太地区（APAC）
• 自定义域名：不需要（私有读写走 S3 API）

API 令牌

• R2 → 管理 R2 API 令牌 → 创建令牌
• 权限：读写；作用域：仅限定到 zmus3 桶

S3 参数

• endpoint：https://91b76c6250566091ddc7ad7ab0c450dc.r2.cloudflarestorage.com
• bucket：zmus3
• region：auto
• 地址风格：path-style，签名 s3v4

rclone 配置

[zmus3]
type = s3
provider = Cloudflare
access_key_id = <R2 Access Key ID>
secret_access_key = <R2 Secret Access Key>
endpoint = https://91b76c6250566091ddc7ad7ab0c450dc.r2.cloudflarestorage.com
region = auto

挂载：

rclone mount zmus3:zmus3 /data/markmap/docs/zmus3 --vfs-cache-mode writes --daemon

--vfs-cache-mode writes 只影响经挂载点写入的行为；新对象可见速度只看 --dir-cache-time（S3 不支持 poll，只能等目录缓存过期）。

三、使用约定

• 「放到我 S3 存储里」= 上传到 R2 zmus3 桶
• 每次传文件时在聊天里贴 Access Key ID 和 Secret 两个值，用完销毁、永不存档
• endpoint / 桶名 / region 已固定，无需重复提供
• 文件落地后经服务器 rclone 挂载可见，挪到 /data/markmap/docs 后可经自有域名对外访问