Backupninja 1.2.2 ninjahelper 与 CLI 详解

目标：完整拆解 Backupninja 的两个操作入口——backupninja 主命令的全部选项与运行语义（含试运行/立即执行/单动作执行三态），以及 ninjahelper TUI 向导的菜单结构、tar 向导逐屏实录与自动生成配置。文中全部命令输出、菜单文本与生成文件均为 Debian 13 上 1.2.2-1 实机操作采集，TUI 实录通过 pty 自动化驱动 ninjahelper 完成。

一、环境信息

项目	实测值
操作系统	Debian 13.7 (trixie)，x86_64，systemd + cron 运行中
软件版本	backupninja 1.2.2-1、dialog 1.3-20250116-1、expect 5.45.4、python3-pexpect 4.9
实测日期	2026-10-24
实测动作	/etc/backup.d/ 下 10-etc.tar、20-var.rsync、30-sys.sys、40-dpkg.sh、50-etc.rdiff、向导生成 10.tar

安装与运行验证见《Debian 13 安装 Backupninja 1.2.2 指南》；配置字段语义见《Backupninja 1.2.2 配置文件体系详解》；本文专注「怎么操作」。

二、backupninja 主命令

2.1 全部选项（--help 实测原文）

/usr/sbin/backupninja usage:
This script allows you to coordinate system backup by dropping a few
simple configuration files into /etc/backup.d/. Typically, this
script is run hourly from cron.

The following options are available:
-h, --help           This usage message
-V, --version        Show backupninja version number
-d, --debug          Run in debug mode, where all log messages are
                     output to the current shell.
-f, --conffile FILE  Use FILE for the main configuration instead
                     of /etc/backupninja.conf
-t, --test           Test run mode. This will test if the backup
                     could run, without actually preforming any
                     backups. For example, it will attempt to authenticate
                     or test that ssh keys are set correctly.
-n, --now            Perform actions now, instead of when they might
                     be scheduled. No output will be created unless also
                     run with -d.
    --run FILE       Execute the specified action file and then exit.
                     Also puts backupninja in debug mode.

When in debug mode, output to the console will be colored:
Debug: Debugging info (when run with -d)
Info: Informational messages (verbosity level 4)
Warning: Warnings (verbosity level 3 and up)
Error: Errors (verbosity level 2 and up)
Fatal: Errors which halt a given backup action (always shown)
Halt: Errors which halt the whole backupninja run (always shown)

即全部选项只有 7 个：-h/-V/-d/-f/-t/-n/--run，没有 reload/status 类子命令——状态一律看 /var/log/backupninja.log 与邮件报告。

2.2 三种运行形态与实测语义

形态	命令	行为（实测）
定时轮询	`backupninja`（cron 0 * * * * 拉起）	逐文件 check_perms → when 匹配 → 命中者执行；未命中者日志记 `skipping ... because current time does not match <when>`
试运行	`backupninja --test` / `--test --run FILE`	全部动作走「权限校验 + when 判定 + 连通性检查」，不真正执行备份；`.sh` 动作在 test 模式不执行（handler 内 `[ $test ] \|\| ( . $1 )`），但 tar/rsync 等会补建目标目录——「建目录但不落备份」是 test 模式的真实边界
立即执行	`backupninja --run FILE`（单动作）/ `backupninja --now`（全量忽略调度）	忽略 when，日志标注 `because of --now`；`--run` 同时隐含 debug 模式

实测记录三种形态的日志标注差异（同一动作 40-dpkg.sh）：

Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because 'when = hourly')   # 定时命中
Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because of --now)          # --run / --now
Debug: skipping /etc/backup.d/20-var.rsync because current time does not match everyday at 01:00   # 未命中

2.3 --version 与 --help 的运行陷阱（实测）

root@backup-server:~# backupninja --version
backupninja 1.2.2
root@backup-server:~# tail -4 /var/log/backupninja.log
Oct 24 06:44:39 Info: >>>> starting action /etc/backup.d/40-dpkg.sh (because 'when = hourly')
Oct 24 06:44:39 Info: <<<< finished action /etc/backup.d/40-dpkg.sh: SUCCESS
Oct 24 06:44:39 Debug: send report to root
Oct 24 06:44:39 Info: FINISHED: 1 actions run. 0 fatal. 0 error. 0 warning.

-V/--version（及 -h/--help）打印后不退出，主脚本继续执行一整轮调度——上例中 --version 把 when = hourly 的动作真实执行了一遍。查版本请用 dpkg -l backupninja。无副作用的安全查看途径还有 backupninja --test（dry-run）与 --test --run FILE。

2.4 调试方法与退出码

-d/--debug：日志同步输出到当前 shell（着色分级 Debug/Info/Warning/Error/Fatal/Halt，配色见 2.1 原文）；--run FILE 自带 debug；
全局 loglevel = 4（/etc/backupninja.conf）控制落盘日志详细度，5 最啰嗦；
退出码实测：未知选项直接 usage; exit 3（主脚本源码行为），正常轮次退出 0；主流程结尾按 fatal/error/warning 计数写 FINISHED 汇总行——判断成败以该行与各动作 SUCCESS/WARNING/FATAL 为准，不要只看退出码。

三、ninjahelper TUI 向导

3.1 菜单结构（实测转录）

ninjahelper 基于 dialog 渲染两层菜单（实测屏幕文本转录）：

主菜单——标题 main menu，正文 Select a backup action for more options, or create a new action:，条目为当前 /etc/backup.d/ 全部动作文件（1、2、3…）外加 new（create a new backup action）与 quit 两个固定项；

新建动作菜单——标题 new action menu，正文 select an action to create，条目来自 /usr/share/backupninja/*.helper（实测顺序：return、sys: system info backup、mysql: mysql backup、borg: borg backup、rdiff: rdiff-backup backup、dup: duplicity backup、pgsql: postgresql backup、tar: tar backup、restic: restic backup、makecd: iso/cd backup）。

选中已有动作后的二级菜单（action menu，标题为动作路径）共 8 项：

菜单项	函数	实际行为
main	—	返回主菜单
view	cat 显示	查看配置内容
xedit	$EDITOR 编辑	用外部编辑器改配置
disable / name	mv 改名	加/去 `.disabled` 后缀、重命名
run	`backupninja --run $action`	立即正式执行
test	`backupninja --test --run $action`	单动作试运行（实测可见 handler 将执行的完整命令行）
kill	do_rm_action	删除该动作

3.2 tar 向导逐屏实录（实测）

通过 pty 驱动 ninjahelper 新建 tar 动作，四屏问答与默认值实录：

[Q1] When to run this action?            默认 everyday at 01
[Q2] Name of backups?                    默认 backup-server（取主机 fqdn）
[Q3] Directory where to store the backups?  默认 /var/backups/tar/backup-server
[Q4] Compression:                        radioBox，bzip 预选（* bzip / gzip / none）
[Q5] Includes:                           form，默认 /etc /home /usr/local
[Q6] Excludes:                           form，默认 /tmp /proc /sys /dev /srv /media /misc /net /selinux

向导结束后自动生成 /etc/backup.d/10.tar（命名自增取号，实测 10 号位空闲即用 10.tar；文件权限 600）。生成文件实测原文：

when = everyday at 01
backupname = backup-server
backupdir = /var/backups/tar/backup-server
compress = bzip
includes =  /etc /home /usr/local
excludes =  /tmp /proc /sys /dev /srv /media /misc /net /selinux

# tar binary - have to be GNU tar
#TAR=/bin/tar
#DATE           /bin/date
#DATEFORMAT     "%Y.%m.%d-%H%M"

对照手写示例（见配置详解篇 5.1），向导版多了 excludes 的标准虚拟文件系统排除项与底部工具路径注释块；when = everyday at 01 与 Q1 答案一致。该文件随后经 backupninja --test --run /etc/backup.d/10.tar 与 --run 双重实测，完整命令行为：

Debug: Running backup:  /usr/bin/tar -c -p -v -j --exclude /tmp --exclude /proc --exclude /sys
 --exclude /dev --exclude /srv --exclude /media --exclude /misc --exclude /net --exclude /selinux
 -f /var/backups/tar/backup-server/backup-server-2026.10.24-0704.tar.bz2 /etc /home /usr/local
Info: <<<< finished action /etc/backup.d/10.tar: SUCCESS

3.3 向导使用要点（实测归纳）

驱动方式：菜单内输入条目首字母可直接定位（n=new、t=tar、q=quit），回车确认；表单/输入框回车即提交默认值；
** Includes/Excludes 表单**：默认已填三个路径，直接回车保留；清空某行再回车可删除该条；
test 菜单项：与命令行 --test --run 等价（源码即 backupninja --test --run $1），执行后 Hit return to continue... 返回菜单；
最小环境前置：dialog 必须在（依赖自动带）；SSH 会话需正确 TERM，否则界面渲染异常；在 pty 自动化实测中，无 TERM 时 ninjahelper 直接退出（dialog 无法初始化）；
9 类带向导的后端（borg/dup/makecd/mysql/pgsql/rdiff/restic/sys/tar）问答字段各不相同，均最终落成对应后缀的 ini 配置——与手写文件完全等价，可继续手工微调。

四、常见问题排错（命令与 TUI 向）

--version/--help 执行了备份：见 2.3 节实测。生产上避免直接跑它们，或先临时把动作文件改名 .disabled。
test 模式「看起来什么都没发生」：test 只做权限/调度/连通性检查并显示将执行的命令；要看真实落盘产物请 --run。.sh 动作在 test 模式永不执行（实测产物未生成）。
日志里 handler returned exit code 1 但 SUCCESS：tar handler 末行 [ $? -ne 0 ] 判定式的返回值，属框架正常噪音（实测 5.1 节三件套正常落盘）；真正的失败标识是 FATAL 行与 FINISHED 汇总的 fatal 计数。
每轮日志末尾 Error: /var/lib/prometheus/node-exporter does not exist!：reportprom 目录缺失提示，不计入错误统计；mkdir -p /var/lib/prometheus/node-exporter 即消失。
ninjahelper 界面乱码/秒退：确认 echo $TERM 合法、dialog 已装；自动化驱动（expect/pexpect）时务必设置 TERM 且逐屏匹配（实测盲发按键会丢失焦点，需按 Select a backup action、select an action to create 等屏幕锚点推进）。
cron 没跑：按次序查 systemctl is-active cron（容器实测曾缺失需补装）→ /etc/cron.d/backupninja 存在与否 → journalctl -u cron | grep backupninja 是否出现 CMD 行 → /var/log/backupninja.log 是否有对应时间戳。

五、参考链接

本站专栏：《Backupninja 1.2.2 配置文件体系详解》（本文操作对象的字段语义）
本站专栏：《Debian 13 安装 Backupninja 1.2.2 指南》（安装与全链路验证）
本站专栏：《Backupninja 1.2.2 介绍与选型指南》（架构与选型）
本站专栏：《rdiff-backup 常用 CLI 命令详解》（.rdiff 后端引擎的命令行对照）
本站专栏：《rsnapshot 介绍与选型指南》（无 TUI 向导的替代方案对照）
随包手册：backupninja(1)、ninjahelper(1)（backupninja 1.2.2-1，实测环境 Debian 13）