iTop 3.3.0 配置参数详解

iTop 的全部运行期配置集中在一个 PHP 数组文件 conf/production/config-itop.php 中，由安装向导/无人值守安装器生成；扩展与数据模型变更则通过"重新编译"落入 env-production/。本文基于 iTop 3.3.0 实测，逐类详解核心参数、修改方法（手工编辑与向导两条路径）与扩展声明机制，并附生产配置模板。

一、环境信息

二、前置条件

• 已按《Ubuntu 22.04 安装 iTop 3.3.0 指南》完成安装并可正常登录；
• 具备服务器 root 与 iTop admin 账号；
• 理解配置文件属主：Web 进程（www-data）必须可读，文件默认权限 440。

三、参数查看与修改

3.1 文件位置与权限

安装器生成的配置文件默认只读：

-r--r----- 1 www-data www-data 11751 Nov  2 22:26 config-itop.php

手工修改需临时放开写权限，改完恢复只读（实测流程）：

chmod 644 /var/www/html/itop/conf/production/config-itop.php
# ...编辑...
chmod 440 /var/www/html/itop/conf/production/config-itop.php

3.2 手工修改实测（时区）

安装后默认 'timezone' => 'Europe/Paris'。实测将其改为上海时区并验证：

sed -i "s/'timezone' => 'Europe\/Paris'/'timezone' => 'Asia\/Shanghai'/" \
  /var/www/html/itop/conf/production/config-itop.php
curl -s -o /dev/null -w "%{http_code}\n" http://10.89.58.1:8130/itop/pages/UI.php
# 200

改后第 241 行：'timezone' => 'Asia/Shanghai',，站点正常，工单/日志时间按新时区显示。绝大多数参数（语言、时区、日志开关、显示条数等）手工编辑后立即生效，无需重启 Apache。

3.3 向导与响应文件

两类参数不能只改配置文件：

1. 影响数据模型/模块集合的参数（安装扩展、改 URL、换数据库账号）：必须重跑 Setup 向导（/itop/setup/wizard.php，选"更新"模式）或无人值守安装器，向导会重新编译 env-production/ 并回写 config-itop.php；
2. 向导每次运行都会把本次全部选择落盘为响应文件 log/install-<日期>.xml（口令脱敏为 **removed**），它既是审计记录，也是 CLI 重装的参数模板。

实测：执行过一次 update 模式重编译后，手工改过的 timezone 参数被保留（安装器合并既有配置，不整体覆盖），但文件属主会被重置为 root，需再次 chown www-data:www-data（见 8.2）。

四、参数总览

config-itop.php 是一个 $aConfig = array(...) 大数组，实测包含约 60 个全局参数与按模块分组的扩展参数数组（authent-cas、authent-ldap、itop-attachments、itop-backup 等），文件末尾 $MyModules = array(); 列出加载的模块。全局参数按职责分为八类，详见下文。

五、核心参数分类详解

5.1 数据库与 URL

5.2 语言、时区与格式

5.3 安全与认证

模块级认证数组：authent-cas（cas_host/cas_port/cas_version 等）、authent-ldap（uri、base_dn、user_query、start_tls、servers 多服务器列表）在安装后为占位默认值，启用对应认证模式时按注释填写即可，无需改代码。

5.4 日志与调试

5.5 邮件

5.6 性能与缓存

5.7 UI 与交互

5.8 备份扩展参数（itop-backup）

实测生成的模块级数组：

'itop-backup' => array (
    'mysql_bindir' => '',            // mysqldump 不在 PATH 时指定
    'week_days' => 'monday, tuesday, wednesday, thursday, friday',
    'time' => '23:30',               // 每日备份时刻（cron 时区）
    'retention_count' => 5,          // 保留份数
    'enabled' => true,
    'itop_backup_incident' => '',    // 备份失败时通知的 CI
),

该配置由后台任务 BackupExec 消费，实测任务计划时刻与 time=23:30 一致（见运维篇 cron 实测）。

六、生产配置模板

在默认配置基础上，生产环境建议显式调整（实测可用）：

'timezone' => 'Asia/Shanghai',
'default_language' => 'ZH CN',
'csv_file_default_charset' => 'UTF-8',
'app_root_url' => 'https://itop.example.com/itop/',   // 改后必须重跑向导
'behind_reverse_proxy' => true,
'secure_connection_required' => true,
'email_transport' => 'SMTP',
'email_default_sender_address' => 'itop@example.com',
'email_default_sender_label' => 'iTop 服务台',
'php_path' => '/usr/bin/php8.2',
'log_issue' => true,
'cron_max_execution_time' => 600,

修改流程：备份 config-itop.php → chmod 644 → 编辑 → chmod 440 → 属主确认 www-data → 涉及 URL/模块的改动重跑向导 → curl 验证 200。

七、扩展机制实测

iTop 的定制以扩展为载体。实测从零构建并安装一个最小扩展 combodo-test-ext，完整走通"声明 → 编译 → 注册"链路。

7.1 扩展声明文件

扩展放入 /var/www/html/itop/extensions/combodo-test-ext/，extension.xml 必须使用 store 格式（实测旧式 <extension_root> 根节点会被安装器静默忽略）：

<?xml version="1.0" encoding="UTF-8"?>
<extension format="1.0">
  <extension_code>combodo-test-ext</extension_code>
  <version>1.0.0</version>
  <label><![CDATA[Test Extension]]></label>
  <description><![CDATA[Minimal test extension]]></description>
  <mandatory>false</mandatory>
  <more_info_url></more_info_url>
</extension>

7.2 模块声明文件

仅有 extension.xml 不够——模块发现要求目录内存在 module.<code>.php（源码 setup/modulediscovery.class.inc.php 以正则 ^module\.(.*).php$ 识别）。实测缺失该文件时安装器回显 installed! 但什么都不装。补齐后：

<?php
SetupWebPage::AddModule(
    __FILE__,
    "combodo-test-ext/1.0.0",
    [
        "label" => "Test Extension",
        "category" => "customizations",
        "dependencies" => [],
        "mandatory" => false,
        "visible" => true,
        "datamodel" => [],
        "dictionary" => [],
        "data.struct" => [],     // 缺失时报 exit 255：
        "data.sample" => [],     // Error: Module 'combodo-test-ext/1.0.0': missing argument 'data.struct'
        "doc.manual_setup" => "",
        "doc.more_information" => "",
    ]
);

实测键不全时报错并中止：

Error: Module 'combodo-test-ext/1.0.0': missing argument 'data.struct'
Encountered stopper issues. Aborting...

7.3 CLI 装载扩展

--installation_xml 模式下扩展清单只认 installation.xml 已知模块，自定义扩展会被忽略。实测可行做法：参数文件 <mode> 改为 update，把全部模块（含新扩展，共 58 项）显式写入 selected_modules，不带 --installation_xml 执行：

cd /var/www/html/itop/setup/unattended-install
php8.2 unattended-install.php --param-file=/root/itop-update2.xml
# ...
installed!
Restart the webserver in order to get the updated data model

7.4 编译产物验证

安装后扩展被拷贝进编译目录并注册到自动加载：

/var/www/html/itop/env-production/combodo-test-ext/
├── datamodel.combodo-test-ext.xml
├── extension.xml
└── module.combodo-test-ext.php

# env-production/autoload.php 第 183 行起：
'combodo-test-ext' =>
    'root_dir' => $sCurrEnv.'/combodo-test-ext',

随后 chown www-data:www-data conf/production/config-itop.php 并重启 Apache，站点 HTTP 200 正常。

八、常见问题

8.1 改参数不生效

先确认改的是 conf/production/ 下生产环境配置（多环境实例各有 conf/<env>/）；涉及数据模型的参数（URL、模块集合）必须重跑向导编译后才生效。

8.2 重跑安装/更新后站点 500

安装器以 root 重写 config-itop.php（root:root 440），www-data 不可读即抛 ConfigException: Could not read configuration file。固定动作：每次安装器运行后执行 chown www-data:www-data /var/www/html/itop/conf/production/config-itop.php。

8.3 扩展装了没反应

按序检查：extension.xml 是否为 <extension format="1.0"> 根节点；目录内是否有 module.<code>.php 且 AddModule 键完整；参数文件 selected_modules 是否包含该模块；env-production/<code>/ 是否生成。

九、相关文档

• 《iTop 3.3.0 介绍与选型指南》
• 《Ubuntu 22.04 安装 iTop 3.3.0 指南》
• 《iTop 3.3.0 常用运维命令与排障实操》

十、参考链接

• 官方配置参数文档：https://www.itophub.io/wiki/page?id=latest:customize:config_parameters
• 扩展开发指南：https://www.itophub.io/wiki/page?id=latest:customize:index
• 数据模型编译说明：https://www.itophub.io/wiki/page?id=latest:dev:index