Tuleap 17.5 配置详解：配置文件与系统变量逐项精讲
Tuleap 17.5 配置体系逐项精讲：/etc/tuleap/conf 配置文件族全景、 tuleap config-set/get/list 现代配置方式、29 个 sys 系统变量分组精讲，以及 MySQL/nginx/Valkey/Postfix 组件配置实战与变更生效三步曲。
Tuleap 17.5 配置详解：配置文件与系统变量逐项精讲
Tuleap 的配置分两层：/etc/tuleap/conf/ 下的 PHP 配置文件族（站点变量、数据库、缓存），以及围绕它的组件配置（MySQL sql-mode、nginx TLS、Postfix 邮件、Valkey）；变更落地统一靠 tuleap-cfg site-deploy 生效。本文逐文件、逐变量讲清每一项改什么、怎么改、如何验证，全部命令与预期结果整理自官方安装指南与管理指南（docs.tuleap.com，查询日 2026-10-28），未实测处均已标注口径与原因（本系列实测环境为 Ubuntu 22.04.5，Tuleap 无法直装，见《Ubuntu 22.04 安装 Tuleap 17.5 指南》的排障实录）。组件背景见《Tuleap 认知与选型：开源 ALM 敏捷项目管理平台全景》。
一、配置体系总览
1.1 两层配置架构
第一层：历史 PHP 变量体系。 官方管理指南 Configuration Variables 页明确：「Historically, default values are defined in /usr/share/tuleap/src/etc/local.inc.dist and can be re-defined in /etc/tuleap/conf/local.inc」——所有 $sys_* 变量的默认值在发行包内，运维只需在 local.inc 里覆盖要改的项。
第二层：现代 config 命令体系。 同页指出：「The modern version of managing configuration variables is done with tuleap config-set, you can get the list of variables with their default values with tuleap config-list」。优先用命令而非手改文件，可避免语法错误且随 site-deploy 一致生效。
# 预期结果：列出全部可配置变量及其默认值（官方文档明确支持）
tuleap config-list
1.2 配置文件全景
| 文件 | 归属 | 作用 | 出处 |
|---|---|---|---|
/etc/tuleap/conf/local.inc | Tuleap 核心 | $sys_* 系统变量覆盖；站点 URL 在此定义 | 管理指南 Configuration Variables / Troubleshooting |
/etc/tuleap/conf/database.inc | Tuleap 核心 | 数据库连接账号与密码（tuleapadm） | 管理指南 Services（MySQL 节） |
/etc/tuleap/conf/redis.inc | Tuleap 核心 | Valkey 连接参数（监控场景） | 安装指南 Valkey Configuration |
/etc/my.cnf.d/tuleap.cnf | MySQL 8.4 | 强制 sql-mode="NO_ENGINE_SUBSTITUTION" | 安装指南 Prepare the database |
/etc/nginx/conf.d/tuleap.conf | nginx | 站点入口、ssl_certificate / ssl_certificate_key | 安装指南 TLS configuration |
/etc/httpd/conf/httpd.conf + /etc/httpd/conf.d/ | Apache | 应用层主配置与子配置 | 管理指南 Services（Apache 节） |
/etc/valkey/valkey.conf | Valkey | 缓存监听与 AOF 持久化 | 安装指南 Valkey Configuration |
/etc/postfix/main.cf、/etc/aliases、/etc/aliases.codendi | Postfix | 邮件域名与别名映射 | 管理指南 Services（Postfix 节）/ 安装指南 Mail configuration |
/root/.tuleap_passwd | 安装产物 | admin 初始密码（官方要求尽快删除） | 安装指南 First connection |
二、核心系统变量逐项精讲（$sys_*）
以下变量与默认值全部来自官方 Configuration Variables 页（查询日 2026-10-28），按用途分组。
2.1 站点身份与基础行为
| 变量 | 默认值 | 说明与运维建议 |
|---|---|---|
$sys_default_domain | %sys_default_domain% | 站点「裸域名」，也是 Web 服务器默认名；可带端口（测试服常用）。改它必须与 nginx 配置同步，否则登录死循环（排障见运维篇） |
$sys_cookie_prefix | TULEAP | 会话 Cookie 前缀；多实例集群需保持一致 |
$sys_auth_type | codendi | 认证源：本机库 codendi 或 ldap；接企业 AD/LDAP 必改 |
$sys_supported_languages | en_US, fr_FR, pt_BR, ko_KR | 平台支持语言列表（官方注明当前可用 en_US/fr_FR/pt_BR） |
$sys_lang | en_US | 站点默认语言 |
$sys_use_project_registration | 1 | 是否开放自助建项目；内部管控平台建议改 0 |
$sys_user_can_choose_project_privacy | 1 | 建项目时是否显示公开/私密切换；改 0 隐藏该选项 |
$sys_display_project_privacy_in_service_bar | 1 | 服务栏是否显示项目可见性 |
$sys_use_trove | 1 | 项目分类树（软件地图）；单体部署可关 |
2.2 账号生命周期与安全
| 变量 | 默认值 | 说明 |
|---|---|---|
$sys_session_lifetime | 1209600 | 会话最长存活（秒），默认 14 天（3600×24×14）；合规场景收紧到 8 小时即 28800 |
$sys_pending_account_lifetime | 60 | 未激活账号保留天数，到期删除 |
$sys_password_lifetime | 0 | 密码有效期（天），0 = 永不过期；等保场景建议 90 |
$sys_suspend_inactive_accounts_delay | 0 | 不活跃账号自动冻结（天），0 = 不检查 |
$sys_suspend_non_project_member_delay | 0 | 不属于任何项目的账号冻结天数，0 = 永不 |
$sys_file_deletion_delay | 3 | 文件「删除后」到真正抹除的宽限天数，用于误删恢复 |
$sys_max_size_upload | 67108864 | 上传上限（字节），默认 64 MiB |
$sys_frs_license_mandatory | 0 | 从 FRS 下载是否强制确认许可；1 时必须配 $sys_exchange_policy_url |
$sys_exchange_policy_url | '' | 许可确认弹窗链接的政策页 URL |
2.3 邮件与通知
| 变量 | 默认值 | 说明 |
|---|---|---|
$sys_email_admin | codendi-admin@%sys_default_domain% | 站点管理员邮箱（页面/文档展示） |
$sys_email_contact | codendi-contact@%sys_default_domain% | 对外联系邮箱 |
sys_noreply | "Tuleap" <noreply@%sys_default_domain%> | 系统发信 From 地址 |
$sys_default_mail_domain | '' | 邮件网关特性的域，默认取 $sys_default_domain |
$sys_max_number_of_emailed_people | 100 | 新闻群发人数硬上限 |
$sys_mail_secure_mode | 0 | 安全要点：为 0 时邮件可能外泄私有项目信息给非成员；对外开放注册的实例建议改 1 |
2.4 平台行为与集成
| 变量 | 默认值 | 说明 |
|---|---|---|
$sys_logger_level | warning | 全平台日志级别，可选 emergency/alert/critical/error/warning/notice/info/debug（详见运维篇日志节） |
$sys_allow_empty_svn_commit_message | 1 | 是否允许空 SVN 提交说明；治理场景改 0 强制填写 |
$sys_project_backup_path | $tmp_dir | 已删除项目的归档路径 |
$sys_csp_script_scr_whitelist | '' | CSP script-src 白名单，页面引用外部 JS 时填写（空格分隔多个来源） |
$sys_trusted_proxies | '' | 安全要点：前置反向代理/LB 的 IP 逗号列表。启用后 Tuleap 信任 X_FORWARDED_FOR、X_FORWARDED_PROTO、REMOTE_ADDR 三个头——官方警告若代理未正确设置这些头，会成为攻击注入点。方案 A 架构（Ubuntu 反代 + EL9 后端）必配 |
$last_access_resolution | 3600 | 用户「最近访问」时间刷新间隔（秒），调太小影响性能 |
2.5 变量的正确改法
# 预期结果：以 config-set 修改变量（官方推荐的现代方式，变量名不带 $ 前缀）
tuleap config-set sys_default_domain tuleap.example.com
# 预期结果：回读确认
tuleap config-get sys_default_domain
# 预期结果：全量变更落地（含模板渲染、数据库迁移检查）
tuleap-cfg site-deploy
手改 /etc/tuleap/conf/local.inc 依然有效（历史方式），但改完同样要执行 tuleap-cfg site-deploy，并重启 tuleap nginx httpd。
三、组件配置实战
3.1 数据库连接与专用账号
官方 Services 页定义了三个数据库账号的职责边界：
| 账号 | 权限 | 用途 |
|---|---|---|
root | 全库管理 | 仅用于授权/回收等管理操作 |
tuleapadm | tuleap 库读写，仅限本机 | 所有 PHP 脚本的运行身份；凭据在 /etc/tuleap/conf/database.inc |
cxuser | 项目导出库只读、免密 | 项目数据库导出专用 |
巡检命令（官方示例）：
mysql -u tuleapadm -p -e "show databases;"
预期结果：至少包含主库 tuleap 与启用插件各自的库；备份策略见运维篇。
3.2 TLS 与 nginx 入口
官方 TLS configuration 页要点：默认使用自签名证书，生产必须换 CA 证书（推荐 certbot/Let's Encrypt）；证书路径在 /etc/nginx/conf.d/tuleap.conf 的两个指令：
ssl_certificate /etc/letsencrypt/live/tuleap.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/tuleap.example.com/privkey.pem;
nginx -t && systemctl restart nginx
预期结果：nginx -t 输出 syntax is ok 与 test is successful；浏览器访问无证书告警。官方同时提醒：改完 nginx 配置必须 systemctl restart nginx。
3.3 Valkey（Prometheus 监控场景）
官方 Valkey Configuration 页完整流程（不使用监控功能可整体跳过）：
# 1) 生成随机密码（官方原样命令）
dd if=/dev/urandom bs=1 count=32 2>/dev/null | base64 -w 0 | rev | cut -b 2- | rev
# 2) 安装
dnf install -y valkey
修改 /etc/valkey/valkey.conf 三处：#requirepass foobared 改为 requirepass <上一步密码>；appendonly no 改为 appendonly yes；auto-aof-rewrite-percentage 100 改为 20、auto-aof-rewrite-min-size 64mb 改为 200kb。
创建 /etc/tuleap/conf/redis.inc（PHP 数组语法，官方原文）：
<?php
$redis_server = '127.0.0.1';
$redis_port = 6379;
$redis_password = 'PREVIOUS_GENERATED_PASSWORD';
收紧权限并生效：
chown codendiadm:codendiadm /etc/tuleap/conf/redis.inc
chmod 640 /etc/tuleap/conf/redis.inc
systemctl enable valkey
systemctl restart tuleap valkey
预期结果（官方原文）：服务就绪后监控特性即可使用 Valkey。
3.4 Postfix 邮件
官方 Mail configuration 页：Tuleap 默认经 Postfix 收发邮件，/etc/postfix/main.cf 需确认/修改四行：
myhostname = tuleap.example.com
alias_maps = hash:/etc/aliases,hash:/etc/aliases.codendi
alias_database = hash:/etc/aliases,hash:/etc/aliases.codendi
recipient_delimiter = +
预期结果：newaliases 重建别名库无报错；平台发出的通知邮件 From 为 sys_noreply 定义的地址。
3.5 前置反向代理（方案 A 架构）
Ubuntu 侧 nginx 做四层/七层转发到 EL9 后端时，后端 Tuleap 必须配置：
tuleap config-set sys_trusted_proxies 192.168.1.62
tuleap-cfg site-deploy
预期结果：用户真实 IP 正确记录、HTTPS 判定不回环跳转。官方安全警告重申：代理必须正确设置 X_FORWARDED_FOR / X_FORWARDED_PROTO / REMOTE_ADDR，否则该信任链是注入点。
四、变更生效与验证
4.1 生效三步曲
tuleap-cfg site-deploy # 部署站点配置、跑数据库迁移检查
systemctl restart tuleap nginx httpd
ss -lntp | grep -E ':443|:22|:25'
预期结果：site-deploy 正常退出无 PHP Fatal；三单元 active (running)；443 在监听。
4.2 验证清单
tuleap config-get <变量>与预期一致；curl -kI https://tuleap.example.com返回HTTP/2 200（或 302 到登录页）；- 以示例账号
admin / q1w2e3r4登录，改密码弹窗、项目创建等核心页无 500； - 若动了域名相关变量：全站退出重新登录一次，确认无登录死循环（该故障的完整排障见运维篇）。
4.3 配置层高频故障
| 症状 | 根因 | 处置 |
|---|---|---|
| 登录无限跳回 | local.inc 域名与 tuleap.conf URL 不一致 | 两处统一为同一地址后 site-deploy + 重启 |
| 页面 500 白屏 | PHP/nginx 配置语法或权限错误 | nginx -t；查 PHP-FPM error.log（路径见运维篇） |
| 邮件发不出 | myhostname 未设或别名库未重建 | 按 3.4 修四行 + newaliases |
| 代理后拿到内网 IP/跳 HTTP | $sys_trusted_proxies 未配或代理头缺失 | 按 3.5 配置并核对代理头 |
延伸阅读
- 《Tuleap 认知与选型：开源 ALM 敏捷项目管理平台全景》：为什么这些配置项长这样；
- 《Ubuntu 22.04 安装 Tuleap 17.5 指南》：安装与迁移先行步骤；
- 《Tuleap 17.5 运维命令手册：服务、备份与排障》：配置改完之后的日常维护。
官方文档来源（查询日 2026-10-28）：docs.tuleap.com 管理指南 Configuration Variables、Services 页；安装指南 Prepare the database / Setup / TLS configuration / Mail configuration / Valkey Configuration / Troubleshooting 各页。