Cacti 1.2.31 配置参数详解

目标：系统梳理 Cacti 1.2.31 的四层配置体系——include/config.php 连接参数、Web 界面 Settings 运行参数（settings 表）、Spine 轮询器 spine.conf、数据模板与设备模板，并给出每类参数的实测取值、修改方式与生产推荐模板；全部参数与回显已在 Ubuntu 22.04 实测环境逐项验证（2026-10-20）。

一、环境信息

本章给出参数实查所用环境的版本与组件清单。Cacti 1.2.31 的配置分散在四处：PHP 层的连接配置、数据库 settings 表的运行参数、Spine 的独立配置文件、以及模板体系（设备/图形/数据模板），理解分层是改对参数的前提。

版本与配置文件位置实测回显：

cat /var/www/html/cacti/include/cacti_version
/usr/local/spine/bin/spine --version
ls -l /var/www/html/cacti/include/config.php /etc/spine.conf

实测输出：

1.2.31
SPINE 1.2.31  Copyright 2004-2024 by The Cacti Group
-rw-r--r-- 1 www-data www-data 5518 Oct 20 04:27 /var/www/html/cacti/include/config.php
-rw-r--r-- 1 root root 3585 Oct 20 11:26 /etc/spine.conf

二、前置条件

本章说明阅读与动手实践本篇所需的基础环境，满足以下条件即可逐节复现：

• Cacti 1.2.31 已完成安装（Web 安装向导走完，settings 表存在 install_complete 行）；部署过程见《Cacti 1.2.31 Docker Compose 部署指南》第四章；
• 服务器可登录数据库（本篇 SQL 示例统一用 mysql -uroot -pq1w2e3r4 cacti，口令为演示环境实测值，读者按实际替换）；
• 拥有 Cacti 管理员账号 admin（演示口令 q1w2e3r4）可访问 Web 界面 Configuration → Settings；
• 安装说明：本篇不含安装主线，只覆盖参数体系；安装与向导排障在部署篇中已完整给出。

三、参数查看与修改方式

Cacti 的参数有四个查看/修改入口，各自管辖范围不同，先厘清「改哪里生效」，后续各节才能对号入座。

3.1 四个入口与生效范围

实测：Settings 界面的 10 个页签（从源码 include/global_settings.php 的页签定义实查）为：

General / Paths / Device Defaults / Poller / Data /
Visual / Authentication / Performance / Spikes / Mail/Reporting/DNS

settings 表与 Web 界面同源验证：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT COUNT(*) AS settings_rows FROM settings;"

实测输出：

settings_rows
302

3.2 用 SQL 直查与修改参数示例

以轮询方式 poller_type 为例，查看与修改（Web 界面 Poller 页签 → Poller Type 的底层同一行）：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT name,value FROM settings WHERE name='poller_type';"
mysql -uroot -pq1w2e3r4 cacti -e "UPDATE settings SET value='2' WHERE name='poller_type';"

实测输出：

name         value
poller_type  2

💡 说明：poller_type 取值 1 为 cmd.php（PHP 脚本轮询器）、2 为 Spine（C 多线程轮询器）。实测源码 include/global_arrays.php 中 $poller_options 仅这两项，且当 path_spine 无效时 Web 界面会自动隐藏 Spine 选项。Web 界面修改即时写库，SQL 直改后下一轮询周期读取，两种方式等价。

四、参数总览

本章给出 302 行 settings 参数的分组地图，便于按域定位。参数名前缀即其所属功能域，实测分组概览如下：

关键值实测（安装向导完成后的默认落库值）：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT name,value FROM settings WHERE name IN ('poller_type','poller_interval','poller_sync_interval','concurrent_processes','max_threads','php_servers','log_verbosity','log_destination','path_spine','path_php_binary','path_rrdtool','rrdtool_version','auth_method','secpass_minlen');"

实测输出：

name                    value
auth_method             1
concurrent_processes    1
log_destination         1
log_verbosity           2
max_threads             1
path_php_binary         /usr/bin/php
path_rrdtool            /usr/bin/rrdtool
path_spine              /usr/local/spine/bin/spine
php_servers             1
poller_interval         300
poller_sync_interval    7200
poller_type             2
rrdtool_version         1.7.2
secpass_minlen          8

解读：全新安装后 poller_type=2（Spine）是安装向导第 5 步探测到 Spine 后自动写入的；poller_interval=300 与向导第 7 步选择的 5 分钟配置档一致；并发三件套均为 1，是单机小规模默认值。

五、核心参数分类详解

本章按功能域逐节详解核心参数，每节含「参数含义 → 实测取值 → 修改方式与验证」。

5.1 config.php：数据库连接与站点参数

config.php 是 Cacti 的启动期配置，位于 /var/www/html/cacti/include/config.php，管辖数据库连接、站点 URL、轮询器编号三类参数。实测部署后的有效行如下：

$database_type     = 'mysql';
$database_default  = 'cacti';
$database_hostname = 'cacti-db';
$database_username = 'cacti';
$database_password = 'q1w2e3r4';
$database_port     = '3306';
$database_retries  = 5;
$database_ssl      = false;
$database_persist  = false;

$poller_id = 1;

$url_path = '/';

$cacti_session_name = 'Cacti';

逐项说明：

另有两类注释态参数值得认识（默认关闭，实测确认文件中为注释）：

• 远端轮询器回连主库参数 $rdatabase_*（$rdatabase_type/$rdatabase_default/$rdatabase_hostname/...）：仅远端采集器（Remote Data Collector）模式取消注释；
• 扩展路径与安全参数：$scripts_path、$resource_path（远端轮询器脚本路径）、$input_whitelist（数据输入白名单文件路径，默认随源码路径）、$path_csrf_secret（CSRF 密钥文件路径）、$php_path（显式 PHP 路径）、$php_snmp_support（禁用 PHP SNMP 扩展）、$proxy_headers（反向代理取真实 IP 的头）。

修改与验证：改完 config.php 后重跑轮询验证连接正常：

php /var/www/html/cacti/poller.php --force

实测输出（正常收尾行）：

OK u:0.00 s:0.00 r:0.00

5.2 轮询器设置（Poller 页签）

Poller 页签管辖轮询方式与调度并发，是最影响采集实时性的参数组。实测核心参数与取值：

💡 技术拓展：Cacti 的轮询后端不止一种，选择前先横向对比——

后端	原理	特点	适用场景
cmd.php	PHP 脚本逐设备轮询	零额外依赖；进程级并发，开销大	小规模（<100 台设备）
Spine	C 多线程轮询器	线程级并发、内存占用低、速度快数倍	中大规模生产推荐
Net-SNMP 轮询	直接调用 snmp 命令	特定脚本查询场景	少见

本篇实测环境选择 Spine（poller_type=2），理由：设备规模增长后无需改代码路径，且 Cacti 官方生产部署默认推荐 Spine。

轮询调度与 cron 的关系（易错点）：系统 cron 每 cron_interval 秒触发一次 poller.php，poller 内部按 poller_interval 判定本轮是否全量采集。两者不一致会导致采集漂移。实测环境中二者均为 300 秒，cron 条目实测：

cat /etc/cron.d/cacti

实测输出：

*/5 * * * * www-data /usr/bin/php /var/www/html/cacti/poller.php > /dev/null 2>&1

修改验证：把线程数调为 4 并确认落库（生产建议见第六章）：

mysql -uroot -pq1w2e3r4 cacti -e "UPDATE settings SET value='4' WHERE name='max_threads'; SELECT name,value FROM settings WHERE name='max_threads';"

实测输出：

name         value
max_threads  4

5.3 Spine 轮询器与 spine.conf 实配实测

Spine 的运行参数分两层：数据库连接与远端回连参数在 /etc/spine.conf（独立于 settings 表），线程/超时等运行参数在 settings 表。本节含一次完整的「Spine 静默失效 → 定位 → 修复 → 验证」实录，源码安装的用户大概率会遇到。

第一层：spine.conf。 Spine 启动时按固定顺序找配置：/etc/spine.conf → /usr/local/spine/etc/spine.conf → 当前目录 spine.conf；也可由 Cacti 的 path_spine_config 参数显式指定。源码安装的陷阱是：make install 只带 spine.conf.dist 模板，不生成生效配置，实测确认：

ls -l /usr/local/spine/etc/

实测输出（修复前）：

total 12
-rw-r--r-- 1 root root 3585 Oct 20 04:27 spine.conf.dist

此时手动运行 Spine 立即暴露问题：

cd /usr/local/spine/bin && ./spine --version && ./spine

实测输出：

SPINE 1.2.31  Copyright 2004-2024 by The Cacti Group
FATAL: Unable to read configuration file! (Spine init)

修复：从模板复制并按实际数据库写入连接参数：

cp /usr/local/spine/etc/spine.conf.dist /etc/spine.conf
sed -i -e 's/^DB_Host.*/DB_Host       cacti-db/' \
       -e 's/^DB_Database.*/DB_Database   cacti/' \
       -e 's/^DB_User.*/DB_User       cacti/' \
       -e 's/^DB_Pass.*/DB_Pass       q1w2e3r4/' /etc/spine.conf
grep -E '^DB_' /etc/spine.conf

实测输出：

DB_Host       cacti-db
DB_Database   cacti
DB_User       cacti
DB_Pass       q1w2e3r4
DB_Port       3306

spine.conf 核心参数逐项说明（模板原文注释实译）：

第二层：settings 表的 Spine 运行参数与路径。 path_spine 指向二进制（实测 /usr/local/spine/bin/spine），path_spine_config 为空时 Spine 用默认搜索路径。Cacti 启动 Spine 前会校验 path_spine 存在性（源码 poller.php 实查：文件不存在则直接报 ERROR: The spine path: ... is invalid. Poller can not continue! 并退出）。

修复后验证。 重建配置后强制轮询，实测 Spine 真正工作：

php /var/www/html/cacti/poller.php --force
grep -E 'SPINE|SYSTEM STATS' /var/www/html/cacti/log/cacti.log | tail -3

实测输出：

2026-10-20 11:30:43 - SPINE: Poller[1] PID[167] PT[128271407875904] Time: 0.5410 s, Threads: 1, Devices: 2
2026-10-20 11:30:44 - SYSTEM STATS: Time:42.2677 Method:spine Processes:1 Threads:1 Hosts:2 HostsPerProcess:2 DataSources:5 RRDsProcessed:10
2026-10-20 11:31:05 - SYSTEM STATS: Time:1.2097 Method:spine Processes:1 Threads:1 Hosts:2 HostsPerProcess:2 DataSources:5 RRDsProcessed:5

⚠️ 排障实录结论：修复前轮询日志照样每 5 分钟打印 SYSTEM STATS ... Method:spine ... DataSources:0 RRDsProcessed:0，看似正常实则 Spine 因缺配置文件 FATAL 空转；修复后出现 SPINE: Poller[1] ... Devices: 2 明细行且 RRDsProcessed 从 0 变为实际值。判据就是看有无 SPINE: Poller[N] 行与 RRDsProcessed 是否增长，不能只看 SYSTEM STATS 行存在。

5.4 采集周期与数据源配置档（Data 页签）

数据源配置档（Data Source Profile）决定每个数据模板的采集步长与 RRA 归档结构，是「采多密、存多久」的总开关。实测库内三个内置配置档：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT id,name,step,heartbeat FROM data_source_profiles;"

实测输出：

id      name                    step    heartbeat
1       5 Minute Collection     300     600
2       30 Second Collection    30      1200
3       1 Minute Collection     60      600

逐项说明：step 是采集步长（秒），heartbeat 是失效心跳（秒，超过则记 unknown）。安装向导第 7 步把默认配置档写为 5 Minute Collection（300/600），30 秒档仅建议对延迟敏感的少量端口使用——步长减半，RRD 文件与 IO 翻倍。

💡 技术拓展：RRD 归档的聚合函数（CF）决定了图表取数方式，常见四种——

CF	原理	适用
AVERAGE	步长内取均值	流量/负载等连续量，默认选择
MAX	步长内取最大值	峰值观察（带宽峰值、连接数尖峰）
MIN	步长内取最小值	谷值观察
LAST	取步长内最后一个值	瞬时量（当前连接数、队列长度）

每个配置档通过 data_source_profiles_cf 关联启用的 CF，实测三个内置配置档默认全部同时启用四种 CF（consolidation_function_id 1–4 对应 AVERAGE/MIN/MAX/LAST），图表查询时按图形模板引用的 CF 取数。

配置档与轮询参数的联动：向导第 7 步选 5 Minute 档时，同时把 cron_interval/poller_interval 写为 300（实测见 5.2），三层一致采集才稳。修改方式：Console → Configuration → Data Sources → Data Source Profiles 页面调整步长/心跳/RRA 结构，改后需对新数据源生效（已有数据源保留原结构）。

5.5 数据模板与设备模板

模板是 Cacti 「一次定义、批量复用」的核心机制：设备模板捆绑设备的数据查询与图形模板，图形模板捆绑数据模板，数据模板定义数据源与 RRD 结构。实测安装向导预装的模板规模：

mysql -uroot -pq1w2e3r4 cacti -N -e "SELECT COUNT(*) FROM host_template; SELECT COUNT(*) FROM graph_templates; SELECT COUNT(*) FROM data_template;"

实测输出：

29
208
277

设备模板实测清单（节选，共 29 个）：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT id,name FROM host_template ORDER BY id LIMIT 12;"

实测输出：

id      name
1       ACME
2       AKCP Device
3       Apache Webserver
4       APC InfraStruXure InRow CRAC
5       APC InfraStruXure PDU
6       Aruba Instant AP Cluster
7       Aruba OSCX switch 6x00
8       Aruba Wireless Controller
9       ArubaOS switch
10      BayTech PDU
11      Cacti Stats
12      Cisco Router

三张模板表的关系与关键参数（实测表结构要点）：

hash 是模板的身份指纹：导入导出模板（CLI 的 import_template.php 或 Web 界面 Import）靠 hash 去重与合并，改模板会更新 hash。模板与实例的对应关系：每台设备按设备模板 + 数据查询（host_snmp_query）实例化出 host_graph/graph_local 图形。修改方式：Console → Templates 下三个菜单（Device/Graph/Data Templates）；批量导入用 CLI（见《Cacti 1.2.31 常用 CLI 命令详解》的 import_template 节）。

模板修改验证示例：确认某设备模板捆绑的数据查询：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT ht.name, hsq.id AS query_id, sq.name AS query_name FROM host_template ht JOIN host_snmp_query hsq ON hsq.host_template_id=ht.id JOIN snmp_query sq ON sq.id=hsq.snmp_query_id WHERE ht.name='Cisco Router';"

实测输出：

name            query_id        query_name
Cisco Router    1               SNMP - Interface Statistics
Cisco Router    8               SNMP - Get Associated MAC Addresses

5.6 路径参数（Paths 页签）

路径参数决定 Cacti 调用的外部程序与文件位置，错一个字母整条链路断。实测取值：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT name,value FROM settings WHERE name LIKE 'path_%';"

实测输出：

name                            value
path_cactilog                   /var/www/html/cacti/log/cacti.log
path_php_binary                 /usr/bin/php
path_rrdtool                    /usr/bin/rrdtool
path_snmpget                    /usr/bin/snmpget
path_snmpwalk                   /usr/bin/snmpwalk
path_spine                      /usr/local/spine/bin/spine

修改验证：路径改动后立即用二进制自检。例如验证 rrdtool 可用：

/usr/bin/rrdtool --version | head -1

实测输出：

RRDtool 1.7.2  Copyright by Tobias Oetiker <tobi@oetiker.ch>

5.7 日志参数（General 页签）

日志参数控制轮询与 Web 事件的记录粒度。实测取值：

日志级别与排障联动：5.3 节的 Spine 排障中，把 log_verbosity 临时调 5 可看到 Spine 每设备明细；常规运行建议保持 2（实测该级别下每 5 分钟一条 SYSTEM STATS）。验证：

mysql -uroot -pq1w2e3r4 cacti -e "UPDATE settings SET value='5' WHERE name='log_verbosity'; SELECT value FROM settings WHERE name='log_verbosity';"
# 排障完成后记得改回 2，避免日志膨胀
mysql -uroot -pq1w2e3r4 cacti -e "UPDATE settings SET value='2' WHERE name='log_verbosity';"

实测输出（两次查询分别回显）：

value
5

value
2

5.8 性能参数（Performance/Boost）

Boost 是 Cacti 的大规模写盘缓冲：轮询结果先落 poller_output_boost 内存表，由 boost 进程批量写 RRD，减少小 IO。实测参数与默认值：

mysql -uroot -pq1w2e3r4 cacti -e "SELECT name,value FROM settings WHERE name LIKE 'boost%';"

实测输出：

name                                    value
boost_parallel                          1
boost_png_cache_directory               /var/www/html/cacti/cache/boost/
boost_png_cache_enable
boost_poller_mem_limit                  1024
boost_redirect
boost_rrd_update_enable
boost_rrd_update_interval               60
boost_rrd_update_max_records            1000000
boost_rrd_update_max_records_per_select 50000

逐项说明：

💡 说明：Boost 默认关闭（boost_rrd_update_enable 为空），单机几千数据源内不需要开；开启后 RRD 更新延迟一个写盘周期，图表展示的取数逻辑由 Cacti 自动兼容。

5.9 认证与安全（Authentication 页签）

认证参数管辖登录方式与密码策略。实测取值：

💡 技术拓展：auth_method 三种认证方式对比——

方式	原理	适用
Builtin Local	Cacti 自管账号（user_auth 表）	默认；小团队直接管理
Web Basic Authentication	由 Web 服务器先认证，Cacti 取 REMOTE_USER	已有 Apache/Nginx 统一认证
LDAP Authentication	对接 LDAP/AD 目录	企业统一身份，支持组映射模板

本篇实测环境使用 Builtin Local（auth_method=1），配套统一演示口令 q1w2e3r4；为此放宽了大小写与特殊字符两项策略，过程实录见部署篇 4.7 节。

密码策略排障实录（实测报错原文，首次改密时触发）：

Your password must contain a mix of lower case and upper case characters!

原因与处置：secpass_check_pass（源码 lib/auth.php）按 minlen → 数字 → 大小写 → 特殊字符顺序校验；演示环境按第 5.9 表放宽 secpass_reqmixcase/secpass_reqspec 后改密成功。安全提示：生产环境应保留策略并使用强密码。

六、生产配置模板

本章按规模给出三档推荐参数集，均基于第五章实测参数项。标注适用内存/磁盘/场景；改动路径为 Web 界面对应页签或 SQL（二者同源）。

6.1 小规模（≤100 台设备，≤5 千数据源）

适用：4 GB 内存 / 100 GB 磁盘 / 单机 Web+轮询。

6.2 中规模（100–1000 台设备，5 千–5 万数据源）

适用：8–16 GB 内存 / 500 GB SSD / 单机或 Web 与 DB 分离。

6.3 大规模（>1000 台设备，>5 万数据源）

适用：32 GB+ 内存 / NVMe SSD / Web、数据库、轮询分离，可加远端采集器。

⚠️ 注意：任何规模下 $url_path、poller_id、cron 与 poller_interval 三者的一致性是底线；改步长前先评估 RRD 文件尺寸翻倍带来的磁盘与 IO 影响。

七、常见问题

Q1：改了 settings 表的参数，Web 界面没变（或反之）？

两者同源（同一张 settings 表），先强刷浏览器缓存；SQL 改动立即生效但 Web 页面数据在下次请求时重新读取。若仍不一致，确认改的是同一个 name（注意大小写敏感）。

Q2：Spine 选择了但轮询统计里 DataSources 一直是 0？

按 5.3 节排障：cd /usr/local/spine/bin && ./spine 看是否 FATAL: Unable to read configuration file!——是则补 /etc/spine.conf；再看 path_spine 是否存在、日志有无 ERROR: The spine path ... is invalid。

Q3：settings 表被改坏了怎么恢复默认值？

每个参数的默认值都在源码 include/global_settings.php 中登记（'default' => ...），按名查出后 UPDATE settings SET value='<默认值>' WHERE name='<参数名>'; 恢复；极端情况可从安装包 cacti.sql 对照补行。

Q4：改了数据源配置档的步长，老图形没变化？

配置档只对新实例化的数据源生效；存量数据源保留原 RRA 结构。需要统一时用 Web 界面批量更换数据源所属配置档，Cacti 会提示 RRD 迁移风险。

Q5：config.php 改了 $url_path 后页面白屏或样式丢失？

$url_path 必须与实际访问路径与 Apache 站点根完全一致（含尾部斜杠）；改后重启 Web 服务并清浏览器缓存，向导预检也会重新校验该值。

Q6：如何确认某个参数当前真正生效？

运行期参数以 settings 表为准（SQL 直查）；启动期参数以 config.php 为准（改后重跑 poller.php --force 看连接是否正常）；Spine 参数以 /etc/spine.conf 为准（spine 启动即读，改后下轮询生效）。

八、参考链接

• Cacti 官方文档（Settings 说明）：https://docs.cacti.net/
• Cacti 1.2.31 源码（参数默认值定义 include/global_settings.php）：https://github.com/Cacti/cacti/tree/release/1.2.31
• Spine 源码与 spine.conf 模板：https://github.com/Cacti/spine
• RRDtool 文档（RRA/CF 概念）：https://oss.oetiker.ch/rrdtool/doc/
• 同专栏《Cacti 1.2.31 介绍与选型指南》
• 同专栏《Cacti 1.2.31 Docker Compose 部署指南》
• 同专栏《Cacti 1.2.31 常用 CLI 命令详解》（命令行维护模板与设备）