MinIO 替代，使用 Garage 自建对象存储服务教程及常见问题的解决

Posted on by 聞其詳

熟悉我的朋友都知道我倡导使用开源项目自建基础设施，从大公司手中取回自己的数据。对象存储方面，我曾经写过一篇《使用 MinIO 自建对象存储服务器教程及常见问题的解决》，无奈 MinIO 项目采取了自毁行为，关闭了开源这条道路，我只能被迫更换项目，重新部署我的自建对象存储服务。

经过反复对比 RustFS, Ceph 等项目，我最终选择了 Garage ，这是一个来自法国的开源项目，官方主页 https://garagehq.deuxfleurs.fr/ 经过一番摸索，终于成功搭建，并开始逐步替代我的 MinIO 服务器。

安装 docker compose

自建开源服务绝大多数都是用 docker compose，因为方便部署安装以及迁移，官方指令教程如下，以 Debian 为例：

sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo “$VERSION_CODENAME”)
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装 caddyserver

我们使用 caddy 作为 webserver, 安装很简单

sudo apt install caddy

目录结构

安装完 docker compose 和 caddy 后，我们正式进入部署过程，建立文件夹：garage-object-storage 或者任何你想要的文件夹名称。下面是目录结构

├── docker-compose.yml
├── garage.toml
├── meta/ (自动生成，存储数据库与元数据)
└── data/ (自动生成，存储实际的 S3 对象数据)

创建 garage.toml

这是 Garage 的核心配置文件。在当前目录创建 garage.toml，并务必修改其中的 secret 和 token。 请格外注意 rpc_secret 这里，不能随便填写，需要是64位英文和数字组成的字符串，可参见文末的“坑点”

# 存储路径配置 (已通过 docker-compose 映射到了外部的 ./meta 和 ./data)
metadata_dir = “/var/lib/garage/meta”
data_dir = “/var/lib/garage/data”
db_engine = “sqlite”
metadata_auto_snapshot_interval = “6h”

# 针对单台 VPS 部署，数据副本数必须设置为 1
replication_factor = 1
compression_level = 2

# RPC 配置 (节点间内部通信)
rpc_bind_addr = “[::]:3901”
rpc_public_addr = “127.0.0.1:3901”
rpc_secret = “YOUR_SUPER_SECRET_RPC_KEY” # 【重要】修改为一个64位随机字符串

[s3_api]
s3_region = “garage”
api_bind_addr = “[::]:3900”
root_domain = “.s3.yourdomain.com” # 替换为你计划在 Caddy 绑定的 S3 域名

[s3_web] # (可选) 用于 S3 静态网站托管
bind_addr = “[::]:3902”
root_domain = “.web.yourdomain.com”
index = “index.html”

[admin]
api_bind_addr = “[::]:3903”
admin_token = “YOUR_SUPER_SECRET_ADMIN_TOKEN” # 【重要】修改为高强度密码
metrics_token = “YOUR_SUPER_SECRET_METRICS_TOKEN” # 【重要】修改为高强度密码

创建 docker-compose.yml

考虑到服务器上已经有了 Caddy，将端口直接绑定在宿主机的 127.0.0.1 上是最安全的做法，这样可以避免 API 后台直接裸露在公网。下面是 docker-compose.yml 文件内容

 

services:
garage:
image: dxflrs/garage:v2.0.0
container_name: garage
restart: unless-stopped
volumes:
– ./garage.toml:/etc/garage.toml:ro
– ./meta:/var/lib/garage/meta
– ./data:/var/lib/garage/data
ports:
# 仅绑定到 localhost，由外层的 Caddy 进行 SSL 终结与反代
– “127.0.0.1:3900:3900” # S3 API (应用读写 S3 时使用)
– “127.0.0.1:3901:3901” # RPC 通信
– “127.0.0.1:3902:3902” # S3 Web 静态托管 (如不需要可注释)
– “127.0.0.1:3903:3903” # Admin API (供 WebUI 内部调用)
networks:
– s3_network

webui:
image: khairul169/garage-webui:latest
container_name: garage-webui
restart: unless-stopped
volumes:
# WebUI 会直接读取 garage.toml 来获取端口和 Token 配置
– ./garage.toml:/etc/garage.toml:ro
ports:
– “127.0.0.1:3909:3909” # WebUI 访问端口
environment:
# 通过 Docker 内部网络名直接通信
API_BASE_URL: “http://garage:3903”
S3_ENDPOINT_URL: “http://garage:3900”

# (可选配置) 如果你想给 WebUI 加上基础的账号密码验证，取消下面两行的注释。
# 可在 VPS 终端运行 htpasswd -nbBC 10 “admin” “password” 生成哈希值填入
# AUTH_USER_PASS: “admin:$2y$10$…”
networks:
– s3_network

networks:
s3_network:
name: garage_s3_network

使用 caddy 反代

# 1. 暴露给自己的 WebUI 管理面板
ui.yourdomain.com {
reverse_proxy 127.0.0.1:3909
}

# 2. 暴露给程序调用的实际 S3 API 地址
s3.yourdomain.com {
reverse_proxy 127.0.0.1:3900
}

启动服务

配置好上方内容之后，在当前文件夹输入

docker compose up -d

启动服务，并使用你配置好的域名 ui.yourdomain.com 访问，并在 web 界面上添加节点即可使用

注意坑点

  1. 我在这里失败多次，garage 容器一直重启，无法成功运行，发现是因为 garage.toml 中的 rpc_secret 的问题，我失败的原因是我使用 vaultwarden 生成的十几位随机字符，这是不行的，必须是一个精确到 32 字节的十六进制字符串（即 64 个字符，只包含 0-9 和 a-f）标准的 64 位十六进制字符，所以 Garage 刚读取到配置文件，发现密钥格式不对，就立刻“自杀”退出了。Debian 下可以使用命令 openssl rand -hex 32 终端会输出一串类似这样的 64 位纯小写字母和数字的组合：4a1b2c3d4e5f6a9b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b（请复制你自己终端里生成的那一串）
  2. 在图形界面可以进去之后，要先添加节点并 assign 才可以使用
  3. region 的问题， 很多第三方客户端都喜欢“自作主张”地默认使用 us-east-1 当作 region, 所以我们在 garage.toml 中的region 写为 garage, 可能有的客户端无法正常连接，或者能连接但是无法写入。所以想要省心的话，可以直接把 garage.toml 中的 region 设置为：us-east-1。

最后放一个我成功运行的截图

参考资料

  1. https://unixhost.pro/blog/2025/11/webui-for-garage-s3-server/
  2. https://garagehq.deuxfleurs.fr/documentation/quick-start/

发表回复