ZenTao 22.6 配置参数详解

版本基线：ZenTao 开源版 22.6（官方 Docker 形态，MYSQL_INTERNAL=true 单机模式） 参数来源：配置文件逐行实测 + 镜像默认环境变量清单 + 官方文档，非参数罗列想象 前置阅读：《ZenTao Docker Compose 部署实战》

一、配置体系总览

禅道的运行时配置由三层叠加而成，优先级从低到高：

关键机制：config/my.php 在加载末尾被 config.php include，其中 installed=true 是整个框架"已安装"的判定标志；my.php 不存在或为空时框架进入安装向导。官方运维文档强调的"备份配置文件"指的就是这个文件。

容器化形态下还有第四层：镜像环境变量。首次安装时 s6 初始化脚本把 ZT_*/PHP_* 等环境变量渲染进配置与 php.ini；安装完成后则以 my.php 与数据库配置为准。该层级完整清单见第八节。

二、my.php 实测全文与逐行解读

22.6 安装向导完成后生成的 /data/zentao/config/my.php（软链到应用配置目录）实测内容如下：

<?php
$config->installed      = true;
$config->debug          = false;
$config->requestType    = 'GET';
$config->timezone       = 'Asia/Shanghai';
$config->db->driver     = 'mysql';
$config->db->host       = '127.0.0.1';
$config->db->port       = '3306';
$config->db->name       = 'zentao';
$config->db->user       = 'root';
$config->db->encoding   = 'utf8mb4';
$config->db->collation  = 'utf8mb4_unicode_ci';
$config->db->password   = '123456';
$config->db->prefix     = 'zt_';
$config->db->strictMode = false;

$config->webRoot        = getWebRoot();
$config->default->lang  = 'zh-cn';
$config->customSession  = true;

逐项解读：

• installed：安装完成标志。false 或缺失时所有请求被重定向到安装向导；也是镜像内 sentry 守护进程判断"可以移除 install.php"的依据。
• debug：打开后框架输出调试信息并记录更详细日志（/data/zentao/tmp/log/）。生产建议 false，排障期临时开启。
• requestType：URL 风格，GET（index.php?m=user&f=login）或 PATH_INFO（user-login.html）。详见第四节。
• timezone / default->lang：默认时区与界面语言，对应安装向导第 1 步的两个选择。
• db.*：数据库连接六件套 + 编码/排序规则/前缀/严格模式，详见第三节。
• webRoot：站点根路径。getWebRoot() 由入口自动探测；反向代理部署在子路径下时需手工固化为 /zentao/ 这类形式。
• customSession：会话存储路径自定义开关，true 时 session 写入应用 tmp 目录（容器内为 /data 持久化的一部分），避免系统默认路径权限问题——这也是安装向导"环境检查"步骤自动完成的修正。

注意 requestType='GET'：尽管镜像默认环境变量声明了 ZT_REQUEST_TYPE=PATH_INFO，实测 22.6 镜像写出的 my.php 仍是 GET。脚本集成请以实测生效值为准（详见第十节排障 1）。

三、数据库连接参数

3.1 内置数据库模式（单机）

单机模式下数据库就在本机，my.php 的 db->host=127.0.0.1 指向内置 MariaDB：

• 内置 MariaDB 数据落盘在 /data/mysql/（data/etc/logs/tmp 四个子目录），修改 MySQL 配置直接编辑 /data/mysql/etc/my.cnf 后重启服务；
• 内置库 root 密码由环境变量 MYSQL_ROOT_PASSWORD 控制，官方默认 123456；修改后需同步 my.php 的 db->password；
• 需要远程连库（如 DBA 工具直连）时，映射端口并在库内执行 rename user 'root'@'localhost' to 'root'@'%';（官方 FAQ 276 篇方案）。

3.2 外部数据库模式（生产推荐）

生产环境建议将数据库拆到独立实例，两种接法：

方式 A：环境变量注入（首次安装前）。镜像支持 ZT_DB_* 系列变量（20+ 版本起新增，兼容旧 ZT_MYSQL_* 与通用 MYSQL_* 变量）：

方式 B：手工改 my.php。已安装系统迁移数据库时，直接编辑 my.php 的 db->host/port/user/password 并保持 installed=true，重启生效；旧数据用 mysqldump 导出、导入新库（导出命令见运维篇）。

db->strictMode=false 是禅道刻意为之：关闭 MySQL 严格模式以容忍历史数据兼容场景，外部库建库时不要强开 STRICT_TRANS_TABLES，否则个别旧数据写入会报错。编码建议与实测值保持一致：utf8mb4 / utf8mb4_unicode_ci。

四、请求路由与 webRoot

• requestType=GET：index.php?m=<module>&f=<method>&<params>，兼容性最好，默认值；
• requestType=PATH_INFO：<module>-<method>-<param>.html，URL 更友好，需要 Web 服务重写规则配合；切换后 webRoot 下所有链接风格变化，已有外部收藏/集成链接会失效，切换需谨慎；
• webRoot：反代子路径部署的关键参数。例如通过 https://pm.example.com/zentao/ 访问时，应将 my.php 的 config->webRoot 固化为 '/zentao/'（镜像环境变量 ZT_WEB_ROOT 可在首次渲染时注入）。

五、会话与安全

• 会话存储：customSession=true 时 session 文件写入 /data/php/session/（容器形态），随数据卷持久化；多实例负载均衡场景应改用 Redis（环境变量 PHP_SESSION_TYPE=redis + ZT_REDIS_HOST/PORT/PASSWORD，镜像 21.2+ 支持），并把会话超时（config->sessionLife，默认 86400 秒）按需调整；
• 登录加密：登录密码客户端执行 md5(md5(明文)+随机数) 后提交，服务端同规则校验（见部署篇排障 4）；随机数接口为 index.php?m=user&f=refreshRandom；
• CSRF 防御：框架对所有 POST 校验 Referer 同源，失败时静默清空请求体（framework/base/router.class.php）。浏览器无感；脚本集成必须带 Referer 头；
• 弱密码策略：内置弱密码清单（config->safe->weak）+ 复杂度校验（至少 6 位含大小写与数字），管理员连续失败锁定（user->lockMinutes，默认锁定阈值 user->failTimes）；
• debug：排障期临时 true，日志落在 /data/zentao/tmp/log/，用完即关。

六、附件上传相关

附件上限由 PHP 层与禅道层双重控制，实测容器默认值：

调大上传上限需要三处同步：php.ini 两个值 ≥ 禅道页面值；php-fpm/Apache 无额外限制（容器内 Apache 参数 APACHE_MAX_REQ_WORKERS=150 等已预置）；PHP_SESSION_PATH 等路径保持默认。附件实际落盘在 /data/zentao/www/data/（即应用 www/data 附件目录），随数据卷持久化，是备份四要素之一。

七、邮件配置

邮件支持 SMTP 直发，两处配置：

1. 环境变量（渲染期）：SMTP_ENABLED、SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASS、SMTP_FROMNAME，适合首次部署即定型的场景；
2. 后台界面（运行期，常用）：后台 → 系统 → 邮件，配置发信方式（SMTP/phpmail）、服务器、端口、账号密码与发件人，保存后用页面的"测试发信"验证。

邮件采用异步发送：发送任务入队，由内置定时任务 mail asyncSend（每 1 分钟）消费——若邮件"保存成功但收不到"，先检查定时任务是否被停用（后台 → 系统 → 定时），再看 asyncSend 的执行日志。该机制与运维篇的 crond 一节联动。

八、镜像环境变量全景

以下为 22.6 官方镜像内 /etc/s6/s6-init/envs 实测整理的环境变量清单（按域分组，值为镜像默认）：

使用原则：环境变量主要影响首次初始化；安装完成后以 my.php 与后台界面配置为准，改环境变量不会回写已生成的 my.php。

九、/data 持久化目录清单

容器形态下 /data 是唯一数据卷，实测目录布局与用途：

整机迁移 = 停服务 + 拷贝 /data 整目录；升级 = 拉新镜像重挂同一 /data。

十、常用配置修改实操

以下操作均在 22.6 实测：

1. 切换界面语言：改 my.php $config->default->lang = 'en'; 重启；或登录页右上角即时切换（写 Cookie）。
2. 调整时区：my.php $config->timezone = 'Asia/Shanghai';，同步影响日志时间与定时任务触发。
3. 外接数据库：按第三节 3.2 方式 B 改 my.php，迁移数据用 mysqldump zentao > zentao.sql 导出、新库导入。
4. 调大附件上限：php.ini 环境变量 + 后台"最大上传"同步改（见第六节）。
5. 开启调试：my.php $config->debug = true;，查 /data/zentao/tmp/log/，结束回 false。

十一、排障实录

1）ZT_REQUEST_TYPE 环境变量未生效 现象：镜像声明 ZT_REQUEST_TYPE=PATH_INFO，但安装后 my.php 实测为 requestType='GET'，.html URL 全部 302 回查询串形式。 处置：以实测生效值为准——脚本集成一律用 index.php?m=&f= 查询串形式；确需 PATH_INFO 时手工改 my.php 并验证重写规则可用后再切换。

2）POST 数据被清空 现象：接口/脚本方式提交任何禅道表单均"成功但无效果"。 原因与解法：CSRF 校验 Referer（见第五节），请求补 -e <同源URL> 即可。此问题同样影响安装向导（部署篇排障 1）。

3）邮件发不出去 排查顺序：后台邮件测试发信 → 定时任务 mail asyncSend 是否 normal → /data/zentao/tmp/log/ 邮件日志 → SMTP 服务商的授权码/端口（465/587）限制。

4）远程连不上内置数据库 按官方 FAQ 检查两点：端口是否映射（-p 33060:3306 之类）；库内是否放开 root 远程（rename user 'root'@'localhost' to 'root'@'%'）。生产环境不建议长期开放 root 远程，建议建专用账号授权 zentao 库。

5）session 频繁失效 确认 customSession 与 PHP_SESSION_PATH 指向的目录可写且随数据卷持久化；多实例场景必须切 Redis 会话（第五节），否则请求被负载均衡到另一实例即丢失会话。

十二、小结

禅道的配置面收敛为"my.php + 后台界面 + 镜像环境变量"三处，其中 my.php 是唯一需要手工维护的文件，改前备份、改后重启即可生效。下一篇《ZenTao 22.6 常用 CLI 命令与运维实战》把本文的备份机制、定时任务和会话安全落到命令行实操与 API 集成上。

参考资料

• 官方备份文档（配置文件/附件/数据库/代码四要素）：https://www.zentao.net/book/zentaopmshelp/42.html
• 官方远程连接数据库 FAQ：https://www.zentao.net/book/zentaopmshelp/276.html
• 站内文章：《ZenTao Docker Compose 部署实战》
• 站内文章：《ZenTao 介绍与选型指南》