BorgBackup 常用 CLI 命令详解

目标：系统讲解 borg v1.2.8 的常用命令行。borg 命令统一为 borg <command> <参数>，核心生命周期为「初始化仓库 → 创建备份 → 列出/校验 → 提取还原 → 清理归档 → 密钥管理」。本文按此流程分组讲解，所有回显来自真实执行。

一、环境信息与准备

borg 版本：v1.2.8
仓库：/data/borg-repo（repokey BLAKE2b 加密）
数据源：/data/backup-src

export BORG_REPO=/data/borg-repo
export BORG_PASSPHRASE=q1w2e3r4
mkdir -p /data/backup-src
echo "log line 1" > /data/backup-src/app.log
echo "alpha" > /data/backup-src/docs.md

二、仓库初始化与信息

2.1 init —— 初始化仓库

borg init --encryption=repokey-blake2 "$BORG_REPO"

输出含安全提示（旧版本兼容、密钥需备份告警），初始化成功后仓库可被 borg 操作。

2.2 info —— 仓库信息

borg info "$BORG_REPO"

实测输出（关键行）：

Repository ID: 091e506219453d6ad158790f29f8816c8621998febcb949bb1a02a485b598865
Location: /data/borg-repo
Encrypted: Yes (repokey BLAKE2b)
                       Original size      Compressed size    Deduplicated size
All archives:                    0 B                  0 B                  0 B

💡 使用 borg info <repo>（非旧版 repo-info）。

三、备份创建（create）

3.1 首次全量备份

borg create --list --stats "$BORG_REPO"::"host{hostname}-$(date +%F-%H%M%S)" /data/backup-src

实测回显（去重统计）：

------------------------------------------------------------------------------
Repository: /data/borg-repo
Archive name: host4e9a45ab11c5-2026-10-08-053931
Number of files: 3
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
This archive:                  628 B                726 B                726 B
All archives:                   43 B                172 B              1.12 kB

3.2 增量备份（去重）

echo "new line" >> /data/backup-src/app.log
echo "second doc" > /data/backup-src/notes.txt
borg create --list --stats "$BORG_REPO"::"host{hostname}-inc2" /data/backup-src

关键指标：

Number of files: 4
                       Original size      Compressed size    Deduplicated size
This archive:                  629 B                788 B                674 B
Chunk index:                       9                   11

💡 This archive Original 629 B，但 Deduplicated 仅 674 B——多数字节复用首次备份的块，证实块级去重生效。

四、列出与校验

4.1 list —— 列出归档/归档内文件

# 列出所有归档
borg list "$BORG_REPO"
# host4e9a45ab11c5-2026-10-08-053931   Thu, 2026-10-08 05:39:31 [fingerprint...]
# host4e9a45ab11c5-inc2                Thu, 2026-10-08 05:39:37 [fingerprint...]

# 列出指定归档内文件
borg list "$BORG_REPO"::host4e9a45ab11c5-inc2
# drwxr-xr-x root   root          0 Thu, 2026-10-08 05:37:38 data/backup-src
# -rw-r--r-- root   root         18 Thu, 2026-10-08 05:37:38 data/backup-src/docs.md
# ...

4.2 check —— 完整性校验

borg check "$BORG_REPO"           # 校验仓库 + 归档（无输出即通过）
borg check --verify-data "$BORG_REPO"   # 校验每个块哈希，最彻底（慢）
borg check --repository-only "$BORG_REPO"  # 只查仓库索引

4.3 diff —— 比较两个归档差异

borg diff "$BORG_REPO"::host4e9a45ab11c5-2026-10-08-053931 "$BORG_REPO"::host4e9a45ab11c5-inc2
# 逐文件显示 changed/added/modified 差异

五、提取还原（extract）

5.1 完整提取_restore

cd /tmp && mkdir -p borg-restore && cd borg-restore
borg extract "$BORG_REPO"::host4e9a45ab11c5-inc2

find data -type f | sort
# data/backup-src/app.log
# data/backup-src/big.dat
# data/backup-src/docs.md
# data/backup-src/notes.txt

5.2 提取单个路径

cd /tmp/borg-restore
borg extract "$BORG_REPO"::host4e9a45ab11c5-inc2 data/backup-src/docs.md
ls data/backup-src/           # 只含 docs.md

💡 borg extract 默认解压到当前工作目录，保留原相对路径；指定归档后路径参数可只还原部分文件。

5.3 mount / umount —— 挂载浏览

mkdir -p /mnt/borg
borg mount "$BORG_REPO"::host4e9a45ab11c5-inc2 /mnt/borg
ls /mnt/borg/data/backup-src/
borg umount /mnt/borg

💡 mount 用 FUSE 把归档只读挂载，方便直接浏览/找回单个文件，无需全量解压。

六、清理保留策略（prune）

6.1 演练（--dry-run）

borg prune --dry-run --list --keep-last 1 --keep-daily 2 --keep-weekly 1 "$BORG_REPO"

实测回显：

Keeping archive (rule: secondly #1):     host4e9a45ab11c5-inc2 ...
Keeping archive (rule: daily[oldest] #1): host4e9a45ab11c5-2026-10-08-053931 ...

6.2 实际清理

borg prune --keep-last 1 --keep-daily 2 --keep-weekly 1 "$BORG_REPO"

⚠️ 删除操作不可逆，先 --dry-run --list 确认被删归档，再执行。

七、密钥管理（key）

# 导出密钥（备份兜底，可打印格式）
borg key export "$BORG_REPO" /root/borg-key.txt

# 导入密钥
borg key import "$BORG_REPO" /root/borg-key.txt

# 更换口令
borg key change-passphrase "$BORG_REPO"
# 交互提示输入新旧口令

💡 密钥与口令都是解密仓库的凭据，务必分开保管、离线备份。

八、远程备份（SSH）

仓库路径支持 user@host:/path，走 SSH 备份到远端：

export BORG_REPO=backupuser@192.168.1.50:/srv/borg-repo
export BORG_PASSPHRASE=q1w2e3r4
export BORG_RSH="ssh -i /root/.ssh/id_ed25519 -p 22"
ssh-copy-id backupuser@192.168.1.50   # 首次建立免密

borg init --encryption=repokey-blake2 "$BORG_REPO"
borg create --stats "$BORG_REPO"::"host{hostname}-{now}" /data/backup-src

⚠️ 远端主机需安装 borg；若远端 borg 不在 PATH，用 BORG_REMOTE_PATH=/usr/bin/borg 指定。

九、端到端实测链路

完整「备份 → 校验 → 还原 → 清理」：

export BORG_REPO=/data/borg-repo
export BORG_PASSPHRASE=q1w2e3r4

# 1. 备份（首备 + 增量）
borg create --stats --compression lz4 "$BORG_REPO"::day1 /data/backup-src
echo "more" >> /data/backup-src/app.log
borg create --stats "$BORG_REPO"::day2 /data/backup-src

# 2. 校验
borg check "$BORG_REPO"   # 通过则无输出

# 3. 还原
cd /tmp/restore && borg extract "$BORG_REPO"::day2

# 4. 清理旧归档
borg prune --dry-run --list --keep-last 2 "$BORG_REPO"

常见问题

Q1：borg repo-info/archive-info 报 not a valid choice？

borg 1.2 子命令改为 info（查仓库）与 list（查归档/内容），无 repo-info。

Q2：extract 后文件不在期望位置？

extract 解压到当前工作目录（相对于运行路径），且默认保留 / 之前的相对结构。先 cd 到目标目录再 extract。

Q3：check 报仓库损坏如何处理？

先 borg check --verify-data 定位坏块；再用 borg export-tar/优先从备份副本恢复。确需修复才用 --repair，但会截断损坏数据，务必先备份仓库。

Q4：远程备份很慢？

加 --compression lz4/lz4，zstd、限并发 --checkpoint-interval，或用 BORG_RSH 指定 -o Compression=no（若 SSH 已压缩则避免重复压缩）、调 --upload-ratelimit。

参考链接

borg 命令索引：https://borgbackup.readthedocs.io/en/stable/usage.html
borg extract：https://borgbackup.readthedocs.io/en/stable/usage/extract.html
borg mount：https://borgbackup.readthedocs.io/en/stable/usage/mount.html