Thruk 3.30 常用 CLI 命令与工具详解

目标：以 Ubuntu 22.04 + Thruk 3.30-1（Naemon 后端）实测环境为基础，逐一实测 Thruk 自带命令行工具 thruk 的 24 个 CLI 插件：后端查询（backend）、自检（selfcheck）、对象列表（host/service/hostgroup/contact）、命令展开（command）、配置引用查找（find）、REST API 客户端（rest/r）、报表与定时任务（report/cron/downtimetask）、缓存与集群维护（cache/lmd/cluster/plugin）等，给出每个命令的真实回显与生产用法。全部命令与输出逐条实测照抄。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（amd64）
软件版本：Thruk 3.30-1（thruk --version 实测输出 thruk v3.30）
后端：naemon-core 1.5.2-1 + naemon-livestatus 1.5.1-1（unix socket /var/cache/naemon/live）
CLI 入口：/usr/bin/thruk（deb 包 thruk-base 提供）
监控对象规模：4 台主机、18 个服务（实测）
查询日期：2026-11-01

二、工具概览

Thruk 只有一个 CLI 二进制 thruk，功能以"插件子命令"形式组织。直接运行不带参数即列出全部 24 个启用插件（实测）：

thruk

usage: /usr/bin/thruk [<globaloptions>] <plugin> [<options>]
see --help for detailed help.
Enabled cli plugins: apikey, backend, bp, cache, cluster, command, contact, cron, downtimetask, find, graph, host, hostgroup, livecache, lmd, logcache, maintenance, panorama, plugin, r, report, rest, selfcheck, service, servicegroup, url
get help for a specific plugin with: /usr/bin/thruk <plugin> help

⚠️ 重要实测结论：网络上教程常提到的 thruk-config、thruk-backup 独立命令在 3.30 deb 安装中不存在（thruk version 实测返回 FAILED - no such command: version.），thruk-autosetup 同样不存在（实测 command not found）。配置管理与备份就是"编辑 /etc/thruk/ + 打包目录"，CLI 不承担这些职责。

全局选项（thruk --help 实测节选）：

Globaloptions:
  -h, --help                    Show this help message and exit
  -v, --verbose                 Print verbose output
  -V, --version                 Print version
  -b, --backend=<backend>       Comma-separated list of backends/sites
  -A, --auth=<auth>             Set username for queries
  -y, --yes                     answer yes to all given questions.
  -l, --list-backends           List available backends/sites. Alias for 'backend list'.

-b 在多后端聚合部署时按站点过滤查询范围，是运维脚本里最常用的全局开关。

三、前置条件

Thruk 已安装且 /etc/thruk/thruk_local.conf 配置了后端 peer（配置方法见配置篇 5.1）；
CLI 与 Web 共用配置：后端 socket 权限问题同样影响 CLI——以 root 运行 CLI 时可访问 socket（admin_role_from_system_and_conf = 1 使 root 自动获得管理员角色），但行为要与 Web 一致验证时建议用 sudo -u www-data；
每个子命令都支持 help 后缀查看说明：thruk <plugin> help。

四、各工具详解

4.1 backend——后端状态查询

最核心的运维入口，列出所有 Livestatus peer 及连通状态：

thruk backend list

实测回显：

+--------+---------+-------+---------+------------------------+--------------------------------+--------+
| Name   | Section | Key   | Enabled | Address                | Version                        | Status |
+--------+---------+-------+---------+------------------------+--------------------------------+--------+
| naemon | Default | 2918f | Yes     | /var/cache/naemon/live | Livestatus 1.5.1.source-naemon | OK     |
+--------+---------+-------+---------+------------------------+--------------------------------+--------+

-l 是其快捷别名（实测输出同上）。Status 列的 491: failed to connect - Permission denied 排障见配置篇 5.1。

4.2 selfcheck——自检（插件格式输出）

检查后端、目录权限、日志、停机计划、报表五类健康项，输出即 Nagios 插件格式（带 perfdata），可被 Naemon 自身监控：

thruk selfcheck

实测回显：

OK - backends, filesystem, logfiles, recurring_downtimes, reports
Backends:
  - no errors in 1 backends

Filesystem:
  - var path /var/lib/thruk is writable
  - tmp path /var/cache/thruk is writable

Logfiles:
  - /var/lib/thruk/cron.log: no errors

Recurring Downtimes:
  - no errors in 0 downtimes

Reports:
  - no errors in 0 reports

 |'sessions_active_5min_total'=13;;;; 'sessions_total'=13;;;; 'sessions_uniq_user_5min_total'=1;;;; 'sessions_uniq_user_total'=1;;;; 'users_locked_total'=0;;;; 'users_total'=3;;;;
 runtime=0.059s;;;;

perfdata 里能看到会话数、用户数（实测 users_total=3）等指标，可直接喂给 PNP4Nagios 绘图。

4.3 host / service / hostgroup / servicegroup / contact——对象列表

从 Livestatus 拉取对象清单：

thruk host list

hplj2605dn
linksys-srw224p
localhost
winserver

thruk service list

PING
Printer Status
Port 1 Bandwidth Usage
Port 1 Link Status
Uptime
Current Load
Current Users
HTTP
Root Partition
SSH
Swap Usage
Total Processes
C:\ Drive Space
CPU Load
Explorer
Memory Usage
NSClient++ Version
W3SVC

thruk hostgroup list

linux-servers                  localhost
network-printers               hplj2605dn
switches                       linksys-srw224p
windows-servers                winserver

thruk contact list 实测输出 naemonadmin。这些列表命令适合做部署后的对象核对与脚本遍历（配合 -b 过滤后端）。

4.4 command——检查命令展开

排障利器：把宏展开成真实插件命令行，验证 $USERn$ 资源宏与 check_command 参数：

thruk command localhost PING

实测回显：

Check Command:    check_ping!100.0,20%!500.0,60%
Expanded Command: /usr/lib/naemon/plugins/check_ping -H 127.0.0.1 -w 100.0,20% -c 500.0,60% -p 5

-n 只打印展开后的命令行，方便直接复制执行：

thruk command -n localhost PING

/usr/lib/naemon/plugins/check_ping -H 127.0.0.1 -w 100.0,20% -c 500.0,60% -p 5

💡 技术拓展：帮助文本明确该命令"仅用于取回展开的 check 命令行"——它不执行检查。要下发检查/提工单等动作，用 4.6 的 rest 命令走 REST API。

4.5 find——对象引用查找

给定对象名，反查它出现在哪些配置文件行——改对象前评估影响面、清理僵尸定义必备：

thruk find host localhost

实测回显（节选）：

naemon:
  Configuration:
    localhost                      host found in the filesystem: /etc/naemon/conf.d/localhost.cfg:20
    linux-servers                  referenced in hostgroup 'linux-servers' at /etc/naemon/conf.d/localhost.cfg:35
    PING                           referenced in service 'PING' at /etc/naemon/conf.d/localhost.cfg:49
    HTTP                           referenced in service 'HTTP' at /etc/naemon/conf.d/localhost.cfg:115

支持类型含 host/hostgroup/service 等（thruk find --help 实测）。

4.6 rest / r——REST API 命令行客户端

r 是 rest 的别名。Thruk 全部对象经 REST 读写，CLI 是脚本化运维的主通道：

thruk rest --help

实测用法节选：

- simple query:
  thruk [global options] rest [-m method] [-d postdata] <url>

Examples:
  Get list of hosts sorted by name
    %> thruk r /hosts?sort=name

  Reschedule next host check for host localhost:
    %> thruk r -d "start_time=now" /hosts/localhost/cmd/schedule_host_check

实测查询（输出为对象 JSON，节选）：

thruk r /hosts?sort=name

[
   {
      "accept_passive_checks" : 1,
      "acknowledged" : 0,
      "address" : "192.168.1.30",
      "alias" : "HP LaserJet 2605dn",
      "check_command" : "check-host-alive",
      ...

-m PUT/POST -d '...' 即可完成确认、提评论、调度检查等操作；配合 thruk apikey 生成的 API Key 可在无口令场景下认证（X-Thruk-Auth-Key 请求头，见 Apache include 第 10 行实测）。

4.7 report / cron / downtimetask——报表与定时任务

thruk report：命令行生成 Web 里定义的报表（report list 实测本环境为空，report mail <nr> 可生成并邮件）；
thruk cron：安装/卸载 Thruk 的 cron 任务（实测帮助原文 "The cron command installs/uninstalls cronjobs"）；
thruk downtimetask：执行周期性停机任务（实测帮助 "executes recurring downtimes tasks"），配合 crontab 每分钟跑一次即让 Web 里定义的 recurring downtime 落地。

4.8 apikey——API 密钥管理

管理 REST 认证用的 API Key（实测帮助 "Show information about a Thruk api keys"）。thruk apikey list 输出用法说明，实际管理子命令为 info/add/remove 等，适合给监控自动化发密钥而不用交出口令。

4.9 bp / panorama——业务模型与仪表盘

thruk bp：Business Process 全套 CLI（实测帮助列出 all/<nr>/commit [--no-reload-core] [--no-reload-cron] 等动作），可在命令行计算/提交 BP 模型，配合 cron 让 BP 状态定期重算；
thruk panorama：命令行管理 Panorama 仪表盘（实测帮助 "manages panorama dashboards from the command line"）。

4.10 cache / plugin / cluster / graph / url / logcache / lmd——缓存与维护

命令	实测描述	用途
`cache`	"handles the internal thruk cache"	清理/查看内部缓存
`plugin`	"handles thruk plugins itself"	界面插件启用/禁用
`cluster`	"Show information about a Thruk cluster"	多 Thruk 实例集群状态
`graph`	"exports pnp/grafana graphs"	命令行导出图形
`url`	"displays any thruk url on stdout and can be used to create command line reports"	服务端渲染页面到 stdout（实测 `thruk url "/thruk/cgi-bin/status.cgi?host=localhost"` 输出完整 HTML），可做归档快照
`logcache`	"creates/updates the mysql/mariadb logfile cache"	日志缓存库维护
`lmd`	"controls the LMD process"	Livestatus 内存缓存守护进程管理
`livecache`	实测提示已废弃："deprecated and replaced by the lmd command"	勿再使用

maintenance 执行日常维护（实测帮助 "cleaning old session files"），一般由 cron 定时调用。

五、注意事项

只有 thruk 一个入口：thruk-config、thruk-backup、thruk-autosetup 均不存在（实测），凡教程出现即过期信息；
root 自动管理员：admin_role_from_system_and_conf = 1（默认）使 root 跑 CLI 即有管理员角色，生产审计场景建议显式 sudo -u www-data thruk ... 保持与 Web 同权；
livecache 已废弃：脚本迁移到 lmd（实测帮助原文标注 deprecated）；
CLI 与 Web 同配置：thruk_local.conf 改错会同时打挂 Web——改完先 thruk backend list 校验再收工；
REST 写操作会真实生效：thruk r -m POST ... 直接改监控状态/下发命令，脚本里加 -y 前务必评审。

六、常见问题

FAILED - no such command: xxx.：子命令拼写错误或该命令不存在（如 thruk version），对照第二节 24 插件清单；
backend list 显示 Permission denied：CLI 以 www-data 身份或 socket 组权限不足，usermod -aG naemon www-data 后重启 Apache（同配置篇 5.1）；
report list 无输出：本环境未定义报表，属正常（实测）；
thruk url 输出 HTML 而非 URL：该命令设计即"渲染页面到 stdout"，要取链接请直接用 Web 界面分享书签；
cron 任务没跑：用 thruk cron list 查看已装任务，thruk selfcheck 的 Logfiles 段会报 /var/lib/thruk/cron.log 错误。

七、参考链接

Thruk 官方文档（CLI/REST API 章节）：https://www.thruk.org/documentation.html （查询日期 2026-11-01）
GitHub 源码 CLI 插件目录：https://github.com/sni/thruk/tree/master/thruk/lib/Thruk/CLI （查询日期 2026-11-01）
本机帮助：thruk --help、thruk <plugin> help（24 插件逐一实测）
站内关联：《Thruk 介绍与选型指南》、《Ubuntu 22.04 安装 Thruk 3.30 指南》、《Thruk 3.30 配置参数详解》、《Naemon 1.5 常用 CLI 命令与工具详解》