UrBackup 快速入门与实战示例

UrBackup 快速入门实战：Web 管理端登录、客户端注册与状态判读、手动触发文件备份并解读服务端日志、增量/全量备份策略、备份浏览与单文件下载、Web 界面恢复文件到客户端全流程验证、urbackupclientctl 命令行实操，以及镜像备份适用边界说明。所有操作与回显均在 Server 2.5.38 / Client 2.5.31 实测环境复验。

UrBackup备份恢复Ubuntu 22.042026/10/19

UrBackup 快速入门与实战示例

一、登录 Web 管理端

安装完成后（安装步骤见《Ubuntu 22.04 安装 UrBackup 2.5.38 指南》），浏览器访问：

http://<服务端IP>:55414

输入管理员账号密码登录。本文实测环境为 admin / q1w2e3r4（示例账号，生产环境请用强密码）。登录成功后默认进入 Status（状态）页。

一个值得了解的实现细节：UrBackup Web 端登录不是简单提交明文密码，浏览器会先请求服务端拿随机 salt 与 rnd（POST /x?a=salt，实测响应包含 pbkdf2_rounds: 10000），前端对密码做 md5(salt+密码) → PBKDF2 → md5(rnd+结果) 后才提交。因此抓包看不到明文密码，排查登录问题时也不能用明文直接调登录接口，模拟登录需要复刻这套哈希流程。

二、客户端注册与状态判读

客户端安装并加入备份集后，在 Web 端 Status 页可以看到每个客户端的实时状态。实测环境唯一的客户端 backup-client1 状态数据如下（Web API status 返回，节选）：

{
  "name": "backup-client1",
  "online": true,
  "id": 1,
  "ip": "10.89.49.11",
  "os_simple": "linux",
  "os_version_string": "Ubuntu 22.04.5 LTS (Jammy Jellyfish); Kernel 6.8.0-138-generic x86_64",
  "client_version_string": "2.5.31",
  "file_ok": true,
  "image_ok": false,
  "image_not_supported": true,
  "lastbackup": 1792379862,
  "lastbackup_image": 0,
  "lastseen": 1792413608
}

关键字段判读：

  • online：客户端当前是否可达；
  • file_ok / image_ok：文件备份/镜像备份是否在允许的时间窗口内完成过，超时变 false 并触发告警（见《UrBackup 日常运维手册》）；
  • image_not_supported: true：Linux 客户端在没有可用的块设备快照机制（LVM 等）时，镜像备份不可用——这是容器/云主机环境的常态，只做文件备份即可；
  • lastbackup：Unix 时间戳，最近一次文件备份时间。

存储占用在 Statistics（统计）页查看，实测：

{ "usage": [ { "files": 12583000.0, "images": 0, "name": "backup-client1", "used": 12583000.0 } ] }

即文件备份占用约 12.6 MB（多次增量去重后），镜像备份为 0。

三、文件备份实战

3.1 手动触发一次增量备份

UrBackup 默认按设置的时间窗口自动调度（增量每 15 分钟、全量每日等，见运维手册参数速查），也可以随时手动触发。最常用的方式是在客户端上执行：

urbackupclientctl start -i    # 增量文件备份
urbackupclientctl start -f    # 全量文件备份

实测先向受备份目录追加一个文件再触发增量：

echo "restore-test-1760877760" >> /home/ubdata/file1.txt
urbackupclientctl start -i

实测回显：

Waiting for server to start backup... done
Timeout while waiting for server to start backup

注意这个看似失败的回显是一个典型的坑：命令退出码为 4，但它只表示"等待备份完成的状态轮询超时"，备份本身已在服务端正常启动并完成。用 urbackupclientctl status 可以看到：

{
"finished_processes": [{
"process_id": 1,
"success": true
}],
"last_backup_time": 1792413760
}

再到服务端确认，备份列表中出现了新的增量备份（Web API backups?sa=backups&clientid=1 返回）：

id 3 incr 2026-10-19 20:42:39    39 bytes
id 2 incr 2026-10-19 16:44:02    4194332 bytes
id 1 FULL 2026-10-19 16:41:17    8388638 bytes

id=3 只占 39 字节——正是增量去重的效果：只有 file1.txt 变了，其余文件全部通过硬链接引用历史块。

3.2 解读服务端备份日志

每次备份在服务端生成一条结构化日志（Web 端 Logs 页可见）。上述增量备份的完整日志（实测）：

Starting unscheduled incremental file backup...
Backing up "ubdata" without snapshot.
Indexing of "ubdata" done. 2 filesystem lookups 0 db lookups and 0 db updates
backup-client1: Loading file list...
backup-client1: Calculating file tree differences...
backup-client1: Calculating tree difference size...
backup-client1: Linking unchanged and loading new files...
Waiting for file transfers...
Referencing snapshot on "backup-client1" for path "ubdata" failed: FAILED
Waiting for file hashing and copying threads...
Writing new file list...
All metadata was present
Transferred 1021 bytes - Average speed: 44.384 KBit/s
(Before compression: 499 bytes ratio: 0.488737)
Time taken for backing up client backup-client1: 10s
Backup succeeded

两条常见提示的含义：

  • Backing up "ubdata" without snapshot.：该路径未使用文件系统快照，直接备份运行中的数据（Linux 无 LVM/btrfs 快照时的正常退化，不是错误）；
  • Referencing snapshot on "backup-client1" for path "ubdata" failed: FAILED：客户端不支持/未配置块设备快照时同样属正常现象，备份仍成功结束。

而全量备份（urbackupclientctl start -f）的日志会多一行关键信息：

Starting unscheduled full file backup...
Last virtual full index unfinished. Performing incremental (virtual full) indexing...

即 UrBackup 的"合成全量"机制：全量备份并不重新传输所有数据，而是复用已有块重新组装出一个完整备份点（实测一次 8MB 数据的"全量"仅传输了压缩比 0.9996 的少量元数据与未去重块）。

3.3 增量/全量的自动调度

备份类型与频率由服务端设置决定，实测环境默认值为：文件增量间隔 update_freq_incr=18000 秒（5 小时）、文件全量间隔 update_freq_full=2592000 秒（30 天）、保留策略 max_file_incr=100 / min_file_incr=40 / max_file_full=10 / min_file_full=2。完整参数说明见《UrBackup 日常运维手册》。

四、镜像备份说明

UrBackup 支持对整块磁盘/分区做块级镜像备份，但能力取决于客户端环境：

  • Windows 客户端：基于 VSS 做全盘镜像，输出 VHD(Z) 格式，可在服务端直接挂载浏览，配合 UrBackup Restore Stick 2.6.0 引导盘做裸机恢复；
  • Linux 客户端：依赖块设备快照机制（LVM、btrfs、dattobd 等），客户端安装时会部署 dm_create_snapshot 等快照辅助脚本；
  • 不可用场景：没有块设备快照能力的主机（本实测的容器环境即如此，Status 页显示 image_not_supported: true），此时只能使用文件备份。

实操建议：物理机/虚拟机全盘保护用镜像备份 + 文件备份双轨；云主机、容器等无快照环境直接使用文件备份，并在设置中关闭镜像备份相关告警（运维手册 5.4 节）。

五、备份浏览与单文件下载

5.1 浏览备份目录树

Web 端进入某客户端 → Backups → 选择一个备份点 → 浏览文件。实测浏览备份 id=2 的 /ubdata 目录（Web API 返回）：

{
 "backupid": 2,
 "clientname": "backup-client1",
 "path": "/ubdata",
 "files": [
  { "name": "sub", "dir": true,  "mod": 1792399259 },
  { "name": "data1.bin", "dir": false, "size": 8388608,
    "shahash": "y7GBbX3EYSaulsfA5sgK2jCc4m/IIQe18Tg7HrM4tHQ5L6Px1RY+jEB3eqqsI1w+6eSCgDbeyF0Dug2r2ubvlQ==" },
  { "name": "data2.bin", "dir": false, "size": 4194304,
    "shahash": "6PnHhQC8bJFRBEJZnaOeM8Uw7+MGTZQzinhU9ooHkDtfofT8Yqg1fgsBJff+wOxfp4Xyk3NpoCBnKNcu1fmRuQ==" },
  { "name": "file1.txt", "dir": false, "size": 28,
    "shahash": "hxwDd8UXE/BZUA2U5htpNpsJdJMBAAAAAQAAAAEAAAABAAAAAQAAAAEAAAABAAAAAQAAAAEAAAABAAAAAQAAAA==" }
 ]
}

5.2 单文件下载（下载到浏览器所在机器）

在备份浏览界面点击文件即可下载，对应 API 为 sa=filesdl。实测下载备份 id=1 中的 file1.txt：

HTTP 200
Content-Disposition: attachment; filename="file1.txt"
Content-Length: 18
BODY: hello urbackup v1

一个必须知道的坑：如果所选备份点里并不存在该文件（例如 data2.bin 是在备份 id=2 才新增的），下载 data2.bin@backup id=1 不会报 404，而是返回 0 字节的空文件。下载前务必确认文件确实存在于所选备份点（实测复现：filesdl clientid=1 backupid=1 path=/ubdata/data2.bin → 0 bytes）。

六、恢复实操：把文件恢复到客户端

UrBackup 支持两种恢复路径：从 Web 界面把文件"推送"回客户端（本节），或在客户端本机用命令行恢复（下一节）。

6.1 前提：客户端开启 Web 恢复

客户端配置文件 /etc/default/urbackupclient 的 RESTORE 参数默认为 disabled，此时从 Web 界面发起恢复会失败，服务端日志实测：

Starting restore of path "ubdata/"...
Starting restore failed: disabled

需要将其改为 server-confirms（服务端直接发起，无需客户端确认；client-confirms 则需要客户端 GUI 用户确认），并重启客户端服务：

sudo sed -i 's/^RESTORE=disabled/RESTORE=server-confirms/' /etc/default/urbackupclient
sudo systemctl restart urbackupclientbackend

6.2 完整恢复流程实测

场景：删除客户端上的 /home/ubdata 全部内容，再从备份 id=2（16:44:02 的增量）整体还原。

# 客户端上：删除制造灾难现场
rm -rf /home/ubdata/*

Web 端操作：客户端 → Backups → 选择备份 id=2 → 浏览到 /ubdata → 勾选后点击 Restore。对应 API 实测两步：

// 第一步：发起恢复（sa=clientdl）
{ "ok": "true", "wait_key": "9Ed2dHIpGx" }

// 第二步：轮询恢复进度（restore_prepare_wait）
{ "completed": true, "wait_key": "9Ed2dHIpGx" }

服务端日志实测：

Starting restore of path "ubdata/"...
Starting restore...
Loading file list...
Calculating download size...
Downloading necessary file data...
Applying file metadata...
Restore finished successfully.

客户端验证恢复结果（实测）：

ls -la /home/ubdata/

total 12304
drwxr-xr-x 3 root root    4096 Oct 19 12:52 .
drwxr-xr-x 3 root root    4096 Oct 19 08:40 ..
-rw-r--r-- 1 root root 8388608 Oct 19 08:40 data1.bin
-rw-r--r-- 1 root root 4194304 Oct 19 08:43 data2.bin
-rw-r--r-- 1 root root      28 Oct 19 08:43 file1.txt
drwxr-xr-x 2 root root    4096 Oct 19 08:40 sub

md5sum /home/ubdata/data2.bin
cat /home/ubdata/file1.txt

7280bb95c8ec2993f1d9fe2b8881ffa3  /home/ubdata/data2.bin
hello urbackup v2 - changed

注意 file1.txt 的内容是备份 id=2 时点的版本（v2 - changed），而不是被删前的最新版本——恢复精确还原到所选备份点，这正是备份系统的正确行为。

6.3 恢复排障要点

实测过程中踩到两个坑，值得记录：

  1. 选错备份点报"Cannot read files from folder"：恢复单文件时必须确认该文件存在于所选备份点。实测从备份 id=1 恢复 data2.bin（该文件当时还不存在），服务端日志报： 
    ERROR: Cannot read files from folder /media/BACKUP/urbackup/backup-client1/261019-0841/ubdata/data2.bin. Cannot start restore.
    且 Web 端轮询仍返回 completed: true——Web 界面显示的 completed 不代表恢复成功，务必结合服务端日志与客户端实际文件确认。
  2. 客户端本机命令行恢复报 access token 错误：urbackupclientctl browse / restore-start 依赖客户端本地的文件备份访问令牌（/usr/local/var/urbackup/data/tokens_*.properties 中的备份 id 列表）。实测环境中该令牌的 ids 字段为空，两条命令均报： 
    No file backup access tokens found. Did you run a file backup yet?
    此时改用 Web 端恢复（6.2 节）或浏览器单文件下载（5.2 节）即可；该问题在官方论坛有同类案例，通常与客户端令牌同步机制有关，重新做一次完整备份并等待令牌文件刷新（文件含非空 ids=）后重试。

七、客户端命令行速查

Linux 客户端命令行工具 urbackupclientctl 常用子命令（均在实测环境验证过语法）：

urbackupclientctl status                 # 查看备份状态与服务端连接
urbackupclientctl start -i               # 触发增量文件备份
urbackupclientctl start -f               # 触发全量文件备份
urbackupclientctl list-backupdirs        # 列出备份集目录
urbackupclientctl add-backupdir -d /path -n 名称   # 添加备份目录
urbackupclientctl remove-backupdir -d /path        # 移除备份目录
urbackupclientctl browse -b last         # 浏览最近备份的文件
urbackupclientctl restore-start -b <id> -d /path   # 从指定备份恢复文件

restore-start 常用参数（--help 实测摘录）：-b/--backupid（备份号，必填，可用 last 表示最近完整备份）、-d/--path（恢复的路径）、-n/--no-remove（不删除备份中不存在的文件）、-l/--non-blocking（后台执行不阻塞）。

八、常见问题

Q1：urbackupclientctl start -i 提示 Timeout 并返回退出码 4，备份失败了吗？ 没有。该超时只发生在"等待完成"环节，实际备份通常已在服务端完成。用 urbackupclientctl status 的 finished_processes 或服务端 Logs 页确认 Backup succeeded 即可（见 3.1 节实测）。

Q2：Web 端备份列表里全量备份比增量还小正常吗？ 正常。UrBackup 的"全量"多为合成全量（virtual full），大部分数据通过硬链接复用历史块，备份点大小（size_bytes）反映的是该点完整数据的逻辑体积，实际新增传输量看日志里的 Transferred 行。

Q3：下载备份文件得到 0 字节空文件？ 该文件在所选备份点不存在（见 5.2 节坑）。换包含该文件的备份点重新下载。

Q4：Web 界面发起恢复，轮询显示 completed 但文件没回来？ 先查客户端 /etc/default/urbackupclient 的 RESTORE 是否为 disabled（日志报 Starting restore failed: disabled），改为 server-confirms 重启客户端服务；再确认所选备份点包含目标文件（备份点选错会报 Cannot read files from folder）；最后以服务端日志 Restore finished successfully. 为准。

Q5：Linux 客户端能不能做镜像备份？ 取决于是否有可用的块设备快照（LVM/btrfs/dattobd）。无快照环境（容器、部分云主机）会显示 image_not_supported，只能文件备份（见第四节）。

Q6：状态页 file_ok 变成 false 是什么意思？ 表示该客户端已超过"备份间隔 × 告警倍数"没有成功的文件备份，会触发告警。检查客户端是否在线、备份任务是否报错、时间窗口设置是否过严，处理方法见《UrBackup 日常运维手册》。

九、参考链接

  1. UrBackup 官方下载页：https://www.urbackup.org/download.html
  2. 服务器管理手册：https://www.urbackup.org/ServerAdminGuide-v2.4.x.pdf
  3. 客户端命令行文档（urbackupclientctl）：https://www.urbackup.org/client_debian_ubuntu_install.html
  4. UrBackup Restore Stick（裸机恢复盘）：https://github.com/uroni/urbackup_restore_cd/releases
  5. 官方论坛（排障案例检索）：https://forums.urbackup.org/