Thruk 3.30 配置参数详解

目标：以 Ubuntu 22.04 + Thruk 3.30-1 + Naemon 1.5.2 实测环境为基础，系统梳理 Thruk 的配置体系：主配置 thruk.conf（311 个参数）与本地覆盖 thruk_local.conf 的分层机制、XML 式嵌套段语法、后端 Livestatus peer 声明、认证授权（htpasswd/cgi.cfg）、界面与性能调优参数、Apache/FastCGI 集成配置，并给出生产配置模板与实测踩坑实录。全部参数与回显均实测采集。

一、环境信息

• 操作系统：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、Apache 2.4.52
• 配置目录：/etc/thruk/
• 后端形态：Naemon + Livestatus unix socket（/var/cache/naemon/live）
• 查询日期：2026-11-01

二、前置条件

1. 已按部署篇完成 Thruk + Naemon + Apache 安装并可登录 Web；
2. 具备 root 权限编辑 /etc/thruk/ 下的配置文件；
3. 理解 Thruk 配置与监控核心配置（/etc/naemon/）是两套独立体系：本篇只涉及 Thruk 侧与 Apache 侧。

三、参数查看与修改方式

3.1 配置文件分层机制

/etc/thruk/ 目录实测清单：

action_menus/          # 动作菜单
bp/                    # Business Process 定义（www-data 属主）
cgi.cfg                # Nagios 兼容授权模型（8378 字节）
htpasswd               # Web 登录口令文件（25 字节）
log4perl.conf          # 日志框架配置
menu_local.conf        # 菜单本地覆盖
naglint.conf           # 配置引用一致性检查器
panorama/              # Panorama 仪表盘定义
plugins/               # 界面插件
ssi/                   # 页头页脚 SSI 模板
themes/                # 主题
thruk.conf             # 主配置（48101 字节，1274 行）
thruk_local.conf       # 本地覆盖（升级不覆盖）
thruk_local.d/         # drop-in 片段目录
usercontent/           # 用户个性化数据

分层规则（thruk.conf 文件头标注 "DONT CHANGE THIS FILE"）：

1. thruk.conf：出厂默认全量参数（实测含 311 个参数行），升级包时会被覆盖，不要直接改；
2. thruk_local.conf：官方指定的本地覆盖文件，同名参数覆盖主配置，升级保留——所有自定义都应写在这里；
3. thruk_local.d/：drop-in 目录，可把多份配置拆成多个片段文件，便于管理；
4. Web 界面 ConfigTool 插件也可直接编辑 thruk_local.conf、cgi.cfg、htpasswd（见 5.7）。

3.2 语法格式：XML 式嵌套段而非 INI

Thruk 配置解析器（Config.pm）采用 XML 式段语法：

<Component Thruk::Backend>
    <peer>
        name = naemon
        <options>
            peer = /var/cache/naemon/live
        </options>
    </peer>
</Component>

实测踩坑两条：

• 用 INI 风格 [Backend] 段报错：unknown config entry: [Backend]；
• 闭合标签写 </Component Thruk::Backend> 报错：unexpected closing block found——闭合标签一律只写元素名 </Component>。

3.3 修改后如何生效与校验

Thruk 以 FastCGI 进程运行，每次请求都会读取配置；但为稳妥起见修改后重启 Apache：

systemctl restart apache2

配置是否可解析，用 CLI 触发解析校验（CLI 与 Web 共用同一套配置加载逻辑）：

thruk backend list

配置有语法错误时该命令会直接打印解析错误（如上文两条实测报错）；正常则输出后端表。thruk selfcheck 可进一步检查后端连通、目录可写、日志无错。

⚠️ 注意：任务或教程中常见的 thruk-config、thruk-backup 独立命令在 3.30 deb 安装中不存在（实测 thruk config 返回 FAILED - no such command），配置管理就是"编辑文件 + 重启"，备份直接打包 /etc/thruk/ 即可。

四、参数总览

thruk.conf 实测参数总数：

grep -cE "^\s*#?\s*[a-z_]+\s*=" /etc/thruk/thruk.conf

311

按用途分类的核心参数一览（默认值均实测自 3.30-1 出厂配置）：

五、核心参数分类详解

5.1 后端连接（Thruk::Backend peer）

这是 Thruk 最重要的配置：thruk.conf 第 959-1019 行给出官方示例（出厂全注释），实际生效配置写入 thruk_local.conf。本实验完整实测段：

<Component Thruk::Backend>
    <peer>
        name   = naemon
        type   = livestatus
        <options>
            peer          = /var/cache/naemon/live
            resource_file = /etc/naemon/resource.cfg
        </options>
        <configtool>
            core_conf      = /etc/naemon/naemon.cfg
            obj_check_cmd  = /usr/bin/naemon -v /etc/naemon/naemon.cfg
            obj_reload_cmd = systemctl reload naemon
        </configtool>
    </peer>
</Component>

逐项说明：

• name：后端标识，多后端时必须唯一；
• type：livestatus（生产标准），另有 thruk（对接远端 Thruk 实例做聚合，示例见主配置第 1016 行 auth = secret_key_from_remote_instance）；
• options.peer：Livestatus 地址，unix socket 路径或 host:port TCP；
• options.resource_file：核心的 resource.cfg，用于展开 $USERn$ 宏；
• configtool.*：Web 配置编辑器的校验/重载命令三件套——没有这段，configtool 只读；
• 主配置第 979 行另有注释示例 groups = admins，可把后端可见性限定到指定用户组。

生效验证（实测）：

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     |
+--------+---------+-------+---------+------------------------+--------------------------------+--------+

⚠️ socket 权限是高频坑：Livestatus socket 属组 naemon、权限 srw-rw----，Apache 的 www-data 默认无权访问，Status 会显示 491: failed to connect - Permission denied。修复：usermod -aG naemon www-data && systemctl restart apache2（实测 id www-data 回显 uid=33(www-data) gid=33(www-data) groups=33(www-data),108(naemon) 后恢复 OK）。

5.2 路径与运行时

实测生效值：

thruk_user=www-data
thruk_group=www-data
tmp_path = /var/cache/thruk
var_path = /var/lib/thruk
max_process_memory = 1000

• thruk_user/thruk_group：Thruk 进程身份，必须与 Web 服务器用户一致（deb 默认 www-data）；var_path、tmp_path 及其下文件属主随之为 www-data（实测 ls -l /etc/thruk/ 中 bp/、panorama/、thruk_local.conf 均为 www-data 属主）；
• max_process_memory = 1000：单个 FastCGI 进程内存超 1000MB 自动回收，是大型安装的关键保护；
• 日志经 log4perl：/etc/thruk/log4perl.conf 实测生效配置——输出到 /var/log/thruk/thruk.log，Threshold=INFO：

log4perl.logger=ALL, ThrukLog
log4perl.appender.ThrukLog.filename=/var/log/thruk/thruk.log
log4perl.appender.ThrukLog.Threshold=INFO
log4perl.appender.ThrukLog.layout.ConversionPattern=[%d][%H][%p] %m{chomp}%n

5.3 认证与授权

Thruk 认证是"三层拼合"：

1. 口令文件 /etc/thruk/htpasswd（Apache Basic Auth 与 Thruk 登录共用）：

htpasswd -b -B /etc/thruk/htpasswd thrukadmin q1w2e3r4

实测回显：Updating password for user thrukadmin

2. 授权模型 /etc/thruk/cgi.cfg——兼容 Nagios 的 authorized_for_* 体系，实测生效值节选：

use_authentication=1
authorized_for_admin=thrukadmin
authorized_for_reports=*

authorized_for_admin 决定谁能进系统管理；authorized_for_reports=* 表示所有认证用户可看报表；其余 authorized_for_all_hosts、authorized_for_system_commands 等留空即仅管理员。

3. 口令策略参数（thruk.conf）：user_password_min_length = 5（生产建议调大）、disable_user_password_change = 0、admin_role_from_system_and_conf = 1（root 运行 CLI 时自动视为管理员）。

csrf_allowed_hosts=127.0.0.1 / ::1：仅本机发起的 POST 免 CSRF 校验，通过反向代理访问 Thruk 时必须把代理 IP 加入白名单，否则界面操作报 CSRF 错误——这是反代场景第一大坑。

5.4 界面与性能

实测生效值与调整建议：

• paging_steps = *100, 500, 1000, 5000, all（* 为默认选中项）：千级主机规模建议改 *50, 100, ... 减小首屏渲染；
• group_paging_overview = *3, 10, 100, all、group_paging_summary = *10, 50, 100, all：主机组视图分页；
• problems_limit = 500：首页问题列表上限，超大规模站点防止拖垮 Livestatus 查询；
• default_theme = Light / default_theme_dark = Dark：双主题，跟随浏览器偏好；
• show_long_plugin_output = popup：插件长输出以弹层展示；
• use_bookmark_titles = 0、use_dynamic_titles = 1：书签与页面标题策略。

5.5 功能开关

• use_feature_trends = 1：状态页趋势小图（无数据依赖，纯 Livestatus 历史）；
• use_feature_recurring_downtime = 1：周期性停机计划；
• strict_passive_mode = 1：被动检查也走新鲜度判定，过期即 UNKNOWN；
• show_config_edit_buttons = 0：默认隐藏表格里直达 configtool 的编辑按钮，启用需配合 5.7；
• hide_top = auto、show_notification_number = 1、status_color_background = 0 等显示细节开关。

5.6 Apache 侧配置（FastCGI 集成）

deb 安装自动生成的 /etc/apache2/conf-available/thruk.conf 是 Web 链路核心，实测关键内容：

<IfModule mod_fcgid.c>
  IPCCommTimeout 120
  AliasMatch ^/thruk/(.*\.cgi|.*\.html|r/).* /usr/share/thruk/fcgid_env.sh/thruk/$1
  Alias /thruk/themes/  /etc/thruk/themes/themes-enabled/
  AliasMatch ^/thruk/plugins/(.*?)/(.*)$     /etc/thruk/plugins/plugins-enabled/$1/root/$2
  <Location /thruk/>
    Options ExecCGI FollowSymLinks
    AuthName "Thruk Monitoring"
    AuthType Basic
    AuthUserFile /etc/thruk/htpasswd
    Require valid-user
  </Location>
</IfModule>

• IPCCommTimeout 120：FastCGI 进程通信超时，报表导出等慢操作不够用时调大（注释给出了 FcgidCmdOptions ... IOTimeout 扩法）；
• AliasMatch 把 /thruk/*.cgi 映射进 fcgid 包装脚本——这就是 Thruk 保留 Nagios CGI URL 习惯（status.cgi 等）的实现方式；
• <Location /thruk/cgi-bin/remote.cgi> 单独 Require all granted：远程命令通道免 Basic Auth（由 Thruk 自身校验 auth key），外部脚本提交检查结果的入口。

cookie 认证 include（/usr/share/thruk/thruk_cookie_auth.include，被 postinst 写入 000-default.conf 第 30 行）实测第 9 行：

RewriteMap  thruk_users              prg:/usr/share/thruk/thruk_auth

第 14 行（本实验已打补丁）：

RewriteRule ^(.*)$                   ${thruk_users:$1|/loginbad/} [C,NS,UnsafeAllow3F]

Apache 2.4.46+ 必须带 UnsafeAllow3F，否则重写产物含 %3f 被拒，全站 403（完整排障实录见部署篇 7.1）。该文件由 deb 包管理，升级 thruk 后需重新打补丁。

5.7 ConfigTool 与插件段

thruk.conf 第 1032-1053 行 ConfigTool 段（出厂即启用）：

<Component Thruk::Plugin::ConfigTool>
    show_plugin_syntax_helper = 1
    thruk    = /etc/thruk/thruk_local.conf
    cgi.cfg  = /etc/thruk/cgi.cfg
    htpasswd = /etc/thruk/htpasswd
</Component>

• 声明了 Web 界面可直接编辑的三个文件；配合 5.1 的 <configtool> 校验/重载命令，实现"Web 改对象 → naemon -v 校验 → systemctl reload naemon"闭环；
• 注释项 pre_obj_save_cmd/post_obj_save_cmd 可挂保存前后钩子（如 git 备份）；obj_readonly 可锁定部分文件只读；
• 主配置第 1030 行注释明确：拥有 authorized_for_configuration_information 与 authorized_for_system_commands 角色的用户才能进 configtool。

Panorama 段实测含 full_reload_interval = 10800（仪表盘 3 小时整页刷新防内存泄漏，0 关闭）。

六、生产配置模板

/etc/thruk/thruk_local.conf 最小生产模板（在本实验实测配置基础上收紧）：

# 身份与路径
thruk_user        = www-data
thruk_group       = www-data

# 口令策略
user_password_min_length = 12

# 反代场景把代理机加入 CSRF 白名单（直连部署删除本行）
csrf_allowed_hosts = 127.0.0.1
csrf_allowed_hosts = 10.89.61.1

# 大型安装保护
max_process_memory = 2000
problems_limit     = 1000
paging_steps       = *50, 100, 500, 1000, all

# 后端（多站点时复制 <peer> 段）
<Component Thruk::Backend>
    <peer>
        name   = naemon
        type   = livestatus
        <options>
            peer          = /var/cache/naemon/live
            resource_file = /etc/naemon/resource.cfg
        </options>
        <configtool>
            core_conf      = /etc/naemon/naemon.cfg
            obj_check_cmd  = /usr/bin/naemon -v /etc/naemon/naemon.cfg
            obj_reload_cmd = systemctl reload naemon
        </configtool>
    </peer>
</Component>

配套动作清单：

1. htpasswd 改默认口令、cgi.cfg 收紧 authorized_for_*；
2. usermod -aG naemon www-data（同机 socket 方案）或改用 TCP livestatus + 防火墙；
3. systemctl restart apache2 后 thruk backend list 确认 Status=OK、thruk selfcheck 全绿；
4. 备份：tar czf /backup/thruk-etc.tar.gz /etc/thruk/（无 thruk-backup 命令，实测不存在）。

七、常见问题

• unknown config entry: [Backend]：用了 INI 段语法，改 XML 式 <Component> 段（见 3.2）；
• unexpected closing block found：闭合标签带了属性名，改为 </Component>；
• 后端 Status 显示 Permission denied：www-data 无权读 socket，usermod -aG naemon www-data 后重启 Apache（实测有效）；
• 界面操作报 CSRF 错误：反向代理来源 IP 不在 csrf_allowed_hosts，补白名单；
• 升级 thruk 包后全站 403：cookie auth include 的 UnsafeAllow3F 补丁被覆盖，重新打（见 5.6）；
• 改了配置不生效：FastCGI 进程缓存了旧配置，systemctl restart apache2 最稳妥；
• thruk config / thruk-config 找不到：3.30 无此命令（实测 FAILED - no such command），配置校验用 thruk backend list。

八、参考链接

1. Thruk 官方文档（配置章节）：https://www.thruk.org/documentation.html （查询日期 2026-11-01）
2. 主配置出厂注释样例：/etc/thruk/thruk.conf（1274 行，959-1019 行后端示例、1028-1053 行 ConfigTool 段）
3. GitHub 源码配置解析器：https://github.com/sni/thruk/blob/master/thruk/lib/Thruk/Config.pm （查询日期 2026-11-01）
4. Apache mod_rewrite UnsafeAllow3F 变更说明：https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html （查询日期 2026-11-01）
5. 站内关联：《Thruk 介绍与选型指南》、《Ubuntu 22.04 安装 Thruk 3.30 指南》、《Naemon 1.5 配置参数详解》