Minarca 7.2 常用 CLI 命令与工具详解

面向 Minarca Server 6.2.5 与 Minarca Client 7.2.0 的命令行实操手册：服务端覆盖 minarca-server 主命令与 systemd 运维（status/cat/is-enabled/journalctl）、minarca-shell 备份通道、rdiff-backup-delete 仓库内容删除（dry-run→实删）、rdiff-backup 三版本并存机制；客户端逐条实测 start/backup/stop、status/--json、include/exclude、restore、schedule/unschedule、pause、configure、forget、verify、ui、rdiff-backup 透传与 imap-backup。含备份通道与 Web 服务分离、restore 与 verify 排障实录。

Minarca备份恢复Minarca2026/10/22

Minarca 7.2 常用 CLI 命令与工具详解

目标：把 Minarca 服务端与客户端的日常命令行工具讲透——服务端覆盖 minarca-server 主命令与 systemd 运维、minarca-shell 备份通道、rdiff-backup-delete 仓库内容删除、rdiff-backup 多版本并存机制；客户端逐条实测 minarca 的全部 17 个子命令（含成功与报错两条路径），并把「命令输入 → 实测回显 → 结论」完整沉淀。全部命令与输出均在 1 台服务端（Ubuntu 22.04.5 LTS，minarca-server 6.2.5）+ 1 台客户端（Ubuntu 22.04.5 LTS，minarca-client 7.2.0-1）的双机环境逐条实测。安装部署见 《Ubuntu 22.04 安装 Minarca 指南（服务端与客户端）》，产品定位与选型背景见 《Minarca 介绍与选型指南》，配置参数见 《Minarca Server 6.2 配置参数详解》。

一、环境信息

本文沿用安装篇的「1 台服务端 + 1 台客户端」双机拓扑：

角色主机名操作系统软件版本
备份服务器minarca-serverUbuntu 22.04.5 LTSminarca-server 6.2.5
被备份主机client02Ubuntu 22.04.5 LTSminarca-client 7.2.0-1

两端关键路径与端口（均已实测确认）：

端项值
服务端主程序目录/opt/minarca-server/（含 minarca-server、minarca-shell、rdiff-backup-delete）
服务端配置文件/etc/minarca/minarca-server.conf
服务端备份仓库根/backups/<用户名>/<仓库名>/（本文为 /backups/admin/client02）
服务端日志目录/var/log/minarca/（access.log、server.log、shell.log）
服务端端口22（SSH 备份通道）、8080（Web 管理界面）
服务端systemd 单元minarca-server.service
客户端主程序/opt/minarca/minarca
客户端配置目录/etc/minarca/（minarca0.properties、patterns0、id_rsa0、known_hosts0）
客户端日志文件/var/log/minarca.log
客户端调度root 的 crontab（由 minarca schedule 写入）

演示账号为 admin（密码 admin123），演示备份源为客户端的 /srv/data/ 目录（其中含 66 字节的 app.conf 与曾被删除的 notes.txt，恰好用于第五章的还原演示）。下文所有命令默认以 root 执行；除特别说明外，「输出」均为实测回显逐行照抄，过长的输出会标注「输出节选（实测首尾）」或「输出节选（实测节选）」并只保留引用到的行。

二、前置条件

本章确认双端处于可用状态：服务端 Web 服务与 SSH 通道在监听、客户端命令可用且实例已关联。后续第五章的全部子命令演示都依赖这两项检查通过。

2.1 服务端就绪检查

依次确认 systemd 单元状态与两个端口的监听：

systemctl is-active minarca-server
systemctl is-enabled minarca-server

active
enabled

ss -ltn | grep 8080

LISTEN 0      5            0.0.0.0:8080       0.0.0.0:*

ss -ltn | grep :22

LISTEN 0      128          0.0.0.0:22         0.0.0.0:*
LISTEN 0      128             [::]:22            [::]:*

is-active 返回 active、is-enabled 返回 enabled 说明 Web 服务在运行且开机自启；8080 与 22 都在监听说明 Web 管理界面与 SSH 备份通道均就绪。两个端口的角色差异（备份走 SSH、管理走 Web）在 4.2 节与 6.2 节有实测验证。

2.2 客户端就绪检查

确认客户端版本与关联状态：

minarca -v

minarca 7.2.0

minarca status --instance 0

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T07:31:01+0000
Last backup date:         2026-10-22T07:31:01+0000
Last backup status:       SUCCESS

Connectivity status: Connected 与 Last backup status: SUCCESS 说明实例 0 已关联服务端且最近一次备份成功。若此处不是 Connected，先按 6.3 节排查 SSH 通道。

三、命令总览

本章先给出两端命令的全景清单，便于按需跳转到第四章（服务端工具）与第五章（客户端子命令）查阅逐条实测。

3.1 客户端主命令与子命令总览

客户端只有一个入口命令 minarca（安装在 /opt/minarca/minarca，已加入 PATH），其帮助输出即全部能力的清单（实测）：

minarca --help

usage: minarca [-h] [-v] [-d] {command} ...

Manages your computer's backup by linking your computer with a centralized
server and running backups on a given schedule.

positional arguments:
  {command}
    start             start a backup in background mode
    backup            start a backup in foreground mode
    exclude           exclude files from being backed up
    include           include files to be backed up
    configure (link)  configure this agent to backup to a new destination
                      (remote or local)
    patterns          list the include/exclude patterns
    restore           restore data from backup
    stop              stop the backup
    schedule          create the required scheduled task in crontab
    unschedule        remove the scheduled task from crontab
    status            return the current backup status
    forget (unlink)   forget backup settings
    pause             temporarily delay the execution of the backup for the
                      given number of hours. Default is 24 hours.
    verify            verify backup integrity
    ui                open graphical user interface (default when calling
                      minarcaw)
    rdiff-backup      For internal use
    imap-backup       For internal use

options:
  -h, --help          show this help message and exit
  -v, --version       show program's version number and exit
  -d, --debug

17 个子命令按用途分组如下（「实测小节」列指向第五章对应小节）：

子命令别名用途实测小节
start—后台模式发起一次备份5.1
backup—前台模式发起一次备份5.1
exclude—追加排除模式5.3
include—追加包含模式5.3
configurelink关联新的备份目的端（远端服务器或本地目录）5.4
patterns—查看 include/exclude 模式列表5.3
restore—从备份还原数据5.9
stop—停止正在运行的备份5.6
schedule—在 crontab 写入调度任务5.7
unschedule—从 crontab 移除调度任务5.7
status—查看实例状态（支持 --json）5.2
forgetunlink解除实例关联5.5
pause—暂停备份若干小时（默认 24）5.8
verify—校验备份完整性5.10
ui—打开图形界面（无参数调用 minarca 时的默认行为）5.11
rdiff-backup—透传调用内置 rdiff-backup5.12
imap-backup—IMAP 邮箱归档工具5.12

关键解读：全局参数只有三个——-h 帮助、-v 版本、-d 调试输出（排障时在子命令前加 -d，5.9 与 5.10 节实测用到）。ui 在帮助里标注为无参数调用时的默认行为，因此无头服务器上误敲裸 minarca 会尝试启动图形界面（见 6.6 节）。

3.2 服务端工具总览

服务端没有统一的 minarca-server 子命令体系，日常运维由「1 个主命令 + 3 个配套工具 + systemd」组成：

工具路径用途
minarca-server/opt/minarca-server/minarca-server服务端主命令（Web 服务进程本体）
minarca-shell/opt/minarca-server/minarca-shellSSH 备份通道的服务端入口（由 authorized_keys 强制执行，不供人工交互）
rdiff-backup-delete/opt/minarca-server/rdiff-backup-delete从仓库中删除指定路径及其全部历史
rdiff-backup/usr/bin/rdiff-backup-1.2 / 2.0 / 2.2底层备份引擎，三个版本并存（见 4.4 节）

关键解读：主命令与配套工具都装在 /opt/minarca-server/ 下且未加入系统 PATH，调用时需要写全路径（4.1 节实测演示了直接敲 minarca-server 会报 command not found）。systemd 单元 minarca-server.service 负责 Web 服务的托管，SSH 通道不依赖该单元。

四、服务端工具详解

本章逐个实测服务端的四个工具：先是最常用的主命令与 systemd 运维，再讲两台机器之间真正的备份通道 minarca-shell，然后是可以「从仓库里精准抹掉某路径全部历史」的 rdiff-backup-delete，最后解释为什么服务端会同时装着三个版本的 rdiff-backup。

4.1 minarca-server 主命令与 systemd 日常运维

minarca-server 主命令极少需要手工执行（systemd 已托管），但版本查看、帮助输出与 systemd 状态检查是日常巡检的基本功，本节逐项给出实测回显。

版本查看。 主命令不在系统 PATH 中，直接敲命令名会失败，必须用全路径：

minarca-server --version

bash: line 1: minarca-server: command not found

/opt/minarca-server/minarca-server --version

minarca-server 6.2.5

⚠️ 注意：/opt/minarca-server/ 未加入 PATH 是打包形态决定的，写巡检脚本时一律用全路径调用，避免在非交互 shell（如 cron、CI）里踩 command not found。

帮助输出。 主命令支持大量启动参数（与配置文件键一一对应，改值建议走配置文件，参见 《Minarca Server 6.2 配置参数详解》）：

/opt/minarca-server/minarca-server --help | head -40

usage: minarca-server [-h] [-f FILE] [--database-uri URI] [-d]
                      [--admin-user USERNAME] [--admin-password USERNAME]
                      [--default-lang DEFAULT_LANG]
                      [--default-theme {default,blue,orange,custom}]
                      [--environment {development,production}]
                      [--email-encryption {none,ssl,starttls}]
                      [--email-host HOST] [--email-sender EMAIL]
                      [--email-notification-time TIME]
                      [--email-username USERNAME] [--email-password PASSWORD]
                      [--email-send-changed-notification]
                      [--email-catch-all EMAIL] [--brand-favicon FAVICON]
                      [--brand-logo LOGO] [--brand-header-logo HEADER_LOGO]
                      [--brand-header-name HEADER_NAME]
                      [--brand-link-color LINK_COLOR]
                      [--brand-btn-bg-color BTN_BG_COLOR]
                      [--brand-btn-fg-color BTN_FG_COLOR]
                      [--brand-btn-rounded BTN_ROUNDED]
                      [--brand-navbar-color NAVBAR_COLOR]
                      [--brand-font-family FONT_FAMILY] [--add-missing-user]
                      [--add-user-default-role {admin,maintainer,user}]
                      [--add-user-default-userroot ADD_USER_DEFAULT_USERROOT]
                      [--login-with-email] [--ldap-uri LDAP_URI]
                      [--ldap-base-dn DN]
                      [--ldap-scope {base,onelevel,subtree}] [--ldap-tls]
                      [--ldap-username-attribute ATTRIBUTE]
                      [--ldap-user-filter LDAP_USER_FILTER]
                      [--ldap-required-group CN]
                      [--ldap-group-filter LDAP_GROUP_FILTER]
                      [--ldap-group-attribute ATTRIBUTE]
                      [--ldap-group-attribute-is-dn] [--ldap-bind-dn DN]
                      [--ldap-bind-password PASSWORD] [--ldap-version {2,3}]
                      [--ldap-network-timeout SECONDS]
                      [--ldap-timeout SECONDS] [--ldap-encoding ENCODING]
                      [--ldap-fullname-attribute LDAP_FULLNAME_ATTRIBUTE]
                      [--ldap-firstname-attribute LDAP_FIRSTNAME_ATTRIBUTE]
                      [--ldap-lastname-attribute LDAP_LASTNAME_ATTRIBUTE]
                      [--ldap-email-attribute LDAP_EMAIL_ATTRIBUTE]
                      [--oauth-provider-name OAUTH_PROVIDER_NAME]
                      [--oauth-client-id OAUTH_CLIENT_ID]
                      [--oauth-client-secret OAUTH_CLIENT_SECRET]

（输出节选，实测前 40 行；LDAP/OAuth/品牌化等参数清单继续向后延伸，此处从略。）关键解读：-f FILE 指定配置文件（默认 /etc/minarca/minarca-server.conf），--admin-user/--admin-password 用于初始化管理员，--default-theme、--email-*、--ldap-*、--oauth-* 分别对应界面主题、邮件通知与企业认证，这些键的配置文件写法与生效验证见配置参数篇。

systemd 日常运维。 单元状态与开机自启在 2.1 节已验过（active/enabled），这里补充状态详情与单元定义：

systemctl status minarca-server --no-pager | sed -n '1,8p'

● minarca-server.service - Minarca Web Server
     Loaded: loaded (/lib/systemd/system/minarca-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 07:00:20 UTC; 7min ago
       Docs: https://minarca.org/
   Main PID: 17576 (minarca-server)
      Tasks: 14 (limit: 94371)
     Memory: 82.3M
        CPU: 828ms

（输出节选，实测前 8 行。）进程常驻内存约 82 MB，对一台备份服务器来说开销很小。

systemctl cat minarca-server

# /lib/systemd/system/minarca-server.service
[Unit]
Description=Minarca Web Server
Documentation=https://minarca.org/

[Service]
ExecStart=/opt/minarca-server/minarca-server
User=minarca
Group=minarca

[Install]
WantedBy=multi-user.target

关键解读：单元定义极简——以 minarca 用户身份执行全路径主命令，没有任何自定义内存限制；如需调整运行参数，推荐用 systemd drop-in（systemctl edit minarca-server）而不是改单元原文件。

journalctl -u minarca-server -n 5 --no-pager

Oct 22 07:00:13 minarca-server minarca-server[17145]: continue logging to /var/log/minarca/server.log
Oct 22 07:00:13 minarca-server systemd[1]: minarca-server.service: Deactivated successfully.
Oct 22 07:00:13 minarca-server systemd[1]: Stopped Minarca Web Server.
Oct 22 07:00:13 minarca-server systemd[1]: minarca-server.service: Consumed 1.526s CPU time.
Oct 22 07:00:20 minarca-server systemd[1]: Started Minarca Web Server.

关键解读：journal 里的 Stopped/Started 对应此前一次手动 stop/start 周期（即 6.2 节排障实录里的那一次）；应用自身的业务日志在 /var/log/minarca/server.log，journal 只记录启停事件。stop/start/restart 的实测效果见 6.2 节的完整周期。

4.2 minarca-shell：SSH 备份通道的服务端入口

minarca-shell 是理解 Minarca 备份通道的关键：客户端发起备份时并不调用 Web 端口，而是通过 SSH 登录服务端，由 authorized_keys 中的强制命令直接拉起 minarca-shell，再由它启动对应版本的 rdiff-backup 服务进程。本节把这条链路的每一段都用实测证据钉死。

先看版本（同样是全路径调用）：

/opt/minarca-server/minarca-shell --version

minarca-shell 6.2.5

客户端的 SSH 公钥在服务端授权文件里带有 command="..." 强制选项（实测摘录，密钥本体从略）：

FILE:/root/.ssh/authorized_keys
command="export MINARCA_USERNAME='admin' MINARCA_USER_ROOT='/backups/admin';/opt/minarca-server/minarca-shell"

关键解读：客户端密钥登录后无论想执行什么，实际都会被强制执行 minarca-shell，并且通过环境变量注入了用户名（admin）与其仓库根（/backups/admin）——这就是客户端只能触达自己仓库的隔离机制。MINARCA_USER_ROOT 的取值正对应 4.3 节将要看到的仓库路径 /backups/admin/。

承载 minarca 仓库的 minarca 系统账号信息（实测）：

getent passwd minarca

minarca:x:0:107:minarca repository hosting,,,:/backups/:/bin/bash

关键解读：该账号 UID 为 0（与 root 同 UID），家目录指向 /backups/，所以备份仓库文件的属主显示为 root 而目录规划仍以 /backups/ 为根。

一次真实备份期间，服务端 shell.log 记录了 minarca-shell 的工作过程（实测节选，取自 6.2 节 Web 停服演示期间）：

[2026-10-22 07:30:11,019][INFO   ][10.89.66.3][admin][PID:18561][__main__] running command [/usr/bin/rdiff-backup-2.2 --server] in jail [/backups/admin] for: minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)
[2026-10-22 07:30:11,198][INFO   ][10.89.66.3][admin][PID:18561][__main__] rdiff-backup terminated successfully
[2026-10-22 07:30:15,217][INFO   ][10.89.66.3][admin][PID:18589][__main__] running command [/usr/bin/rdiff-backup-2.2 --server] in jail [/backups/admin] for: minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)
[2026-10-22 07:30:15,351][INFO   ][10.89.66.3][admin][PID:18589][__main__] rdiff-backup terminated successfully

这一行日志把整条链路说清楚了：来源 IP（10.89.66.3，客户端）、账号（admin）、在 jail 目录 /backups/admin 内执行 /usr/bin/rdiff-backup-2.2 --server，且会话标识串是 minarca/7.2.0 rdiff-backup/2.2.6 (...)。排查备份通道问题时，shell.log 是服务端侧的第一现场；客户端侧的第一现场是 /var/log/minarca.log（见 5.9 节排障实录）。

4.3 仓库目录结构与 rdiff-backup-delete（dry-run → 实删 → 整仓下线）

rdiff-backup-delete 用于「把某个路径从备份仓库中彻底删除——连同当前镜像与全部历史增量」，典型场景是误把敏感目录纳入备份后需要合规抹除。动手之前，先认识仓库的目录结构。以实例 0 的仓库 /backups/admin/client02 为例（实测）：

ls -l /backups/admin/client02/srv/data/

total 3076
-rw-r--r-- 1 root minarca      66 Oct 21 18:07 app.conf
-rw-r--r-- 1 root minarca 3145728 Oct 21 18:07 db-snapshot-2.bin

ls -l /backups/admin/client02/rdiff-backup-data/increments/srv/data/

total 8456
-rw------- 1 root minarca       0 Oct 22 05:51 app.conf.2026-10-21T18:23:25Z.missing
-rw-r--r-- 1 root minarca 8388608 Oct 21 18:22 contracts_2026.bin.2026-10-21T18:23:25Z.snapshot
-rw------- 1 root root          0 Oct 21 18:23 contracts_2026_addendum.bin.2026-10-21T18:23:03Z.missing
-rw------- 1 root minarca  262144 Oct 21 18:23 contracts_2026_addendum.bin.2026-10-21T18:23:25Z.snapshot
-rw------- 1 root minarca       0 Oct 22 05:51 db-snapshot-2.bin.2026-10-21T18:23:25Z.missing
-rw-r--r-- 1 root root         31 Oct 21 18:22 notes.txt.2026-10-21T18:23:03Z.diff
-rw-r--r-- 1 root root         35 Oct 21 18:23 notes.txt.2026-10-21T18:23:20Z.snapshot

ls -l /backups/admin/client02/rdiff-backup-data/current_mirror*

-rw------- 1 root minarca 10 Oct 22 07:08 /backups/admin/client02/rdiff-backup-data/current_mirror.2026-10-22T07:08:00Z.data

关键解读：仓库 = 当前镜像（仓库根下的目录树，如 srv/data/ 下的两个文件）+ rdiff-backup-data/ 元数据区；历史版本都沉淀在 rdiff-backup-data/increments/ 下，文件名携带版本时间戳（如 notes.txt.2026-10-21T18:23:20Z.snapshot 就是 notes.txt 在该时刻的历史版本，源机上它后来被删除，5.9 节将用它演示按时间点还原）；current_mirror.<时间>.data 标记最近一次成功备份的时间点。

💡 技术拓展：备份系统对「历史版本怎么存」有三种主流形态——

形态原理取舍
全量备份每次完整拷贝全部数据恢复最简单，空间与时间开销最大
差异备份与某次全量做基准，备份差集恢复需「全量 + 最近差异」两份
增量备份与上一次备份做差，只存变化空间最省，恢复需沿链回放

rdiff-backup 采用「增量 + 镜像」混合形态：仓库根始终维护一份最新镜像（恢复最新版最快），历史版本以反向增量存放在 increments/ 下（越旧越省空间）。Minarca 底层即 rdiff-backup，本文所述仓库结构、rdiff-backup-delete 与 restore 行为均基于该形态。

删除前先看仓库全貌（本次演示目标是把已下线仓库 client01 中的 srv/ 路径抹掉）：

ls -la /backups/admin/
du -sh /backups/admin/client01

total 16
drwxrwx--- 4 root root 4096 Oct 21 18:23 .
drwxr-x--- 6 root root 4096 Oct 21 18:11 ..
drwxr-xr-x 4 root root 4096 Oct 21 17:48 client01
drwxr-xr-x 4 root root 4096 Oct 21 17:48 client02
12M	/backups/admin/client01

第一步：--help 确认用法。

/opt/minarca-server/rdiff-backup-delete --help


Usage: /opt/minarca-server/rdiff-backup-delete [OPTION]... PATH
    Delete PATH from a rdiff-backup repository including the current
    mirror and all its history.
Options:
    h, --help
            Display this help text and exit
    d, --dry-run
            Run the script without doing modifications to the repository.
    PATH
            A relative or absolute path to be deleted. This path must be
            inside a rdiff-backup repository.

关键解读：参数只有 --dry-run 与 PATH；PATH 必须位于某个 rdiff-backup 仓库内部，删除范围包含当前镜像与全部历史。

第二步：dry-run 预演（不改任何数据）。

/opt/minarca-server/rdiff-backup-delete --dry-run /backups/admin/client01/srv

start deleting path `srv` from repository /backups/admin/client01
running in dry-run mode
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/access_control_lists.2026-10-21T18:06:00Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/mirror_metadata.2026-10-21T18:06:00Z.diff.gz
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/file_statistics.2026-10-21T18:07:38Z.data
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/extended_attributes.2026-10-21T18:07:13Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/mirror_metadata.2026-10-21T18:07:13Z.diff.gz
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/file_statistics.2026-10-21T18:07:13Z.data
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/extended_attributes.2026-10-21T18:07:38Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/mirror_metadata.2026-10-21T18:07:38Z.snapshot.gz
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/access_control_lists.2026-10-21T18:07:13Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/file_statistics.2026-10-21T18:06:00Z.data
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/access_control_lists.2026-10-21T18:07:38Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/extended_attributes.2026-10-21T18:06:00Z.snapshot
deleting directory `/backups/admin/client01/srv` recursively
deleting increments `/backups/admin/client01/rdiff-backup-data/increments/srv.2026-10-21T18:06:00Z.missing`
deleting increments `/backups/admin/client01/rdiff-backup-data/increments/srv.2026-10-21T18:07:13Z.dir`
done

关键解读：dry-run 会把「将要从哪些元数据文件里摘除该路径、将递归删除哪个目录、将清掉哪些增量」全部列出来，且第二行明确标注 running in dry-run mode——确认清单符合预期后再实删。

第三步：正式删除。

/opt/minarca-server/rdiff-backup-delete /backups/admin/client01/srv

start deleting path `srv` from repository /backups/admin/client01
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/access_control_lists.2026-10-21T18:06:00Z.snapshot
removing entries `srv` from /backups/admin/client01/rdiff-backup-data/mirror_metadata.2026-10-21T18:06:00Z.diff.gz
（输出节选，实测中段与 dry-run 完全一致，仅少了第二行 running in dry-run mode）
deleting directory `/backups/admin/client01/srv` recursively
deleting increments `/backups/admin/client01/rdiff-backup-data/increments/srv.2026-10-21T18:06:00Z.missing`
deleting increments `/backups/admin/client01/rdiff-backup-data/increments/srv.2026-10-21T18:07:13Z.dir`
done

删除后验证仓库状态：

ls -la /backups/admin/client01/

total 12
drwxr-xr-x 3 root root 4096 Oct 22 07:08 .
drwxrwx--- 4 root root 4096 Oct 21 18:23 ..
drwx------ 3 root root 4096 Oct 22 07:08 rdiff-backup-data

srv/ 目录及其全部增量已被抹除，仓库只剩元数据区。第四步：整仓下线。 若目的是让整个仓库彻底消失（如客户端已报废），直接删除仓库目录即可：

rm -rf /backups/admin/client01
ls -la /backups/admin/

total 12
drwxrwx--- 3 root root 4096 Oct 22 07:08 .
drwxr-x--- 6 root root 4096 Oct 21 18:11 ..
drwxr-xr-x 4 root root 4096 Oct 21 17:48 client02

⚠️ 注意：rdiff-backup-delete 的删除不可逆——它同时抹掉当前镜像与全部历史增量，不经过回收站。务必先 --dry-run 核对清单再实删；整仓下线用的 rm -rf 更是如此。若只是想让客户端换仓库名，用客户端的 minarca forget + minarca configure（5.4、5.5 节）重新关联即可，不要动服务端仓库。

4.4 rdiff-backup 三版本并存机制

在服务端上同时存在三个 rdiff-backup 版本，这不是安装残留，而是 Minarca 的跨版本客户端兼容设计。实测版本清单：

rdiff-backup-1.2 --version
rdiff-backup-2.0 --version
rdiff-backup-2.2 --version

rdiff-backup 1.2.8
rdiff-backup 2.0.5
rdiff-backup 2.2.6

三个版本以独立目录安装、用 /usr/bin/ 下的符号链接暴露（实测）：

ls -l /usr/bin/ | grep rdiff-backup

lrwxrwxrwx 1 root root        34 Jun 21  2025 rdiff-backup-1.2 -> /opt/rdiff-backup-1.2/rdiff-backup
lrwxrwxrwx 1 root root        34 Aug 19 19:20 rdiff-backup-2.0 -> /opt/rdiff-backup-2.0/rdiff-backup
lrwxrwxrwx 1 root root        34 Oct 20 15:15 rdiff-backup-2.2 -> /opt/rdiff-backup-2.2/rdiff-backup

ls -ld /opt/rdiff-backup-*

drwxr-xr-x 2 root root 4096 Oct 21 17:49 /opt/rdiff-backup-1.2
drwxr-xr-x 6 root root 4096 Oct 21 17:49 /opt/rdiff-backup-2.0
drwxr-xr-x 3 root root 4096 Oct 21 17:49 /opt/rdiff-backup-2.2

选择机制：客户端发起 SSH 会话时，会把自身版本标识作为远程命令传给服务端。在客户端用 -d 观察一次备份即可看到该标识（实测节选，5.9 节排障实录中同样可见）：

instance 0: remote schema: /usr/bin/ssh -F /dev/null -oConnectTimeout=10 -oBatchMode=yes -oPreferredAuthentications=publickey -oUserKnownHostsFile=/etc/minarca/known_hosts0 -oIdentitiesOnly=yes -i /etc/minarca/id_rsa0 %s 'minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)'

服务端 minarca-shell 收到会话后，从标识串中的 rdiff-backup/2.2.6 解析出大版本号 2.2，选择 /usr/bin/rdiff-backup-2.2 拉起服务端进程——4.2 节的 shell.log 日志（running command [/usr/bin/rdiff-backup-2.2 --server] ... for: minarca/7.2.0 rdiff-backup/2.2.6 ...）就是这一选择的直接证据。客户端侧也能看到服务端回告的版本（minarca -d verify 输出实测节选）：

instance 0: rdiff-backup 2.2.6

关键解读：7.2.0 客户端对应服务端 2.2.6；若现场混用老版本客户端（如仍带 rdiff-backup 1.2.8 的旧 Minarca），minarca-shell 会按标识自动切换到 rdiff-backup-1.2，无需人工干预。运维要点有二：不要删除或改动 /opt/rdiff-backup-/ 目录与 /usr/bin/rdiff-backup- 符号链接（升级 minarca-server 时它们随包管理）；排查通道问题时，先在 shell.log 确认服务端实际选用的版本，再对照客户端标识串。

五、客户端子命令逐条详解

本章按「用途 → 用法（--help 实测）→ 实测输入输出 → 要点」的顺序逐条过 17 个子命令。除单独标注外，所有演示都在实例 0（远端仓库 client02）上执行；每个子命令的成功与报错两条路径都尽量给出，报错场景本身就是排障素材。

5.1 start 与 backup：发起一次备份

两个子命令参数完全一致，区别只在运行方式：backup 前台执行（命令阻塞到备份结束），start 后台执行（立即返回，过程日志写 /var/log/minarca.log）。两者共用 --force（未到调度时间也强制执行）与 --instance（只操作指定实例，缺省作用于全部实例）：

usage: minarca start [-h] [--force] [--instance INSTANCE_ID]

options:
  -h, --help            show this help message and exit
  --force               force execution of a backup even if it's not time to
                        run
  --instance INSTANCE_ID
                        Limit backup to the given instance(s).

usage: minarca backup [-h] [--force] [--instance INSTANCE_ID]

options:
  -h, --help            show this help message and exit
  --force               force execution of a backup even if it's not time to
                        run
  --instance INSTANCE_ID
                        Limit backup to the given instance(s).

前台备份实测——成功时完全没有输出，退出码 0：

minarca backup --force --instance 0
echo RC=$?

RC=0

后台备份实测——start 立即返回，随后连续两次 status 可以看到备份完成时间从 06:58:55 推进到 06:59:00，说明后台任务在静默执行：

minarca start --force --instance 0
echo RC=$?

RC=0

minarca status --instance 0

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T06:58:55+0000
Last backup date:         2026-10-22T06:58:55+0000
Last backup status:       SUCCESS   

sleep 8
minarca status --instance 0

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T06:59:00+0000
Last backup date:         2026-10-22T06:59:00+0000
Last backup status:       SUCCESS

⚠️ 注意：两个坑都在「退出码与输出」上。其一，未到调度时间（默认每 24 小时）直接执行 minarca backup 会跳过本次执行，日志提示 backup not yet scheduled to run. You may force execution using '--force' (Error: 13)——手动测试请一律加 --force。其二，备份成功时命令完全静默，失败时也不一定给非零退出码（6.1 与 6.3 节有失败仍返回 0 的实证），所以「备份是否成功」永远以 minarca status 为准。

5.2 status 与 status --json：查看实例状态

status 是使用频率最高的子命令，文本输出面向人、JSON 输出面向脚本：

usage: minarca status [-h] [--instance INSTANCE_ID] [--json-output]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Show status for the given instance(s).
  --json-output, --json, -j
                        Output status as json for parsing.

不带参数时输出全部实例（本环境有两个实例：远端实例 0 与本地目的端实例 1，实例概念见 5.4 节）：

minarca status

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T05:51:19+0000
Last backup date:         2026-10-22T05:51:19+0000
Last backup status:       SUCCESS   
----------------------------------------------------
Backup instance:          local-dest
Identifier:               1         
Local device:             localbak  
Paused until:             2026-10-22T06:52:19+0000
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   Never     
Last backup date:         Never     
Last backup status:       UNKNOWN

关键解读：每个实例块自上而下是实例名、标识号、目的端（远端显示 Remote server，本地显示 Local device）、频率、连通性与最近备份三元组（成功时间/日期/结果）。实例 1 从未备份过（Never/UNKNOWN），且处于暂停中（Paused until 行只在暂停期出现，见 5.8 节）。

脚本化取状态用 --json（实测输出节选，保留实例 0 完整对象，实例 1 对象从略）：

minarca status --json

[
  {
    "id": "0",
    "connected": true,
    "status": {
      "details": "",
      "lastdate": "1792648279853",
      "lastresult": "SUCCESS",
      "lastsuccess": "1792648279853",
      "pid": 7508,
      "action": "backup",
      "lastnotificationid": null,
      "lastnotificationdate": null
    },
    "settings": {
      "username": "admin",
      "accesstoken": null,
      "repositoryname": "client02",
      "remotehost": "minarca-server",
      "remoteurl": "http://minarca-server:8080",
      "remoterole": 0,
      "schedule": 24,
      "configured": true,
      "pause_until": null,
      "diskid": null,
      "maxage": 0,
      "inactivity": null,
      "ignore_weekday": [],
      "keepdays": -1,
      "check_latest_version": true,
      "localmountpoint": null,
      "localuuid": null,
      "localrelpath": null,
      "localcaption": null,
      "pre_hook_command": null,
      "post_hook_command": null,
      "ignore_hook_errors": false,
      "extra_rdiff_backup_args": null,
      "remote_capabilities": []
    }
  }

关键解读：status 子对象是运行态（lastresult/lastdate/pid 等），settings 子对象是配置态——它的键与 /etc/minarca/minarca0.properties 中的配置键一一对应（schedule=24 即每 24 小时，keepdays=-1 表示不按天数清理），配置项含义的逐键详解见 《Minarca Server 6.2 配置参数详解》。监控脚本只需关心两个值：connected 与 status.lastresult。

5.3 include / exclude / patterns：管理备份范围

Minarca 客户端默认「全部排除、显式包含」：不添加任何 include 模式时什么都不备份（底层命令以 --exclude "/**" 收尾）。因此日常运维中最常见的需求就是用 include/exclude 收放备份范围，用 patterns 复核当前生效的模式列表。三个命令的用法：

usage: minarca exclude [-h] [--instance INSTANCE_ID] pattern [pattern ...]

positional arguments:
  pattern               file pattern to be excluded. May contain `*` or `?`
                        wildcard

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Add exclude file pattern to the given instance(s).

usage: minarca include [-h] [--instance INSTANCE_ID] pattern [pattern ...]

positional arguments:
  pattern               file pattern to be excluded. May contain `*` or `?`
                        wildcard

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Add include file pattern to the given instance(s).

usage: minarca patterns [-h] [--instance INSTANCE_ID]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Show include and exclude patterns only for the given
                        instance(s).

先看实例 0 当前生效的完整模式列表（实测，13 行）：

minarca patterns --instance 0

-/dev
-/proc
-/sys
-/tmp
-/run
-/mnt
-/media
-**/lost+found
-**/.~*
-**/*~
+/srv/data
-**/*.tmp
+/etc/minarca/patterns*

关键解读：+ 开头是包含、- 开头是排除，自上而下首次命中生效。默认列表先排除系统目录与临时文件，再显式包含 /srv/data，随后排除其中的 .tmp，最后把模式文件自身（/etc/minarca/patterns）也纳入备份以便追溯。带模式匹配语义时注意：* 与 ? 为通配符，** 跨目录层级。

不带 --instance 时按实例顺序输出所有实例的模式块（实测）：

minarca patterns

-/dev
-/proc
-/sys
-/tmp
-/run
-/mnt
-/media
-**/lost+found
-**/.~*
-**/*~
+/srv/data
-**/*.tmp
+/etc/minarca/patterns*
-/dev
-/proc
-/sys
-/tmp
-/run
-/mnt
-/media
-**/lost+found
-**/.~*
-**/*~
-/srv/localbak

关键解读：输出就是两个实例模式块的直接拼接（实例 0 十三行 + 实例 1 十一行），中间没有分隔标记，脚本解析时建议始终带 --instance。另一个细节：实例 1 是本地目的端实例（目的目录 /srv/localbak），其模式列表末尾自动追加了 -/srv/localbak，防止把备份目的端自身再备进去。

include/exclude 追加模式实测——成功同样静默，用 patterns 复核：

minarca include '/srv/data/*.conf' --instance 0
echo RC=$?

RC=0

tail -3 /etc/minarca/patterns0

+/srv/data
-**/*.tmp
+/srv/data/*.conf

minarca patterns --instance 0 | tail -4

-**/*~
+/srv/data
-**/*.tmp
+/srv/data/*.conf

minarca exclude '**/*.log' --instance 0
echo RC=$?

RC=0

tail -2 /etc/minarca/patterns0

-**/*.tmp
-**/*.log

关键解读：include/exclude 就是往 /etc/minarca/patterns0 末尾追加一行（+模式 或 -模式），改动即时生效、无需重启。客户端没有「删除单条模式」的子命令，撤销时直接编辑模式文件，例如删除刚才追加的排除行并验证清零（实测）：

sed -i '\|^-...\*\.log$|d' /etc/minarca/patterns0
grep -c '\*\.log' /etc/minarca/patterns0

0

5.4 configure（link）：关联新的备份目的端

configure 负责把本机关联到一个新的备份目的端——远端 Minarca 服务器或本地目录，每成功执行一次就新增一个备份实例（Identifier 递增）。别名 link 等价。用法：

usage: minarca configure [-h] [-r REMOTEURL] [-u USERNAME] [-p PASSWORD]
                         [-n NAME] [--force] [--purge-destination]
                         [-d LOCALDEST]

options:
  -h, --help            show this help message and exit
  -r REMOTEURL, --remoteurl REMOTEURL
                        URL to the remote server. e.g.:
                        http://example.com:8080/
  -u USERNAME, --username USERNAME
                        username to be used for authentication with the remote
                        server
  -p PASSWORD, --password PASSWORD
                        password or access token to use for authentication.
                        You will be prompted if not provided
  -n NAME, --name NAME  repository name to be used
  --force               replace existing repository on backup destination if
                        it exists without confirmation
  --purge-destination   delete all contents of destination, then
                        initialize/configure it -- only work for local
                        destination
  -d LOCALDEST, --localdest LOCALDEST
                        path to local destination

先实测一个报错场景：关联本地目的端时，目的目录必须预先存在，否则直接失败（实测）：

minarca configure -d /srv/localbak2 -n local-demo
echo RC=$?

unexpected error retrieving patterns
Traceback (most recent call last):
  File "main.py", line 821, in main
  File "main.py", line 138, in _configure
  File "minarca_client/core/compat/disk.py", line 361, in get_location_info
  File "minarca_client/core/compat/disk.py", line 352, in splitmountpoint
  File "minarca_client/core/compat/disk.py", line 82, in _get_mountpoint_posix
  File "pathlib.py", line 840, in stat
FileNotFoundError: [Errno 2] No such file or directory: '/srv/localbak2'
RC=101

修复方式是先建目录再关联（实测）：

mkdir -p /srv/localbak2
minarca configure -d /srv/localbak2 -n local-demo
echo RC=$?

Linked successfully
RC=0

关联成功后 status 立即多出实例 2（实测输出节选，保留新实例块，实例 0/1 从略）：

minarca status

----------------------------------------------------
Backup instance:          local-demo
Identifier:               2         
Local device:             localbak2 
Paused until:             2026-10-22T08:07:53+0000
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   Never     
Last backup date:         Never     
Last backup status:       UNKNOWN

关键解读：三个要点。其一，-d 本地目的端的前提是目录已存在（报错退出码 101，traceback 落在 stat 调用上，根因一目了然）；其二，远端关联只需按上方 usage 组合 -r（服务器地址如 http://minarca-server:8080）、`-u`/`-p`（账号密码，本文环境为 admin/admin123）与 -n（仓库名），关联后的实例管理命令与本节完全相同；其三，新建实例默认暂停 1 小时（Paused until 比创建时刻晚 60 分钟），给用户留出调整 patterns 的时间窗，不想等就用 5.8 节的 pause --clear 解除。

5.5 forget（unlink）：解除实例关联

forget 删除指定实例的本机关联配置（服务端仓库不受影响），别名 unlink 等价。用法：

usage: minarca forget [-h] [--instance INSTANCE_ID] [--force]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Forget settings of the given backup instance(s).
  --force               Force forget operation without confirmation from the
                        user.

实例号不存在时的报错形态（实测于实例 2 尚不存在时）：

minarca forget --instance 2 --force
echo RC=$?

Backup Instances:
No backup instances match: 2
RC=103

删除已创建的实例 2（实测）：

minarca forget --instance 2 --force
echo RC=$?

Backup Instances:
* local-demo
RC=0

删除后的状态与磁盘残留（实测）：

minarca status

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T07:05:06+0000
Last backup date:         2026-10-22T07:05:43+0000
Last backup status:       FAILURE   
Details:                  Unable to connect to the remote server. The problem may be with the remote server. If the problem persists, contact your system administrator to check the SSH server configuration and a possible firewall blocking the connection. (Error: 14)
----------------------------------------------------
Backup instance:          local-dest
Identifier:               1         
Local device:             localbak  
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   Never     
Last backup date:         Never     
Last backup status:       UNKNOWN   

ls /srv

data
localbak
localbak2

关键解读：forget 成功时会先列出匹配到的实例名（* local-demo）再删除；不带 --instance 时作用于全部实例、--force 免确认（生产上建议始终带 --instance 精确操作）。两点残留要知晓：本机目的端目录 /srv/localbak2 成为空目录残留，需要手工清理；服务端仓库（若有远端实例）不随 forget 删除，要彻底下线仓库走 4.3 节的服务端操作。上例 status 中实例 0 的 FAILURE 是当时 SSH 断连演示留下的记录（见 6.3 节），与 forget 无关。

5.6 stop：停止正在运行的备份

stop 用于中断正在执行的备份（例如误把大目录纳入范围后想立刻停下）：

usage: minarca stop [-h] [--instance INSTANCE_ID] [--force]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Stop only the given instance(s).
  --force               doesn't fail if the backup is not running.

空闲状态下（没有备份在跑）两种写法的实测对比：

minarca stop
echo RC=$?

RC=105

minarca stop --force
echo RC=$?

RC=0

关键解读：--force 的语义是「没有备份在跑也不报错」（usage 原文 doesn't fail if the backup is not running），所以空闲时无 --force 返回 105、有 --force 返回 0。写停止脚本时建议固定带 --force 实现幂等。

5.7 schedule 与 unschedule：管理 crontab 调度

schedule 把备份调度写入 root 的 crontab，unschedule 移除。用法：

usage: minarca schedule [-h] [--hourly] [--daily] [--weekly]
                        [--instance INSTANCE_ID]

options:
  -h, --help            show this help message and exit
  --hourly              schedule backup to run hourly
  --daily               schedule backup to run daily
  --weekly              schedule backup to run weekly
  --instance INSTANCE_ID
                        Configure only the given instance(s).

usage: minarca unschedule [-h]

options:
  -h, --help  show this help message and exit

完整生命周期实测——先看当前 crontab（每天 4 个时点）：

crontab -l


7,22,37,52 * * * * /opt/minarca/minarca backup

移除调度（成功静默，crontab 清空）：

minarca unschedule
echo RC=$?

RC=0

crontab -l
echo RC=$?

RC=0

grep schedule /etc/minarca/minarca0.properties

schedule=24

重新写回调度（--daily 对应 24 小时频率）：

minarca schedule --daily
echo RC=$?

RC=0

crontab -l


6,21,36,51 * * * * /opt/minarca/minarca backup

grep schedule /etc/minarca/minarca0.properties

schedule=24

⚠️ 注意：两次 schedule 写入的分钟数不同（7,22,37,52 → 6,21,36,51）——minarca 在整点内随机选择 4 个错开的分钟偏移，避免大批客户端在同一分钟涌向服务器。因此不要在监控或配置比对中硬编码 crontab 的分钟值，比对「每小时 4 个时点」的存在性即可。--hourly/--weekly 同理按所选频率写入对应时点；properties 里的 schedule=24 是「频率小时数」，与 crontab 时点无关，两者由 schedule 命令一起维护。

5.8 pause：临时暂停与解除

pause 让实例在指定小时数内不执行调度备份，适合变更窗口、全量杀毒扫描等场景。用法：

usage: minarca pause [-h] [--instance INSTANCE_ID] [-d DELAY] [-c [DELAY]]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Pause only the given instance(s).
  -d DELAY, --delay DELAY
                        number of hours
  -c [DELAY], --clear [DELAY]
                        clear previously set delay

暂停 1 小时 → 查看生效 → 解除，全流程实测：

minarca pause -d 1 --instance 0
echo RC=$?

RC=0

grep pause_until /etc/minarca/minarca0.properties

pause_until=1792655955155

minarca status --instance 0 | grep -i paused

Paused until:             2026-10-22T07:59:15+0000

minarca pause --clear
echo RC=$?

RC=0

grep -c pause /etc/minarca/minarca0.properties

0

关键解读：-d 单位是小时（不带 -d 时默认 24）；暂停状态落在 properties 的 pause_until 键（毫秒时间戳，1792655955155 即 07:59:15），status 文本输出会同步显示 Paused until 行，--clear 立即解除并删除该键。注意 minarca pause 0、minarca pause --hours=0 都是错误语法，解除暂停只有 --clear 一种写法。

5.9 restore：从备份还原数据

restore 支持还原到原位置或指定目录、支持按时间点取历史版本。用法：

usage: minarca restore [-h] [--instance INSTANCE_ID]
                       [--restore-time RESTORE_TIME]
                       [--destination DESTINATION] [--force]
                       [paths ...]

positional arguments:
  paths                 files and folders to be restored

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Force the use of a given instance for restore.
  --restore-time RESTORE_TIME
                        Date and time to be restored. Could be 'now' to
                        restore the latest backup. Could be an epoch value
                        like '1682367069'. Could be an ISO date format like
                        '2023-02-24T04:11:09-04:00'. Could be an interval like
                        '3D' for 3 days ago.
  --destination DESTINATION
                        Define an alternate location to restore files or
                        folders instead of restoring them in place.
  --force               Force execution of restore operation without
                        confirmation from the user.

报错实录：目的目录未预创建。 直接还原到不存在的目录会失败（实测）：

rm -rf /tmp/restore-demo2
minarca restore --instance 0 --destination /tmp/restore-demo2 --force /srv/data/app.conf
echo RC=$?
ls -d /tmp/restore-demo2 2>&1

instance 0: restore FAILED
process returned a non-zero exit status (1). Check logs for more details
RC=11
ls: cannot access '/tmp/restore-demo2': No such file or directory

定位手段：在子命令前加 -d 复跑，从调试输出中能看到实际执行的底层命令与远端路径（实测节选，远端 schema 行见 4.4 节）：

minarca -d restore --instance 0 --destination /tmp/restore-demo2 --force /srv/data/app.conf 2>&1 | tail -8

looking for `ssh` executable in path /opt/minarca:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
instance 0: remote schema: /usr/bin/ssh -F /dev/null -oConnectTimeout=10 -oBatchMode=yes -oPreferredAuthentications=publickey -oUserKnownHostsFile=/etc/minarca/known_hosts0 -oIdentitiesOnly=yes -i /etc/minarca/id_rsa0 %s 'minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)'
instance 0: constructing backup path for /srv/data/app.conf
instance 0: remote backup path: minarca@minarca-server::client02/srv/data/app.conf
instance 0: executing command: rdiff-backup -v 5 --force --remote-schema "/usr/bin/ssh -F /dev/null -oConnectTimeout=10 -oBatchMode=yes -oPreferredAuthentications=publickey -oUserKnownHostsFile=/etc/minarca/known_hosts0 -oIdentitiesOnly=yes -i /etc/minarca/id_rsa0 %s 'minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)'" restore --at now minarca@minarca-server::client02/srv/data/app.conf /tmp/restore-demo2/app.conf
looking for `minarca` executable in path /opt/minarca:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
instance 0: restore FAILED
process returned a non-zero exit status (1). Check logs for more details

关键解读：debug 输出里的 remote backup path 行说明还原源会被拼成 minarca@minarca-server::<仓库名>/<源路径>（客户端自动补仓库前缀 client02/），目标则是 <destination>/app.conf——即先在目标目录下创建同名文件；/tmp/restore-demo2 不存在导致创建失败，这就是 RC=11 的根因。修复：先建目录再还原（实测）：

mkdir -p /tmp/restore-demo2
minarca restore --instance 0 --destination /tmp/restore-demo2 --force /srv/data/app.conf
echo RC=$?
ls -l /tmp/restore-demo2/
cat /tmp/restore-demo2/app.conf
wc -c /tmp/restore-demo2/app.conf

RC=0
total 4
-rw-r--r-- 1 root root 66 Oct 21 18:07 app.conf
minarca demo config file v1
server-host=0.0.0.0
increment line v2
66 /tmp/restore-demo2/app.conf

按时间点还原历史版本。 源机上的 /srv/data/notes.txt 后来被删除，但仓库里仍有它的历史版本（见 4.3 节 increments 列表）。用 --restore-time 指定它仍存在的时间点即可取回（实测）：

mkdir -p /tmp/restore-time-demo2
minarca restore --instance 0 --destination /tmp/restore-time-demo2 --force --restore-time '2026-10-21T18:23:10+00:00' /srv/data/notes.txt
echo RC=$?
ls -l /tmp/restore-time-demo2/
cat /tmp/restore-time-demo2/notes.txt

RC=0
total 4
-rw-r--r-- 1 root root 25 Oct 21 18:22 notes.txt
server room checklist v1

关键解读：三点经验。其一，成功的 restore 同样完全静默，退出码 0，还原出的文件保留原始 mtime（上例 app.conf 的 Oct 21 18:07、notes.txt 的 Oct 21 18:22 都是源文件原时间戳）；其二，--restore-time 接受 now/epoch/ISO/interval（如 3D）四种写法，指定的时间点会落到其之前最近的一次备份状态——本例 18:23:10 落到 18:23:03 那次备份的 notes.txt；其三，还原「已被删除的文件」时若时间点选在其被删之后，命令会静默成功但不产生任何文件（实测 20:00 时间点即如此，RC=0 且目标目录为空），遇到「还原成功但没文件」先检查时间点。还原失败不报文件系统错误细节时，排查路径固定为：-d 复跑看底层命令 → 核对目标目录存在性 → 查 /var/log/minarca.log。

5.10 verify：校验备份完整性

verify 的用途是校验远端仓库备份完整性，但在 7.2.0 客户端 + 6.2.5 服务端的组合上实测不可用：

usage: minarca verify [-h] [--instance INSTANCE_ID]

options:
  -h, --help            show this help message and exit
  --instance INSTANCE_ID
                        Verify backup integrity of the given backup
                        instance(s).

minarca verify --instance 0
echo RC=$?

Repository cannot be found on remote server
RC=26

用 -d 定位根因（实测关键行）：

minarca -d verify --instance 0 2>&1 | grep -E "executing command|ERROR"

instance 0: executing command: rdiff-backup -v 5 --remote-schema "/usr/bin/ssh -F /dev/null -oConnectTimeout=10 -oBatchMode=yes -oPreferredAuthentications=publickey -oUserKnownHostsFile=/etc/minarca/known_hosts0 -oIdentitiesOnly=yes -i /etc/minarca/id_rsa0 %s 'minarca/7.2.0 rdiff-backup/2.2.6 (Linux 6.8.0-138-generic x86_64)'" verify minarca@minarca-server::.
instance 0: ERROR: Path '.' couldn't be identified as being within an existing backup repository
instance 0: ERROR: Action verify failed on step check

关键解读：底层命令把校验目标写死为 minarca@minarca-server::.（用户根目录），而服务端 rdiff-backup 要求路径必须落在某个仓库内，于是报 Path '.' couldn't be identified as being within an existing backup repository——这是 7.2.0 客户端在该服务端组合下的实现缺陷，不是环境故障，无需修复服务端。完整性校验的替代做法：抽取关键文件做 minarca restore --restore-time now 到临时目录比对内容（5.9 节实测可行）。

5.11 ui：图形界面（服务器场景不可用）

ui 启动基于 Kivy 的图形界面，也是无参数调用 minarca 时的默认行为：

usage: minarca ui [-h]

options:
  -h, --help  show this help message and exit

无头服务器上实测（带 4 秒超时防止挂住）：

timeout 4 minarca ui 2>&1 | grep -E "not supported|OSError" | head -2

Input: MTDev is not supported by your version of linux
OSError: libmtdev.so.1: cannot open shared object file: No such file or directory

（未加管道过滤时进程以退出码 124 被 timeout 结束。）关键解读：ui 依赖图形栈与输入设备库（libmtdev）、剪贴板工具（xclip/xsel），服务器环境不具备也不需要——服务器场景一律用本章 CLI。若误执行了裸 minarca，Ctrl-C 或等待超时即可。

5.12 rdiff-backup 透传与 imap-backup

rdiff-backup 透传。 把参数原样传给客户端内置的 rdiff-backup，用于查询版本等内部用途：

minarca rdiff-backup --version
echo RC=$?

rdiff-backup 2.2.6
rdiff-backup 2.2.6
RC=0

关键解读：输出两行是实测原样（内部做了两次版本探测），客户端内置引擎为 2.2.6，与服务端为其选择的版本一致（4.4 节）。除版本查询外不建议经此透传执行操作，备份/还原一律走本章标准子命令。

imap-backup：IMAP 邮箱归档。 帮助标注为内部工具，但具备完整功能：把 IMAP 邮箱归档到 Minarca 数据目录，支持四种认证方式（basic/outlook/microsoft365/google），默认 993 端口 SSL。完整用法（实测）：

minarca imap-backup --help

usage: minarca [-h] [--server SERVER] [--port PORT] [--no-ssl] --username
               USERNAME [--password PASSWORD]
               [--auth {basic,outlook,microsoft365,google}] [--output OUTPUT]
               [--include-folder INCLUDE_FOLDER]
               [--exclude-folder EXCLUDE_FOLDER] [--token-file TOKEN_FILE]
               [--google-client-id GOOGLE_CLIENT_ID]
               [--google-client-secret GOOGLE_CLIENT_SECRET]
               [--google-scopes GOOGLE_SCOPES] [--ms-client-id MS_CLIENT_ID]
               [--ms-tenant MS_TENANT] [--ms-scopes MS_SCOPES]

IMAP Backup used to archive mailbox.

options:
  -h, --help            show this help message and exit
  --server SERVER       IMAP server.
  --port PORT           Server port. Default to 993.
  --no-ssl              Disable SSL
  --username USERNAME   IMAP user or email address
  --password PASSWORD   Password or App password
  --auth {basic,outlook,microsoft365,google}
                        Authentication method: basic (username/password),
                        outlook (Personal Microsoft Account), microsoft365 or
                        google.
  --output OUTPUT       Relative path to Minarca data home
  --include-folder INCLUDE_FOLDER
                        Glob pattern to include folders (e.g. "INBOX",
                        "Work/*")
  --exclude-folder EXCLUDE_FOLDER
                        Glob pattern to exclude folders
  --token-file TOKEN_FILE
                        Relative path to Minarca data home for OAuth tokens.
  --google-client-id GOOGLE_CLIENT_ID
                        Google application (client) ID.
  --google-client-secret GOOGLE_CLIENT_SECRET
                        Google application (client) Secret.
  --google-scopes GOOGLE_SCOPES
                        Comma or space separated Google OAuth scopes. Default
                        is full Gmail IMAP/SMTP scope.
  --ms-client-id MS_CLIENT_ID
                        Microsoft application (client) ID.
  --ms-tenant MS_TENANT
                        consumers, organizations, common, tenant-id or domain.
  --ms-scopes MS_SCOPES
                        Comma or space separated Microsoft OAuth scopes for
                        IMAP.

关键解读：归档结果落在 --output 指定的 Minarca 数据目录相对路径下，随后作为普通文件被备份实例收进仓库；--include-folder/--exclude-folder 用 glob 圈定邮箱文件夹（如 "INBOX"、"Work/*"）。OAuth 类认证需要预先在对应云厂商注册应用并填入 client-id/secret。本环境无真实邮箱可连，未做归档实测，参数以官方帮助输出为准。

六、常见问题

6.1 backup/start 无输出且退出码恒为 0——判定一律用 status

现象：无论备份成功还是失败，minarca backup --force 的输出与退出码都可能毫无区别（成功静默 RC=0；6.3 节的断连失败同样 RC=0）。根因：客户端把备份结果的判定职责完全交给了 status——命令返回 0 只表示「备份流程被正常发起并走完」，不代表数据成功落仓。

处置：任何脚本化备份后固定跟一次状态判定，示例（JSON 字段含义见 5.2 节）：

minarca backup --force --instance 0
minarca status --json --instance 0 | grep -o '"lastresult": "[A-Z]*"'

实测（成功时）：

"lastresult": "SUCCESS"

6.2 排障实录：停止 Web 服务后备份照常成功（备份通道与 Web 界面分离）

现象：有观点认为客户端配置里写着 remoteurl: http://minarca-server:8080，备份一定依赖 Web 服务。实测推翻了这个直觉，完整周期如下。

服务端停 Web 并确认端口消失：

systemctl stop minarca-server
systemctl is-active minarca-server
echo RC=$?

inactive
RC=3

ss -ltn | grep 8080
echo RC=$?

RC=1

客户端状态检查：SSH 连通性判定不受 Web 影响（输出节选，仅保留连通性行）：

minarca status --instance 0

Connectivity status:      Connected

Web 停止期间发起备份，随后立即查看状态（Web 仍未恢复）：

minarca backup --force --instance 0
echo RC=$?

RC=0

minarca status --instance 0

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T07:30:14+0000
Last backup date:         2026-10-22T07:30:14+0000
Last backup status:       SUCCESS

服务端侧的第一现场佐证——Web 停止窗口内 shell.log 记录了完整的 SSH 备份会话（节选见 4.2 节，会话时间 07:30:11/07:30:15 正落在停服窗口内），journal 则记录了 Web 的停止事件：

journalctl -u minarca-server -n 3 --no-pager

Oct 22 07:30:08 minarca-server systemd[1]: minarca-server.service: Deactivated successfully.
Oct 22 07:30:08 minarca-server systemd[1]: Stopped Minarca Web Server.
Oct 22 07:30:08 minarca-server systemd[1]: minarca-server.service: Consumed 1.926s CPU time.

恢复 Web 并确认服务回到 active：

systemctl start minarca-server
systemctl is-active minarca-server

active

结论与处置：备份通道 = SSH(22) + minarca-shell（4.2 节），Web(8080) 只承担管理界面与首次关联，两者完全独立。运维上可以放心对 Web 做维护重启，不影响备份任务；反过来，6.3 节证明真正会让备份全停的是 SSH 通道故障。

6.3 排障实录：SSH 断连才是备份通道真中断（Error: 14）

现象与服务端停止 Web 不同，服务端 SSH 服务停止后，客户端备份立即失败且 traceback 直指 SSH。完整周期实测如下。

服务端停 SSH 并确认端口关闭：

systemctl stop ssh
ss -ltn | grep :22
echo RC=$?

RC=1

客户端状态立即显示未连接（注意退出码仍是 0）：

minarca status --instance 0
echo RC=$?

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Not connected
Last successful backup:   2026-10-22T07:30:14+0000
Last backup date:         2026-10-22T07:30:14+0000
Last backup status:       SUCCESS   
RC=0

发起备份，得到完整 traceback（输出节选，保留末尾关键行）：

minarca backup --force --instance 0 2>&1 | tail -6
echo BACKUP_RC=${PIPESTATUS[0]}

Traceback (most recent call last):
  File "minarca_client/core/instance.py", line 282, in backup
  File "minarca_client/core/instance.py", line 338, in _backup_anchor
  File "minarca_client/core/instance.py", line 490, in _rdiff_backup
minarca_client.core.exceptions.ConnectException: Unable to connect to the remote server. The problem may be with the remote server. If the problem persists, contact your system administrator to check the SSH server configuration and a possible firewall blocking the connection. (Error: 14)
instance 0: backup FAILED
BACKUP_RC=0

恢复 SSH 并确认监听回归：

systemctl start ssh
ss -ltn | grep :22

LISTEN 0      128          0.0.0.0:22         0.0.0.0:*
LISTEN 0      128             [::]:22            [::]:*

客户端状态已回到 Connected，但最近一次备份状态为 FAILURE 且 Details 带上了错误详情：

minarca status --instance 0

Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T07:30:14+0000
Last backup date:         2026-10-22T07:30:52+0000
Last backup status:       FAILURE   
Details:                  Unable to connect to the remote server. The problem may be with the remote server. If the problem persists, contact your system administrator to check the SSH server configuration and a possible firewall blocking the connection. (Error: 14)

补跑一次备份完成闭环（实测）：

minarca backup --force --instance 0
echo RC=$?
minarca status --instance 0

RC=0
Verifying connection...
----------------------------------------------------
Backup instance:          client02  
Identifier:               0         
Remote server:            minarca-server
Backup frequency:         every 24h 
Connectivity status:      Connected 
Last successful backup:   2026-10-22T07:31:01+0000
Last backup date:         2026-10-22T07:31:01+0000
Last backup status:       SUCCESS

结论与处置：遇到 ConnectException ... (Error: 14) 按固定顺序排查——服务端 systemctl is-active ssh、ss -ltn | grep :22、两机间防火墙；恢复后无需重启客户端，直接补跑备份即可，FAILURE 记录会被新一次 SUCCESS 覆盖。同时再次印证 6.1 节：备份 FAILED 的命令退出码仍是 0（BACKUP_RC=0），自动化判定必须走 status。

6.4 verify 报 "Repository cannot be found on remote server"

现象：minarca verify --instance 0 返回 Repository cannot be found on remote server，退出码 26。根因：7.2.0 客户端把校验目标拼成了用户根目录（minarca@minarca-server::.），不在任何仓库内，服务端 rdiff-backup 拒绝（debug 关键行见 5.10 节）。处置：这是客户端在该组合下的实现问题，服务端无需（也无法）修复；完整性校验改用 5.9 节的 restore --restore-time 抽样比对。升级客户端后可先用本节命令复测 verify 是否已修复。

6.5 schedule 之后 crontab 的分钟数变了

现象：重跑 minarca schedule --daily 后，crontab 从 7,22,37,52 变成 6,21,36,51（实测见 5.7 节）。根因：minarca 每次写调度时在整点内随机选择错开的分钟偏移，避免大量客户端同一分钟集中发起备份。处置：不要在监控、配置基线里硬编码具体分钟值；判断调度是否正常用「每小时是否存在 4 个 /opt/minarca/minarca backup 时点」这类结构化比对，或直接 minarca status 看备份是否按节奏出现。

6.6 ui 在无头服务器上无法启动

现象：minarca ui（或误敲裸 minarca）报 OSError: libmtdev.so.1: cannot open shared object file，随后可能挂住不退出。根因：ui 是 Kivy 图形程序，依赖触摸输入库与图形环境，服务器没有这些组件（实测报错见 5.11 节）。处置：服务器场景统一用 CLI 子命令；误执行时用 Ctrl-C 中断，脚本环境可像 5.11 节那样套 timeout 兜底。

七、参考链接