Garage v2.4.1 配置参数详解

目标：逐参数讲透 Garage v2.4.1 的 garage.toml 配置文件——每个参数的位置、类型、默认值、实测行为与无效值报错样例，并给出按场景划分的生产配置模板。全部参数行为均在 Ubuntu 22.04 + Garage v2.4.1 实测验证。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Garage：v2.4.1 静态二进制（features 含 fjall/lmdb/sqlite/k2v/consul-discovery/kubernetes-discovery）
• 配置文件：/etc/garage.toml（CLI 默认路径；可用 GARAGE_CONFIG_FILE 或 -c 改变）
• 实测方式：修改配置后前台启动 garage server 观察日志与报错，或用 garage -c <测试配置> server 并行验证多套参数

二、前置条件

1. Garage v2.4.1 已安装（安装见《Garage v2.4.1 Ubuntu 22.04 安装指南》）；
2. 能编辑 /etc/garage.toml 并重启服务（systemctl restart garage）；
3. 了解 Garage 基本架构：元数据（bucket/key/对象索引）存元数据引擎，对象内容按 1MiB 分块存数据目录，集群状态靠 RPC 同步。

三、参数查看与修改方式

3.1 查看当前生效配置

Garage 无 dump-config 子命令，当前配置即 /etc/garage.toml 内容；启动时加载的配置文件路径会打印在日志第一行：

systemctl status garage --no-pager | grep -m1 'Loading configuration'

实测回显：

Oct 17 04:29:53 garage-server garage[2937]: 2026-10-17T04:29:53.859942Z  INFO garage::server: Loading configuration from /etc/garage.toml...

3.2 修改方式与生效条件

• 文件修改：编辑 /etc/garage.toml → systemctl restart garage 生效（Garage 启动时一次性读取，不支持热加载）；
• 命令行覆盖：garage -c /path/to/garage.toml 指定配置文件；--rpc-secret、--admin-token 等可临时覆盖密钥类参数（用于远程管理别的节点）；
• 环境变量覆盖：GARAGE_ 前缀 + 大写路径，如 GARAGE_METADATA_DIR=/var/lib/garage/meta、GARAGE_REPLICATION_FACTOR=1，优先级高于 toml 文件；
• 集群布局类参数（节点容量、zone）不在 toml 里改，用 garage layout assign/apply（见《Garage v2.4.1 快速入门（集群初始化与 S3 实测）》）。

3.3 配置错误的第一现场

所有配置错误都在启动时报出且进程退出，看服务日志即可定位：

journalctl -u garage -n 5 --no-pager

实测回显（配置文件缺失时）：

Oct 17 04:28:20 garage-server garage[1528]: 2026-10-17T04:28:20.684704Z  INFO garage::server: Loading configuration from /etc/garage.toml...
Oct 17 04:28:20 garage-server garage[1528]: Error: Failed to read config file /etc/garage.toml: No such file or directory (os error 2)

四、参数总览

💡 技术拓展：元数据引擎（db_engine）三选一对比——

引擎	实测启动日志	特点	适用场景
fjall（v2 默认）	Opening Fjall database at: .../db.fjall	LSM 式 KV，写入吞吐好，不支持 metadata_fsync	默认选择，通用
lmdb	Opening LMDB database at: .../db.lmdb	内存映射 B+ 树，成熟稳定，支持 fsync/快照	追求久经考验的稳定性
sqlite	Opening Sqlite database at: .../db.sqlite	单文件，便于用 SQLite 工具直接查看	调试、元数据人工排查

本文默认采用 fjall（官方 v2.x 推荐）；需要 metadata_fsync 强持久化时选 lmdb。切换引擎不会自动迁移数据，需用 garage convert-db 子命令离线转换（garage convert-db --help 可查参数）。

五、核心参数分类详解

5.1 存储路径与数据目录（metadata_dir / data_dir）

• metadata_dir：元数据目录，存 db.fjall（或 db.lmdb/db.sqlite）、集群布局 cluster_layout、节点密钥 node_key/node_key.pub、邻居列表 peer_list 等。IO 密集，建议独立 SSD；
• data_dir：对象数据块目录，按内容寻址散列存放 1MiB 块文件，可多盘扩展（data_dir 可写多行声明多个目录实现盘间分散）。

实测目录结构（单节点初始化后）：

/var/lib/garage/meta/
├── cluster_layout
├── data_layout
├── db.fjall/
├── lifecycle_worker_state
├── node_key
├── node_key.pub
└── peer_list

⚠️ 注意：两目录权限必须归运行用户（如 garage），root 手动启动会留下 root 属主文件导致后续启动 Permission denied（实测报错与修复见《Garage v2.4.1 Ubuntu 22.04 安装指南》FAQ 7.5）。

5.2 元数据引擎与持久化（db_engine / metadata_fsync / data_fsync / 快照）

• db_engine = "fjall" | "lmdb" | "sqlite"：三种引擎全部实测可用，无效值报错实测：

Error: Invalid `db_engine` value in configuration file: database error: Invalid DB engine: rocksdb (options are: lmdb, sqlite, fjall)

• metadata_fsync：每次元数据提交都 fsync。fjall 引擎不支持，配 true 直接启动失败（实测）：

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

用法：fjall 下删除该参数；lmdb/sqlite 下可设 metadata_fsync = true 换取断电安全（牺牲少量写延迟）；

• data_fsync = false：数据块落盘 fsync，默认关闭（性能优先）；开启可进一步降低掉电丢块风险；
• metadata_auto_snapshot_interval = "6h"：每 6 小时自动做一次元数据快照到 metadata_dir/snapshots/<UTC 时间戳>/。手动快照命令（运行中可执行，实测）：

garage meta snapshot

实测回显：

Node              Result
d0bb67c993d97376  Snapshot created

实测快照落盘位置：

/var/lib/garage/meta/snapshots/2026-10-17T04:40:05Z/db.fjall/

5.3 分块与压缩（block_size / compression）

• block_size：对象内容分块大小，默认 1 MiB。调大减少块数降低元数据压力，调小提升小改大对象时的去重粒度，一般不动；
• compression：数据块 zstd 压缩级别，默认 1；compression = 0 或 compression = "none" 禁用压缩。实测 compression = 5、compression = "none" 均可正常启动。压缩对已存数据不追溯，仅对新写入块生效；二进制媒体（已压缩）建议 0 省 CPU。

5.4 复制与一致性（replication_factor / consistency_mode）

• replication_factor：每个分区的副本数，数字类型（usize）。v2.x 必须用本参数，v1.x 的 replication_mode 已移除（实测报错）：

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

类型错误实测（写成字符串）：

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

取值 1/2/3：1 单副本（单机测试）、2 双副本、3 生产推荐。集群布局的有效容量按 总容量 / 副本数 计算（garage layout show 的 Effective capacity (replication factor N)）。修改副本数是重大变更，需配合 layout 变更并在官方指引下执行；

• consistency_mode：读一致模式，默认 consistent。v2.4.1 实测仅接受 consistent，写成 eventual / read-after-write / read_after_write 均报：

Error: Invalid consistency_mode in config file.

保持默认即可，v1.x 时代文档描述的 eventual 等模式在 v2.4.1 尚不可用。

5.5 RPC 集群通信（rpc_bind_addr / rpc_public_addr / rpc_secret / bootstrap_peers）

• rpc_bind_addr = "[::]:3901"：RPC 监听，[::] 双栈；3901 是集群内部端口，不要暴露公网；
• rpc_public_addr：本节点在集群中的对外地址，集群部署必填。实测必须写 IP:port 形式（写主机名时 bootstrap 解析失败，实测日志）：

WARN garage_rpc::system: Unable to parse and/or resolve peer hostname node1:3901

• rpc_secret：32 字节 hex 集群密钥（openssl rand -hex 32 生成），同集群全部节点必须一致。安全起见可用 rpc_secret_file = "/etc/garage/rpc_secret" 从 0600 权限文件读取；把密钥放进全组可读文件时会触发权限检查报错，此时才需要 allow_world_readable_secrets = true（不推荐）；
• bootstrap_peers：启动时自动连接的引导节点列表。v2.4.1 实测格式必须是 <完整节点ID>@<IP>:<端口>（写裸 IP:端口 或主机名均报 Unable to parse and/or resolve peer hostname）。完整 ID 用对端节点的 garage node id 获取：

garage node id | head -1

实测回显：

1f55dfb376baabbe29f0b4c1cdbdb97e91a8981b4d0ef56c73f177c76427c988@127.0.0.1:3901

集群配置写法（node2 的 toml 片段，实测可用）：

bootstrap_peers = [
  "d0bb67c993d97376770f9583a11c52512c1b81b5d31e82f8a234ee937c522a32@172.29.0.2:3901",
  "37905798112536c4d676dec47938928afa54d161735f913b81d7cdc97dce9647@172.29.0.4:3901",
]

运行期临时连接可用 garage node connect <完整ID@IP:端口>；节点发现还支持 consul/kubernetes（feature 已编译启用，详见官方文档对应小节）。

5.6 S3 API（[s3_api]）

• s3_region = "garage"：region 名，客户端签名必须与此一致，不一致的实测报错：

aws: [ERROR]: An error occurred (AuthorizationHeaderMalformed) when calling the ListBuckets operation: Authorization header malformed, unexpected scope: '20261017/us-east-1/s3/aws4_request', expected: '20261017/garage/s3/aws4_request'

• api_bind_addr = "[::]:3900"：S3 兼容 API 监听；
• root_domain = ".s3.garage.localhost"：虚拟主机风格访问的后缀（bucket.s3.garage.localhost → bucket）。仅用路径风格（endpoint/bucket/key）可不配；配了之后除 IP:3900 路径风格外，还接受子域访问。

5.7 静态网站托管（[s3_web]）

• bind_addr = "[::]:3902"：网站监听；
• root_domain = ".web.garage.localhost"：网站域名后缀，bucket 需先开启网站访问（garage bucket website --allow <bucket>）；
• index = "index.html"：目录请求的默认页。

5.8 K2V API（[k2v_api]）

• api_bind_addr：K2V 键值 API 监听（通常 3904）。二进制 features 含 k2v 才可用；K2V 面向「批量简单 KV 读写 + 队列语义」场景，普通 S3 需求不需要开启。

5.9 Admin API（[admin]）

• api_bind_addr = "[::]:3903"：管理监听。鉴权实测结论：根路径 /health 免令牌（返回 "Garage is fully operational"），/v2/* 一律要求 Authorization: Bearer <admin_token>，否则 403：

{
  "code": "AccessDenied",
  "message": "Forbidden: Bearer token must be provided in Authorization header",
  "region": "garage",
  "path": "/v2/GetClusterHealth"
}

• admin_token：管理令牌（32 字节随机串，演示用 q1w2e3r4-admin）；支持 admin_token_file 从文件读取；命令行 --admin-token 可临时覆盖；
• metrics_token：/metrics Prometheus 端点专用令牌（与 admin_token 分离，便于给监控最小授权）。

5.10 其他系统参数

• allow_world_readable_secrets = false：默认拒绝全组可读的密钥文件，防止误配泄露；
• 日志输出：默认打 stdout（journald 收取）；二进制 features 含 journald/syslog，可按需接入系统日志（详见官方配置参考的 log 部分）。

六、生产配置模板

6.1 单节点（开发/个人自托管，1 核 1GB 内存即可）

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

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"

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

适用：单机、无冗余，数据可重建；实测空闲内存占用约 3MB 级。

6.2 三节点三 zone 生产（各节点 4 核 8GB、SSD、跨机房）

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "lmdb"
metadata_fsync = true
metadata_auto_snapshot_interval = "6h"

replication_factor = 3
consistency_mode = "consistent"

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "192.168.1.11:3901"
rpc_secret_file = "/etc/garage/rpc_secret"
bootstrap_peers = [
  "d0bb67c993d97376770f9583a11c52512c1b81b5d31e82f8a234ee937c522a32@192.168.1.11:3901",
  "146172322f18f7bab5ab8d7ca0f87c290a1d7a351ddb8f2668f8f2dd3c19708b@192.168.1.12:3901",
  "37905798112536c4d676dec47938928afa54d161735f913b81d7cdc97dce9647@192.168.1.13:3901",
]

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"

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

适用：生产三副本跨 zone；rpc_public_addr 每节点各写自己的 IP（192.168.1.11/12/13）；完整节点 ID 用各节点 garage node id 的实测输出替换；rpc_secret_file 指向 0600 权限的共享密钥文件。容灾能力与故障演练实测见《Garage v2.4.1 进阶实战与运维》。

七、常见问题（FAQ）

Q1：改完配置重启没生效？ Garage 仅在启动时读配置，确认执行了 systemctl restart garage；若 unit 里用了 GARAGE_CONFIG_FILE 环境变量，确认指向的文件才是你改的那份。环境变量 GARAGE_* 优先级高于 toml，逐一排查。

Q2：启动报 The legacy replication_mode is no longer supported？ v1.x 旧键。改为 replication_factor = <数字>；单机为 1。

Q3：启动报 metadata_fsync is not supported with the Fjall database engine？ fjall 引擎不支持该参数。要么删掉/注释 metadata_fsync，要么 db_engine = "lmdb" 后再启用。

Q4：Invalid consistency_mode in config file？ v2.4.1 只接受 consistency_mode = "consistent"（默认值，可直接删掉该行）。

Q5：Invalid DB engine：rocksdb？ db_engine 只接受 fjall/lmdb/sqlite（实测报错原文：Invalid DB engine: rocksdb (options are: lmdb, sqlite, fjall)）。旧教程中的 sled 在 v2.x 已移除。

Q6：Unable to parse and/or resolve peer hostname？ bootstrap_peers 或 rpc_public_addr 写了主机名或裸 IP:端口。v2.4.1 要求：rpc_public_addr 用 IP:端口；bootstrap_peers 用 <完整节点ID>@<IP>:<端口>（对端 garage node id 获取）。

Q7：怎么把元数据从 fjall 迁到 lmdb？ 先 garage meta snapshot 快照并停服备份元数据目录，再用 garage convert-db --help 按官方指引做离线转换（转换期间集群必须停写），转换后改 db_engine 启动验证。切换前务必演练备份恢复。

八、参考链接

• 配置参考（官方）：https://garagehq.deuxfleurs.fr/documentation/reference-manual/configuration/
• 三节点组网指南：https://garagehq.deuxfleurs.fr/documentation/cookbook/real-world/
• 同系列：《Garage v2.4.1 快速入门（集群初始化与 S3 实测）》《Garage v2.4.1 进阶实战与运维》