TestLink 1.9.20 配置参数详解

目标：把 TestLink 1.9.20 的配置面拆成「编排层环境变量 → 主配置 config.inc.php → 覆盖层 custom_config.inc.php」三层，逐项说明常用参数的作用、默认值、实测生效方式与生产建议。所有默认值均来自本机运行环境内 config.inc.php 的逐行实读（2026-10-25），非文档转述。

一、环境信息

取证方式：docker exec 进入运行环境后 grep -n 逐行读取 config.inc.php，下文标注的行号即该文件内的真实行号。

二、配置体系总览

TestLink 的配置分三层，后层覆盖前层：

覆盖层的用法：把 custom_config.inc.php.example 复制为 custom_config.inc.php，在里面写同名变量赋值即可——主配置在文件末尾会 require 覆盖层，因此覆盖层里的赋值优先级更高，且升级时不会被上游覆盖。

常用参数速查（默认值取自本机实读）：

三、数据库连接配置

数据库连接由安装向导写入两处：config.inc.php 内的 $g_db* 变量与 config_db.inc.php。实测安装成功后主机地址为服务名 db、库名 testlink、账号 testlink（或向导创建的管理员同名账号）。

生产建议：

• 账号最小权限：日常运行账号只需目标库的 SELECT/INSERT/UPDATE/DELETE 与 EXECUTE（UDFStripHTMLTags 函数），不必保留安装阶段用到的 CREATE USER/GRANT OPTION——安装完成后可收回。
• 字符集：库必须是 utf8mb4，否则中文用例与附件名会出现截断或乱码。本机编排在数据库启动参数里固定了 --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci。
• 函数创建开关：--log-bin-trust-function-creators=1 只在安装阶段必须；若环境默认开启该限制，缺少它会导致安装创建自定义函数失败。
• 连接数：TestLink 是同步 PHP 应用，连接数压力主要来自并发用户数，MySQL 默认 max_connections=151 对中小团队足够。

四、会话与登录安全

会话超时（$tlCfg->sessionInactivityTimeout，默认 9900 秒）：空闲超过 165 分钟会话失效，用户被弹回登录页。安全要求高的环境建议降到 1800～3600 秒。

登录口令长度上限（$tlCfg->loginPagePasswordMaxLenght，默认 40）：只限制输入框可接受的长度，不是强度策略；口令强度由「管理员设置用户」流程约束。

登录页与 CSRF：登录表单固定携带 CSRFName / CSRFToken 两个隐藏字段，由服务端生成、提交时校验。这意味着任何脚本化登录都必须先 GET 登录页取令牌——这也是部署篇里用 curl 登录需要两步的原因。成功登录后颁发的会话 cookie 名为 TESTLINK1920TESTLINK_USER_AUTH_COOKIE（64 字符），另有一个 PHPSESSID。

注销地址（$tlCfg->logoutUrl，默认空）：留空时注销走内置 logout.php；配置成外部 SSO 注销地址可实现单点退出。

默认角色（$tlCfg->default_roleid = TL_ROLES_GUEST）：通过 LDAP/外部认证首次登录的新用户默认只有 guest 权限，必须由管理员逐项目授权——生产上这是防止越权的关键默认值，不要轻易改成 TL_ROLES_TESTER。

五、日志与审计

生产建议：把 log_path 挂到宿主卷并接入日志轮转；log_level 长期保持 ERROR，仅在排障窗口临时调整后回滚。

六、邮件通知（SMTP）

TestLink 的用户邀请、密码重置、任务分配通知都依赖 SMTP。主配置默认全是占位值，不改就一封邮件也发不出：

$g_smtp_host        = '[smtp_host_not_configured]';
$g_tl_admin_email   = '[testlink_sysadmin_email_not_configured]';
$g_from_email       = '[from_email_not_configured]';
$g_return_path_email= '[return_path_email_not_configured]';
$g_phpMailer_method = PHPMAILER_METHOD_SMTP;
$g_smtp_port        = 25;
$g_SMTPAutoTLS      = false;

生产模板（写入 custom_config.inc.php，示例值按实际替换）：

<?php
$g_smtp_host          = 'mail.example.com';
$g_smtp_port          = 587;
$g_smtp_username      = 'testlink@example.com';
$g_smtp_password      = 'q1w2e3r4';
$g_smtp_connection_mode = 'tls';
$g_SMTPAutoTLS        = true;
$g_tl_admin_email     = 'qa-lead@example.com';
$g_from_email         = 'testlink@example.com';
$g_return_path_email  = 'testlink@example.com';
$g_mail_priority      = 3;

注意：$g_smtp_connection_mode 与 $g_SMTPAutoTLS 要配对设置（587 端口 + tls + AutoTLS=true 是常见组合）；只改端口不改模式，握手会失败且日志里只留一行 SMTP Error，很容易误判为账号问题。

七、附件仓库

附件仓库的增长是 TestLink 长期运维的主要磁盘压力来源（执行证据截图、需求文档）。建议：挂独立卷 + 定期归档历史项目的 upload_area/<project> 子目录，并把备份与数据库备份放在同一次一致性快照里。

八、XML-RPC 接口

安全建议：若暂时不做 CI 集成，把 $tlCfg->api->enabled 置 FALSE 可减少一个攻击面；启用时应在反向代理层限制来源网段，因为接口本身只靠 devKey 认证，没有 IP 白名单也没有限流。

九、界面与本地化

十、生产环境配置模板

把下列内容写入 /var/www/testlink/custom_config.inc.php，即可在不改主配置的前提下完成加固：

<?php
// 语言与会话
$tlCfg->default_language = 'zh_CN';
$tlCfg->sessionInactivityTimeout = 3600;

// 日志
$tlCfg->log_level = 'ERROR';
$g_removeEventsOlderThan = 90;

// 新用户默认最小权限
$tlCfg->default_roleid = TL_ROLES_GUEST;

// 接口：不做 CI 集成时关闭
$tlCfg->api->enabled = FALSE;

// SMTP（按实际替换）
$g_smtp_host = 'mail.example.com';
$g_smtp_port = 587;
$g_smtp_connection_mode = 'tls';
$g_SMTPAutoTLS = true;
$g_smtp_username = 'testlink@example.com';
$g_smtp_password = 'q1w2e3r4';
$g_from_email = 'testlink@example.com';

改完无需重启服务——PHP 每个请求都会重新加载配置；但建议立刻访问一次登录页确认没有语法错误，语法错误会导致全站 500。

十一、FAQ

1. 改了 config.inc.php 但没生效？ 检查是否同时存在 custom_config.inc.php 且其中对同名变量有赋值——覆盖层优先。

2. 升级后配置全丢？ 因为你改的是 config.inc.php（会被新版本覆盖）。所有自定义项都应放 custom_config.inc.php。

3. 邮件一直发不出，日志只有 SMTP Error？ 先核对端口与加密模式是否配对（25/明文、587/STARTTLS、465/SSL），再核对发件地址是否被邮件服务商要求与登录账号一致。

4. 会话频繁掉线？ sessionInactivityTimeout 被调得过小，或反向代理层有自己的会话超时（两处取更短的那个）。

5. 附件上传成功但页面下载 404？ $g_repositoryPath 指向的目录不可写，或服务重建后该目录未挂卷导致文件丢失。

6. 中文界面切换后仍显示英文？ default_language 只影响新用户；已登录用户在「我的设置」里有个人语言偏好，优先于全局默认。

十二、参考链接

• TestLink 官网文档：https://testlink.org/docs/ （查询日期 2026-10-25）
• 主配置样例（发行包内）：config.inc.php 与 custom_config.inc.php.example
• GitHub 源码仓库：https://github.com/TestLinkOpenSourceTRMS/testlink-code
• 本专栏：《TestLink 1.9.20 介绍与选型指南》、《TestLink 1.9.20 Docker Compose 部署指南》