Ubuntu 22.04 安装 iTop 3.3.0 指南

本文在 Ubuntu 22.04 服务器上完整实测 iTop 3.3.0 社区版的两种安装方式：Web 安装向导与 CLI 无人值守安装器，覆盖依赖准备（含 PHP 8.1 → 8.2 升级排障）、下载校验、目录与权限规划、安装验证与卸载清理。全部命令与回显均为真实执行结果。

一、环境信息

项目	值
操作系统	Ubuntu 22.04（Linux x86_64）
Web 服务器	Apache/2.4.52 (Ubuntu)，本实验监听 8130 端口
数据库	MariaDB 10.6.23（mysql Ver 15.1 Distrib 10.6.23-MariaDB）
PHP	PHP 8.2.35 (cli) (built: Oct 21 2026 14:29:22) (NTS)
图形依赖	graphviz 2.43.0（/usr/bin/dot）
iTop 版本	3.3.0 社区版（build 21411）
安装路径	/var/www/html/itop
访问地址	http://10.89.58.1:8130/itop/

二、前置条件

2.1 安装基础依赖

apt update
apt install -y apache2 mariadb-server graphviz unzip acl

实测版本回显：

Server version: Apache/2.4.52 (Ubuntu)
mysql  Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using  EditLine wrapper
dot - graphviz version 2.43.0 (0)

2.2 PHP 8.2（关键，含排障）

iTop 3.3 硬性要求 PHP ≥ 8.2，而 Ubuntu 22.04 官方源只提供 PHP 8.1。实测直接用 PHP 8.1 打开安装向导返回 HTTP 500，Apache 错误日志显示 Composer 平台检查失败：Composer detected issues in your platform: ... PHP version >= 8.2.0。通过 PPA 升级到 8.2：

apt install -y software-properties-common
add-apt-repository -y ppa:ondrej/php
apt update
apt install -y php8.2 libapache2-mod-php8.2 php8.2-mysql php8.2-gd \
  php8.2-intl php8.2-xml php8.2-mbstring php8.2-curl php8.2-zip \
  php8.2-soap php8.2-apcu php8.2-imap php8.2-ldap
a2dismod php8.1 && a2enmod php8.2
systemctl restart apache2

升级后实测：

PHP 8.2.35 (cli) (built: Oct 21 2026 14:29:22) (NTS)
php8.2 -m | grep -E 'apcu|curl|gd|intl|ldap|mbstring|mysqlnd|soap|xml|zip'
apcu curl gd intl ldap mbstring mysqlnd soap xml zip

2.3 数据库准备

mysql_secure_installation   # 为 root 设置口令
mysql -uroot -p -e "CREATE DATABASE itop CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;"

2.4 Apache 端口

本实验 80 端口已被其他服务占用，在 /etc/apache2/ports.conf 追加 Listen 8130 后 systemctl restart apache2。生产环境通常使用 80/443。

三、版本选型

联网查询于 2026-11-03：3.3.0 为官方主推最新稳定版（2026-09-15 发布）；3.2.3-3 为 3.2 旧分支补丁版（2026-10-16），仅建议无法升级 PHP 8.2 的存量环境过渡使用。社区版下载（SourceForge 与 GitHub Release 双通道，内容一致）：

文件：iTop-3.3.0-21411.zip
大小：37342217 字节（约 35.6 MiB）
MD5： b299a65d757961965da8b2deefc2a893
地址：https://sourceforge.net/projects/itop/files/itop/3.3.0/

wget -O iTop-3.3.0-21411.zip \
  "https://sourceforge.net/projects/itop/files/itop/3.3.0/iTop-3.3.0-21411.zip/download"
md5sum iTop-3.3.0-21411.zip   # 应与上方 MD5 一致

四、方案 A：Web 安装向导

4.1 部署代码与权限

官方 Quick install（Ubuntu）步骤实测如下：

unzip iTop-3.3.0-21411.zip -d /opt/itop-pkg
mv /opt/itop-pkg/web /var/www/html/itop
cd /var/www/html/itop
setfacl -R -m u:www-data:rwX -m u:$(whoami):rwX data
setfacl -R -d -m u:www-data:rwX -m u:$(whoami):rwX data
mkdir -p env-production conf/production
chown -R www-data:www-data env-production conf

发行包内代码位于 web/ 子目录，将其直接作为 iTop 根目录（URL 前缀 /itop/）即可，无需保留外层目录。

4.2 向导步骤

浏览器访问 http://10.89.58.1:8130/itop/setup/wizard.php，实测页面标题为 Welcome to iTop version 3.3.0，Prerequisites validation 全部通过（PHP 8.2 就绪后）。向导依次完成：

欢迎页 → 同意许可（AGPL-3.0）；
环境检查（PHP 版本/扩展、目录写权限、graphviz 路径）；
数据库配置：主机 localhost、库 itop、账号口令，可勾选"创建新数据库"；
安装类型：选择"ITIL"完整流程集（含事件/请求/问题/变更/已知错误/增强门户等）；
附加选项：勾选样例数据（sample data）、默认语言 ZH CN、管理员账号口令；
确认并安装，完成后提示删除 setup 目录（生产建议）。

4.3 安装产物

向导完成后自动生成 conf/production/config-itop.php（权限 440）、log/install-<日期>.xml（本次安装参数响应文件，可复用于 CLI 重装）与 env-production/ 编译产物。

五、方案 B：CLI 无人值守安装

适合批量部署与 CI 场景，核心是准备一个 XML 参数文件后调用 setup/unattended-install/unattended-install.php。

5.1 参数文件

实测使用的 /root/itop-install.xml（关键节选）：

<?xml version="1.0" encoding="UTF-8"?>
<installation>
  <mode>install</mode>
  <source_dir>datamodels/2.x/</source_dir>
  <datamodel_version>3.3.0</datamodel_version>
  <extensions_dir>extensions</extensions_dir>
  <target_env>production</target_env>
  <database>
    <server>localhost</server>
    <user>root</user>
    <pwd>q1w2e3r4</pwd>
    <name>itop</name>
  </database>
  <url>http://10.89.58.1:8130/itop/</url>
  <graphviz_path>/usr/bin/dot</graphviz_path>
  <admin_account>
    <user>admin</user>
    <pwd>q1w2e3r4</pwd>
    <language>ZH CN</language>
  </admin_account>
  <language>ZH CN</language>
  <selected_extensions type="array">
    <item>itop-config-mgmt-datacenter</item>
    <item>itop-ticket-mgmt-itil-incident</item>
    <item>itop-ticket-mgmt-itil-user-request</item>
    <item>itop-change-mgmt-itil</item>
    <!-- 共 12 项，与向导"ITIL 完整"选择一致 -->
  </selected_extensions>
  <sample_data>1</sample_data>
</installation>

参数文件最可靠的来源是方案 A 完成后 log/install-<日期>.xml（口令会被脱敏为 **removed**，回填即可）。

5.2 执行安装

cd /var/www/html/itop/setup/unattended-install
php8.2 unattended-install.php \
  --param-file=/root/itop-install.xml \
  --installation_xml=/var/www/html/itop/datamodels/2.x/installation.xml \
  --clean=1

实测完整回显（节选，exit code 0）：

Modules to install computed based on installation.xml file and installation choices (listed in section `selected_extensions` of itop-install.xml file):
itop-config-mgmt-datacenter,...,itop-kown-error-mgmt

Computed modules to install:
authent-cas, authent-external, authent-ldap, authent-local,
combodo-backoffice-darkmoon-theme, ..., itop-backup, itop-config,
itop-structure, itop-tickets, itop-portal, itop-full-itil

Installation mode detected.
Cleanup mode detected.
No config file to delete (/var/www/html/itop/conf/production/config-itop.php does not exist).
Emptying the cache directory '/var/www/html/itop/data/cache-production'.
Emptying the target directory '/var/www/html/itop/env-production'.
Deleting database 'itop'
Info: mysqldump is present: Ok.
Starting the unattended installation...
Copying data model files        Executing 'copy'          Ok. 50 % done.
Compiling the data model        Executing 'compile'       Ok. 75 % done.
Log parameters                  Executing 'log-parameters' Ok. 20 % done.
Migrate data before database upgrade  'migrate-before'    Ok. 30 % done.
Updating database schema        Executing 'db-schema'     Ok. 40 % done.
Migrate data after database upgrade   'migrate-after'     Ok. 50 % done.
Loading data                    Executing 'load-data'     Ok. 70 % done.
Recording installation          Executing 'record-installation' Ok. 80 % done.
Creating the configuration File Executing 'create-config' Ok. 90 % done.
Finalize                        Executing 'commit'        Ok. 100 % done.

installed!
Restart the webserver in order to get the updated data model

回显中 Could not connect to the DB server: host = , user = , mysql_errno = 1698 一行是安装器先探测现有 config 文件失败的信息性输出，随后会使用参数文件中的数据库账号，不影响结果。

5.3 收尾（必做）

安装器以 root 身份重写 config-itop.php（属主 root:root、权限 440），Web 进程读不到会导致 500，必须修正属主：

chown -R www-data:www-data /var/www/html/itop/conf /var/www/html/itop/env-production
systemctl restart apache2

六、两种方案对比

维度	方案 A Web 向导	方案 B CLI 无人值守
交互	浏览器 6 步	一条命令
可重复性	手工操作	参数文件版本化，可批量
参数文件	自动生成于 log/	需自备（可用 A 的产物）
适用	首次单机部署	重装/批量/CI
坑	少	必须传 --installation_xml；装完要 chown

七、安装结果验证

curl -s -o /dev/null -w "%{http_code}\n" http://10.89.58.1:8130/itop/          # 200
curl -s -o /dev/null -w "%{http_code}\n" http://10.89.58.1:8130/itop/pages/UI.php # 200
mysql -uroot -p itop -e "SHOW TABLES;" | wc -l    # 255（254 张表）
mysql -uroot -p itop -e "SELECT COUNT(*) FROM organization;"  # 7
mysql -uroot -p itop -e "SELECT COUNT(*) FROM contact;"       # 53

浏览器打开 http://10.89.58.1:8130/itop/，登录页标题实测为"iTop登录"；用 admin 登录后进入"欢迎使用iTop"工作台。登录表单字段为 auth_user/auth_pwd/login_mode/loginop，脚本验证登录：

curl -s -c cj.txt "http://10.89.58.1:8130/itop/pages/UI.php" \
  -d "auth_user=admin&auth_pwd=<口令>&login_mode=db&loginop=login" -o after.html
grep -o '<title>[^<]*' after.html   # <title>欢迎使用iTop

生成的关键文件：

/var/www/html/itop/conf/production/config-itop.php   # 11751 字节，权限 440
/var/www/html/itop/log/install-2026-11-02.xml        # 安装参数响应文件
/var/www/html/itop/log/setup.log
/var/www/html/itop/env-production/                   # 69 个编译模块目录

八、常见问题

8.1 向导页 HTTP 500（PHP 版本）

现象：打开 wizard.php 即 500，错误日志提示 Composer 平台检查失败、要求 PHP ≥ 8.2。原因：Ubuntu 22.04 默认 PHP 8.1。解决：见 2.2，PPA 升级并切换 mod_php 后重启 Apache。

8.2 CLI 安装 exit=255：Missing unique tag: groups

现象：

Executing 'compile'
Error: Missing unique tag: groups in: /itop_design/user_rights
encountered installation issues!
installation failed!

原因：未传 --installation_xml，selected_modules 为空导致用户权限节编译失败。解决：追加 --installation_xml=/var/www/html/itop/datamodels/2.x/installation.xml，并用 --clean=1 清掉半成品残留后重跑。

8.3 安装成功但页面 500：ConfigException

现象：CLI 安装回显 installed!，但访问 UI.php 返回 500，Apache 日志：

PHP Fatal error: Uncaught ConfigException: Could not read configuration file
(the file exists but cannot be read). Do you have the rights to access this file?:
file = /var/www/html/itop/conf/production/config-itop.php in /var/www/html/itop/core/config.class.inc.php:2108

原因：安装器以 root 生成配置文件（root:root 440），Apache 的 www-data 无读权限。解决：chown www-data:www-data conf/production/config-itop.php（或按 5.3 全量 chown conf 与 env-production）。注意：每次执行安装/更新后都要复查属主。

九、卸载清理

systemctl stop apache2
mysql -uroot -p -e "DROP DATABASE itop;"
rm -rf /var/www/html/itop
rm -f /etc/apache2/sites-available/itop.conf
systemctl start apache2

如需保留数据迁移，先执行 mysqldump 备份（见运维篇）。

十、相关文档

十一、参考链接

官方安装文档（Quick install Ubuntu）：https://www.itophub.io/wiki/page?id=latest:install:install_start
社区版下载：https://sourceforge.net/projects/itop/files/itop/3.3.0/
GitHub 发布页：https://github.com/Combodo/iTop/releases
PHP PPA：https://launchpad.net/~ondrej/+archive/ubuntu/php