Ubuntu 22.04 安装 Tuleap 17.5 指南

先给结论：Tuleap 17.5 在 Ubuntu 22.04 上没有可用的官方直装渠道——官方支持矩阵只覆盖 Enterprise Linux 9（RHEL/Rocky/AlmaLinux 9），apt 源无包、社区 RPM 源域名已注销、企业订阅仓库要求付费凭证、源码无公开匿名入口，本文第一节逐条记录实测过程与真实报错（这是本篇最有价值的排障实录）。第二节按官方支持路径给出 AlmaLinux 9 上的完整安装步骤（命令 + 预期结果，未实测处明确标注），第三节给出 Ubuntu 环境的三条迁移建议，第四节沉淀安装排障速查表。组件背景与选型依据见《Tuleap 认知与选型：开源 ALM 敏捷项目管理平台全景》。

基准环境：Ubuntu 22.04.5 LTS（第一、四节实测），AlmaLinux 9/Rocky 9（第二节命令来自官方文档、未实测）；
目标版本：Tuleap 17.5（官方 Release Notes 截至 2026-10-28 列出的最新稳定版）；
端口规划：HTTPS 443、SSH 22、SMTP 25。

一、为什么 Ubuntu 直装不可行：官方边界与实测证据

1.1 官方支持边界

官方分步安装指南 Requirements 页（docs.tuleap.com，查询日 2026-10-28）原文要点：

仅支持 Enterprise Linux 9（RHEL、Rocky、AlmaLinux 9）x86_64，且安装前必须关闭 SELinux；
Tuleap 与宿主系统深度集成（接管 Apache、Postfix、SSH、Gitolite），官方要求独占服务器；
数据库必须为独立的 MySQL 8.4，sql-mode 仅允许 NO_ENGINE_SUBSTITUTION。

对 Ubuntu 的表述官方直接沉默——没有任何 deb 源、没有移植指南。以下实测就是围绕「还有没有变通」展开的。

1.2 排障实录：Ubuntu 22.04.5 上五条路径逐一验证

以下命令与回显均在 Ubuntu 22.04.5 LTS 实测（2026-10-28），逐行照抄。

尝试一：APT 官方源。

apt-get update && apt-cache search tuleap && apt-cache policy tuleap

预期结果：搜索与策略查询均无任何输出——Ubuntu 22.04 全量索引中不存在名为 tuleap 的包。强行安装得到明确报错：

apt-get install -y tuleap

实测回显（rc=100）：

Reading package lists...
Building dependency tree...
Reading state information...
E: Unable to locate package tuleap

尝试二：历史社区 RPM 源（ci.tuleap.net）。

老版本文档曾指导通过 ci.tuleap.net 安装社区版 RPM。实测 DNS 解析：

getent hosts ci.tuleap.net || echo NXDOMAIN

实测回显：

DNS NXDOMAIN for ci.tuleap.net

本机解析器与 8.8.8.8、1.1.1.1 公共 DNS 三重复核均为 NXDOMAIN——该社区源域名已注销，RPM 直装的老路彻底断掉。

尝试三：企业订阅仓库（rpm-repository.tuleap-enterprise.com）。

curl -sI https://rpm-repository.tuleap-enterprise.com/pub/tuleap-by-enalean/gpg.key

实测回显（域名解析正常，51.68.88.219）：

HTTP/2 401
server: nginx

匿名访问一律 401，仓库凭证需向 Enalean 商务申请——纯订阅制。

尝试四：从 tuleap.net 拉源码自编译。

git clone --depth 1 https://tuleap.net/plugins/git/tuleap/tuleap.git /tmp/tuleap-src

实测回显：

Cloning into '/tmp/tuleap-src'...
fatal: repository 'https://tuleap.net/plugins/git/tuleap/tuleap.git/' not found

/plugins/git/tuleap/tuleap（不带 .git 后缀）同样返回 fatal: repository ... not found。GitHub 侧 Enalean 组织经 API 列举仅有文档与周边工具仓库，无主源码。

尝试五：语言运行时版本差。

apt-get install -y php-cli && php -v | head -1

实测回显：

PHP 8.1.2-1ubuntu2.28 (cli) (built: Oct 19 2026 18:54:45) (NTS)

Ubuntu 22.04 官方源提供 PHP 8.1，而 Tuleap 17.x 运行于 PHP 8.2 线（官方管理指南日志路径 /var/opt/remi/php82/log/php-fpm/error.log 佐证），即便解决了包来源，运行时也要靠第三方源硬凑。

尝试小结：五条路径全部断头。rpm/alien 虽可在 Ubuntu 上安装（apt-get install -y rpm alien 实测成功），但没有任何公开可下载的 Tuleap RPM 可供转换，且 Tuleap 深度接管 httpd/Postfix/Gitolite、强依赖 dnf module 的 MySQL 8.4，转换安装既无输入也无成功可能，不再浪费时间验证。

1.3 结论

在 Ubuntu 22.04 上安装 Tuleap 17.5 不具备可行路径，任何绕行方案（换源、转包、手工编译）都停留在「理论」层面且无法获得官方更新。正确姿势是把它部署在官方支持的系统上——这正是第二节的内容。

二、推荐路径：AlmaLinux 9 / Rocky 9 官方安装

口径说明：本节命令整理自官方安装指南（docs.tuleap.com，查询日 2026-10-28），按「命令 + 预期结果」撰写；因本系列实测环境锁定 Ubuntu 22.04，本节未实测，标注了每步的预期来源。社区版公网 RPM 直装入口已收缩（见 1.2 尝试二/三），获取安装包请以官方安装指南与 Enalean 官方渠道为准；官方文档另提供适合快速评估的预集成部署方案，本节聚焦分步安装。

2.1 准备系统

要求一台独占的 EL9 x86_64 主机（虚拟机亦可），具有 Internet 连接。

# 关闭 SELinux（官方硬性要求）
setenforce 0
sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config

# 设置主机名与 DNS（FQDN 需可解析，如 tuleap.example.com → 192.168.1.123）
hostnamectl set-hostname tuleap.example.com

预期结果：getenforce 返回 Disabled；hostname -f 返回完整域名。防火墙按 2.6 开放端口。

2.2 安装依赖源（EPEL 与 Remi）

dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
dnf install -y https://rpms.remirepo.net/enterprise/remi-release-9.rpm

预期结果（官方 Install dependencies 页）：EPEL 提供部分依赖包，Remi 提供现代 PHP 版本，两条命令均以 Complete! 结束。

2.3 安装 Tuleap 与插件

在 yum 仓库配置就绪后（订阅凭证或官方渠道发放的 release 包），执行（命令来自官方 Install packages 页，插件列表可按需精简）：

dnf module enable mysql:8.4 && \
dnf install -y mysql-server \
valkey \
tuleap \
tuleap-plugin-agiledashboard \
tuleap-plugin-cardwall \
tuleap-plugin-crosstracker \
tuleap-plugin-document \
tuleap-plugin-git \
tuleap-plugin-graphontrackers \
tuleap-plugin-label \
tuleap-plugin-ldap \
tuleap-plugin-pullrequest \
tuleap-plugin-svn \
tuleap-plugin-testmanagement \
tuleap-plugin-testplan \
tuleap-plugin-timetracking \
tuleap-realtime \
tuleap-theme-burningparrot \
tuleap-theme-flamingparrot

预期结果：事务完成、无冲突；rpm -q tuleap 显示 tuleap-17.5-*（版本以仓库当日为准）。官方建议：不必一次装满 40+ 插件，起步装核心，后续按需追加（见《Tuleap 17.5 配置详解：配置文件与系统变量逐项精讲》）；全文检索建议后期切换 fts-meilisearch 提升性能。

2.4 初始化 MySQL 8.4

echo -e '[mysqld]\nsql-mode="NO_ENGINE_SUBSTITUTION"' > /etc/my.cnf.d/tuleap.cnf
systemctl enable mysqld
systemctl start mysqld
mysqladmin -u root password

预期结果（官方 Prepare the database 页原文步骤）：sql-mode 固定为 NO_ENGINE_SUBSTITUTION（官方警告：添加其他 mode 或以其他 sql-mode 启动会导致 Tuleap 故障）；mysqladmin 交互输入两次 root 密码。

2.5 运行 setup.sh 完成初始化

/usr/share/tuleap/tools/setup.sh \
 --configure \
 --server-name=tuleap.example.com \
 --mysql-server=localhost \
 --mysql-password=YOUR_DB_ROOT_PWD

预期结果（官方 Setup 页）：脚本完成站点配置、数据库建库与系统账号初始化；完成后 Web 服务与 tuleap 服务处于运行状态。防火墙需放行 Web（TCP/80、443）与 SSH（TCP/22）。

2.6 防火墙放行

firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https
firewall-cmd --permanent --add-service=ssh
firewall-cmd --reload

预期结果：firewall-cmd --list-all 中 services 包含 http/https/ssh；端口要求见官方 Services 页（Web UI 443、SSH 22、SMTP 25）。

2.7 首次登录

浏览器访问 https://tuleap.example.com（默认使用自签名证书，生产环境建议按官方 TLS 页换发 Let's Encrypt 证书并修改 /etc/nginx/conf.d/tuleap.conf 的 ssl_certificate* 两项）。

站点管理员初始密码存放在 /root/.tuleap_passwd（官方 First connection 页；官方同时建议尽快查看并删除该文件）：

cat /root/.tuleap_passwd

用账号 admin 登录后立即改密——本系列示例统一使用 admin / q1w2e3r4（仅作示例，生产环境必须换强口令）。登录成功即安装完成；验证清单与日常维护见《Tuleap 17.5 运维命令手册：服务、备份与排障》。

三、Ubuntu 环境的迁移建议

3.1 三种方案对比

方案	做法	适用	代价
A. 独立 EL9 主机（推荐）	新装一台 AlmaLinux 9/Rocky 9 虚机，按第二节走完安装；Ubuntu 只做访问端或反向代理	绝大多数团队	多一台主机；需配置 `$sys_trusted_proxies`（见配置篇）
B. Ubuntu 整机换系	重装该服务器为 EL9（数据先出后进）	该机本来就专职跑 Tuleap	停机窗口；其余应用需迁走（官方本就要求独占）
C. 放弃 Tuleap 换方案	若必须留在 Ubuntu：评估 OpenProject（官方 DEB 支持 Ubuntu）	无强合规/测试管理诉求的团队	功能面变化，见选型篇对比表

3.2 若已有 Tuleap 数据要搬进新机

来源可以是旧 Tuleap 主机或评估环境，数据面三件套（官方 Backup/Restore 页）：

mysqldump -u tuleapadm -p --all-databases > tuleap_all.sql
tar czf tuleap_etc.tgz /etc/tuleap
tar czf tuleap_data.tgz /var/lib/tuleap /var/lib/gitolite

恢复顺序（官方 Restore 流程）：装好同版本新机 → 停服务 → 导库 → 还原目录（注意 RPM 部署间 uids/gids 一致，必要时 rsync 重映射）→ 执行 tuleap-cfg site-deploy → 起服务。

3.3 迁移后验证清单

systemctl status nginx httpd tuleap mysqld 四单元均 active；
ss -lntp 可见 443/22 监听；
浏览器以 admin / q1w2e3r4 示例账号登录成功（生产换强口令）；
创建测试项目、建 Tracker 工件、提交一次带 TULEAP-1 引用的 Git 提交，确认追溯链路正常。

四、安装排障速查

4.1 症状 → 检查 → 处置

症状	检查命令	处置（官方 Troubleshooting 页）
首页打不开	`systemctl status nginx`、`systemctl status tuleap-php-fpm`、`systemctl status mysqld`、`ss -lntp`、`systemctl status firewalld`、`firewall-cmd --list-all`	拉起故障单元；确保 80/443 放行
页面白屏	查 nginx 与 PHP-FPM 错误日志（路径见运维篇日志清单）	按日志定位 PHP 扩展/权限问题
登录后死循环跳回登录页	比对 `/etc/tuleap/conf/local.inc` 与 `/etc/nginx/conf.d/tuleap.conf` 中站点 URL	全局只允许一个访问地址，统一 URL 后重启
后台事件不处理	`tail /var/log/tuleap/worker_log`	需要更细日志时调高 `$sys_logger_level`（配置篇）
证书告警	浏览器查看证书签发者	自签名属默认行为；生产替换为 CA 证书

4.2 本篇实测结论复述

Ubuntu 22.04.5 上：apt 无包（E: Unable to locate package tuleap）、社区 RPM 源域名注销（NXDOMAIN）、企业仓库 401、源码仓库 not found、PHP 差 8.2 一档——直装判死，请按第二节在 AlmaLinux 9/Rocky 9 上安装，或按第三节方案 A/C 调整架构。

延伸阅读

《Tuleap 认知与选型：开源 ALM 敏捷项目管理平台全景》：支持边界与选型对比的完整论证；
《Tuleap 17.5 配置详解：配置文件与系统变量逐项精讲》：装完之后该改哪里；
《Tuleap 17.5 运维命令手册：服务、备份与排障》：日常巡检、备份与升级。

官方文档来源（查询日 2026-10-28）：docs.tuleap.com 安装指南 Requirements / Install dependencies / Install packages / Prepare the database / Setup / TLS configuration / First connection / Upgrade / Troubleshooting 各页；管理指南 Services、Backup/Restore 页。