Traq 3.8.6 配置参数详解

目标：把 Traq v3.8.6 的全部可配置面讲透——文件层（vendor/traq/config/ 下的 database.php、mailer.php、routes.php）与数据层（AdminCP 设置项，存储于 traq_settings 表），覆盖数据库、邮件通知 DSN、站点信息、注册策略、时间格式、工单行为、路由与伪静态、项目级设置与权限、插件管理。本篇所有结构与字段均来自对 v3.8.6 实测环境的逐项核对（实测日期 2026-10-28）。

一、配置体系总览

Traq 的配置分两层，生效优先级与用途不同：

实测的文件层目录清单：

# ls -la /var/www/traq/vendor/traq/config/
total 28
drwxr-xr-x  2 www-data www-data  4096 Oct 22 16:35 .
drwxr-xr-x 10 www-data www-data  4096 Oct 22 16:35 ..
-rw-r--r--  1 www-data www-data  1383 Oct 22 16:35 database.default.php
-rw-r--r--  1 www-data www-data   173 Oct 22 16:35 mailer.default.php
-rw-r--r--  1 www-data www-data 11149 Oct 22 16:35 routes.php

三个文件的角色：

• database.default.php：数据库配置样例。安装向导完成后会生成正式的 database.php（向导存在该文件则拒绝重复安装）；
• mailer.default.php：邮件配置样例，需要「文件方式」配置邮件时复制为 mailer.php 再改；
• routes.php：路由注册表，97 条路由规则全部集中于此（grep -c "Router::" routes.php 实测 = 97）。

数据层设置实测共 21 条记录，改动即存库，无需重启任何服务。

二、database.php：数据库连接配置

2.1 字段逐项说明

安装向导生成的 database.php 实测内容（示例值即本系列实测值）：

<?php
$db = array(
    'driver' => "pdo",
    'type' => "mysql",
    'host' => "127.0.0.1",
    'username' => "traq",
    'password' => "q1w2e3r4",
    'database' => "traq",
    'prefix' => "traq_",
);

2.2 官方样例文件原文

database.default.php 去除版权头后的实测原文，展示了三种连接形态：

// MySQL connection
$db = array(
    'driver'   => 'PDO',       // Leave as is.
    'type'     => 'MySQL',     // Database type.
    'host'     => 'localhost', // Database server.
    'username' => 'root',      // Database username.
    'password' => 'root',      // Database password.
    'database' => 'traq',      // Database name.
    'prefix'   => ''           // Table prefix.
    //'port'     => 3306         // Database server port
);

// SQLite connection
/*
$db = array(
    'driver' => 'PDO',
    'type'   => 'SQLite',
    'path'   => '/path/to/database.sqlite'
);
*/

// Other database
// See: http://php.net/manual/en/pdo.drivers.php
/*
$db = array(
    'driver' => 'PDO',
    'dsn'    => 'PDO DSN goes here'
);
*/

即除 MySQL/SQLite 外，还支持任意「PDO DSN」直填的第三种形态（如 PostgreSQL）。注意大小写在样例中写作 MySQL/SQLite，而向导生成的是小写 mysql，内核按不区分大小写处理，实测两者均可被识别。

2.3 修改与生效

改 database.php 保存即生效（每次请求都会重新加载），无需重启。风险操作提醒：

• 改 prefix 等于指向另一套表，保存后所有数据「消失」——其实是新前缀下没有表，不要误判为丢库；
• 主应用启动时检测 database.php 不存在会直接 302 跳转到 /install，所以备份配置文件是重装/迁移的第一步（详见运维篇）。

三、邮件通知配置（mailer）

3.1 两种模式与加载规则

Traq 的订阅通知（工单变更邮件）基于 Symfony Mailer 6.4 实现，配置入口在 AdminCP「Settings」页，实测有两个字段：

内核的加载逻辑（实测代码核对）：mailer_config 为 config 且 vendor/traq/config/mailer.php 存在时读文件里的 dsn，否则回落到设置里的 mailer_dsn。

3.2 DSN 语法与实测解析

DSN 遵循 Symfony Mailer 规范，常用两种：

sendmail://default                          # 本机 sendmail/postfix
smtp://用户名:密码@smtp主机:端口             # 外部 SMTP（密码需 URL 编码）

用 Traq 自带的 vendor 依赖对两种 DSN 做解析实测（php8.3 -r 加载 vendor/autoload.php 后调用 Transport::fromDsn()）：

# php8.3 -r "require \"/var/www/traq/vendor/autoload.php\"; \
  use Symfony\Component\Mailer\Transport; \
  \$t = Transport::fromDsn(\"smtp://my-username:my-password@smtp.my-site.com:587\"); \
  echo get_class(\$t), PHP_EOL;"
Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport

# php8.3 -r "require \"/var/www/traq/vendor/autoload.php\"; \
  use Symfony\Component\Mailer\Transport; \
  \$t = Transport::fromDsn(\"sendmail://default\"); echo get_class(\$t), PHP_EOL;"
Symfony\Component\Mailer\Transport\SendmailTransport

两类 DSN 均解析成功，分别得到 ESMTP 与 Sendmail 传输器——在 AdminCP 保存 DSN 前可先用此法验证语法。

3.3 config 模式：mailer.php

选择 config 模式时，把样例文件复制为正式文件：

sudo -u www-data cp /var/www/traq/vendor/traq/config/mailer.default.php \
                    /var/www/traq/vendor/traq/config/mailer.php

mailer.default.php 样例原文（实测）：

<?php
return [
    'dsn' => sprintf(
        'smtp://%s:%s@%s',
        urlencode('my-username'),
        urlencode('my-password'),
        'smtp.my-site.com:587',
    )
];

要点：文件返回一维数组，键为 dsn；样例用 urlencode() 处理账号密码是官方推荐写法（密码含 @、# 等字符时必须编码）。保存后 AdminCP 的 mailer_config 切到 config 即生效。

3.4 发件人地址

notification_from_email（AdminCP 可改）决定通知邮件的 From 地址，安装时按安装域名自动生成为 noreply@<host>。本系列实测值（示例 IP 环境保存后）：

# mysql -e "SELECT setting,value FROM traq.traq_settings WHERE setting IN ('notification_from_email','mailer_dsn');"
setting	value
mailer_dsn	sendmail://default
notification_from_email	noreply@192.168.1.100

发送失败时 Traq 会直接在页面抛出「Unable to send email」错误框并带出底层异常消息（见 8.2 排障）。

四、AdminCP 设置项逐项详解

AdminCP 入口 /admin，设置页 /admin/settings。实测页面字段清单如下（字段名即 traq_settings 表的 setting 键）：

4.1 站点与注册

4.2 时间与展示格式

中文环境建议改为 24 小时制，例如 date_time_format 填 H:i Y-m-d、date_format 填 Y-m-d。

4.3 工单行为

4.4 保存实测

保存后 302 回设置页，落库即时生效（实测核对）：

# curl -sS -b cookie.txt -d "settings[site_name]=Ops Lab" ... http://127.0.0.1:8143/admin/settings -D - -o /dev/null
HTTP/1.1 302 Found
Location: /admin/settings

# mysql -N -e "SELECT setting,value FROM traq.traq_settings WHERE setting IN ('site_name','site_url','mailer_config','mailer_dsn');"
mailer_dsn	sendmail://default
notification_from_email	noreply@192.168.1.100
site_name	Ops Lab
site_url	http://192.168.1.100:8143

五、路由注册与伪静态

5.1 routes.php 结构

vendor/traq/config/routes.php 是全站路由的唯一注册处，实测 97 条规则，分四大段：

路由中的 {project} 由常量 PROJECT_SLUG 占位，即项目 slug 直接占据 URL 首段（如 /demo/tickets/1）。改动此文件属于二次开发范畴，改前务必备份，语法错误将导致整站 500。

5.2 Web 服务器伪静态要求

• Nginx：安装篇第五章的 try_files $uri $uri/ /index.php?$query_string; 一条即可。原理：主应用内核按 $_SERVER['REQUEST_URI'] 取路径（实测框架源码核对），回落规则不改变 REQUEST_URI，路由自然正确。
• Apache：把程序目录的 htaccess.txt 改名为 .htaccess（内容为 RewriteRule ^(.*)$ index.php/$1 [L]），并启用 mod_rewrite。
• 安装向导是特例：向导用查询串路由，真实提交地址形如 /install/index.php?/step/1，这是安装篇排障 8.1 的根源，正常跟页面操作不受影响。

六、项目级设置与权限模型

6.1 项目设置

每个项目有自己的设置区（需管理员或项目管理员身份），实测路由：

6.2 全局用户组与项目角色

全局用户组实测（安装即内置三条，traq_usergroups 表）：

mysql> SELECT id,name,is_admin FROM traq.traq_usergroups;
+----+----------------+----------+
| id | name           | is_admin |
+----+----------------+----------+
|  1 | Administrators |        1 |
|  2 | Members        |        0 |
|  3 | Guests         |        0 |
+----+----------------+----------+

权限模型要点（实测代码与数据核对）：

• 全局组（AdminCP → Groups）控制注册、后台访问等全局能力；Administrators 组 is_admin=1，绕过工单创建延迟等限制；
• 项目角色（AdminCP → Roles，存 traq_project_roles）+ 每项目的成员指派（traq_user_roles）控制项目内细粒度权限，权限键如 ticket_properties_set_milestone、ticket_properties_set_version、ticket_properties_set_component、ticket_properties_set_severity、ticket_properties_set_priority、ticket_properties_set_status、ticket_properties_set_assigned_to、ticket_properties_set_tasks、ticket_properties_set_related_tickets 等（控制器实测核对）；
• 权限矩阵实际存储在 traq_permissions 表（组 × 权限键 × 值）。

七、插件管理

7.1 内置插件

v3.8.6 发布包自带三个插件（vendor/traq/plugins/ 实测）：

7.2 管理操作

AdminCP → Plugins（/admin/plugins）列表页可对每个插件执行安装（install）、启用（enable）、停用（disable）、卸载（uninstall），对应实测 URL 形态：

/admin/plugins/enable/{plugin}
/admin/plugins/disable/{plugin}
/admin/plugins/install/{plugin}
/admin/plugins/uninstall/{plugin}

插件启用状态存 traq_plugins 表（enabled 字段），内核每次请求按该表加载 vendor/traq/plugins/{name}/{name}.php——直接删目录而不卸载会留下脏记录，卸载操作请在 AdminCP 完成。

八、排障实录

8.1 改了设置「不生效」

先确认改动是否落库：SELECT setting,value FROM traq.traq_settings WHERE setting='...';。保存动作正常时响应 302 回设置页（见 4.4）；若提交后回到表单且值未变，多半是被表单校验拦下（如日期格式字段为空）。数据层设置即时生效，无需重启；仅当修改的是文件层（database.php/routes.php）且涉及 OPCache 时，才需要 systemctl reload php8.3-fpm。

8.2 页面抛「Unable to send email」

这是通知邮件发送失败的显式错误框，异常消息会带出底层原因（连接被拒/认证失败/DSN 语法错误等）。处理顺序：① 用 3.2 节的 Transport::fromDsn() 解析法验证 DSN；② 确认 mailer_config 与你实际使用的配置方式一致（dsn 模式改了 mailer.php 是不生效的）；③ 本机 sendmail 模式确认主机 MTA 在监听。

8.3 页面 500 但日志没信息

生产配置 display_errors = Off 时异常不可见。定位方法：开启 FPM 层错误日志（php.ini 中 log_errors = On，或 pool 配置 php_admin_value[error_log] 指向可写文件），重载 php8.3-fpm 后复现，读日志。本系列实测示例：缺字段建单触发的 SQLSTATE[HY000]: General error: 1364 Field 'version_id' doesn't have a default value，就是靠该方法定位的（详见运维篇排障 7.1）。

8.4 向导提示「Config file already exists」

向导检测到 vendor/traq/config/database.php 存在即拒绝重装（实测提示语）。重装流程：备份并移走该文件 →（可选）重建空库 → 再访问 /install。若只想升级而不是重装，不要动该文件，走运维篇的升级向导。

九、系列文档导航

• 从零装好的全过程（含 Nginx 配置原文）：《Ubuntu 22.04 安装 Traq 3.8.6 指南》
• 备份恢复、升级向导、API 运维与排障汇总：《Traq 3.8.6 运维命令详解》
• 产品定位、功能全景与竞品量化对比：《Traq 介绍与选型指南》