Debian 13 安装 Backupninja 1.2.2 指南

目标：在一台干净的 Debian 13（trixie）服务器上从零安装 Backupninja 1.2.2 并完成「安装 → 试运行 → 实跑 → 邮件报告 → cron 定时触发」的全链路验证。本文全部命令与回显均在真实容器环境中逐条执行采集（环境见第一节），依赖链、安装产物、日志与邮件正文均为实测原文；配置文件体系的深层原理见本专栏配置详解篇，backupninja/ninjahelper 命令行详见命令详解篇。

一、环境信息

项目	实测值
操作系统	Debian 13.7 (trixie)，容器内 systemd 正常运行
内核/架构	5.15.0-151-generic / x86_64
实测日期	2026-10-24（容器内 UTC 时间，日志时间戳一致）
执行用户	root
软件来源	官方仓库 http://deb.debian.org/debian trixie/main（无需添加第三方源）
安装版本	backupninja 1.2.2-1（Debian 打包，当前 stable/oldstable/testing/unstable 全线同版本）

选型背景与版本节奏见《Backupninja 1.2.2 介绍与选型指南》；本文直接进入实操。

二、安装前准备

2.1 软件源与候选版本

Backupninja 在 Debian 主仓库的 admin 分区中，无需第三方源。实测确认候选版本：

root@backup-server:~# apt policy backupninja
backupninja:
  Installed: 1.2.2-1
  Candidate: 1.2.2-1
  Version table:
 *** 1.2.2-1 500
        500 http://deb.debian.org/debian trixie/main amd64 Packages

2.2 硬依赖链（Depends）

包声明的硬依赖只有三项，均为系统基础组件（实测 apt-cache show 回显）：

Depends: bash (>= 2.05b-26), dialog, gawk | mawk
Recommends: bsd-mailx | mailx | mailutils
Suggests: borgbackup, bzip2, debconf-utils, duplicity, fdisk | util-linux,
          genisoimage, hwinfo, mdadm, rdiff-backup, restic, rsync,
          subversion, trickle, wodim

关键解读：

dialog 是 ninjahelper TUI 向导的界面库，apt 会自动装上（附 libdialog15）；
bsd-mailx 作为 Recommended 一并安装，同时把 exim4 MTA 链拉进来——这是邮件报告的投递通道；
Suggests 里的全部是「各 handler 的后端工具」，默认不装：要用哪类 handler 再装哪个（如 .rdiff 对应 rdiff-backup、.rsync 对应 rsync、.sys 对应 debconf-utils + hwinfo），这是 Backupninja 的即插即用设计。

2.3 关于 cron 的特别说明

backupninja 不依赖 cron 包（Depends 中没有它），只按惯例在 /etc/cron.d/ 放了一个调度文件。真实 Debian 服务器几乎必装 cron，但在最小化容器/镜像中可能缺失——本实测环境就遇到了：安装 backupninja 后 systemctl is-active cron 返回 inactive，检查发现 cron 根本未安装。需要补装：

root@backup-server:~# apt-get install -y cron
root@backup-server:~# systemctl start cron
root@backup-server:~# systemctl is-active cron
active

⚠️ 如果没有 cron（或未启动 /etc/cron.d 机制），backupninja 的任何定时能力都不生效，只能靠 backupninja --run 手动执行——这是最小化环境部署时最容易漏掉的一环。

三、安装步骤

3.1 执行安装

root@backup-server:~# apt-get update
root@backup-server:~# DEBIAN_FRONTEND=noninteractive apt-get install -y backupninja

实测回显（关键部分原文）：

The following additional packages will be installed:
  adduser bsd-mailx ca-certificates dialog exim4-base exim4-config
  exim4-daemon-light krb5-locales libcom-err2 libdialog15 libevent-2.1-7t64
  libffi8 libfile-fcntllock-perl libgdbm-compat4t64 libgdbm6t64
  libgnutls-dane0t64 libgnutls30t64 libgpm2 libgssapi-krb5-2 libidn12
  libidn2-0 libk5crypto3 libkeyutils1 libkrb5-3 libkrb5support0
  liblockfile-bin liblockfile1 libncursesw6 libnsl2 libp11-kit0 libperl5.40
  libtasn1-6 libtirpc-common libtirpc3t64 libunbound8 libunistring5 netbase
  openssl perl perl-modules-5.40 psmisc
Suggested packages:
  liblocale-gettext-perl cron quota borgbackup bzip2 debconf-utils duplicity
  fdisk | util-linux genisoimage hwinfo mdadm rdiff-backup restic rsync
  subversion trickle wodim ...
The following NEW packages will be installed:
  adduser backupninja bsd-mailx ca-certificates dialog exim4-base exim4-config
  ...（同上，含 backupninja 本体）
0 upgraded, 42 newly installed, 0 to remove and 3 not upgraded.
Need to get 17.3 MB of archives.
After this operation, 76.4 MB of additional disk space will be used.
...
Get:14 http://deb.debian.org/debian trixie/main amd64 dialog amd64 1.3-20250116-1 [126 kB]
Get:15 http://deb.debian.org/debian trixie/main amd64 backupninja all 1.2.2-1 [92.1 kB]
...
Setting up backupninja (1.2.2-1) ...
Setting exim4-daemon-light (4.98.2-1+deb13u5) ...

量级解读：backupninja 本体仅 92.1 kB；42 个新包里约 30 个来自 exim4/bsd-mailx 邮件链与 perl 依赖。若服务器已有 MTA 或不需要邮件报告，可用 --no-install-recommends 把安装面缩到最小（仅 bash/dialog/gawk），代价是没有报告邮件。

3.2 安装产物清单

实测 dpkg -L backupninja 关键产物：

路径	作用
/usr/sbin/backupninja	主调度脚本（cron 调用它）
/usr/sbin/ninjahelper	TUI 向导
/etc/backupninja.conf	全局主配置（loglevel、reportemail、when 等）
/etc/backup.d/	动作配置目录（空，权限 drwxrws---，setgid 位）
/etc/cron.d/backupninja	cron 调度入口
/etc/logrotate.d/backupninja	日志轮转（monthly + rotate 6 + compress）
/usr/share/backupninja/	13 个 handler 脚本 + 9 个 .helper 向导脚本
/usr/share/doc/backupninja/examples/	各 handler 示例配置（example.rdiff、example.mysql 等）
/var/log/backupninja.log	运行日志（首次运行时生成）
/usr/share/man/man1/backupninja.1.gz 等	手册页（backupninja.1、ninjahelper.1、backup.d.5、backupninja.conf.5）

包内置的 cron 条目（/etc/cron.d/backupninja 原文）：

# run backupninja every hour on the hour
0 * * * * root if [ -x /usr/sbin/backupninja ]; then /usr/sbin/backupninja; fi

即：每小时整点由 root 拉起主脚本一次，具体某个配置要不要在这一次执行，由它自己的 when = 决定（默认 everyday at 01:00，即只在每天 01:00 那次整点触发命中）。

3.3 版本确认（含一个陷阱）

root@backup-server:~# backupninja --version
backupninja 1.2.2

⚠️ 陷阱：--version（与 -h/--help）在打印信息后并不会退出，主脚本会继续走完一整轮「扫描配置 → when 匹配 → 执行 handler」流程。实测中 backupninja --version 真实执行了当时存在的 when = hourly 配置（.sh 动作，产物 /srv/backup/dpkg-selections.txt 被重新生成）。在生产服务器上做「顺手看一下版本」这类操作时要记住这一点；想无副作用查版本，用 dpkg -l backupninja 或 apt policy backupninja 更安全。

四、运行验证

4.1 首次试运行（--test）

先放一条最小动作配置（.sh 后缀 = 直接执行的 shell 脚本），when = manual 表示不参与定时、只接受手动执行：

root@backup-server:~# cat > /etc/backup.d/40-dpkg.sh <<'EOF'
when = manual
dpkg --get-selections > /srv/backup/dpkg-selections.txt
EOF
root@backup-server:~# chmod 600 /etc/backup.d/40-dpkg.sh
root@backup-server:~# backupninja --test

实测回显（原文节选，loglevel=5）：

Debug: check_perms /etc/backup.d
Debug: perms: drwxrws---
Debug: gperm: rws
Debug: wperm: ---
Debug: check_perms /etc/backup.d/40-dpkg.sh
Debug: perms: -rw-------
Debug: gperm: ---
Debug: wperm: ---
Debug: skipping /etc/backup.d/10-etc.tar because current time does not match manual
Debug: skipping /etc/backup.d/20-var.rsync because current time does not match everyday at 01:00
Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because 'when = hourly')
Debug: yes
Debug: executing handler in locked section controlled by /var/lock/backupninja/_etc_backup.d_40-dpkg.sh
Debug: handler returned exit code 0
Info: <<<< finished action /etc/backup.d/40-dpkg.sh: SUCCESS
Debug: send report to root
Info: FINISHED: 1 actions run. 0 fatal. 0 error. 0 warning.

要点：--test 模式下会对每个配置执行 check_perms 权限校验并逐个报告 when 匹配结果，.sh handler 在 test 模式下不会真正执行（实测确认 test 模式结束后产物文件并未生成）。

4.2 正式实跑（--run）

root@backup-server:~# backupninja --run /etc/backup.d/40-dpkg.sh

实测回显（关键行）：

Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because of --now)
Debug: executing handler in locked section controlled by /var/lock/backupninja/_etc_backup.d_40-dpkg.sh
Debug: handler returned exit code 0
Info: <<<< finished action /etc/backup.d/40-dpkg.sh: SUCCESS
Info: FINISHED: 1 actions run. 0 fatal. 0 error. 0 warning.

产物验证：

root@backup-server:~# ls -la /srv/backup/dpkg-selections.txt
-rw-r--r-- 1 root root 1874 Oct 24 06:44 /srv/backup/dpkg-selections.txt
root@backup-server:~# head -3 /srv/backup/dpkg-selections.txt
adduser						install
apt						install
apt-listchanges					install

4.3 邮件报告验证

默认配置 reportemail = root，每轮结束后经本地 MTA（安装时一并装好的 exim4）投递汇总邮件。实测收到邮件正文原文：

Subject: backupninja: backup-server / success -- /etc/backup.d/40-dpkg.sh

Backup report -- backup-server
=========
BACKUPNINJA SERVER REPORT
|  System   :   backup-server
|  Date     :   Oct 24, 2026 06:44
|
|  Legend   :   ^  = disabled
|               +  = success
|               !  = unused
|               ?  = unknown
|               (F) = FATAL
|               (E) = ERROR
|               (W) = WARNING
|
|
+  /etc/backup.d/40-dpkg.sh  |  0 fatal / 0 error / 0 warning
|
== An unexpected "SUCCESS" : your backups seem to be working!

主题行格式为「backupninja: <主机名> / <状态> -- <最后一个动作>」，正文是逐动作的结果清单。收不到邮件时先确认三件事：报告粒度开关（reportsuccess 等）、exim4 服务是否运行、/var/mail 下 root 邮箱（本容器实测投递到了 /var/mail/mail，因容器环境的 MTA 别名配置与常规服务器不同）。

4.4 cron 定时触发验证

为在合理时间内验证「cron → backupninja → when 命中 → handler 执行」的完整链路，实测采用「临时把 cron 调度改密」的方法（生产服务器保持默认 0 * * * * 即可）：

root@backup-server:~# cp /etc/cron.d/backupninja /etc/cron.d/backupninja.orig
root@backup-server:~# printf '*/2 * * * * root if [ -x /usr/sbin/backupninja ]; then /usr/sbin/backupninja; fi\n' > /etc/cron.d/backupninja
root@backup-server:~# rm -f /srv/backup/dpkg-selections.txt   # 清掉手动测试产物
root@backup-server:~# sleep 180 && date

双证据命中（journalctl 与运行日志交叉印证）：

root@backup-server:~# journalctl -u cron --no-pager | tail -3
Oct 24 06:54:01 backup-server cron[820]: (root) CMD (if [ -x /usr/sbin/backupninja ]; then /usr/sbin/backupninja; fi)
Oct 24 06:54:01 backup-server CRON[820]: (root) CMD (if [ -x /usr/sbin/backupninja ]; then /usr/sbin/backupninja; fi)

root@backup-server:~# tail -2 /var/log/backupninja.log
Oct 24 06:54:01 Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because 'when = hourly')
Oct 24 06:54:01 Info: <<<< finished action /etc/backup.d/40-dpkg.sh: SUCCESS

root@backup-server:~# ls -la /srv/backup/dpkg-selections.txt   # 由 cron 触发重新生成
-rw-r--r-- 1 root root 1874 Oct 24 06:54 /srv/backup/dpkg-selections.txt

验证完成后恢复默认调度（mv /etc/cron.d/backupninja.orig /etc/cron.d/backupninja）。至此「安装依赖链 → 配置动作 → 试运行 → 实跑 → 邮件报告 → 定时触发」全链路打通。

五、初步使用（多后端速览）

按 handler 类型补装 Suggests 依赖后，把示例配置改写为自己的即可，例如：

tar 全量归档（只需 bzip2）：/etc/backup.d/10-etc.tar，配置 backupdir = /var/backups/tar、includes = /etc；
rsync 目录镜像（补装 rsync）：/etc/backup.d/20-var.rsync，[source] include = /var/log + [dest] dest = local；
sys 系统信息（补装 debconf-utils、hwinfo、fdisk）：/etc/backup.d/30-sys.sys，产物落 /var/backups；
rdiff 增量（补装 rdiff-backup，选型见《rdiff-backup 介绍与选型指南》）：/etc/backup.d/50-etc.rdiff，[source] type = local + [dest] type = local、keep = 60。

五类 handler 的完整字段、目录语义与踩坑实录制本专栏配置详解篇；不想手写配置可运行 ninjahelper 用 TUI 向导生成（实测见命令详解篇）。如果只是要单机文件快照、不需要多后端编排，直接用 rsnapshot 更轻量，见《rsnapshot 介绍与选型指南》。

六、常见问题排错

以下 7 条均为本环境实测复现的真实问题（现象原文 + 解法）：

配置文件权限不符，动作被拒绝执行 现象：Debug: skipping ... because current time does not match manual 或权限报错；主脚本要求 /etc/backup.d/ 下每个文件 -rw-------（600）且属主 root。解法：chmod 600 /etc/backup.d/*。目录本身带 setgid（drwxrws---）是包内置权限，保持即可。
rsync handler 报 Fatal: Backupdir /srv/backup/rsync/var does not exist 原因：rsync handler 不自动创建目标目录层级。解法：按 mountpoint + backupdir 的组合路径提前 mkdir -p，再重跑。
rdiff handler 报 Fatal: desttype '' is neither local nor remote 原因：[dest] 段漏配 type = local（或 remote），handler 无法判断目标类型。解法：补上 type = local；随后可能再报 Unable to delete and/or create directory ... does not exist，把 [dest] directory 的父目录提前 mkdir 即可（rdiff 目标目录实际会再叠加一层 [source] label 子目录）。
sys handler 报 Warning: can't find sfdisk 与 /sbin/lsmod: No such file or directory 原因：Suggests 依赖未装（sfdisk 在 fdisk 包）或工具路径与 merged-/usr 下的实际路径不一致。解法：apt-get install fdisk kmod 后重跑；仍会看到 Info: executing of /sbin/modinfo failed 的 Info 级提示，不影响 SUCCESS。
backupninja --version / --help 顺手执行了备份 原因：主脚本对 -V/-h 只打印信息、不退出，之后继续完整跑一轮调度（见 3.3 节实测）。解法：查版本用 dpkg -l backupninja；确认无副作用再跑它们。
每轮日志末尾固定出现 Error: /var/lib/prometheus/node-exporter does not exist! 原因：1.2.2 的 reportprom 功能对 node-exporter 文本文件目录做存在性检查，目录缺失时打印该行；即便 reportprom = false 也会出现。影响：仅提示，不计入 fatal/error 统计（FINISHED 行仍为 0 fatal / 0 error）。解法：装 prometheus-node-exporter、mkdir -p /var/lib/prometheus/node-exporter，或无视。
收不到报告邮件 排查顺序：reportemail 配置 → reportsuccess = yes 是否开启（默认 no 时成功轮次不发）→ MTA 服务状态（systemctl status exim4）→ /var/mail/root。容器/policy-rc.d 环境下 exim4 装完未自启，需手动 systemctl start exim4。

七、参考链接

本站专栏：《Backupninja 1.2.2 介绍与选型指南》（版本溯源与架构认知）
本站专栏：《rdiff-backup 介绍与选型指南》（.rdiff 后端引擎选型）
本站专栏：《rsnapshot 介绍与选型指南》（单机快照替代方案）
本站专栏：《Duplicity 介绍与选型指南》（.dup 加密增量后端）
Debian 包页：https://packages.debian.org/stable/backupninja （查询日期 2026-10-24）
随包示例与手册：/usr/share/doc/backupninja/examples/、backupninja(1)、backup.d(5)