Tuleap 17.5 运维命令手册：服务、备份与排障
Tuleap 17.5 日常运维手册：服务拓扑与端口清单、tuleap-cfg 与 tuleap config 命令族、20 余个专用日志文件全景与日志级别、一致性备份与恢复流程、月度升级五步法及排障决策树速查表。
Tuleap 17.5 运维命令手册：服务、备份与排障
Tuleap 单机实例由「tuleap 主服务 + nginx + httpd + PHP-FPM + MySQL 8.4」加可选的 Valkey/Postfix 组成，日常运维的要点是分清「哪个动作动哪个服务、日志落在哪里、升级怎么走」。本文是安装（《Ubuntu 22.04 安装 Tuleap 17.5 指南》）与配置（《Tuleap 17.5 配置详解：配置文件与系统变量逐项精讲》）两篇的运维续篇，命令与预期结果整理自官方安装指南、管理指南与升级文档（docs.tuleap.com，查询日 2026-10-28）；因 Tuleap 17.5 无法在 Ubuntu 22.04 直装（原因与实测证据见安装篇第一节），本篇命令均为「命令 + 预期结果」口径、未实测，已在各节标注。组件背景见《Tuleap 认知与选型：开源 ALM 敏捷项目管理平台全景》。
一、服务与端口清单
1.1 服务拓扑速查
| 服务 | 角色 | 关键路径 | 备注 |
|---|---|---|---|
tuleap | 平台主服务（后台事件、队列） | /var/log/tuleap/worker_log | 官方升级命令的操作对象之一 |
nginx | TLS/443 入口 | /etc/nginx/conf.d/tuleap.conf | 证书两行 ssl_certificate* |
httpd（Apache） | 应用层 Web | /etc/httpd/conf/httpd.conf、/etc/httpd/conf.d/ | 官方升级命令三单元之一 |
tuleap-php-fpm | PHP 进程池（Remi PHP 8.2） | /var/opt/remi/php82/log/php-fpm/error.log | 官方排障页点名检查 |
mysqld | MySQL 8.4 | /etc/my.cnf.d/tuleap.cnf | sql-mode 强制 NO_ENGINE_SUBSTITUTION |
valkey | 缓存（监控特性场景） | /etc/valkey/valkey.conf | 可选 |
postfix | 邮件收发 | /etc/postfix/main.cf | 别名库含 /etc/aliases.codendi |
| sshd + Gitolite | Git/SVN 托管 | /var/lib/gitolite | SSH 22 |
1.2 端口清单
官方 Services 页原文口径：Web UI 443（HTTPS）、SSH 22、SMTP 25。MySQL 仅本机访问；防火墙要求 80/443 对外（官方排障页）。
1.3 每日巡检命令组合
systemctl is-active tuleap nginx httpd mysqld # 预期结果：四行 active
ss -lntp | grep -E ':443 |:22 |:25 ' # 预期结果：三条监听齐全
tail -5 /var/log/tuleap/worker_log # 预期结果：worker 心跳/事件记录持续刷新
口径：未实测（命令整理自官方 Services / Troubleshooting 页；运行时基线为官方支持的 EL9 环境）。
二、平台自带命令行工具
2.1 tuleap-cfg：站点级操作
# 部署站点配置（改配置/升级后必跑；预期结果：正常退出、无 PHP Fatal）
tuleap-cfg site-deploy
site-deploy 官方升级文档原文描述为「Deploy site configurations, run database migration & co」——它同时承担配置模板渲染与数据库迁移检查，是 Tuleap 最重要的单条命令。
2.2 tuleap：配置变量命令族
tuleap config-list # 预期结果：列出全部变量及默认值
tuleap config-get sys_logger_level # 预期结果：warning（默认）
tuleap config-set sys_logger_level info # 预期结果：写入成功，需 site-deploy 生效
2.3 服务管理标准动作
systemctl restart tuleap nginx httpd # 配置变更后的重启三连
systemctl status tuleap-php-fpm # 排障页点名的检查项
三、日志体系与排查
3.1 日志级别
$sys_logger_level（/etc/tuleap/conf/local.inc 或 config-set）可取 8 个值（官方 Logs 页）：emergency、alert、critical、error、warning（默认）、notice、info、debug。级别作用于全部驱动（file/syslog/graylog）与全部服务。
3.2 日志文件全景
官方 Logs 页列出的完整清单（查询日 2026-10-28）：
| 类别 | 文件 | 内容 |
|---|---|---|
| nginx | /var/log/nginx/access.log、/var/log/nginx/error.log | 入口访问与错误 |
| PHP-FPM | /var/opt/remi/php82/log/php-fpm/error.log | PHP 响应构造错误 |
| Apache | /var/log/httpd/access_log、/var/log/httpd/error_log | 应用层访问与错误 |
| 平台事件 | /var/log/tuleap/codendi_syslog | 系统事件执行（后台操作） |
| 异步 worker | /var/log/tuleap/worker_log | 后台 worker 活动（异步通知等） |
| Git | /var/log/tuleap/git_syslog、/var/log/tuleap/git_http_error_log | Git 系统事件队列、HTTP 错误 |
| REST API | /var/log/tuleap/rest_api_log | API 错误 |
| 邮件 | /var/log/tuleap/mail_syslog | 邮件分发错误与信息 |
| LDAP | /var/log/tuleap/ldap_syslog | LDAP 插件活动 |
| 认证 | /var/log/tuleap/openid_connect_client.log、/var/log/tuleap/oauth2_server.log | OIDC 客户端、OAuth2 服务端 |
| 图表 | /var/log/tuleap/burndown_syslog、/var/log/tuleap/burnup_syslog | 燃尽/燃起图生成 |
| 导入/迁移 | /var/log/tuleap/project_xml_import_syslog、/var/log/tuleap/tv3_tv5_migration_syslog | XML 项目导入、Tracker v3→v5 迁移 |
| 其他 | /var/log/tuleap/statistics_syslog、/var/log/tuleap/archive_deleted_item.log、/var/log/tuleap/botMattermost_syslog、/var/log/tuleap/onlyoffice_syslog、/var/log/tuleap/webdav_syslog、/var/log/tuleap/frontend_error | 统计、归档插件、BotMattermost、ONLYOFFICE、WebDAV、前端错误上报 |
3.3 日志驱动选择
官方建议：file 为默认方式但「unlikely to fit production needs」，生产环境推荐 syslog 或 graylog/gelf（后者上下文信息更丰富），并建议把 nginx/Apache 错误日志一并纳入同一驱动收集。
3.4 高频排查组合
# 预期结果：最近 10 分钟平台侧错误概览
tail -200 /var/log/tuleap/codendi_syslog | grep -i error
# 预期结果：登录死循环时定位重定向源（对比站点 URL 一致性）
grep -i server_name /etc/nginx/conf.d/tuleap.conf
grep sys_default_domain /etc/tuleap/conf/local.inc
# 预期结果：worker 卡住时确认队列活动
tail -f /var/log/tuleap/worker_log
四、备份与恢复
4.1 备份面（官方 Backup/Restore 页）
- 数据库：主库
tuleap+ 各插件库，一把全备：
mysqldump -u tuleapadm -p --all-databases > tuleap_all.sql
- 目录：
/etc/nginx、/etc/valkey、/etc/tuleap、/var/lib/gitolite、/var/lib/tuleap（官方提示部分目录视插件存在）。
4.2 一致性备份流程
systemctl stop nginx
systemctl stop httpd
systemctl stop tuleap
su - gitolite -c "gitolite writable @all off 'Backup in progress'"
# ……执行 mysqldump 与目录打包……
# 备份完成后恢复：gitolite writable @all on 并 systemctl start 三单元
官方原话：先停服务「should guarantee you a consistent backup」；有快照能力的平台可直接停服务后打快照。
4.3 恢复流程（官方 Restore 原文顺序）
- 准备同版本 Tuleap 服务器（按安装篇流程）；
- 停全部服务；
- 导入数据库（官方注：从 sqldump 恢复是保证实例间兼容的最稳妥方式）；
- 还原目录（RPM 部署间迁移需注意 uids/gids 映射一致，官方提供 rsync 重映射方法）；
- 执行
tuleap-cfg site-deploy； - 重启服务并按 4.4 验证。
4.4 定时备份骨架与验证
# /etc/cron.d/tuleap-backup（示例：每日 02:30，先停后起）
30 2 * * * root systemctl stop nginx httpd tuleap && \
mysqldump -u tuleapadm -p'PWD' --all-databases > /backup/tuleap_$(date +\%F).sql && \
tar czf /backup/tuleap_etc_$(date +\%F).tgz /etc/tuleap /var/lib/tuleap /var/lib/gitolite && \
systemctl start tuleap nginx httpd
恢复演练验证清单：导入库后 tuleap-cfg site-deploy 无报错、以 admin / q1w2e3r4 示例账号登录成功、抽一个项目确认 Tracker 工件与附件完整。
五、升级流程（月度节奏）
5.1 升级前通告
官方 Upgrade 页要求提前告知用户平台将停机：可走站内群发邮件引擎 + 全站横幅（banner）。
5.2 标准升级五步（官方原文命令）
# 1) 检查可用更新（预期结果：列出 tuleap-* 新版本号）
dnf check-update tuleap\*
# 2) 停服务（官方原样命令）
systemctl stop tuleap nginx httpd
# 3) 升级包（预期结果：事务完成，tuleap 版本号前进）
dnf update
# 4) 部署站点配置、跑数据库迁移（官方原样命令）
tuleap-cfg site-deploy
# 5) 起服务
systemctl start tuleap nginx httpd
官方同时要求：升级前必读对应版本的部署指南（deployment guide）说明。
5.3 升级后验证
systemctl is-active 三单元 active；rpm -q tuleap 版本符合预期；登录平台抽测 Tracker 看板、Git 浏览、REST API（/api/ 探活）三类入口；观察 worker_log 恢复滚动。
六、排障速查（结合本系列实测沉淀）
6.1 故障决策树
Web 打不开？
├─ 否 → systemctl status nginx / tuleap-php-fpm / mysqld
│ └─ 有单元挂 → journalctl -u <单元> 看日志 → 修复后 start
│ └─ 全 active → ss -lntp 查 443 → 防火墙 firewall-cmd --list-all 放行 80/443
├─ 白屏/500 → /var/log/nginx/error.log + /var/opt/remi/php82/log/php-fpm/error.log
└─ 登录死循环 → 统一 /etc/tuleap/conf/local.inc 与 tuleap.conf 的站点 URL → site-deploy + 重启
后台事件不动？→ tail /var/log/tuleap/worker_log；需要细节时调高 $sys_logger_level
6.2 速查表
| 症状 | 一条命令定位 | 处置 |
|---|---|---|
| 前页 502 | systemctl status tuleap-php-fpm | 拉起 fpm；查 PHP 错误日志 |
| 证书告警 | openssl x509 -in <cert> -noout -subject | 按 TLS 配置节换 CA 证书 |
| 邮件不出 | mailq、tail /var/log/tuleap/mail_syslog | 查 Postfix 四行配置与别名库 |
| Git 推拉失败 | tail /var/log/tuleap/git_http_error_log、tail /var/log/tuleap/git_syslog | 核对 SSH 密钥与 Gitolite 权限 |
| API 401 | tail /var/log/tuleap/rest_api_log | 检查令牌/OIDC 配置 |
| 升级后白屏 | tuleap-cfg site-deploy 是否漏跑 | 补跑 site-deploy 并重启三单元 |
延伸阅读
官方文档来源（查询日 2026-10-28）：docs.tuleap.com 安装指南 Upgrade、Troubleshooting 页；管理指南 Services、Logs、Backup/Restore 页；tuleap config-list / tuleap-cfg site-deploy / dnf check-update tuleap\* 等命令均出自上述页面原文。