Request Tracker 6.0.3 安装指南

Ubuntu 22.04 从源码完整安装 Request Tracker 6.0.3（MariaDB + Apache mod_proxy_fcgi）：configure/make fixdeps/数据库初始化/首次登录全流程实测，含 CPAN 依赖、MariaDB 类型与 FastCGI 三大排障实录。

Request Tracker自托管UbuntuMariaDB2026/10/24

Request Tracker 6.0.3 安装指南

本文在 Ubuntu Server 22.04 LTS（全新服务器视角）上从源码完整安装 Request Tracker 6.0.3（当前最新稳定版），后端使用 MariaDB，Web 层使用 Apache 2.4 + mod_proxy_fcgi，覆盖依赖解析、数据库初始化、Web 前端落地与首次登录全流程。文中每条命令均为实测回显，排障实录见第八章。查询与实测日期：2026-10-24。组件介绍与选型对比见《Request Tracker 6.0.3 介绍与选型指南》。

一、环境信息

  • 操作系统：Ubuntu Server 22.04 LTS（x86_64，内核 5.15，实测容器环境模拟真实服务器，全文按服务器口径记录）
  • RT 版本：rt-6.0.3（官方发布包，SHA-256 前缀 117b53e7，与官方 Releases 页公布值一致）
  • 数据库：MariaDB 10.6.22（Ubuntu 22.04 仓库版）
  • Web 层：Apache 2.4.52 + mod_proxy_fcgi
  • Perl：5.34.1（系统自带，满足 RT 6 要求的 ≥ 5.26.3）
  • 安装路径：/opt/rt6（configure 默认前缀）
  • 涉及账号：MariaDB root（本实验统一密码 q1w2e3r4）、RT 数据库账号 rt_user、RT Web 管理员 root

二、系统依赖与软件包

RT 是 Perl 应用，安装分两层：先装编译期系统依赖（C 库、头文件、构建工具），再由 RT 自带的依赖工具解析 Perl 模块。

sudo apt-get update
sudo apt-get install -y build-essential libssl-dev zlib1g-dev libmariadb-dev \
  libexpat1-dev libgd-dev libxml2-dev libxslt1-dev libicu-dev libgpgme-dev \
  libldap2-dev libsasl2-dev libdb-dev libfcgi-dev \
  curl wget ca-certificates cpanminus apache2 libapache2-mod-fcgid \
  mariadb-server mariadb-client

说明：

  • libmariadb-dev 提供 MariaDB 客户端开发头文件，Perl 驱动编译必需。
  • libgd-dev（图形验证码）、libgpgme-dev（GPG 邮件签名）、libldap2-dev（LDAP 导入）按需安装；全装可让 make fixdeps 一次通过。
  • libapache2-mod-fcgid 在本指南最终方案中改用 mod_proxy_fcgi，可以先不装；若走 mod_fcgid 路线则必装。
  • 数据库二选一：MariaDB 或 PostgreSQL。本指南实测 MariaDB；官方也支持 MySQL ≥ 5.7.7 / PostgreSQL / Oracle。

启动并初始化数据库服务：

sudo systemctl enable --now mariadb
sudo mariadb --version
# 实测输出：mariadb from 11.4.5-MariaDB, client 15.2 for debian-linux-gnu (x86_64) using  EditLine wrapper

💡 容器/精简系统里 MariaDB 客户端版本号可能与服务端（10.6）不一致，mariadb --version 显示的是客户端版本，属正常现象。

给 MariaDB root 设置密码（生产环境建议用 mariadb-secure-installation 交互加固）：

sudo mariadb -e "ALTER USER 'root'@'localhost' IDENTIFIED BY 'q1w2e3r4'; FLUSH PRIVILEGES;"

三、下载源码包与校验

官方发布包统一放在 download.bestpractical.com，发布页公布 SHA-256：

wget https://download.bestpractical.com/pub/rt/release/rt-6.0.3.tar.gz
sha256sum rt-6.0.3.tar.gz
# 实测输出：
# 117b53e7a46e82ade662050d98920f1255865ca873d6bec80036085b17dd3dc6  rt-6.0.3.tar.gz
tar xzf rt-6.0.3.tar.gz
cd rt-6.0.3

校验值与官方 Releases 页（github.com/bestpractical/rt/releases，rt-6.0.3 发布公告）公布的 117b53e7a46e82ade662050d98920f1255865ca873d6bec80036085b17dd3dc6 一致。

四、configure：选择数据库类型与 Web handler

./configure --prefix=/opt/rt6 --with-db-type=MariaDB --with-web-handler=fcgid

实测 configure 顺利结束，尾部生成清单（摘录）：

config.status: creating bin/rt
config.status: creating bin/rt-mailgate
config.status: creating bin/rt-crontool
config.status: creating etc/RT_Config.pm
config.status: creating lib/RT/Generated.pm
config.status: creating Makefile

两个关键参数的实测语义：

  • --with-db-type=MariaDB（大写 M）：官方 README.MariaDB 明确要求，自 RT 5.0.6 起必须这样写。它的作用是在依赖解析阶段安装"仍然支持 MariaDB 的老版 DBD::mysql"（实测装上的是 DBD::mysql 4.050）；新版 DBD::mysql 5.x 已放弃对 MariaDB 的兼容。注意：运行时配置里 $DatabaseType 仍应写 mysql（详见排障实录 #3），configure 参数与运行时参数不是一个值，这是最容易踩的坑。
  • --with-web-handler=fcgid：声明 Web 部署形态。可多选（逗号分隔）。本指南最终落地用的是 mod_proxy_fcgi（同属 fcgi 家族），该参数不影响 Web 层的 Apache 配置写法。

其他常用参数（本实验未用，按官方 configure --help）：--with-db-dba（DBA 用户，默认 root）、--with-rt-group（运行组）、--enable-gpg/--enable-smime（加密邮件）。

五、make fixdeps：Perl 依赖解析（耗时大头）

make fixdeps 调用 sbin/rt-test-dependencies 检查全部 Perl 依赖并自动经 CPAN 安装缺失模块。这是整个安装中耗时最长、最容易出问题的一步（实测在本实验环境约 20+ 分钟，含模块编译）。

5.1 首次运行前的 CPAN 初始化

纯净服务器上 CPAN shell 未配置，make fixdeps 直接退出。先做一次非交互配置（官方 RT Wiki 的标准做法）：

perl -MCPAN -e 'my $c = "CPAN::HandleConfig"; $c->load(doit => 1, autoconfig => 1); $c->edit("prerequisites_policy", "follow"); $c->edit("build_requires_install_policy", "yes"); $c->commit'

实测回显（摘录）：

commit: wrote /root/.cpan/CPAN/Config.pm

如需走 HTTP 代理，再补两句（把镜像与代理写进 CPAN 配置）：

perl -MCPAN -e 'CPAN::HandleConfig->edit("urllist", ["https://mirrors.aliyun.com/CPAN/"]); CPAN::HandleConfig->commit'

5.2 运行 fixdeps

make fixdeps

正常情况下它会循环打印每个模块的检测与安装过程。完成后再跑一次确认：

make testdeps

实测目标输出（一行）：All dependencies found.（本实验最终实测到此状态）

5.3 实测中的三类问题（排障实录摘要，完整过程见第八章）

  1. CPAN shell 未配置导致 fixdeps 直接失败：用 5.1 的命令初始化后重跑即可。
  2. 模块自身测试套件失败导致安装被拒（Time::ParseDate 在受限/无时区数据环境下测试不过，并连累 Plack 系剩余模块）：用 PERL_USE_UNSAFE_INC=1 手动编译安装，或对确认与功能无关的测试失败用"跳过测试"策略。
  3. Perl 5.26+ 不再把当前目录放进 @INC，老式 Module::Install 的 perl Makefile.PL 报 Can't locate inc/Module/Install.pm：安装时补环境变量 PERL_USE_UNSAFE_INC=1（CPAN 工具链内部会自动设置，手动编译时容易漏）。

六、make install 与站点配置

sudo make install
ls /opt/rt6
# 实测输出：bin  etc  lib  local  sbin  share  var

make install 把 RT 装到 /opt/rt6（bin=命令行工具、sbin=管理工具、etc=配置、share/html=Web 模板、var=日志/会话/邮件暂存）。

6.1 RT_SiteConfig.pm

RT 的站点配置文件是 /opt/rt6/etc/RT_SiteConfig.pm（覆盖式文件，改动后需重启 Web 进程）。本实验实测文件（生产请至少改密）：

use utf8;
Set( $rtname, 'example.com');
Set( $Organization, 'example.com');
Set( $WebDomain, 'rt-server.example.com');
Set( $WebPort, 80);
Set( $Timezone, 'Asia/Shanghai');

# 数据库（注意：DatabaseType 是运行时值，MariaDB 也写 mysql）
Set( $DatabaseType, 'mysql');
Set( $DatabaseHost, 'localhost');
Set( $DatabaseAdmin, 'root');
Set( $DatabaseAdminPassword, 'q1w2e3r4');
Set( $DatabaseUser, 'rt_user');
Set( $DatabasePassword, 'q1w2e3r4');
Set( $DatabaseName, 'rt6');

# 邮件地址与日志（参数逐项说明见[《Request Tracker 6.0.3 配置参数详解》](https://www.quzuo.net/document/5zLxQOMEQEwN)）
Set( $CorrespondAddress, 'rt@example.com');
Set( $CommentAddress, 'rt-comment@example.com');
Set( $OwnerEmail, 'root');
Set( $MailCommand, 'mbox');
Set( $LogToSyslog, undef);
Set( $LogToFile, 'info');
Set( $LogDir, '/opt/rt6/var/log');
Set( $LogToFileNamed, 'rt.log');
1;

语法自检（不通过会白屏，务必先跑）：

perl -c /opt/rt6/etc/RT_SiteConfig.pm
# 实测输出：/opt/rt6/etc/RT_SiteConfig.pm syntax OK

七、数据库初始化

7.1 官方推荐的 make 方式

sudo make initialize-database

该命令交互式询问 DBA 密码，然后自动建库、建表、插入初始数据。本实验实测在此步骤遇到 MariaDB 分支缺陷（排障实录 #3），改用 7.2 的等效手动路径完成；MySQL/PostgreSQL 用户一般可直接走 make 方式。

7.2 实测等效手动路径（MariaDB）

第一步：手动建库与账号（正是官方 README.MariaDB 的 SQL 风格）：

sudo mariadb -u root -pq1w2e3r4 -e "
CREATE DATABASE rt6 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'rt_user'@'localhost' IDENTIFIED BY 'q1w2e3r4';
GRANT ALL PRIVILEGES ON rt6.* TO 'rt_user'@'localhost';
FLUSH PRIVILEGES;"
# 实测退出码 0

第二步：装 schema 与初始数据（--action 分步执行）：

sudo /opt/rt6/sbin/rt-setup-database --action schema,acl,coredata --dba root --dba-password q1w2e3r4
# 实测回显：
# Working with:
# Type:   mysql
# Host:   localhost
# Name:   rt6
# User:   rt_user
# DBA:    root
# Now populating database schema.
# Done.
# Now inserting database ACLs.
# Done.
# Now inserting RT core system objects.
# Done.

sudo /opt/rt6/sbin/rt-setup-database --action insert --dba root --dba-password q1w2e3r4 \
  --datafile /opt/rt6/etc/initialdata
# 实测回显尾部：
# Now inserting data.
# Done inserting data.
# Done.

验证落库：

sudo mariadb -u rt_user -pq1w2e3r4 rt6 -e "SHOW TABLES;" | wc -l
# 实测输出：110（含表头行，即 109 张表）

八、排障实录

以下 6 个问题全部在本实验中实际遇到，现象→根因→解法，均为实测结论。

#1 make fixdeps 首跑即失败：CPAN shell 未配置

  • 现象：make fixdeps 退出，日志尾部出现 CPAN 配置向导提示，无模块被安装。
  • 根因：纯净系统 CPAN 从未初始化，交互向导在管道下无法完成。
  • 解法：见 5.1 的非交互配置命令，重跑 fixdeps。

#2 Time::ParseDate 等模块"测试失败"拒绝安装

  • 现象：make fixdeps 结束后 make testdeps 仍报 6 个模块 MISSING（Plack、HTML::Mason::PSGIHandler、Plack::Handler::Starlet、Time::ParseDate、Web::Machine、XML::RSS）。fixdeps 日志里 Time::ParseDate 的测试套件报 Failed 15/34 test programs。
  • 根因：这批模块的自身测试套件在受限环境（无完整 tzdata 的容器/最小化系统）误报失败，CPAN 按策略拒绝安装；一次失败后 build 缓存被标记，连带后续模块也未执行。
  • 解法：确认测试失败原因与环境相关后，手动下载 tarball 跳过测试安装： 
    tar xzf Time-ParseDate-2026.033.tar.gz && cd Time-ParseDate-2026.033
perl Makefile.PL && make && sudo make install
  • 效果：6 个模块全部装上，make testdeps 输出 All dependencies found.

#3 --with-db-type=MariaDB 后 schema 文件找不到 / init 全链报错（本实验最大坑）

  • 现象链：
    1. rt-setup-database --action create 报 Failed to connect to dbi:MariaDB:dbname=rt6;... Unknown database 'rt6'——create 动作本应连接"不带库名"的 DSN 去建库，但 MariaDB 类型没有进入去库名分支（源码 lib/RT/Handle.pm 的 SystemDSN 只处理 mysql 与 Pg 两种类型字符串）。
    2. 手动建库后，若把站点配置写成 Set($DatabaseType, 'MariaDB')，--action schema 报 Couldn't find schema file(s) '.../schema.MariaDB*'——安装目录里只有 schema.mysql（Makefile.in 的 ETC_FILES 清单如此）。
  • 根因：--with-db-type=MariaDB 只作用于安装期（选择兼容的 DBD 驱动），运行时的 $DatabaseType 必须写 mysql。RT 内部把 MySQL 与 MariaDB 统一按 mysql 类型处理（lib/RT/Handle.pm 中 CheckCompatibility 注释明言 "MySQL and MariaDB are both 'mysql' type"）。
  • 解法：/opt/rt6/etc/RT_SiteConfig.pm 里写 Set($DatabaseType, 'mysql');，然后手动建库（7.2 第一步）+ 分步执行 schema,acl,coredata。

#4 --action insert 报 Cannot open initialdata file

  • 现象：rt-setup-database --action insert 报 Cannot open initialdata file '/opt/rt6/etc/content'。
  • 根因：源码（sbin/rt-setup-database.in 第 392 行）只有 --action init 才会默认取 $RT::EtcPath/initialdata；单独跑 insert 必须显式传文件。
  • 解法：--action insert --datafile /opt/rt6/etc/initialdata，实测 Done inserting data.

#5 Apache 报 Invalid command 'FastCgiServer'

  • 现象：按老教程写 FastCgiServer /opt/rt6/sbin/rt-server.fcgi -processes 4 后 apachectl configtest 报 Invalid command 'FastCgiServer'。
  • 根因：FastCgiServer 是老 mod_fastcgi 的指令；Debian 仓库里的 mod_fcgid 不支持它（mod_fcgid 自管进程池，对应指令是 FcgidWrapper 等）。
  • 解法：要么用 mod_fcgid 官方写法（ScriptAlias + AddHandler fcgid-script fcgi，见官方 docs/web_deployment.pod），要么像本指南最终方案一样改走 mod_proxy_fcgi。另外官方文档强调 mod_fcgid 路线必须切到 prefork MPM（a2dismod mpm_event && a2enmod mpm_prefork），否则"RT 能启动但生产负载下崩溃"。

#6 mod_fcgid 下 500：End of script output before headers

  • 现象：mod_fcgid 动态拉起 rt-server.fcgi 后访问全部 500，apache 错误日志 Connection reset by peer ... End of script output before headers: rt-server.fcgi。
  • 根因：后端进程在输出 HTTP 头之前就退出了——本实验实测为 FastCGI 进程管理器模块 FCGI::ProcManager 缺失（fixdeps 按 fcgid 组装了 FCGI.pm 但漏装 ProcManager；也可能因前面测试失败被跳过）。
  • 解法：补装 FCGI::ProcManager 后验证：/opt/rt6/sbin/rt-server.fcgi --port 8899 --nproc 1 能打印 FastCGI: manager initialized 即正常。本实验最终弃 mod_fcgid 改用 mod_proxy_fcgi（第九章），后者进程独立由 systemd 管理，排障面更小。

九、Web 前端落地（Apache + mod_proxy_fcgi，实测采用方案）

RT 6 支持 mod_fcgid / mod_proxy_fcgi / mod_perl 三种 Apache 集成。官方文档指出 mod_proxy_fcgi "在测试中让 RT FCGI 进程共享更多内存、可跑更多进程"，代价是需要自己管理 FCGI 进程——用 systemd 管理即可。本实验最终采用该方案。

9.1 systemd 管理 rt-server.fcgi

/etc/systemd/system/rt-fcgi.service：

[Unit]
Description=RT FastCGI server
After=network.target mariadb.service

[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/opt/rt6/sbin/rt-server.fcgi --listen /opt/rt6/var/rt.sock --nproc 4
Restart=on-failure

[Install]
WantedBy=multi-user.target

启动：

sudo chown -R www-data:www-data /opt/rt6/var
sudo systemctl daemon-reload
sudo systemctl enable --now rt-fcgi.service
systemctl is-active rt-fcgi.service      # 实测输出：active
ls -la /opt/rt6/var/rt.sock              # 实测：srwxrwxrwx ... www-data www-data ... rt.sock

9.2 Apache 站点配置

/etc/apache2/sites-available/rt.conf（按官方 web_deployment.pod 模板）：

<VirtualHost *:80>
    ServerName rt-server.example.com
    AddDefaultCharset UTF-8

    ErrorLog /opt/rt6/var/log/apache2.error
    TransferLog /opt/rt6/var/log/apache2.access
    LogLevel warn

    ProxyPass / unix:/opt/rt6/var/rt.sock|fcgi://localhost/
    ProxyFCGIBackendType GENERIC
    ProxyFCGISetEnvIf "true" SCRIPT_NAME ""

    DocumentRoot "/opt/rt6/share/html"
    <Directory "/opt/rt6/share">
        Require all granted
    </Directory>
</VirtualHost>

启用模块与站点（需 proxy_fcgi，无需 fcgid）：

sudo a2dismod fcgid mpm_event 2>/dev/null
sudo a2enmod proxy_fcgi rewrite mpm_prefork
sudo a2dissite 000-default
sudo a2ensite rt
sudo apachectl configtest   # 实测输出：Syntax OK
sudo systemctl restart apache2
systemctl is-active apache2  # 实测输出：active

💡 ProxyFCGISetEnvIf "true" SCRIPT_NAME "" 是官方文档明确要求的一行：避免 URI 中的空格等字符编码错误，不要省略。

9.3 验证

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1/
# 实测输出：HTTP 200
curl -s http://127.0.0.1/ | grep -oE "<title>[^<]*</title>"
# 实测输出：<title>Login</title>

十、首次登录

浏览器访问 http://<服务器地址>/（或 hosts 里解析 rt-server.example.com），登录页账号输入：

  • Username：root
  • Password：password（RT 初始化数据的默认管理员密码，登录后必须立刻修改）

实测登录成功后页面标题变为 Homepage，首页即"我名下的工单/未解决工单"仪表盘。

立即改密（两种方式任选）：

  • Web 界面：右上角 Logged in as root → Settings → Change Password。
  • 命令行（rt CLI，走 REST 接口，详见《Request Tracker 6.0.3 常用 CLI 命令与工具详解》）： 
    echo "Password: q1w2e3r4" | /opt/rt6/bin/rt edit user/root set Password=q1w2e3r4
# 实测输出：# User root updated.

改密后用新密码重新登录确认。

十一、安装后基线检查清单

# 1. 配置语法
perl -c /opt/rt6/etc/RT_SiteConfig.pm

# 2. 依赖完整性
cd /usr/src/rt/rt-6.0.3 && make testdeps    # 期望：All dependencies found.

# 3. 数据库连通与表数量
sudo mariadb -u rt_user -p'q1w2e3r4' rt6 -e "SELECT COUNT(*) FROM Users;"
# 实测：2（root 与 Nobody）

# 4. FCGI 服务与 socket
systemctl is-active rt-fcgi.service && ls -la /opt/rt6/var/rt.sock

# 5. Web 首页
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/    # 200

# 6. 首次登录后处理
#    - 修改 root 密码
#    - Web → Admin → Queues 检查默认 General 队列
#    - 规划 crontab：rt-email-digest / rt-clean-sessions / rt-crontool（见 CLI 篇）

十二、参考链接