Cacti 1.2.31 常用 CLI 命令详解

目标：梳理 Cacti 1.2.31 的命令行工具体系（cli/ 目录 45 个脚本 + 根目录 poller.php），逐条给出用法、关键参数与实测回显，并完成一条「CLI 添加设备 → 建图 → 挂树 → 轮询出数 → 清理」的端到端实战；全部命令已在 Ubuntu 22.04 实测环境逐条运行（2026-10-20）。

一、环境信息

本章给出命令实测环境的版本与路径清单。Cacti CLI 与 Web 界面共享同一套数据库与文件约定，熟练 CLI 是批量运维（批量建设备、导模板、修 RRD、做巡检）的前提。

项目	取值
操作系统	Ubuntu 22.04（Linux 5.15 x86_64）
Cacti	1.2.31（官方源码包安装）
Spine 轮询器	1.2.31（轮询方式已切 Spine）
数据库	MariaDB 10.6
PHP	8.1.2（CLI 与 Web 同一二进制）
Cacti 根目录	`/var/www/html/cacti`
CLI 脚本目录	`/var/www/html/cacti/cli/`
轮询脚本	`/var/www/html/cacti/poller.php`（根目录，不在 cli/）
RRD 数据目录	`/var/www/html/cacti/rra/`

版本自报回显（任意 CLI 脚本的帮助头都会带版本指纹，实测）：

Cacti Add Device Utility, Version 1.2.31 (DB: 1.2.31), Copyright (C) 2004-2026 The Cacti Group

二、前置条件

运行 Cacti CLI 需满足以下条件，逐项核对后即可复现本篇全部命令：

已安装 Cacti 1.2.31 并完成安装向导（CLI 会校验数据库版本，未完成安装会拒绝执行）；
服务器装有 PHP CLI 与 Cacti 依赖扩展（与 Web 端同一份 php.ini 体系）；
运行身份建议与 Web 服务运行用户一致（Ubuntu 系为 www-data），避免 CLI 建出的 RRD/日志文件属主错乱导致轮询写不进，本篇命令统一用 sudo -u www-data php cli/<脚本> 形式给出；
本篇不含安装主线；部署见《Cacti 1.2.31 Docker Compose 部署指南》，参数背景见《Cacti 1.2.31 配置参数详解》。

三、CLI 体系概览

Cacti 的 CLI 脚本分三类：cli/ 目录下的管理命令、根目录的 poller.php 主轮询器、以及 install_cacti.php 等一次性脚本。实测 cli/ 目录清单（ls /var/www/html/cacti/cli/）如下，按用途归类：

类别	脚本	用途
添加类	add_device.php、add_graphs.php、add_graph_template.php、add_datasource.php、add_data_query.php、add_tree.php、add_perms.php	批量建设备/图形/树/权限
修改类	change_device.php、remove_device.php、remove_graphs.php、host_update_template.php、reorder_data_query.php	改设备属性/删除
轮询类	poller.php（根目录）、rebuild_poller_cache.php、poller_output_empty.php、poller_reindex_hosts.php、poller_replicate.php、push_out_hosts.php	轮询与缓存维护
模板/插件	import_template.php、import_package.php、plugin_manage.php	XML 模板导入、插件管理
数据库工具	audit_database.php、analyze_database.php、repair_database.php、convert_tables.php、fix_mediumint.php、install_cacti.php、upgrade_database.php	巡检/修复/升级
RRD 运维	removespikes.php、splice_rrd.php、float_rrdfiles.php、structure_rra_paths.php、batchgapfix.php、md5sum.php、remove_broken_graphs.php、repair_graphs.php、repair_templates.php	RRD 文件级维护
用户/安全	copy_user.php、input_whitelist.php、refresh_csrf.php	用户复制、白名单重建
自动化	apply_automation_rules.php、poller_data_sources_reapply_names.php、poller_graphs_reapply_names.php	应用自动化规则、重命名

本篇第四章详解高频命令，第五章用端到端实战串起来；其余命令给速查要点。

四、核心命令详解

以下每条命令的帮助文本与回显均为实测原文。约定：<cacti> 表示 Cacti 根目录 /var/www/html/cacti。

4.1 add_device.php：添加设备

添加被监控设备（对应 Web 界面 Console → Creation → Devices → Add）。实测帮助头：

usage: add_device.php --description=[description] --ip=[IP] --template=[ID] [--notes="[]"] [--disable]
    [--poller=[id]] [--site=[id] [--external-id=[S]] [--proxy] [--threads=[1]
    [--avail=[ping]] --ping_method=[icmp] --ping_port=[N/A, 1-65534] --ping_timeout=[N] --ping_retries=[2]
    [--version=[0|1|2|3]] [--community=] [--port=161] [--timeout=500]
    [--username= --password=] [--authproto=] [--privpass= --privproto=] [--context=] [--engineid=]
    [--quiet]

Required:
    --description  the name that will be displayed by Cacti in the graphs
    --ip           self explanatory (can also be a FQDN)

关键参数：

参数	默认	说明
`--description` / `--ip`	必填	设备显示名 / IP 或 FQDN
`--template`	0	设备模板 id，`--list-host-templates` 查询
`--avail`	ping	可用性检测方式：none、ping、snmp、pingsnmp、pingorsnmp
`--ping_method`	tcp	icmp/tcp/udp
`--ping_timeout` / `--ping_retries`	库设置 / 2	单次探测超时（毫秒）与重试
`--version`	1	SNMP 版本 0/1/2/3，0 为不启用 SNMP
`--community` / `--port` / `--timeout`	空 / 161 / 500	SNMPv1/v2 团体字、端口、超时
`--username/--password/--authproto/--privpass/--privproto`	—	SNMPv3 认证与加密参数
`--proxy`	—	允许同 IP 重复建设备（多实例监控用）
`--disable`	0	置 1 添加但暂停轮询

实测添加一台仅做 ping 检测的设备（先看重复 IP 的实测报错，再加 --proxy 成功）：

sudo -u www-data php cli/add_device.php --description=D1-Demo-Device --ip=127.0.0.1 \
  --avail=ping --ping_method=icmp --ping_timeout=500 --ping_retries=2 --version=0 --quiet

实测输出（IP 已存在时）：

ERROR: This IP already exists in the database (127.0.0.1) device-id: (1)

实测输出（加 --proxy 允许同 IP 后）：

Adding D1-Demo-Device (127.0.0.1) as "None" using SNMP v0 with community "public"
Success - new device-id: (3)

💡 说明：--version=0 表示不启用 SNMP，仅依赖 ping 检测；有 SNMP 的设备加 --version=2 --community=public（SNMPv2）或 v3 三件套。常用查询子命令：--list-host-templates（设备模板）、--quiet（批处理模式只回显 id）。

4.2 add_graphs.php：为设备建图

批量创建图形，支持两类：cg（图形模板直建）与 ds（数据查询索引建，即 SNMP 接口类）。实测帮助头：

usage: add_graphs.php --graph-type=[cg|ds] --graph-template-id=[ID]
    --host-id=[ID] [--graph-title=title] [graph options] [--force] [--quiet]

关键参数：

参数	说明
`--graph-type`	cg=图形模板，ds=数据查询索引
`--graph-template-id`	图形模板 id
`--host-id`	目标设备 id
`--input-fields`	cg 图的数据模板自定义字段，格式 `[data-template-id:]field-name=value`
`--snmp-query-id/--snmp-query-type-id/--snmp-field/--snmp-value`	ds 图的四件套：数据查询 id、查询类型 id、过滤字段、字段值
`--reindex-method`	ds 图重建索引方式：0=None、1=Uptime（默认）、2=Index Count Changed、3=Verify all Fields

list 系列子命令（查询前提，实测）：

sudo -u www-data php cli/add_graphs.php --list-graph-templates | grep -iE 'ping'

实测输出：

88      Unix - Ping Latency
320     PING - Advanced Ping

sudo -u www-data php cli/add_graphs.php --list-input-fields --graph-template-id=88

实测输出：

Known Input Fields: (name, default, description)
95:ip           IP Address

实测为设备 3 建一张 Ping 延迟 cg 图（95:ip=127.0.0.1 即「数据模板 95 的 ip 字段填 127.0.0.1」）：

sudo -u www-data php cli/add_graphs.php --host-id=3 --graph-type=cg \
  --graph-template-id=88 --input-fields="95:ip=127.0.0.1" --quiet

实测输出：

Graph Added - Graph[5] - DS[6]

💡 说明：ds 型（数据查询）建图示例：--graph-type=ds --snmp-query-id=1 --snmp-query-type-id=3 --snmp-field=ifOperStatus --snmp-value=Up，可对接口流量批量出图；--snmp-value-regex 支持正则过滤。

4.3 add_tree.php：图形树管理

把设备/图形挂到树（Web 界面的 Graph 树）上。实测帮助头：

usage: add_tree.php  --type=[tree|node] [type-options] [--quiet]

Tree options:
    --name=[Tree Name]
    --sort-method=[manual|alpha|natural|numeric]

Node options:
    --node-type=[header|site|host|graph]
    --tree-id=[ID]
    [--parent-node=[ID] [Node Type Options]]

节点类型四种：header（标题节点）、site（站点节点）、host（设备节点，--host-group-style 1=按图形模板分组、2=按数据查询索引分组）、graph（单图节点）。实测建树并挂设备：

sudo -u www-data php cli/add_tree.php --type=tree --name=D1-CLI-Tree --sort-method=manual --quiet

实测输出：

Tree Created - tree-id: (2)

sudo -u www-data php cli/add_tree.php --type=node --node-type=host --tree-id=1 --host-id=3 --quiet

实测输出：

Added Node node-id: (5)

💡 说明：--list-trees/--list-nodes --tree-id=N/--list-hosts 系列先查后挂；父节点用 --parent-node 指定，实现多级目录。

4.4 add_data_query.php：为设备绑定数据查询

ds 型建图的前提是设备已关联 SNMP 数据查询（Web 界面设备编辑页的 Associated Data Queries）。实测帮助头：

usage: add_data_query.php --host-id=[ID] --data-query-id=[dq_id] --reindex-method=[method] [--quiet]

Required Options:
    --host-id         the numerical ID of the host
    --data-query-id   the numerical ID of the data_query to be added
    --reindex-method  the reindex method to be used for that data query
                      0|None   = no reindexing

实测查询清单（安装向导预装模板自带的数据查询）：

sudo -u www-data php cli/add_data_query.php --list-data-queries

实测输出（节选）：

Known SNMP Queries: (id, name)
1       Acme SD Voltage
2       Acme SD Combined Session Stats
3       Acme SD Realm Session info
4       Acme SD Temperature
5       AKCP - Temperature
6       AKCP - Humidity
7       AKCP - Airflow
8       AKCP - 4-20 mAmp
9       APC - InRow - Group Statistics

实测绑定（reindex 方式 2=索引数变化时重建）：

sudo -u www-data php cli/add_data_query.php --host-id=2 --data-query-id=1 --reindex-method=2 --quiet

实测输出：

Success - Host (2: localhost) data query (1: Acme SD Voltage) reindex method (2: Index Count)

💡 说明：绑定后还需 add_graphs.php 以 ds 型按查询索引建图；顺序固定为「绑查询 → 查索引（--list-snmp-values）→ 建图」。--list-snmp-fields/--list-snmp-values --host-id=N --snmp-query-id=N 先查设备上该查询可用的字段与索引值。

4.5 add_perms.php：图形树/设备权限授予

把树、设备、图形的访问权批量授予用户或用户组（配合 Builtin 认证的多租户场景）。实测帮助头：

usage: add_perms.php [ --user-id=[ID] ]
    --item-type=[graph|tree|host|graph_template]
    --item-id [--quiet]

Where item-id is the id of the object of type item-type

List Options:
    --list-users
    --list-trees
    --list-graph-templates
    --list-graphs --host-id=[ID]

💡 说明：--item-type 四类取值对应不同权限表（graph/tree/host/graph_template，落库 user_auth_perms 表）；--user-id 与组授权（用户组管理界面）二选一使用。实测授予 guest 用户默认树的访问权并核验落库：

sudo -u www-data php cli/add_perms.php --item-type=tree --item-id=1 --user-id=3 --quiet

实测输出（成功静默，无回显；核验落库）：

mysql -uroot -pq1w2e3r4 cacti \
  -e "SELECT u.username,p.item_id FROM user_auth_perms p JOIN user_auth u ON u.id=p.user_id WHERE p.user_id=3 AND p.item_id=1;"

实测输出：

username      item_id
guest         1

⚠️ 排障实录：该命令成功时不打印任何回显，新手常误以为失败；用上面的 SQL（或 Web 界面 User Management → Permissions）核验即可。回收权限用 Web 界面或删除 user_auth_perms 对应行（实测验证后已回滚本例授权）。

4.6 change_device.php / remove_device.php：改属性与删除

change_device.php 实测帮助头（注意：参数名是 --id，不是 --host-id）：

usage: change_device.php --id=<device-id> [--description=[description]] [--ip=[IP]] [--template=[ID]]
    [--notes="[]"] [--disable] [--poller=[id]] [--site=[id] [--external-id=[S]] [--proxy] [--threads=[1]
    [--avail=[ping]] --ping_method=[icmp] --ping_port=[N/A, 1-65534] --ping_timeout=[N] --ping_retries=[2]
    [--version=[0|1|2|3]] [--community=] [--port=161] [--timeout=500] [--quiet]

Required:
    --id           the id for a device, that is field id in table host
                   any optional device attribute parameter given, will replace the existing parameter

实测参数名陷阱（用错参数名时的真实回显）：

ERROR: Invalid Argument: (--host-id)

⚠️ 排障实录：add_device/add_graphs 系列用 --host-id，change_device.php 用 --id，脚本间参数名不统一是 CLI 高频踩坑点。实测改探测方式立即生效（无需重启轮询）：
sudo -u www-data php cli/change_device.php --id=3 --ping_method=tcp --ping_port=80 --quiet
实测输出（成功时静默，仅批处理模式说明尾行）：
    --quiet - batch mode value return

remove_device.php 实测帮助头：

usage: remove_device.php --description='S' | --ip='S' | --id=N,N,N,...
    [--confirm] [--quiet]

Required: (on or more)
    --description='S' A substring or regular expression of the hostname or description.
    --ip='S'          A IP or hostname (can also be a FQDN).
    --id=N,N,...      A column delimited list of device ids.

Optional:
    --confirm           confirms that you wish to remove matches

⚠️ 排障实录：不带 --confirm 只预览匹配结果不删除（防误删设计）；批量删除用逗号分隔 id。实测删除设备 3：
sudo -u www-data php cli/remove_device.php --id=3 --confirm --quiet
实测输出：
Removing devices with ids: 3
Success - removed device-ids: 3
删除设备会级联删除其图形与数据源，但 RRD 文件保留在 rra/ 目录，确认不再需要后手工清理（配合 4.12 的 md5sum/float_rrdfiles 巡检）。

4.7 poller.php：主轮询器（根目录）

主轮询器在 Cacti 根目录而非 cli/，这是 CLI 新手第一个坑。实测帮助头：

Cacti Main Poller, Version 1.2.31, Copyright (C) 2020-2026 The Cacti Group

usage: poller.php [--poller=ID] [--force] [--debug]

Optional:
    --poller=ID    Run as the poller indicated and not the default poller.
    --force        Override poller overrun detection and force a poller run.
    --debug|-d     Output debug information.  Similar to cacti's DEBUG logging level.

⚠️ 排障实录：php cli/poller.php 会报 Could not open input file: cli/poller.php。正确路径与实测运行：
cd /var/www/html/cacti && sudo -u www-data php poller.php --force
实测输出（收尾两行）：
OK u:0.00 s:0.00 r:0.00
2026-10-20 11:40:10 - SYSTEM STATS: Time:1.2116 Method:spine Processes:1 Threads:1 Hosts:3 HostsPerProcess:3 DataSources:6 RRDsProcessed:6
--force 的用途：cron 周期内重复触发或上一轮未结束时强制再跑一轮；常规排障（改完配置想立刻见数据）就是 poller.php --force。Method:spine 说明轮询方式为 Spine，RRDsProcessed 是本轮真实写盘的 RRD 数量。

4.8 rebuild_poller_cache.php：重建轮询缓存

轮询缓存（poller_item 表）是「设备/数据源 → 采集命令」的映射，图形或数据源结构性变更后若轮询结果异常，重建缓存是标准动作。实测帮助头：

Cacti Rebuild poller cache Tool, Version 1.2.31 Copyright (C) 2004-2026 The Cacti Group

usage: rebuild_poller_cache.php [--host-id=N] [--host-template-id=N] [--data-template-id=N] [--debug]

Optional:
 --threads=N           - The number of threads to use to repopulate, default = 5
 --host-id=N           - Run for a specific Device

实测全量重建：

sudo -u www-data php cli/rebuild_poller_cache.php

实测输出：

WARNING: Do not interrupt this script.  Rebuilding Poller Cache can take quite some time
There are 2 hosts, 1 threads and 2 hosts to process per thread

💡 说明：--paths 连数据源路径一起重建（迁移/改结构化路径规则后用）；按范围重建可加 --host-id=N --graph-template-id=N --data-template-id=N --data-query-id=N。静默结束无报错即完成。

4.9 轮询维护三兄弟（速查）

命令	用途	关键用法（实测帮助）
poller_output_empty.php	清空 poller_output 中转表（Boost 模式下卡单时用）	`usage: poller_output_empty.php`（无参数，直接执行）
poller_reindex_hosts.php	触发设备数据查询重建索引	`usage: poller_reindex_hosts.php --id=[host_id\|all] [--qid=[ID\|all]] [--host-descr=[description]] [--force] [--debug]`
poller_replicate.php	主站点向远端采集器全量同步（data/auth/settings 三类数据域可选）	`usage: poller_replicate.php [--poller=N] [--class=all\|data\|auth\|settings]`

实测清空中转表与全量重建索引：

sudo -u www-data php cli/poller_output_empty.php

实测输出：

There were 0 RRD updates made this pass

sudo -u www-data php cli/poller_reindex_hosts.php --id=all

实测输出（进度点逐设备滚动）：

WARNING: Do not interrupt this script.  Reindexing can take quite some time
.

💡 说明：poller_output_empty 的回显数字是本轮实际写盘的 RRD 更新数，0 表示中转表本来就空；reindex 的 --qid=N 可只重建某个数据查询的索引。

4.10 模板与插件（速查）

命令	用途	关键用法（实测帮助）
import_template.php	导入 XML 模板（设备/图形/数据模板）	`usage: import_template.php --filename=[filename] [--with-profile \| --profile-id=N] [--remove-orphans] [--replace-svalues]`
import_package.php	导入打包模板包（含资源文件）	`usage: import_package.php --filename=[filename] [--info] [--remove-orphans] [--replace-svalues] [--with-profile] [--profile-id=N]`
plugin_manage.php	插件安装/卸载/启停	`usage: plugin_manage.php [--plugin=S] [--install --enable --allperms] [--uninstall] [--disable]`，`--plugin` 可重复

实测模板导入（文件不存在时的真实报错）：

sudo -u www-data php cli/import_template.php --filename=/tmp/nonexistent.xml

实测输出：

ERROR: file /tmp/nonexistent.xml is not readable, or does not exist

实测插件管理（无插件时的真实回显）：

sudo -u www-data php cli/plugin_manage.php

实测输出：

NOTE: 0 Plugins to be acted on.

💡 说明：导入模板的正道是先 import_package.php --info（或界面导入预览）看 diff——Cacti 按 hash 判断新增/覆盖，确认后再实导；--remove-orphans 在模板升级时清理旧版残留元素，--replace-svalues 替换数据查询建议值规则。

4.11 数据库巡检与修复三件套（速查）

命令	用途	关键用法（实测帮助）
audit_database.php	全库结构审计（对照官方 schema 报缺失/多余字段，升级前后跑一次）	`usage: audit_database.php --report \| --repair [ --upgrade ]`
analyze_database.php	对全库执行 ANALYZE 更新统计信息（轮询变慢的常规保养）	`usage: analyze_database.php [-d\|--debug]`
repair_database.php	修复损坏表	`usage: repair_database.php [--dynamic] [--debug] [--force] [--form]`

实测审计报告（逐表 Clean）：

sudo -u www-data php cli/audit_database.php --report

实测输出（收尾节选）：

---------------------------------------------------------------------------------------------
Checking Table: 'vdef_items'                                  - Clean
---------------------------------------------------------------------------------------------
Checking Table: 'version'                                     - Clean
---------------------------------------------------------------------------------------------
ERRORS are fixable using the --repair option.  WARNINGS will not be repaired
due to ambiguous use of the column.
---------------------------------------------------------------------------------------------

实测全库分析：

sudo -u www-data php cli/analyze_database.php

实测输出（节选）：

NOTE: Analyzing Table -> 'vdef' Successful
NOTE: Analyzing Table -> 'vdef_items' Successful
NOTE: Analyzing Table -> 'version' Successful

💡 说明：audit 的输出按 ERROR/WARN 分级，ERROR 可用 --repair 自动修复、WARN 因语义歧义不自动修；analyze 建议加入巡检 crontab（如每周一次）。

4.12 RRD 文件级运维（速查）

命令	用途	关键用法（实测帮助）
removespikes.php	去除 RRD 中的异常毛刺（误报大值）	`usage: removespikes.php -R\|--rrdfile=rrdfile [-M\|--method=stddev] [-A\|--avgnan] [-S\|--stddev=N]`
splice_rrd.php	合并两个 RRD（设备迁移/文件修复）	`usage: splice_rrd.php --oldrrd=file --newrrd=file [--finrrd=file]`
float_rrdfiles.php	RRD 浮点数据时间范围处理	`usage: float_rrdfiles.php --start=TS --end=TS [--threads=N --host-id=N --host-template-id=N --graph-template-id=N] [--debug]`
structure_rra_paths.php	按结构化路径规则重排 RRD 路径（迁移后）	`usage: structure_rra_paths.php [--host-id=N] [--host-template-id=N] [--proceed]`（不带 `--proceed` 即 dryrun）
batchgapfix.php	按时间范围批量修复图形空档	`usage: batchgapfix.php --start='YYYY-MM-DD HH:MM:SS' --end='YYYY-MM-DD HH:MM:SS' [--threads=N] [--method=fill\|float] [--avgnan=last\|avg] [--host-ids=N,N,N,...] [-f\|--force] [-d\|--debug]`
md5sum.php	计算脚本/文件校验和（排查多机脚本不一致）	`usage: md5sum.php [option] [filename]`

💡 说明：RRD 运维类命令执行前先备份 rra/ 目录；structure_rra_paths.php 不加 --proceed 只预演不落盘；batchgapfix 默认不写数据，--force 才实际填充。

4.13 用户与安全（速查）

命令	用途	关键用法（实测帮助）
copy_user.php	复制用户（权限随模板用户带过去）	`usage: copy_user.php <template user> <new user>`（两个位置参数，非 --option 风格）
input_whitelist.php	数据输入白名单审计/更新（改脚本后必须更新，否则轮询被拒）	`usage: input_whitelist.php [--audit \| --update [--id=N] [--push]]`
refresh_csrf.php	刷新 CSRF 密钥（登录态大面积失效时）	`usage: refresh_csrf.php`（无参数）
upgrade_database.php	版本升级后的库结构迁移	`usage: upgrade_database.php [--debug] [--forcever=VERSION]`

实测白名单审计与 CSRF 密钥刷新：

sudo -u www-data php cli/input_whitelist.php --audit

实测输出：

NOTICE: Data Input Whitelist file not defined in config.php.

sudo -u www-data php cli/refresh_csrf.php

实测输出：

NOTE: Removing old csrf_secret.php file.
NOTE: New csrf_secret.php file written.

💡 说明：白名单文件路径未在 config.php 配置时（$input_whitelist 注释态）audit 给出上面的 NOTICE，属正常——需要白名单强校验时取消 config.php 中 $input_whitelist 注释并跑 --update 生成文件。refresh_csrf 刷新后所有在线用户需重新登录。

五、典型场景组合：CLI 从零建设备到出数（端到端实录）

本章用第四章命令串出最常用的实战链路，全部输出为本篇实测原文。场景：新增一台只做 ping 检测的设备，建图、挂树、立即出数。

cd /var/www/html/cacti

# 1) 添加设备（同 IP 已有设备时加 --proxy）
sudo -u www-data php cli/add_device.php --description=D1-Demo-Device --ip=127.0.0.1 \
  --proxy --avail=ping --ping_method=icmp --ping_timeout=500 --ping_retries=2 --version=0 --quiet
# Success - new device-id: (3)

# 2) 查图形模板与输入字段
sudo -u www-data php cli/add_graphs.php --list-graph-templates | grep -i ping
# 88      Unix - Ping Latency
# 320     PING - Advanced Ping
sudo -u www-data php cli/add_graphs.php --list-input-fields --graph-template-id=88
# Known Input Fields: (name, default, description)
# 95:ip           IP Address

# 3) 建图
sudo -u www-data php cli/add_graphs.php --host-id=3 --graph-type=cg \
  --graph-template-id=88 --input-fields="95:ip=127.0.0.1" --quiet
# Graph Added - Graph[5] - DS[6]

# 4) 建树挂节点
sudo -u www-data php cli/add_tree.php --type=tree --name=D1-CLI-Tree --sort-method=manual --quiet
# Tree Created - tree-id: (2)
sudo -u www-data php cli/add_tree.php --type=node --node-type=host --tree-id=1 --host-id=3 --quiet
# Added Node node-id: (5)

# 5) 立即轮询一次并验证 RRD 落数
sudo -u www-data php poller.php --force
# OK u:0.00 s:0.00 r:0.00
# 2026-10-20 11:40:10 - SYSTEM STATS: Time:1.2116 Method:spine Processes:1 Threads:1 Hosts:3 HostsPerProcess:3 DataSources:6 RRDsProcessed:6

rrdtool lastupdate /var/www/html/cacti/rra/d1-demo-device_ping_6.rrd
#  ping
# 1792467609: U

关于第 5 步的 U：该数据源走 perl scripts/ping.pl（数据输入「Unix - Ping Host」的实测命令串 perl <path_cacti>/scripts/ping.pl <ip>），ping.pl 依赖系统 ping 二进制的原始套接字权限；在无法赋予 ping 能力的受限运行环境（如被裁剪的隔离环境）会静默回 U，标准 Ubuntu 服务器上 ping 自带 cap_net_raw 能力、同命令可正常出数。验证 RRD 写链路本身是否正常，可看无需特权的本机负载数据源（实测）：

rrdtool lastupdate /var/www/html/cacti/rra/local_linux_machine_load_1min_2.rrd

实测输出：

 load_1min load_5min load_15min

1792467660: 5.66 5.89 4.87

时间戳滚动更新、数值落盘，证明「建图 → 轮询 → RRD 写入」整条链路工作正常。

实战收尾清理（删除设备级联删图形与数据源；RRD 手工清理）：

sudo -u www-data php cli/remove_device.php --id=3 --confirm --quiet
# Removing devices with ids: 3
# Success - removed device-ids: 3
rm -f /var/www/html/cacti/rra/d1-demo-device_ping_6.rrd

💡 说明：SNMP 设备的完整链路只是把第 1 步换成 --version=2 --community=public --template=<设备模板>，第 3 步换成 ds 型建图（先 add_data_query.php 绑查询再按索引出图），其余步骤完全一致。

六、常见问题

Q1：CLI 报「Could not open input file: cli/poller.php」？

主轮询器在根目录：php poller.php，cli/ 目录没有这个脚本（实测确认）。add_* 管理命令才在 cli/ 下。

Q2：add_device 报「ERROR: This IP already exists in the database」？

Cacti 默认同 IP 唯一。确需同 IP 多实例（如一台服务器多个端口组）加 --proxy 参数；否则改用真实 IP。

Q3：change_device 报「ERROR: Invalid Argument: (--host-id)」？

该脚本参数名是 --id（实测踩坑实录见 4.6）；同类脚本参数命名不完全统一，动手前先 --help 看一眼。

Q4：CLI 建的图形在 Web 界面看不到 / 用户看不到？

三查：图形树是否挂了节点（add_tree.php）；非 admin 用户是否有权限（add_perms.php）；页面右上角是否切对了时间范围。另外 CLI 建图后可跑 rebuild_poller_cache.php 确保轮询映射最新。

Q5：改了数据采集脚本后轮询报输入校验失败？

Cacti 的数据输入白名单锁定了脚本指纹，改脚本必须重建白名单：php cli/input_whitelist.php（重建）或 --add 增量添加，再用 --verify 核验。

Q6：轮询日志正常但图表长期断档/空？

先 poller.php --force 人工触发一轮看 SYSTEM STATS 的 RRDsProcessed 是否大于 0；大于 0 仍空图多为 RRD 时间空档，跑 batchgapfix.php；属主错乱跑 float_rrdfiles.php；结构性缓存陈旧跑 rebuild_poller_cache.php。

七、参考链接

Cacti 官方文档（CLI Utilities）：https://docs.cacti.net/
Cacti 1.2.31 源码（cli/ 目录）：https://github.com/Cacti/cacti/tree/release/1.2.31/cli
Spine 源码：https://github.com/Cacti/spine
同专栏《Cacti 1.2.31 介绍与选型指南》
同专栏《Cacti 1.2.31 Docker Compose 部署指南》
同专栏《Cacti 1.2.31 配置参数详解》