Garage v2.4.1 Ubuntu 22.04 安装指南

目标：在 Ubuntu 22.04 服务器上从零安装 Garage v2.4.1——Rust 编写的轻量级 S3 兼容分布式对象存储，完成官方静态二进制下载校验、配置文件编写、systemd 托管、单节点集群初始化与 AWS CLI 的 S3 读写全链路验证。已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。

一、环境信息

本文所有命令与回显均在以下环境实测采集：

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Garage 版本：v2.4.1（静态二进制，features：bundled-libs, consul-discovery, fjall, journald, k2v, kubernetes-discovery, lmdb, metrics, sqlite, syslog, telemetry-otlp）
AWS CLI 版本：aws-cli/2.38.1（Python/3.14.6）
安装路径：二进制 /usr/local/bin/garage，配置 /etc/garage.toml，数据目录 /var/lib/garage/{meta,data}
运行用户：系统用户 garage（ruid/gid 999）
端口：3900（S3 API）、3901（RPC 集群通信）、3902（S3 网站）、3903（Admin API）

Garage 是法国 Deuxfleurs 协会开发的轻量级分布式对象存储，单文件静态二进制、无外部依赖（不需要数据库、不需要 etcd/ZooKeeper）、S3 API 兼容，适合自托管与边缘场景。同类对象存储横向对比如下，方便选型定位：

💡 技术拓展：S3 兼容对象存储常见选型对比——

软件语言/形态定位适用场景
MinIO Go，单二进制高性能 S3，功能最全通用自托管、私有云
Garage Rust，单二进制轻量、地理分布式、低资源边缘/同质小集群、多机房弱网
SeaweedFS Go 海量小文件、集成 Filer 海量文件、CDN 回源
Ceph RGW C++ 重量级统一存储大规模生产、块/文件/对象一体
Zenko CloudServer Node.js（Scality S3）云连接器多云聚合场景

本文选择 Garage：单二进制零依赖、内存占用极低（空闲约 30MB 级）、原生支持按地理区域（zone）分布副本，适合中小规模自托管。

软件	语言/形态	定位	适用场景
MinIO	Go，单二进制	高性能 S3，功能最全	通用自托管、私有云
Garage	Rust，单二进制	轻量、地理分布式、低资源	边缘/同质小集群、多机房弱网
SeaweedFS	Go	海量小文件、集成 Filer	海量文件、CDN 回源
Ceph RGW	C++	重量级统一存储	大规模生产、块/文件/对象一体
Zenko CloudServer	Node.js（Scality S3）	云连接器	多云聚合场景

二、前置条件

一台 Ubuntu 22.04 服务器（物理机或虚拟机均可），具备 root 或 sudo 权限；
基础工具：wget、curl、openssl、unzip、ca-certificates（校验与 AWS CLI 安装需要）；
磁盘空间：元数据与数据目录建议预留至少 2GB（实测演示环境分配 1GB 逻辑容量即可跑通全流程）；
若服务器在国外网络环境受限，下载可通过 HTTP 代理（如 export https_proxy=http://192.168.1.62:7897）。

安装基础依赖：

apt-get update && apt-get install -y wget curl openssl unzip ca-certificates

实测回显（已安装时输出节选）：

0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

三、版本选型说明

Garage 的发布渠道为官网 _releases 目录与 GitHub tag（GitHub Releases 页面为空，以 tag 为准）。通过 GitHub API 实测查询最新 tag：

curl -s "https://api.github.com/repos/deuxfleurs-org/garage/tags?per_page=10" | python3 -c "import json,sys; [print(t['name']) for t in json.load(sys.stdin)]"

实测回显：

v2.4.1
v2.4.0
v2.3.0
v2.2.0
v2.1.0
v2.0.0
v2.0.0-rc1
v2.0.0-beta1
v1.99.3-internal
v1.99.2-internal

版本线	最新版本	说明
v2.x（当前主线）	v2.4.1	推荐；自 v2.0 起配置改用 `replication_factor` + `consistency_mode`
v1.x（旧主线）	v1.x	已停止新特性开发，配置用旧键 `replication_mode`

💡 技术拓展：副本（复制）策略对比——Garage v2.x 用 replication_factor（数字）声明每个分区写入的副本数：

replication_factor 副本机制容忍节点故障磁盘有效容量适用场景
1 单副本 0 个 100% 开发测试、可重建数据
2 双副本 1 个 50% 个人自托管、低价值数据
3 三副本 2 个 33% 生产推荐，配合 ≥3 个 zone

Garage 按 256 个分区哈希切分数据，每个分区的 replication_factor 份副本会尽量散布在不同 zone（机房/机架）；zone 数少于副本数时冗余度下降（garage layout show 会显示 Zone redundancy 状态）。本文单节点演示使用 replication_factor = 1，三节点生产集群建议 3（实测见《Garage v2.4.1 进阶实战与运维》）。

replication_factor	副本机制	容忍节点故障	磁盘有效容量	适用场景
1	单副本	0 个	100%	开发测试、可重建数据
2	双副本	1 个	50%	个人自托管、低价值数据
3	三副本	2 个	33%	生产推荐，配合 ≥3 个 zone

⚠️ 注意：v1.x 的 replication_mode = "none"/"2"/"3" 写法在 v2.4.1 已被移除，照抄旧教程会直接启动失败（报错见"常见问题"第 1 条）。

四、方案 A：官方静态二进制在线安装（推荐）

4.1 方案说明

Garage 官方发布静态链接的 musl 二进制（x86_64-unknown-linux-musl），无任何动态库依赖，下载即用。本方案从官网 _releases 直链下载，适合能访问外网的服务器。

4.2 下载与校验

wget https://garagehq.deuxfleurs.fr/_releases/v2.4.1/x86_64-unknown-linux-musl/garage -O /root/garage

实测回显（网络受限环境走代理后耗时约 41 秒）：

真实    0m41.236s
user    0m0.157s
sys     0m0.501s

⚠️ 注意：如果直连下载极慢或失败，走 HTTP 代理下载： wget -e use_proxy=yes -e http_proxy=http://192.168.1.62:7897 https://garagehq.deuxfleurs.fr/_releases/v2.4.1/x86_64-unknown-linux-musl/garage -O /root/garage

计算 sha256 留档核对：

sha256sum /root/garage

实测回显：

ae49f8de4aaee6b5ca305f7cbdccc8cd8a29b2804aac074649f18bfb83d0a2b6  /root/garage

Garage 官方未随二进制发布 SHA256SUMS 文件（官网 _releases/v2.4.1/x86_64-unknown-linux-musl/ 目录下实测无校验文件），建议将上述实测值与团队留档比对；本值与官方发布渠道（Docker Hub 的 dxflrs/garage:v2.4.1 发布物）内置二进制的 sha256 实测一致，可交叉确认二进制未被篡改。

4.3 安装二进制与运行用户

chmod +x /root/garage && /root/garage --version
install -m 755 /root/garage /usr/local/bin/garage
useradd -r -s /usr/sbin/nologin -d /var/lib/garage garage
id garage

实测回显：

garage v2.4.1 [features: bundled-libs, consul-discovery, fjall, journald, k2v, kubernetes-discovery, lmdb, metrics, sqlite, syslog, telemetry-otlp]
uid=999(garage) gid=999(garage) groups=999(garage)

garage --version 输出的 features 列表确认了本二进制内置的元数据引擎（fjall/lmdb/sqlite）、K2V、发现机制（consul/kubernetes）等能力。

4.4 创建目录与配置文件

mkdir -p /var/lib/garage/meta /var/lib/garage/data /etc/garage
chown -R garage:garage /var/lib/garage
openssl rand -hex 32

实测回显（rpc_secret 集群共享密钥，每台服务器随机生成自己的即可）：

24ffffd3332bdb8cfcd478a3d8d652420d936ee9521fe780bafe8ef6874e8928

写入 /etc/garage.toml（将 rpc_secret 替换为你上一步生成的值）：

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "fjall"

replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"
rpc_secret = "24ffffd3332bdb8cfcd478a3d8d652420d936ee9521fe780bafe8ef6874e8928"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"
root_domain = ".s3.garage.localhost"

[s3_web]
bind_addr = "[::]:3902"
root_domain = ".web.garage.localhost"
index = "index.html"

[admin]
api_bind_addr = "[::]:3903"
admin_token = "q1w2e3r4-admin"
metrics_token = "q1w2e3r4-metrics"

逐项说明：

metadata_dir / data_dir：元数据与数据块目录，建议放在两块不同磁盘（元数据盘用 SSD 更佳）；
db_engine = "fjall"：元数据引擎，v2.x 默认值，另有 lmdb、sqlite 可选（对比与切换见《Garage v2.4.1 配置参数详解》）；
replication_factor = 1：单节点必须为 1；多副本见三节点集群文档；
rpc_bind_addr：集群 RPC 监听地址，[::] 表示双栈监听；rpc_public_addr 是集群内其他节点可达的本机地址（单机用 127.0.0.1 即可）；
rpc_secret：集群共享密钥，同一集群所有节点必须一致，泄露即等于集群门禁失守；
s3_api.s3_region = "garage"：S3 region 名，客户端连接时需一致；
root_domain：启用虚拟主机风格（bucket.s3.garage.localhost）访问的域名后缀，仅用路径风格访问可不配；
s3_web：静态网站托管监听（3902），不需要可整段删除；
admin.admin_token：Admin API 鉴权令牌（/v2/* 接口需要），/health 端点无需令牌。

收紧配置文件权限：

chmod 640 /etc/garage.toml && chown root:garage /etc/garage.toml && ls -l /etc/garage.toml

实测回显：

-rw-r----- 1 root garage 721 Oct 17 04:29 /etc/garage.toml

4.5 手动前台验证启动

写 systemd 之前，先用 garage 用户前台启动一次，确认配置可用：

su -s /bin/bash garage -c 'cd /var/lib/garage && timeout 8 garage server 2>&1 | head -12'

实测回显：

2026-10-17T04:29:45.080946Z  INFO garage::server: Loading configuration from /etc/garage.toml...
2026-10-17T04:29:45.081160Z  INFO garage::server: Initializing Garage main data store...
2026-10-17T04:29:45.081197Z  INFO garage_model::garage: Opening database...
2026-10-17T04:29:45.081214Z  INFO garage_db::fjall_adapter: Opening Fjall database at: /var/lib/garage/meta/db.fjall
2026-10-17T04:29:45.089024Z  INFO garage_model::garage: Initializing RPC...
2026-10-17T04:29:45.089054Z  INFO garage_model::garage: Initialize background variable system...
2026-10-17T04:29:45.089058Z  INFO garage_model::garage: Initialize membership management system...
2026-10-17T04:29:45.089089Z  INFO garage_rpc::system: Node ID of this node: d2359677f21e6db2
2026-10-17T04:29:45.089133Z  INFO garage_rpc::layout::manager: No valid previous cluster layout stored (IO error: No such file or directory (os error 2)), starting fresh.
2026-10-17T04:29:45.089158Z  INFO garage_rpc::layout::helper: ack_until updated to 0
2026-10-17T04:29:45.089215Z  INFO garage_model::garage: Initialize block manager...
2026-10-17T04:29:45.089659Z  INFO garage_model::garage: Initialize admin_token_table...

日志中 Node ID of this node: d2359677f21e6db2 是本节点的 16 位短 ID（由公钥派生），后续 layout 分配要用。timeout 8 秒后进程自动退出属正常（测试用）。

4.6 systemd 托管

创建 /etc/systemd/system/garage.service：

[Unit]
Description=Garage Object Storage (S3 compatible)
After=network-online.target
Wants=network-online.target

[Service]
User=garage
Group=garage
Environment=GARAGE_CONFIG_FILE=/etc/garage.toml
ExecStart=/usr/local/bin/garage server
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

逐项说明：User/Group=garage 以低权限用户运行；Environment 显式指定配置文件路径（也可省略，Garage 默认读 /etc/garage.toml）；Restart=on-failure 异常退出 5 秒后自动拉起；LimitNOFILE=65536 提高文件句柄上限。

启用并启动：

systemctl daemon-reload
systemctl enable garage
systemctl start garage

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/garage.service → /etc/systemd/system/garage.service.

验证运行状态：

systemctl is-active garage
systemctl status garage --no-pager -l | head -12

实测回显：

active
● garage.service - Garage Object Storage (S3 compatible)
     Loaded: loaded (/etc/systemd/system/garage.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-10-17 04:29:53 UTC; 2s ago
   Main PID: 2937 (garage)
      Tasks: 22 (limit: 5753)
     Memory: 3.3M
        CPU: 61ms
     CGroup: /system.slice/garage.service
             └─2937 /usr/local/bin/garage server

Oct 17 04:29:53 garage-server garage[2937]: 2026-10-17T04:29:53.860721Z  INFO garage::server: Spawning Garage workers...
Oct 17 04:29:53 garage-server garage[2937]: 2026-10-17T04:29:53.860756Z  INFO garage::server: Initialize Admin API server and metrics collector...

实测空闲内存仅 3.3MB，资源占用极低。

4.7 单节点集群初始化

Garage 的存储空间分配不靠配置文件，而是靠集群布局（layout）声明。三步完成：查节点 ID → 分配角色 → 应用布局。

garage status

实测回显：

==== HEALTHY NODES ====
ID                Hostname       Address         Tags  Zone  Capacity          DataAvail  Version
d2359677f21e6db2  garage-server  127.0.0.1:3901              NO ROLE ASSIGNED             v2.4.1

分配角色（-z 指定 zone、-c 指定容量，二者都不能省；-c 必须带单位，如 1G/100G，写纯数字会被当成字节数报错）：

garage layout assign -z dc1 -c 1G d2359677f21e6db2

实测回显：

Role changes are staged but not yet committed.
Use `garage layout show` to view staged role changes,
and `garage layout apply` to enact staged changes.

garage layout show

实测回显（节选）：

==== STAGED ROLE CHANGES ====
ID                Tags  Zone  Capacity
d2359677f21e6db2  []    dc1   953.7 MiB

==== NEW CLUSTER LAYOUT AFTER APPLYING CHANGES ====
ID                Tags  Zone  Capacity   Usable capacity
d2359677f21e6db2  []    dc1   953.7 MiB  953.7 MiB (100.0%)

Zone redundancy: maximum

==== COMPUTATION OF A NEW PARTITION ASSIGNATION ====

Partitions are replicated 1 times on at least 1 distinct zones.

Optimal partition size:                     3.7 MiB
Usable capacity / total cluster capacity:   953.7 MiB / 953.7 MiB (100.0 %)
Effective capacity (replication factor 1):  953.7 MiB

dc1                 Tags  Partitions        Capacity   Usable capacity
  d2359677f21e6db2  []    256 (256 new)     953.7 MiB  953.7 MiB (100.0%)
  TOTAL                   256 (256 unique)  953.7 MiB  953.7 MiB (100.0%)


To enact the staged role changes, type:

    garage layout apply --version 1

You can also revert all proposed changes with: garage layout revert

注意 1G（十进制 10^9 字节）显示为 953.7 MiB（二进制单位），属正常换算。提交布局：

garage layout apply --version 1

实测回显（节选）：

New cluster layout with updated role assignment has been applied in cluster.
Data will now be moved around between nodes accordingly.

再次确认角色已生效：

garage status

实测回显：

==== HEALTHY NODES ====
ID                Hostname       Address         Tags  Zone  Capacity   DataAvail          Version
d2359677f21e6db2  garage-server  127.0.0.1:3901  []    dc1   953.7 MiB  102.4 GiB (13.0%)  v2.4.1

4.8 创建 Bucket 与访问密钥

garage bucket create garage-demo
garage key create demo-key
garage bucket allow --read --write --owner garage-demo --key demo-key

bucket create 实测回显：

==== BUCKET INFORMATION ====
Bucket:          3d903561058d97e537c51f079bfcda499758fe5d79b31b40ea4604d50d056bd8
Created:         2026-10-17 04:30:43.261 +00:00

Size:            0 B (0 B)
Objects:         0

Website access:  false

Global alias:    garage-demo

==== KEYS FOR THIS BUCKET ====
Permissions  Access key    Local aliases

key create 实测回显：

==== ACCESS KEY INFORMATION ====
Key ID:              GKfec5c8a8af3bc46a897523ec
Key name:            demo-key
Secret key:          9d6ea02e827d3efe88bfe0f8e2a8650618f1109602e7a026ad5ee2ef3f5cadf7
Created:             2026-10-17 04:30:43.356 +00:00
Validity:            valid
Expiration:          never

Can create buckets:  false

==== BUCKETS FOR THIS KEY ====
Permissions  ID  Global aliases  Local aliases
ID                          Created     Name      Expiration
GKfec5c8a8af3bc46a897523ec  2026-10-17  demo-key  never

bucket allow 实测回显：

==== BUCKET INFORMATION ====
Bucket:          3d903561058d97e537c51f079bfcda499758fe5d79b31b40ea4604d50d056bd8
Created:         2026-10-17 04:30:43.261 +00:00

Size:            0 B (0 B)
Objects:         0

Website access:  false

Global alias:    garage-demo

==== KEYS FOR THIS BUCKET ====
Permissions  Access key                            Local aliases
RWO          GKfec5c8a8af3bc46a897523ec  demo-key

RWO 表示 Read/Write/Owner 三项权限已授予。Secret key 只在创建时完整显示一次，务必当场保存；遗失可用 garage key info demo-key --show-secret 再查。

4.9 安装 AWS CLI 并验证 S3 读写

curl -s "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
cd /root && unzip -qo /tmp/awscliv2.zip && ./aws/install
aws --version

实测回显：

You can now run: /usr/local/bin/aws --version
aws-cli/2.38.1 Python/3.14.6 Linux/6.8.0-138-generic exe/x86_64.ubuntu.22

配置凭据（Key ID 与 Secret key 用 4.8 节实测值）：

aws configure set aws_access_key_id GKfec5c8a8af3bc46a897523ec
aws configure set aws_secret_access_key 9d6ea02e827d3efe88bfe0f8e2a8650618f1109602e7a026ad5ee2ef3f5cadf7
aws configure set default.region garage

S3 全链路验证（列举 → 上传 → 列举 → 下载 → 校验内容）：

aws --endpoint-url http://127.0.0.1:3900 s3 ls
echo 'hello garage v2.4.1' > /root/hello.txt
aws --endpoint-url http://127.0.0.1:3900 s3 cp /root/hello.txt s3://garage-demo/hello.txt
aws --endpoint-url http://127.0.0.1:3900 s3 ls s3://garage-demo
aws --endpoint-url http://127.0.0.1:3900 s3 cp s3://garage-demo/hello.txt /root/hello-back.txt
cat /root/hello-back.txt

实测回显：

2026-10-17 04:30:43 garage-demo
upload: root/hello.txt to s3://garage-demo/hello.txt
2026-10-17 04:31:33         20 hello.txt
download: s3://garage-demo/hello.txt to root/hello-back.txt
hello garage v2.4.1

上传与下载内容一致，S3 API 工作正常。

4.10 Admin API 验证

garage health
curl -s -H 'Authorization: Bearer q1w2e3r4-admin' http://127.0.0.1:3903/v2/GetClusterHealth

实测回显：

Cluster health:            HEALTHY
Known nodes:               1
Connected nodes:           1
Storage nodes:             1
Storage nodes up:          1
Partitions:                256
Partitions with quorum:    256
Fully healthy partitions:  256
{
  "code": "AccessDenied",
  "message": "Forbidden: Bearer token must be provided in Authorization header",
  "region": "garage",
  "path": "/v2/GetClusterHealth"
}

⚠️ 注意：/v2/* 管理接口必须携带 Authorization: Bearer <admin_token>，不带令牌返回 403 AccessDenied（如上实测）；不带令牌可访问的只有根路径 /health（返回纯文本 "Garage is fully operational"）。带令牌访问 GetClusterHealth 的返回节选：

curl -s -H 'Authorization: Bearer q1w2e3r4-admin' http://127.0.0.1:3903/v2/GetClusterHealth

实测回显：

{"healthy":true,"knownNodes":1,"connectedNodes":1,"storageNodes":1,"storageNodesUp":1,"partitions":256,"partitionsQuorum":256,"partitionsAllHealthy":256,"partitionsAvailable":256,"quorumCount":1,"storageNodesDown":0,"resyncQueueLen":0,"uploadsPending":0}

五、方案 B：离线二进制安装（内网/断网服务器）

5.1 方案说明

内网服务器无法访问外网时，在一台有外网的机器上下载二进制（同 4.2 节，含 sha256 校验 ae49f8de4aaee6b5ca305f7cbdccc8cd8a29b2804aac074649f18bfb83d0a2b6），通过内网文件传输（scp/U 盘/内部制品库）拷贝到目标服务器，后续安装步骤与方案 A 完全一致。

5.2 传输与校验

在内网目标服务器上对拷入的二进制重新计算 sha256，必须与外网机器记录值一致：

sha256sum /root/garage

实测回显（离线安装环境实测）：

ae49f8de4aaee6b5ca305f7cbdccc8cd8a29b2804aac074649f18bfb83d0a2b6  /root/garage

5.3 安装与验证

安装步骤与 4.3～4.6 节完全一致（安装二进制 → 用户与目录 → garage.toml → systemd），不再重复。启动后验证：

garage status

实测回显（离线安装环境，node ID 与 4.7 节不同属正常，由密钥对随机派生）：

==== HEALTHY NODES ====
ID                Hostname        Address         Tags  Zone  Capacity          DataAvail  Version
1f55dfb376baabbe  offline-server  127.0.0.1:3901              NO ROLE ASSIGNED             v2.4.1

garage node id 可查看完整 64 位节点 ID（多机组网时 bootstrap_peers 需要全量 ID）：

garage node id | head -1

实测回显：

1f55dfb376baabbe29f0b4c1cdbdb97e91a8981b4d0ef56c73f177c76427c988@127.0.0.1:3901

5.4 方案对比与选择建议

维度	方案 A：在线安装	方案 B：离线安装
版本	v2.4.1（官网直链）	v2.4.1（外网下载后拷入）
是否需联网	需访问 garagehq.deuxfleurs.fr	仅内网传输
完整性保障	sha256 留档比对	拷入后 sha256 复验
systemd 托管	相同	相同
适用场景	有外网/代理通道	内网隔离、合规审计环境

内网隔离环境选方案 B，可联网环境选方案 A 更省事。

六、升级与多版本管理

6.1 查询当前版本

garage --version | head -1

实测回显：

garage v2.4.1 [features: bundled-libs, consul-discovery, fjall, journald, k2v, kubernetes-discovery, lmdb, metrics, sqlite, syslog, telemetry-otlp]

6.2 升级步骤（保留数据）

下载新版二进制到临时路径并 chmod +x；
systemctl stop garage（正在运行的二进制不能被覆盖，直接 cp 会报 Text file busy）；
覆盖 /usr/local/bin/garage；
systemctl start garage。

实测演示（v2.4.1 自身来回切换即等效于"跨版本升级"流程）：

systemctl stop garage
cp /root/garage /usr/local/bin/garage
systemctl start garage && sleep 2
systemctl is-active garage

实测回显：

active

⚠️ 注意：三节点集群滚动升级时逐节点执行上述流程（一次只停一个节点），集群在 quorum 满足期间可继续读写；版本兼容性实测见《Garage v2.4.1 进阶实战与运维》。跨大版本（v1.x → v2.x）升级前必须阅读官方 Release Notes 并完成数据备份。

6.3 多版本共存

Garage 单二进制不提供多版本自动切换，需要保留旧版时把旧二进制另存（如 /usr/local/bin/garage-v2.4.0），回滚时 systemctl stop garage 后用旧二进制覆盖 /usr/local/bin/garage 再启动。回滚前同样注意元数据兼容性：只允许从新版本回退到官方声明兼容的旧版本。

七、常见问题（FAQ）

7.1 启动报错 metadata_fsync is not supported with the Fjall database engine

现象（实测）：

2026-10-17T04:28:40.235172Z  INFO garage_db::fjall_adapter: Opening Fjall database at: /var/lib/garage/meta/db.fjall
Error: Unable to open metadata db: database error: metadata_fsync is not supported with the Fjall database engine

定位：metadata_fsync = true 只有 lmdb/sqlite 引擎支持，v2.x 默认引擎 fjall 不支持该参数。解决：删除或注释该行（fjall 自带写入策略），或改用 db_engine = "lmdb" 并保留 metadata_fsync = true。

7.2 启动报错 The legacy replication_mode is no longer supported

现象（实测，v1.x 旧配置写法导致）：

Error: The legacy replication_mode is no longer supported. Use replication_factor and consistency_mode instead.

定位：v2.x 已把 replication_mode 拆分为 replication_factor（数字）与 consistency_mode。解决：改为 replication_factor = 1（单机）或 3（集群）。

7.3 replication_factor = "none" 报 TOML 类型错误

现象（实测）：

Error: TOML decode error: TOML parse error at line 8, column 22
  |
8 | replication_factor = "none"
  |                      ^^^^^^
invalid type: string "none", expected usize

定位：v2.x 的 replication_factor 是数字类型（usize），不再接受字符串 "none"。单机写 replication_factor = 1。

7.4 layout assign 报 Capacity should be at least 1K (1024)

现象（实测）：

Error: UpdateClusterLayout returned InvalidRequest (400): Bad request: Capacity should be at least 1K (1024)

定位：-c 1 被解释为 1 字节容量。解决：容量必须带单位，如 -c 1G、-c 100G、-c 2T。

7.5 数据目录 Permission denied

现象（实测，用 root 手动前台跑过一次 garage server 后）：

Error: Unable to open metadata db: database error: fjall: FjallError: Storage(Io(Os { code: 13, kind: PermissionDenied, message: "Permission denied" }))

定位：root 运行会在数据目录下生成 root 属主的文件，再次以 garage 用户启动即拒绝。解决：chown -R garage:garage /var/lib/garage。养成习惯：一律 su -s /bin/bash garage -c 'garage server' 或交给 systemd 以 User=garage 运行，从不手动以 root 启动。

7.6 CLI 管理命令报 Unable to connect to destination RPC host

现象（实测，server 未运行时执行 garage status）：

Error: Unable to connect to destination RPC host. Check that you are using the same value of rpc_secret as them, and that you have their correct full-length node ID (public key).
IO error: Connection refused (os error 111)

定位：garage status/bucket/key 等管理命令需要连接到运行中的 server 执行。解决：先 systemctl start garage 再执行管理命令。

7.7 AWS CLI 报 InvalidAccessKeyId 或 SignatureDoesNotMatch

定位：Key ID 抄错或 Secret key 不完整。解决：用 garage key list 核对 Key ID、garage key info demo-key --show-secret 查看 Secret；同时确认 aws configure set default.region garage 的 region 与配置文件 s3_region 一致。

八、卸载与清理

systemctl stop garage
systemctl disable garage

实测回显：

Removed /etc/systemd/system/multi-user.target.wants/garage.service.

rm -f /etc/systemd/system/garage.service && systemctl daemon-reload && systemctl reset-failed
rm -f /usr/local/bin/garage /etc/garage.toml
rm -rf /var/lib/garage
userdel garage

验证卸载干净（实测回显）：

systemctl status garage

Unit garage.service could not be found.

garage --version

bash: garage: command not found

ls /usr/local/bin/garage /etc/garage.toml /var/lib/garage

ls: cannot access '/usr/local/bin/garage': No such file or directory
ls: cannot access '/etc/garage.toml': No such file or directory
ls: cannot access '/var/lib/garage': No such file or directory

⚠️ 注意：rm -rf /var/lib/garage 会永久删除全部对象数据，卸载前如需保留请先备份（备份方法见《Garage v2.4.1 进阶实战与运维》）。

九、参考链接

官网与文档：https://garagehq.deuxfleurs.fr/
快速上手：https://garagehq.deuxfleurs.fr/documentation/quick-start/
二进制发布目录：https://garagehq.deuxfleurs.fr/_releases/
源码仓库：https://git.deuxfleurs.fr/Deuxfleurs/garage（镜像：https://github.com/deuxfleurs-org/garage）
Docker Hub：https://hub.docker.com/r/dxflrs/garage
配置参考：https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/