Ubuntu 22.04 安装 Backrest v1.14.1 指南

在 Ubuntu 22.04 上以 install.sh 与手动两种方案安装 Backrest v1.14.1，含 systemd 托管、首配置、首个备份与恢复闭环及排障实录，全程实测。

BackrestUbuntu 22.04安装部署数据备份Linux2026/10/26

Ubuntu 22.04 安装 Backrest v1.14.1 指南

目标：在 Ubuntu 22.04 服务器上从 0 到 1 装好 Backrest v1.14.1（restic 的 Web UI 与备份编排器），完成 systemd 托管、首配置、首个备份与文件恢复的完整闭环。本文全部命令与回显已在 Ubuntu 22.04.5 LTS (x86_64) 环境实测通过，涉及组件版本：Backrest v1.14.1、restic v0.19.1。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS (x86_64)，已启用 systemd；
  • Backrest：v1.14.1（commit 875c9cb51e626a75276a64da42c6a9ec0695010a）；
  • restic：v0.19.1（Backrest 官方发布物配套版本，由 Backrest 托管安装）；
  • 安装路径：二进制 /usr/local/bin/backrest，WebUI 静态资源 /usr/local/share/backrest，数据目录 ~/.local/share/backrest/，配置文件 ~/.config/backrest/config.json；
  • 服务单元：/etc/systemd/system/backrest.service，默认监听 127.0.0.1:9898；
  • 演示运行用户：admin（口令 q1w2e3r4），演示备份源 /srv/demo-data，演示仓库 /srv/backups/local-demo。

二、前置条件

安装开始前需要确认以下事项，逐条给出验证命令与实测回显：

  1. 确认系统版本与架构（决定下载哪个发布包）：
cat /etc/os-release | head -2 && uname -m

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
x86_64
  1. 确认 systemd 可用（安装脚本会注册 systemd 服务）：
systemctl is-system-running

实测回显：

running
  1. 准备 curl 与下载工具（最小安装的系统可能缺失）：
apt-get install -y curl bzip2

实测回显（输出节选，实测首尾）：

Reading package lists... Done
Building dependency tree... Done
...
Setting up bzip2 (1.0.8-5build1) ...
  1. 网络要求：默认安装会从 GitHub Releases 下载 Backrest 发布包与 restic 二进制。若服务器无法直连 GitHub，请先配置可用代理（本文排障实录见十、10.2），或改用方案 B 手动放置二进制。

三、版本选型说明

选版本前先看官方发布线（检索日期 2026-10-26）：

版本发布日期关键内容
v1.13.02026-05-04常规功能版本
v1.14.02026-07-12仪表盘重构、托盘状态、韩语/波兰语翻译、restic 升级至 v0.19.1、多主机同步修复
v1.14.12026-07-12修复保留策略/forget 被静默跳过、仓库 ID 变更后快照文件下载失败

选型结论：新装一律选最新稳定版 v1.14.1——它修复了 v1.14.0 中「按计划保留策略被静默跳过」的问题，备份系统对「保留策略是否真的生效」最敏感，不应停留在带此缺陷的版本。Backrest 发布包与 restic 版本绑定管理（v1.14.x 对应 restic v0.19.1），无需自行对齐版本。

四、方案 A：官方发布包 + install.sh 安装（推荐）

4.1 方案说明

从 GitHub Releases 下载官方发布包 backrest_Linux_x86_64.tar.gz，包内自带 install.sh 安装脚本：自动放置二进制、安装托管的 restic、生成 systemd 服务单元并启动。这是官方 README 推荐路径，适合绝大多数可联网服务器。

4.2 下载与完整性校验

创建下载目录并下载发布包与官方校验和文件：

mkdir -p /opt/backrest-dl && cd /opt/backrest-dl
curl -sL -O https://github.com/garethgeorge/backrest/releases/download/v1.14.1/backrest_Linux_x86_64.tar.gz
curl -sL -O https://github.com/garethgeorge/backrest/releases/download/v1.14.1/backrest_1.14.1_checksums.txt

校验 sha256，本地值必须与官方校验和文件一致：

sha256sum backrest_Linux_x86_64.tar.gz
grep linux_x86_64 backrest_1.14.1_checksums.txt

实测回显（两行哈希一致即校验通过）：

acc7835a9c55b3d254f0fa285cacbe87ac912cb7e069d0211924838020e6921c  backrest_Linux_x86_64.tar.gz
acc7835a9c55b3d254f0fa285cacbe87ac912cb7e069d0211924838020e6921c  backrest_Linux_x86_64.tar.gz

解压并确认包内清单：

mkdir -p extract && tar -xzf backrest_Linux_x86_64.tar.gz -C extract && ls -la extract

实测回显：

total 43240
drwxr-xr-x 2 root  root     4096 Oct 26 08:16 .
drwxr-xr-x 3 root  root     4096 Oct 26 08:16 ..
-rw-r--r-- 1 root  root    77706 Oct 26 08:12 CHANGELOG.md
-rwxr-xr-x 1 root  root  44136624 Oct 26 08:12 backrest
-rw-r--r-- 1 root  root    11357 Oct 26 08:12 install.sh
-rw-r--r-- 1 root  root    35149 Oct 26 08:12 LICENSE
-rw-r--r-- 1 root  root    13756 Oct 26 08:12 README.md
-rwxr-xr-x 1 root  root      117 Oct 26 08:12 uninstall.sh

确认二进制版本与运行参数：

cd extract && ./backrest -version

实测回显：

If you're reading this, you're unnecessarily importing github.com/ncruces/go-sqlite3/embed.
backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a

💡 说明：第一行「unnecessarily importing …」是上游 sqlite 库的构建期提示，每次运行 -version 都会输出，属正常现象，不影响任何功能。

4.3 创建专用运行用户

不建议用 root 日常运行备份服务。创建专用用户 admin（演示口令 q1w2e3r4）并赋予 sudo，供安装脚本在安装阶段调用：

useradd -m -s /bin/bash admin
echo "admin:q1w2e3r4" | chpasswd
echo "admin ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/admin
chmod 440 /etc/sudoers.d/admin

验证 sudo 可用：

su - admin -c "sudo whoami"

实测回显：

root

4.4 执行安装

以运行用户身份执行安装脚本。参数含义：--no-tray 安装为 systemd 服务（而非桌面托盘模式）、--from-local 使用当前目录的 backrest 二进制、--allow-remote-access 监听 0.0.0.0:9898 允许远程访问（缺省仅监听 127.0.0.1）、--root 表示确知以 root 执行（本步以 admin 身份执行故无需）：

chmod -R a+rX /opt/backrest-dl
su - admin -c "cd /opt/backrest-dl/extract && bash install.sh --no-tray --from-local --allow-remote-access"

实测回显：

- Installing Backrest 1.14.1 ...
- Installing backrest to /usr/local/bin
- Installing restic to /home/admin/.local/share/backrest/restic
- Installing UI assets to /usr/local/share/backrest
- Creating systemd service at /etc/systemd/system/backrest.service
If Backrest was previously installed as a system service, it may need to be restarted:
  sudo systemctl restart backrest
successfully installed backrest!
If installing for the first time, run:
  sudo systemctl enable --now backrest
Created symlink /etc/systemd/system/multi-user.target.wants/backrest.service → /etc/systemd/system/backrest.service.
Started backrest systemd service

=== Installation Summary ===
  Previous version : not installed
  New version      : backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a
  Install mode     : service
  Logs             : ~/.local/share/backrest/processlogs/backrest.log
  Access URL       : http://0.0.0.0:9898 (remote access enabled)
  Note: Ensure proper firewall configuration or authentication is set up.
============================

安装脚本实际完成四件事：二进制放 /usr/local/bin/backrest、托管的 restic 放 ~/.local/share/backrest/restic、WebUI 静态资源放 /usr/local/share/backrest、生成并启动 systemd 服务。

4.5 首次启动与状态验证

服务已被脚本拉起，逐项验证：

systemctl is-active backrest

实测回显：

active

systemctl status backrest --no-pager -l | head -7

实测回显：

● backrest.service - Backrest Service
     Loaded: loaded (/etc/systemd/system/backrest.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-26 08:25:56 UTC; 8min ago
   Main PID: 3748 (backrest)
      Tasks: 12 (limit: 3172)
     Memory: 14.0M
        CPU: 18.861s

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9898/

实测回显：

200

HTTP 200 即 WebUI 已就绪。生成的服务单元如下（cat /etc/systemd/system/backrest.service 实测）：

[Unit]
Description=Backrest Service
After=network.target

[Service]
Type=simple
User=admin
Group=admin
ExecStart=/usr/local/bin/backrest
Restart=on-failure
Environment="BACKREST_PORT=0.0.0.0:9898"

[Install]
WantedBy=multi-user.target

⚠️ 注意：User=admin 说明 Backrest 及其调起的 restic、钩子命令全部以 admin 身份运行，备份源与恢复目标目录的读写权限都要按这个用户规划。

五、方案 B：手动安装（二进制 + 手写 systemd 单元）

5.1 方案说明

不依赖 install.sh，手动放置 Backrest 与 restic 二进制、手写 systemd 单元。适合两类场景：无法访问 GitHub、需要把安装过程完全纳入运维脚本管控。

5.2 放置二进制与 restic

沿用 4.2 节下载解压的发布包，手动安装 Backrest 主程序：

install -m 755 /opt/backrest-dl/extract/backrest /usr/local/bin/backrest
/usr/local/bin/backrest -version

实测回显：

If you're reading this, you're unnecessarily importing github.com/ncruces/go-sqlite3/embed.
backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a

💡 说明：v1.14.1 的 WebUI 静态资源内嵌在二进制中，发布包内无独立 webui 目录（见 4.2 节清单），手动安装无需放置静态资源；install.sh 输出中的「Installing UI assets to /usr/local/share/backrest」是其安装摘要的固定行，资源实际随二进制加载。

手动安装 restic 到 Backrest 托管路径（默认 Backrest 会自动从 GitHub 下载；网络受限时此手动方式为标准替代，下载地址取自官方 restic Releases）：

cd /tmp
curl -sL -O https://github.com/restic/restic/releases/download/v0.19.1/restic_0.19.1_linux_amd64.bz2
bunzip2 -t restic_0.19.1_linux_amd64.bz2 && bunzip2 -k restic_0.19.1_linux_amd64.bz2
chmod +x restic_0.19.1_linux_amd64
./restic_0.19.1_linux_amd64 version
install -m 755 -o admin -g admin restic_0.19.1_linux_amd64 /home/admin/.local/share/backrest/restic

实测回显：

restic 0.19.1 compiled with go1.26.4 on linux/amd64

💡 说明：托管 restic 的路径固定为 ~/.local/share/backrest/restic（~ 为运行用户家目录）。Backrest 启动时会校验该文件的存在与版本，校验通过即按托管模式使用。

5.3 手写 systemd 单元

/etc/systemd/system/backrest.service 内容与方案 A 生成的一致（手动部署时逐行写入）：

cat > /etc/systemd/system/backrest.service <<'EOF'
[Unit]
Description=Backrest Service
After=network.target

[Service]
Type=simple
User=admin
Group=admin
ExecStart=/usr/local/bin/backrest
Restart=on-failure
Environment="BACKREST_PORT=0.0.0.0:9898"

[Install]
WantedBy=multi-user.target
EOF

5.4 启动与验证

systemctl daemon-reload
systemctl enable backrest
systemctl start backrest
systemctl is-active backrest

实测回显（逐行对应）：

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

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9898/

实测回显：

200

六、方案对比与选择建议

维度方案 A：install.sh方案 B：手动安装
是否需联网需要（下载发布包与 restic）可完全离线（二进制预先备好）
安装方式脚本自动放置 + 生成单元逐文件手工放置
systemd 来源脚本生成 /etc/systemd/system/backrest.service手写同名单元
托管 restic脚本自动下载安装手动放置到托管路径
升级重复执行脚本（幂等覆盖）重复手动步骤
适用场景可联网服务器、快速上线内网隔离、配置管理工具接管

选择建议：能访问 GitHub 选方案 A（一条命令完成且幂等，重装即升级）；内网隔离或需要审计每一行变更选方案 B。

七、配置说明（首配置：实例、用户与端口）

7.1 初始配置文件

Backrest 首次启动后会在运行用户家目录生成配置目录，配置文件为 JSON 格式：

ls -la /home/admin/.config/backrest/

实测回显（首次启动尚未初始化用户时）：

total 12
drwxr-xr-x 2 admin admin 4096 Oct 26 08:16 .
drwxr-xr-x 6 admin admin 4096 Oct 26 08:16 ..

7.2 管理用户与密码

首次用浏览器访问 http://<服务器IP>:9898，官方文档描述的初始化流程会引导设置实例 ID（Instance ID，标识本机快照来源，设置后不可通过界面修改）与首个管理用户的用户名/密码。演示环境采用用户名 admin、口令 q1w2e3r4。

若需通过配置文件直接写入用户（如初始化前批量预置、或凭据丢失后重置），写入 config.json 的 auth.users 数组，密码保存为 bcrypt 哈希。生成哈希推荐用 Backrest 自带的 HashPassword 接口（保证与校验逻辑完全兼容）：

curl -s -X POST http://127.0.0.1:9898/v1.Authentication/HashPassword \
  -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \
  -d '{"value":"q1w2e3r4"}'

实测回显（value 为哈希的 base64 编码）：

{"value":"JDJhJDEwJHBsdkFwY2dlaUlFcG5QNHVqU3BET3VMd0lzZ2hPaGxsdmpENzdOaGNWa3FvSGFlNlVBcHJh"}

解码得到 $2a$ 开头的 bcrypt 哈希，写入配置后重启服务生效：

"auth": {
  "disabled": false,
  "users": [
    { "name": "admin", "passwordBcrypt": "$2a$10$plvApcgeiIEpnP4ujSpDOuLIsg..." }
  ]
}

⚠️ 注意：密码哈希必须使用 $2a$ 前缀的 bcrypt 格式（与 HashPassword 输出一致）；用其他工具（如 htpasswd -B）生成后再核验一次前缀。忘记管理口令时，官方文档给出的重置方法：删除 config.json 中的 users 字段并重启服务。

💡 说明：Backrest 支持关闭认证（"auth": {"disabled": true}），官方定位是「本地使用或前端已挂认证反代」的场景。演示环境即采用该模式直连 gRPC 接口完成后续实测。若监听 0.0.0.0 对外，必须保持认证开启。

7.3 监听端口与远程访问

端口由 systemd 单元中的 BACKREST_PORT 环境变量控制（等价于命令行 -bind-address）：

  • 127.0.0.1:9898：仅本机可访问，配合 SSH 隧道使用最安全；
  • 0.0.0.0:9898：所有网卡可访问（install.sh 的 --allow-remote-access 即写入此值），务必配合强口令与防火墙。

修改端口后重启服务并验证监听：

systemctl restart backrest && systemctl is-active backrest

实测回显：

active

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9898/

实测回显：

200

八、首个备份与恢复 0→1

本节用演示数据完整走一遍「建仓库 → 建计划 → 备份 → 查快照 → 恢复」闭环。界面操作路径为官方文档描述的 Add Repo / Add Plan / 计划页运行；下文同时给出等价的配置文件与接口方式（均实测通过），二选一即可。

8.1 准备演示数据

mkdir -p /srv/demo-data /srv/backups
echo "backrest demo file 1" > /srv/demo-data/file1.txt
echo "backrest demo file 2" > /srv/demo-data/file2.txt
dd if=/dev/urandom of=/srv/demo-data/random.bin bs=1K count=64 2>/dev/null
chown -R admin:admin /srv/demo-data /srv/backups
ls -la /srv/demo-data

实测回显：

total 84
drwxr-xr-x 2 root  root   4096 Oct 26 08:25 .
drwxr-xr-x 4 root  root   4096 Oct 26 08:25 ..
-rw-r--r-- 1 root  root     22 Oct 26 08:25 file1.txt
-rw-r--r-- 1 root  root     22 Oct 26 08:25 file2.txt
-rw-r--r-- 1 root  root  65536 Oct 26 08:25 random.bin

8.2 新建仓库 local-demo

界面方式：WebUI 左侧 Add Repo，填仓库名 local-demo、URI 填本地目录 /srv/backups/local-demo、密码设 q1w2e3r4（演示口令），勾选自动初始化。等价的配置方式：编辑 /home/admin/.config/backrest/config.json，在顶层加入 repos 数组后重启服务：

"repos": [
  {
    "id": "local-demo",
    "uri": "/srv/backups/local-demo",
    "password": "q1w2e3r4",
    "autoInitialize": true,
    "autoUnlock": true
  }
]

配置项说明：id 仓库名（创建后不可改）；uri restic 仓库地址，本地路径直接写目录，远端写 s3:/b2:/sftp:/rclone: 形式 URI；password 仓库加密密码（明文保存在本配置文件中，由 Backrest 保管，调 restic 时自动注入）；autoInitialize 首次使用自动初始化新仓库；autoUnlock 遇到残留锁文件时自动解锁。

重启后观察自动初始化日志：

journalctl -u backrest --no-pager | grep "auto-initializing"

实测回显：

Oct 26 08:25:56 backrest-server backrest[3748]: 2026-10-26T08:25:56.743Z        INFO        auto-initializing repo        {"repo": "local-demo"}

验证仓库已按 restic 标准布局落盘：

ls /srv/backups/local-demo/

实测回显：

config
data
index
keys
locks
snapshots

8.3 新建备份计划 demo-docs

界面方式：WebUI 左侧 Add Plan，计划名 demo-docs、仓库选 local-demo、Paths 填 /srv/demo-data、调度选 cron 表达式 */5 * * * *（演示用 5 分钟一次，生产建议每日低峰），保留策略选按数量保留最近 3 份。等价的配置方式（加入 plans 数组）：

"plans": [
  {
    "id": "demo-docs",
    "repo": "local-demo",
    "paths": ["/srv/demo-data"],
    "schedule": { "cron": "*/5 * * * *" },
    "retention": { "policyKeepLastN": 3 }
  }
]

重启服务后验证计划已进入调度队列：

journalctl -u backrest --no-pager | grep "scheduled task" | grep demo-docs

实测回显：

Oct 26 08:25:59 backrest-server backrest[3748]: 2026-10-26T08:25:59.727Z        INFO        scheduled task        {"task": "backup for plan \"demo-docs\"", "runAt": "2026-10-26T08:30:00Z"}

8.4 立即执行备份

不等调度，立即触发一次：界面方式为计划页运行命令选择 Backup；接口方式如下：

curl -s -X POST http://127.0.0.1:9898/v1.Backrest/Backup \
  -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \
  -d '{"value":"demo-docs"}' -w "\n[%{http_code}]\n"

实测回显：

{}
[200]

等待数秒后查看操作记录与执行日志：

journalctl -u backrest --no-pager --since "2 minutes ago" | grep -E "running task|snapshot" | tail -3

实测回显：

Oct 26 08:27:05 backrest-server backrest[3748]: 2026-10-26T08:27:05.384Z        INFO        running task        {"task": "backup for plan \"demo-docs\"", "runAt": "2026-10-26T08:27:05Z"}
Oct 26 08:27:07 backrest-server backrest[3748]: 2026-10-26T08:27:07.427Z        INFO        backup for plan \"demo-docs\"        {"totalDuration": 0.763519664}

8.5 查看快照

curl -s -X POST http://127.0.0.1:9898/v1.Backrest/ListSnapshots \
  -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \
  -d '{"repoId":"local-demo"}'

实测回显（输出节选，实测首尾）：

{"snapshots":[{"id":"c73363b1d43cf444f8888429f65d268ee3740b0eae8628c0a37bea85123ad232","unixTimeMs":"1793003226654","hostname":"backrest-server","username":"admin","tree":"2f8e9acbbf8d6a6dbe623963d37d1abbf87557ab0bbdd0e12b7fe6fe1f16702d","paths":["/srv/demo-data"],"tags":["plan:demo-docs","created-by:backrest-server"],"summary":{"filesNew":"4","dirsNew":"2","dataBlobs":"4","treeBlobs":"3","dataAdded":"67739","totalFilesProcessed":"4","totalBytesProcessed":"65599","totalDuration":0.763,...}},
...
{"snapshots": ... ]}

💡 说明：快照带 plan:demo-docs 与 created-by:backrest-server 标签，这是 Backrest 区分不同计划快照、执行保留策略的依据。用原生 restic CLI 也能看到同样的快照（见本专栏命令篇）。

验证定时调度真实生效：等 cron 到点（08:30）后看日志：

journalctl -u backrest --no-pager --since "08:29" | grep "running task" | grep backup

实测回显：

Oct 26 08:30:01 backrest-server backrest[3748]: 2026-10-26T08:30:01.500Z        INFO        running task        {"task": "backup for plan \"demo-docs\"", "runAt": "2026-10-26T08:30:01Z"}

8.6 恢复文件到指定路径

界面方式（官方文档流程）：进入快照视图浏览文件树，选中目录后选择 Restore to path 填目标路径；接口方式如下（从快照中把 /srv/demo-data 恢复到 /srv/backups/restore-out）：

curl -s -X POST http://127.0.0.1:9898/v1.Backrest/Restore \
  -H "Content-Type: application/json" -H "Connect-Protocol-Version: 1" \
  -d '{"planId":"demo-docs","repoId":"local-demo","snapshotId":"3f0eb479d42f441b72dc7dd318dcb85a2d3a464bebb9d728aafb796671c6f69b","path":"/srv/demo-data","target":"/srv/backups/restore-out"}' -w "\n[%{http_code}]\n"

实测回显：

{"operationId":"17"}
[200]

验证恢复结果与源文件一致：

find /srv/backups/restore-out -type f
cat /srv/backups/restore-out/demo-data/file1.txt
md5sum /srv/demo-data/random.bin /srv/backups/restore-out/demo-data/random.bin

实测回显：

/srv/backups/restore-out/demo-data/file3.txt
/srv/backups/restore-out/demo-data/file2.txt
/srv/backups/restore-out/demo-data/file1.txt
/srv/backups/restore-out/demo-data/random.bin
backrest demo file 1
edeb9c386e69c13092515c3955b5e55f  /srv/demo-data/random.bin
edeb9c386e69c13092515c3955b5e55f  /srv/backups/restore-out/demo-data/random.bin

md5 一致，恢复闭环完成。两个实测踩过的权限坑见十、10.3 与 10.4。

九、升级、降级与多版本管理

升级：install.sh 幂等，下载新版本发布包后重跑安装脚本即可（自动覆盖二进制并重启服务）。以下为同版本重装实测（输出同时给出了旧/新版本对照行，跨版本升级时 Previous version 会显示旧版本号）：

su - admin -c "cd /opt/backrest-dl/extract && bash install.sh --no-tray --from-local --allow-remote-access"

实测回显（输出节选，实测首尾）：

- Installing backrest to /usr/local/bin
...
Creating systemd service at /etc/systemd/system/backrest.service
Created symlink /etc/systemd/system/multi-user.target.wants/backrest.service → /etc/systemd/system/backrest.service.
Started backrest systemd service

=== Installation Summary ===
  Previous version : backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a
  New version      : backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a
  Install mode     : service
...

升级后验证：

/usr/local/bin/backrest -version && systemctl is-active backrest

实测回显：

If you're reading this, you're unnecessarily importing github.com/ncruces/go-sqlite3/embed.
backrest version: 1.14.1, commit: 875c9cb51e626a75276a64da42c6a9ec0695010a
active

降级：把上述流程中的发布包换成旧版本 URL（如 v1.13.0 的 backrest_Linux_x86_64.tar.gz）重跑即可；配置文件与数据目录向后兼容性以官方 CHANGELOG 为准，降级前建议先备份 config.json 与数据目录。

多版本并存：Backrest 为单二进制常驻服务，不做并行多实例设计。如需灰度，可在另一目录放置不同版本二进制，用独立的 systemd 单元（改 ExecStart 路径、BACKREST_PORT 端口与 BACKREST_CONFIG 配置路径）跑第二实例。

十、常见问题（FAQ）

10.1 服务反复重启，日志报 install.lock

现象：systemctl is-active 在 activating 与 failed 间循环，日志出现：

{"level":"error","ts":1793002893.0953624,"caller":"resticinstaller/resticinstaller.go:120","msg":"failed to download restic","error":"Get \"https://github.com/restic/restic/releases/download/v0.19.1/restic_0.19.1_linux_amd64.bz2\": dial tcp 20.205.243.166:443: connect: connection refused"}

随后每次重启尝试重装 restic 时报：

fatal error: another instance of backrest is running, or install.lock is stale. If this is intentional, remove the file

定位：Backrest 首次启动会自动从 GitHub 下载托管 restic；网络不可达导致下载失败，而中断残留的 install.lock 又让下一次启动直接退出，Restart=on-failure 因此陷入循环。

解决：二选一。可联网但有代理的，给服务单元加代理环境变量后 systemctl daemon-reload && systemctl restart backrest；完全无法出网的，按五、5.2 手动把 restic 放到 ~/.local/share/backrest/restic 并清理锁文件：

rm -f /home/admin/.local/share/backrest/install.lock
systemctl restart backrest && systemctl is-active backrest

实测回显：

active

10.2 GitHub 下载超时/被拒的通用处理

内网隔离或防火墙环境常见 connection refused / i/o timeout。标准解法是在服务单元 [Service] 段追加（代理地址按实际环境替换）：

Environment="HTTPS_PROXY=http://192.168.1.62:7897"
Environment="HTTP_PROXY=http://192.168.1.62:7897"

然后：

systemctl daemon-reload
systemctl restart backrest

验证方式同 10.1：日志不再出现下载报错、systemctl is-active 稳定 active、~/.local/share/backrest/restic 出现且 ~/.local/share/backrest/restic version 可执行。

10.3 钩子命令执行失败（exit status 2）

现象：备份成功但操作记录里钩子任务失败：

exit status 2

running command hook plan/demo-docs/hook/0 triggered by CONDITION_SNAPSHOT_SUCCESS

定位：钩子命令由 Backrest 服务用户（本例 admin）执行。实测把钩子输出重定向到 /srv/hook-ran.log（/srv 属 root 不可写）即复现此错。

解决：把钩子写入目标改到服务用户可写目录（如 /srv/backups/，属主已 chown admin:admin），修改后重跑备份验证钩子日志出现：

hook-fired-at-2026-10-26_08:28:24

10.4 恢复时报「target directory already exists」

现象：

{"code":"failed_precondition","message":"target directory \"/srv/restore-test\" already exists"}

定位：Backrest 恢复时自行创建目标目录，要求目标目录不存在且其父目录对服务用户可写。实测先建好空目录会触发上述错误；父目录不可写则报 mkdir /srv/restore-test: permission denied。

解决：目标路径选在服务用户可写的父目录下且预先删除同名目录，如目标定为 /srv/backups/restore-out（父目录 /srv/backups 属 admin）后重试即成功。

10.5 快照还在，restic CLI 恢复却报找不到快照

现象：直接用 restic CLI 恢复一个「曾在界面上看到的」快照 ID 时报：

Load(<snapshot/c73363b1d4>, 0, 0) failed: open /srv/backups/local-demo/snapshots/c73363b1d43cf444f8888429f65d268ee3740b0eae8628c0a37bea85123ad232: no such file or directory
Fatal: failed to find snapshot: failed to load snapshot c73363b1: open /srv/backups/local-demo/snapshots/c73363b1d43cf444f8888429f65d268ee3740b0eae8628c0a37bea85123ad232: no such file or directory

定位：计划保留策略 policyKeepLastN: 3 已在后台自动 forget 了更早的快照（实测中 c73363b1… 正是这样被裁掉的），快照 ID 失效。

解决：执行 restic 操作前先拉取当前快照列表（界面快照视图或 restic snapshots），用现存快照 ID 操作。这正是「先 forget 后 prune」体系的正常行为，不是数据损坏。

十一、卸载与清理

发布包自带卸载脚本（等价于 install.sh --uninstall）：

su - admin -c "cd /opt/backrest-dl/extract && bash uninstall.sh"

手动清理（与脚本等价的逐项命令，按需执行）：

systemctl disable backrest

实测回显：

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

systemctl stop backrest && systemctl is-active backrest

实测回显：

inactive

rm -f /etc/systemd/system/backrest.service /usr/local/bin/backrest
rm -rf /usr/local/share/backrest /home/admin/.config/backrest /home/admin/.local/share/backrest
rm -rf /srv/backups /srv/demo-data
systemctl daemon-reload

卸载后确认无残留：

systemctl status backrest --no-pager | head -3

实测回显：

Unit backrest.service could not be found.

十二、参考链接

  • 官方 README（安装说明）：https://github.com/garethgeorge/backrest
  • 官方 getting-started：https://garethgeorge.github.io/backrest/introduction/getting-started
  • v1.14.1 发布页：https://github.com/garethgeorge/backrest/releases/tag/v1.14.1
  • restic v0.19.1 发布页：https://github.com/restic/restic/releases/tag/v0.19.1
  • 站内选型认知篇：《Backrest v1.14.1 介绍与选型指南》