BorgWarehouse 拓展 | 结合borgmatic实现自动备份指南

指南 | Guides 2025年4月23日

1. First | 序

近期有盆友评论说使用 borgmatic 结合 BorgWarehouse 时遇到了问题

早在记录 BorgWarehouse 时就已经提到了 borgmatic 但也只是一笔带过

既然有盆友需要就简单记录一下

1.1. Preconditions | 前提条件

确保 BorgWarehouse & Borgbackup 已部署并正常运行
一定的问题检索能力
以下文档供参考

1.2. OS&APP Version | * 版本

1.2.1. OS

1.2.2. Borgbackup

1.2.3. Borgmatic

1.9.5

1.2.4. BorgWarehouse

2.4.4

2. Procedure | 步骤

Install borgmatic | 安装 borgmatic
生成 ssh 密钥对
添加存储库
编辑 /etc/borgmatic/config.yaml
修改/root/.ssh/config
使用borgmatic初始化存储库
使用 Borgmatic 完成备份
Borgmatic 定时备份

2.1. Install borgmatic | 安装 borgmatic

以 openSUSE Tumbleweed 为例

zypper install borgmatic

⚠️

注意事项

以避免一些问题 borgmatic 并不会附带安装 borgbackup
请至少保持 borgbackup 版本在 1.1 以上
因为 openSUSE Tumbleweed 属于滚动发行版所以borgmatic&borgbackup版本较新,若你的发行版不提供较新的版本,请使用 pipx 安装

2.2. 生成 ssh 密钥对

客户端安装完 borgmatic 后需要使用 BorgWarehouse 生成密钥对

获取 BorgWarehouse 容器ID

podman ps -a --filter "name=容器名称" --format "{{.ID}}"

Ex | 示例

podman ps -a --filter "name=BorgWarehouse" --format "{{.ID}}"

18d5e2da8dd3

进入 BorgWarehouse 容器 shell 交互环境

获取到容器ID后我们进入 BorgWarehouse 容器 shell
```
podman exec -it 18d5e2da8dd3 /bin/bash
```

生成密钥对

ssh-keygen -t ed25519 -C https://xzllll.com/25042301

-C 选项用来备注此密钥对

查找密钥对

生成的密钥对位于容器的 /home/borgwarehouse/.ssh 下分别是
- 私钥 id_ed25519
- 公钥 id_ed25519.pub

⚠️

注意事项

生成的密钥对位于容器 /home/borgwarehouse/.ssh 目录,也可根据部署BorgWarehouse时映射的目录找到此密钥对
这两个私钥和公钥我们均需要,请妥善保管
整个过程看起来像这样

2.3. 添加存储库

获取密钥对后紧接着需要使用 BorgWarehouse 添加一个存储库

打开 BorgWarehouse 控制台点击上方的 Add a repository
可以看到以下四个选项(注释如下)

Alias

别名,给你的repository起一个好听的名字

SSH public key

即在2.2节我们获取到的密钥对其中的 id_ed25519.pub
使用cat查看此值填上即可

Storage Size (GB)

repository 的配额

Comment

一些备注~

看起来像这样
确认参数

确认参数没问题后点击下方 add 添加即可

此时 BorgWarehouse 已经给此 repository 分配了 ID

示例为ec43d555

2.4. 编辑 /etc/borgmatic/config.yaml

接着我们转过头来编辑 /etc/borgmatic/config.yaml

示例如下


## 想要备份的目录

source_directories:
  - /etc
  - /opt
  - /home
  - /root
  - /usr/share/containers/systemd
  - /var/lib/containers/storage/volumes
  
## 排除的目录

exclude_patterns:
  - /etc/udev
  - /root/.cache

#仓库地址(此地址参考控制台https://borgwarehouse.xxx/setup-wizard/4 生成的链接)

repositories:
  - path: ssh://[email protected]:2222/./cd283v0

# 档案的命名方式

archive_name_format: 'hostname-{now}'
encryption_passphrase: ""

#保存策略

keep_daily: 4
keep_weekly: 2
keep_monthly: 4

#检查策略

checks:
  - name: repository
  - name: archives
    frequency: 2 weeks

#仅备份/目录,忽略挂载目录

one_file_system: true

⚠️

注意事项

关于配置 /etc/borgmatic/config.yaml

BorgWarehouse 有可以参考的配置

此配置在控制台链接的 /setup-wizard/4 下

但此配置格式在新版的 Borgmatic 中已经不再使用

格式方面还请参考上述示例

2.5. 修改/root/.ssh/config

编辑完 /etc/borgmatic/config.yaml 后我们还不能初始化仓库

而是需要编辑 borgmatic 所在主机的 /root/.ssh/config 文件

编辑此文件的目的在于需要让 BorgWarehouse 正确识别客户端

Host 1.1.1.1
        HostName 1.1.1.1
        User borgwarehouse
        IdentityFile /root/.ssh/id_borgwarehouse

此文件大概释义为:

当使用ssh链接 BorgWarehouse 服务器时请使用/root/.ssh/id_borgwarehouse私钥进行认证

⚠️

注意事项

IdentityFile
- 此文件必须存在
- 内容为2.2节生成的id_ed25519
- 此文件权限必须为600

Ex | 示例

2.6. 使用borgmatic初始化存储库

borgmatic init -e repokey-blake2

回显如下

The authenticity of host '' can't be established.
ED25519 key fingerprint is SHA256:J2V6/5gOrnsRz4AWew.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Remote: Warning: Permanently added ' (ED25519) to the list of known hosts.
Repository ssh://borgwarehouse@:2222/./9d48eb4c does not exist.

IMPORTANT: you will need both KEY AND PASSPHRASE to access this repo!

Key storage location depends on the mode:
- repokey modes: key is stored in the repository directory.
- keyfile modes: key is stored in the home directory of this user.

For any mode, you should:
1. Export the borg key and store the result at a safe place:
   borg key export           REPOSITORY encrypted-key-backup
   borg key export --paper   REPOSITORY encrypted-key-backup.txt
   borg key export --qr-html REPOSITORY encrypted-key-backup.html
2. Write down the borg key passphrase and store it at safe place.

⚠️

注意事项

密钥指纹

连接时shell会回显密钥指纹

即 ED25519 key fingerprint is SHA256:J2V6/......Rz4AWew

此值一定要与 BorgWarehouse 中提供的一致
Repository 不存在

初始化时会提示 Repository ssh://borgwarehouse@:2222/./9d48eb4c does not exist.

这是因为你在使用 BorgWarehouse 创建 Repository 时实际上只是分配了一个 Repository ID以便 BorgWarehouse 识别不同的 Borgmatic

BorgWarehouse 不会也没有必要创建 Repository

当 Borgmatic 检测到此 Repository 不存在时会自动创建并完成初始化

同时这也是 BorgWarehouse 控制台检测 Borgmatic 是否在线的手段

Borgmatic 初始化前

Borgmatic 初始化后

2.7. 使用 Borgmatic 完成备份

初始化完成后即可使用 Borgmatic 完成备份

borgmatic create --verbosity 1 --list --stats

参数	作用
`create`	运行备份任务，即执行 `borg create`，创建一个新的快照
`--verbosity 1`	输出信息等级为 1，显示关键步骤和命令
`--list`	在创建备份时，列出被包含进备份的所有文件
`--stats`	在备份结束后，显示备份统计信息（备份大小、耗时、压缩率等）

统计信息节选如下

Archive fingerprint: 247fd38619c1ec2273ae2ecca4e19951204dfbbea93e46fe75627bb091118ed2
Time (start): Wed, 2025-04-23 16:52:16
Time (end):   Wed, 2025-04-23 16:53:51
Duration: 1 minutes 35.01 seconds
Number of files: 62654
Utilization of max. archive size: 0%
------------------------------------------------------------------------------
                       Original size      Compressed size    Deduplicated size
This archive:                2.44 GB            981.10 MB            925.48 MB
All archives:                2.44 GB            981.09 MB            925.78 MB
                       Unique chunks         Total chunks
Chunk index:                   59172                62843
------------------------------------------------------------------------------

2.8. Borgmatic 定时备份

Borgmatic 启用定时备份有两种方式分别是

systemd
cron

这里以 cron 为例

编辑 /etc/cron.d/borgmatic 并写入如下内容

0 3 * * * root PATH=$PATH:/usr/bin:/usr/local/bin /root/.local/bin/borgmatic --verbosity -1 --syslog-verbosity 1

项目	内容
`0 3 * * *`	Cron 定时任务时间：每天凌晨 3:00 执行
`root`	指定以 `root` 用户身份运行该命令
`PATH=$PATH:/usr/bin:/usr/local/bin`	设置 PATH 环境变量，确保找到必要命令
`/root/.local/bin/borgmatic`	指定 borgmatic 可执行文件路径
`--verbosity -1`	日志静默模式：仅输出错误（等价于 Borg 的 `--info`）
`--syslog-verbosity 1`	将日志写入系统日志（syslog），级别为 1（常用于系统级日志记录）