BorgBackup 配置参数详解
详解 borg 1.2.8 的核心配置体系：BORG_* 环境变量（BORG_REPO/BORG_PASSPHRASE/BORG_RSH）、加密模式（repokey/keyfile/blake2）、备份归档命名、压缩方式与 chunker 参数、保留策略 prune、global 与 create/check 常用 flags，附真实默认值
BorgBackup 配置参数详解
目标：系统解析 borg v1.2.8 的配置体系。borg 的配置主要分四层：加密与仓库初始化选项（
borg init）、环境变量（BORG_*）、归档命名与 create 行为参数、清理保留策略（prune --keep-*）。本文聚焦最常用参数的真实语义与默认值，默认值来自 1.2.8 实测。
一、环境信息
- borg 版本：v1.2.8
- 仓库路径：
/data/borg-repo - 加密模式：
repokey BLAKE2b
二、加密模式（borg init）
borg init --encryption=<模式> 决定加密与密钥存放方式，是仓库的最核心属性，初始化后不可更改：
| 模式 | 密钥位置 | 加密 | 说明 |
|---|---|---|---|
repokey | 仓库内 | AES-256+HMAC | 密钥随仓库，口令保护；方便但需防仓库丢失 |
repokey-blake2 | 仓库内 | AES-256+BLAKE2b | 本文实测默认选用，哈希用 BLAKE2b |
keyfile | 本机指定路径 | AES-256 | 密钥独立文件，最安全 |
keyfile-blake2 | 本机指定路径 | AES-256+BLAKE2b | 独立密钥 + BLAKE2b |
plaintext | 无 | 不加密 | 仅去重不加密，禁止用于生产 |
authenticated | 无 | 只认证 | 校验篡改但不加密内容 |
⚠️ 加密模式在
init时确定后不可更改。生产建议repokey-blake2（省事且密钥随仓库，配合key export兜底）或keyfile（独立密钥最高安全）。
export BORG_REPO=/data/borg-repo
export BORG_PASSPHRASE=q1w2e3r4
borg init --encryption=repokey-blake2 "$BORG_REPO"
三、BORG_* 环境变量
borg 通过大量 BORG_* 环境变量控制行为，命令行可用 --repo/--passphrase 等参数替代，但环境变量更便于脚本与容器注入：
| 环境变量 | 作用 | 说明 |
|---|---|---|
BORG_REPO | 仓库路径 | 多数命令可省 --repo |
BORG_PASSPHRASE | 仓库口令 | 免交互；生产从密钥管理或容器 env 注入 |
BORG_RSH | 远程 ssh 命令 | 覆盖 ssh 参数，如私钥路径 |
BORG_REMOTE_PATH | 远端 borg 路径 | 远程备份时指定 |
BORG_CHECK_I_KNOW_WHAT_I_AM_DOING | 跳过安全校验 | 用于 check 强制（勿滥用） |
BORG_CACHE_DIR | 缓存目录 | 默认 ~/.cache/borg |
BORG_CONFIG_DIR | 配置目录 | 默认 ~/.config/borg |
BORG_KEYS_DIR | 密钥文件目录（keyfile） | 默认 ~/.config/borg/keys |
BORG_CONFIG_* | 仓库内配置文件逐键覆盖 | 高级 |
💡 容器与脚本中优先用环境变量注入口令，避免把密钥写进命令历史或配置文件明文。
四、归档命名（archive name）
归档名可引用占位符自动展开，常用 create "repo::<名称>"：
| 占位符 | 含义 | 示例 → 值 |
|---|---|---|
{hostname} | 本机主机名 | host 4e9a45ab...（容器场景） |
{now} | 本地时间戳 | 2026-10-08T05:39:31 |
{utcnow} | UTC 时间戳 | 2026-10-08T05:39:31Z |
{user} | 运行用户名 | root |
典型归档名：
borg create "$BORG_REPO"::"host{hostname}-{now}" /data/backup-src
# 生成 host4e9a45ab11c5-2026-10-08T05:39:31
五、create / 备份行为参数
5.1 压缩（--compression）
控制备份块的压缩算法，默认 lz4（速度快、压缩比适中）：
| 值 | 说明 |
|---|---|
lz4 | 默认；快，压缩比中 |
zlib / zlib,N | zlib 压缩（N 级别 0~9） |
lzma / lzma,N | 高压缩比、慢 |
zstd,N / zstd,0-22 | 现代均衡，内存/CPU 明显 |
none | 不压缩 |
borg create --compression zstd,3 "$BORG_REPO"::b1 /data/backup-src
5.2 过滤与排除（--exclude / --pattern）
按需排除无需备份的机器/临时文件（实测 borg create --help 摘录）：
borg create --exclude '*.tmp' --exclude '/data/backup-src/cache' "$BORG_REPO"::b1 /data/backup-src
# 常用：-e/--exclude、--exclude-from FILE、--exclude-caches、--exclude-if-present NAME
💡
--exclude-caches跳过含CACHEDIR.TAG的目录；--exclude-if-present .nobackup可标记某目录不备份。
5.3 create 常用全局 flag
| flag | 说明 |
|---|---|
-s, --stats | 输出统计（Original/Compressed/Deduplicated） |
--list | 列出每个备份对象（A/U/d） |
-n, --dry-run | 只演练不真实创建 |
-p, --progress | 进度条 |
--json | JSON 输出（隐含 --stats） |
-C, --compression | 压缩方式 |
-x, --one-file-system | 不跨文件系统 |
--paths-from-stdin | 从 stdin 读路径列表 |
5.4 块大小（--chunker-params，高级）
borg create --chunker-params 19,23,21,4095 "$BORG_REPO"::b1 /data/backup-src
💡 4 个参数分别为 min exponent、max exponent、hash mask、max window size。默认即去重均衡的配置，无特殊需求不要改。
六、check / 校验参数
borg check 校验仓库与归档一致性：
# 全量校验（repo + archives）
borg check "$BORG_REPO"
# 只校验仓库（快）
borg check --repository-only "$BORG_REPO"
# 只校验归档（含校验每个块的哈希）
borg check --archives-only "$BORG_REPO"
| flag | 说明 |
|---|---|
--repository-only | 只查仓库级索引 |
--archives-only | 查所有归档内容 |
--verify-data | 校验块数据的哈希（最彻底，慢） |
--repair | 如不完整则修复（危险，先备份） |
⚠️
--repair可能截断损坏数据，务必先borg check --verify-data定位，并在确认后谨慎使用。
七、清理保留策略（prune）
prune 删除过期归档，按 --keep-* 保留规则计算：
borg prune --dry-run --list \
--keep-last 1 --keep-daily 2 --keep-weekly 1 "$BORG_REPO"
# Keeping archive (rule: secondly #1): ...
# Keeping archive (rule: daily[oldest] #1): ...
| 选项 | 含义 |
|---|---|
--keep-last N | 保留最近 N 个（与时间规则独立） |
--keep-secondly N | 保留最近 N 个「秒级」归档 |
--keep-minutely N | 保留最近 N 个「分钟级」 |
--keep-hourly N | 保留最近 N 个「小时级」 |
--keep-daily N | 保留最近 N 个「日级」（当日最新） |
--keep-weekly N | 保留最近 N 个「周级」（周一为代表） |
--keep-monthly N | 保留最近 N 个「月级」 |
--keep-yearly N | 保留最近 N 个「年级」 |
--keep-within FORMAT | 保留指定时间段内所有（如 14d） |
-n, --dry-run | 演练不删除 |
-p, --list | 打印每个归档的去留规则 |
⚠️
--keep-all已废弃，改用--keep-last N等。保留规则彼此独立叠加，合理组合实现「多保留近期、精简远期」。
八、综合配置模板（每日增量 + 定期清理）
cat > /etc/borg.env <<'EOF'
export BORG_REPO=/data/borg-repo
export BORG_PASSPHRASE=q1w2e3r4
export BORG_RSH="ssh -i /root/.ssh/id_ed25519 -p 22"
EOF
source /etc/borg.env
borg init --encryption=repokey-blake2 "$BORG_REPO"
# 每日备份 + 按周维度清理
borg create --stats --compression zstd,3 "$BORG_REPO"::"host{hostname}-{now}" /data/backup-src \
--exclude '*.tmp' --exclude '/data/backup-src/cache'
borg prune --keep-daily 7 --keep-weekly 4 --keep-monthly 6 "$BORG_REPO"
# 定期校验
borg check "$BORG_REPO"
💡 适配「服务器级常规数据、每日全量加去重、按日月周保留」的生产场景；SSH 远程备份把
BORG_REPO改为user@host:/path并在BORG_RSH指定私钥。
九、常见问题
Q1：加密模式能改吗？
不能。borg init 决定加密模式且不可更改。若需换模式需新建仓库重新备份。
Q2：--compression 与去重什么关系？
压缩在去重之后：先按块去重（只存唯一块），再对块压缩。两者共同决定存储占用，--stats 同时显示 Compressed 与 Deduplicated 便于观察。
Q3：check 时加 --verify-data 会很慢？
会。--verify-data 对每个数据块重新计算哈希，最彻底但最慢；定期（如每月）做一次即可，日常用默认快速校验。
Q4：远程备份报 Connection refused？
先确认远端 SSH 可达、BORG_RSH 私钥正确；远端需安装 borg（或用 BORG_REMOTE_PATH 指定 borg 可执行路径）。