iTop 3.3.0 常用运维命令与排障实操

iTop 3.x 没有独立的运维控制台命令（2.x 时代的 bin/console.php 在社区包中已不存在，实测 find /var/www/html/itop -name console.php 无结果），日常运维由四条命令线支撑：后台任务 webservices/cron.php、安装/升级器 setup/unattended-install/unattended-install.php、数据库 mysqldump/mysql、以及内置备份扩展 itop-backup。本文全部命令与回显均来自 3.3.0 真实环境实测。

一、环境信息

项目	值
操作系统	Ubuntu 22.04
Web 服务器	Apache/2.4.52，监听 8130
数据库	MariaDB 10.6.23
PHP	PHP 8.2.35 (cli)
iTop	3.3.0，/var/www/html/itop，http://10.89.58.1:8130/itop/
管理员	admin（db 认证）

二、工具概览与前置条件

运维对象	命令/入口	频率
后台任务（通知/SLA/备份/回收）	php8.2 webservices/cron.php	每 5 分钟 crontab
安装/升级/扩展装载	setup/unattended-install/unattended-install.php	按需
数据库备份恢复	mysqldump / mysql	每日
定时备份（Web 管理）	itop-backup 扩展 + BackupExec 任务	配置驱动
日志	log/、data/、/var/log/apache2	巡检

前置条件：iTop 已完成安装（见《Ubuntu 22.04 安装 iTop 3.3.0 指南》）；cron 与安装器需以能读 conf、写 env-production 的用户执行；准备一个具备后台任务权限的 iTop 账号（实测直接用 admin）。

三、后台任务：webservices/cron.php

3.1 用法

不带参数执行会打印用法并退出：

$ php8.2 webservices/cron.php
ERROR: Missing argument 'auth_user'

USAGE:

php cron.php --auth_user=<login> --auth_pwd=<password> [--param_file=<file>] [--verbose=1] [--debug=1] [--status_only=1]

凭据可放参数文件（参考同目录 cron.distrib，注意该文件不可被 Web 读取）：

auth_user=admin
auth_pwd=<口令>

3.2 首次执行实测

$ cd /var/www/html/itop && php8.2 webservices/cron.php --auth_user=admin --auth_pwd=<口令> --verbose=1
Starting: 1793658498 (2026-11-02 23:28:18)
Planned duration = 600 seconds
Loop pause = 2 seconds
Creating record for: CheckStopWatchThresholds
First execution planned at: 2026-11-02 23:28:18
Creating record for: LogFileRotationProcess
First execution planned at: 2026-12-01 00:00:00
Creating record for: ExecAsyncTask
Creating record for: ObsolescenceDateUpdater
Creating record for: BulkExportResultGC
Creating record for: InlineImageGC
Creating record for: BackupExec
First execution planned at: 2026-11-02 23:30:00
Creating record for: Combodo\iTop\Service\Notification\Event\EventNotificationNewsroomGC
Creating record for: Combodo\iTop\Service\TemporaryObjects\TemporaryObjectGC
Creating record for: Combodo\iTop\SessionTracker\SessionGC
Background processes: CheckStopWatchThresholds, LogFileRotationProcess, ExecAsyncTask, ObsolescenceDateUpdater, BulkExportResultGC, InlineImageGC, BackupExec, ...
8 Tasks planned to run now (2026-11-02 23:28:18):

首次运行自动注册 10 个内置任务；注意 BackupExec 计划时刻 23:30 与配置参数 itop-backup.time='23:30' 一致（见《iTop 3.3.0 配置参数详解》）。

3.3 任务状态巡检

$ php8.2 webservices/cron.php --auth_user=admin --auth_pwd=<口令> --status_only=1
+---------------------------+---------+---------------------+---------------------+--------+-----------+
| Task Class                | Status  | Last Run            | Next Run            | Nb Run | Avg. Dur. |
+---------------------------+---------+---------------------+---------------------+--------+-----------+
| BackupExec                | active  |                     | 2026-11-02 23:30:00 |      0 |   0.000 s |
| BulkExportResultGC        | active  |                     | 2026-11-02 23:28:18 |      0 |   0.000 s |
| CheckStopWatchThresholds  | active  |                     | 2026-11-02 23:28:18 |      0 |   0.000 s |
| ExecAsyncTask             | active  |                     | 2026-11-02 23:28:18 |      0 |   0.000 s |
...

Nb Run/Avg. Dur. 是判断任务是否卡死、超时（cron_max_execution_time，默认 600 秒）的第一手指标。

3.4 crontab 部署

crontab -u www-data -l > /tmp/c 2>/dev/null
echo '*/5 * * * * /usr/bin/php8.2 /var/www/html/itop/webservices/cron.php --param_file=/etc/itop/cron.params > /dev/null 2>&1' >> /tmp/c
crontab -u www-data /tmp/c

四、升级与变更：unattended-install

4.1 帮助信息实测

$ php8.2 setup/unattended-install/unattended-install.php --help
Usage: php unattended-install.php --param-file=<path_to_response_file> [--installation_xml=<path_to_installation_xml>] [--use_itop_config]

Options:
    --param-file=<path_to_response_file>  Path to the file (XML) to use for the unattended installation. ...
    --installation_xml=<path>  Use an installation.xml file to compute the modules to install ...
    --use_itop_config          Use the iTop configuration file to get the database settings ...

Advanced options:
    --check-consistency=1      Check the data model consistency after the installation (default: 0)
    --clean=1                  In case of a first installation, cleanup the environment ...
    --install=0                Set to 0 to perform a dry-run (default: 1)

4.2 升级/装载扩展标准流程

备份（见第五节）；
新版本包解压覆盖代码目录（或扩展 zip 解压到 extensions/）；
取最近一次 log/install-<日期>.xml 作参数模板，<mode> 改 update，回填口令，需要时增补 selected 清单；
执行 php8.2 unattended-install.php --param-file=<参数文件>（自定义扩展需显式列全 selected_modules，机制详见配置篇第七章）；
chown www-data:www-data conf/production/config-itop.php 并重启 apache2；
--status_only=1 与登录页 curl 验证。

实测一次 update 全链路 exit=0，回显以 installed! 结束，编译产物与 env-production/autoload.php 注册正常。

五、备份与恢复实测

5.1 全量备份（mysqldump）

mysqldump -uroot -p --single-transaction --routines --triggers itop \
  > /root/itop-backup-$(date +%F-%H%M).sql

实测产物：

-rw-r--r-- 1 root root 1.8M Nov  2 22:28 /root/itop-backup-2026-11-02-2228.sql

文件/附件不在库内，需一并备份：

tar czf /root/itop-data-$(date +%F).tgz -C /var/www/html/itop data conf env-production

5.2 恢复验证实测

恢复演练到临时库，确认对象数一致后再落生产：

mysql -uroot -p -e "CREATE DATABASE itop_restore_test;"
mysql -uroot -p itop_restore_test < /root/itop-backup-2026-11-02-2228.sql
mysql -uroot -p itop_restore_test -e "SELECT COUNT(*) FROM contact;"   # 53，与生产一致
mysql -uroot -p -e "DROP DATABASE itop_restore_test;"

生产恢复即 mysql -uroot -p itop < <备份文件> + 解回 data/conf 目录 + 重启 apache2。

5.3 itop-backup 扩展（Web 管理备份）

社区包内置备份扩展，编译目录 env-production/itop-backup/ 含 backup.php、restore.php、check-backup.php、common.cli-execution.php 等脚本，Web 端"管理 → 备份"可视化执行 mysqldump 并轮转保留（retention_count=5）。其调度即 3.2 节的 BackupExec 任务；mysql_bindir 为空表示 mysqldump 在 PATH 中。安装器同样校验该前提，实测回显：

Info: mysqldump is present: Ok.
Trace: Info - mysqldump -V said: mysqldump  Ver 10.19 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64)

六、日志体系

6.1 文件清单实测

安装/升级过程日志在 log/（每次运行新增一组）：

$ ls /var/www/html/itop/log/
install-2026-11-02.xml          # 安装参数响应文件（可复用为 CLI 模板）
install-2026-11-03.xml          # 后续每次 update 各生成一份
setup-queries-2026-11-02_23_26.sql  # 本次执行的建表/变更 SQL
setup.log                       # 向导/安装器详细日志

运行数据在 data/：

$ ls /var/www/html/itop/data/
cache-production  datamodel-production.xml  instance.txt
precompiled_styles  setup  transactions

Web 与 PHP 错误看 Apache 日志：tail -f /var/log/apache2/error.log。

6.2 版本与健康速查

curl -s http://10.89.58.1:8130/itop/setup/wizard.php | grep -o 'iTop version [0-9.]*'
# iTop version 3.3.0
curl -s -o /dev/null -w "%{http_code}\n" http://10.89.58.1:8130/itop/pages/UI.php
# 200
systemctl status apache2 mariadb --no-pager | grep Active
mysql -uroot -p itop -e "SHOW TABLES;" | wc -l   # 255（254 表）

七、注意事项

每次运行安装器后必须复查 conf/production/config-itop.php 属主（root 重写问题，见 8.1）；
cron 以 www-data 运行可避免缓存/会话文件属主漂移；若以 root 跑过一次，注意 data/ 下新文件属主；
升级前务必 mysqldump + data 目录双备份，setup-queries-*.sql 可审计本次 schema 变更；
生产环境建议删除或加访问控制保护 /itop/setup/ 与 /itop/webservices/ 目录；
备份参数文件（cron.distrib、响应 XML）含明文口令，权限 600 并排除在 Web 根之外。

八、常见问题排障

8.1 安装/升级后整站 500

Apache 日志：

PHP Fatal error: Uncaught ConfigException: Could not read configuration file
(the file exists but cannot be read). ... config.class.inc.php:2108

原因：安装器以 root 重写配置文件（root:root 440）。解决：chown www-data:www-data /var/www/html/itop/conf/production/config-itop.php。实测该问题在 install 与每次 update 后均复现，应写入运维脚本收尾步骤。

8.2 后台任务从不执行

依次检查：crontab 是否部署（crontab -u www-data -l）；--status_only=1 中任务 Status 是否 active、Next Run 是否过期；参数文件口令是否正确（认证失败任务静默跳过）；cron_max_execution_time 是否被长任务（大批量导出）超时截断。

8.3 邮件通知不发出

默认 email_transport=PHPMail 且无发件人时通知会被丢弃。配置 SMTP 与 email_default_sender_address 后，用 --verbose=1 手动跑一次 cron，观察 ExecAsyncTask 执行计数变化。

8.4 恢复后登录报数据库错误

确认恢复用的库名与 db_name 一致、env-production/ 与 datamodel-production.xml 与备份时同版本（跨版本恢复必须先跑 update 重编译数据模型）。

九、相关文档

十、参考链接

官方后台任务文档：https://www.itophub.io/wiki/page?id=latest:admin:cron
官方备份与恢复文档：https://www.itophub.io/wiki/page?id=latest:admin:backup
升级指南：https://www.itophub.io/wiki/page?id=latest:install:upgrade
GitHub 仓库：https://github.com/Combodo/iTop