MantisBT 2.28.4 配置参数详解

目标：讲清 MantisBT 2.28.4 的配置体系（默认值 → 实例配置 → 字符串覆盖三层）并给出站点界面、邮件、附件、权限、注册安全五类核心参数的实测闭环——每项都走「改参数 → 验证生效」全流程，全部命令与回显来自 Ubuntu 22.04 + Apache + MariaDB + PHP 8.1 的实测服务器。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• MantisBT：2.28.4（官方 tarball 安装，部署于 /var/www/html/mantisbt）
• Web：Apache 2.4.52（mod_php）；数据库：MariaDB 10.6.23；PHP：8.1.2-1ubuntu2.27
• 邮件链路：Postfix（本机投递）+ PHPMailer SMTP 方式，测试落点 /var/mail/root
• 演示账号：administrator / q1w2e3r4；实验项目 demo-app、问题 #1、用户 dev1
• 安装过程与业务闭环见《Ubuntu 22.04 安装 MantisBT 指南》；本文所有配置改动都在该环境实测验证。

二、前置条件

• 已按安装指南完成 2.28.4 安装并能登录管理界面。
• 已确认实例配置文件存在：

ls -l /var/www/html/mantisbt/config/config_inc.php

实测输出：

-rw-r--r-- 1 www-data www-data 564 Oct 21 07:20 /var/www/html/mantisbt/config/config_inc.php

• 修改配置文件的写入权限归 www-data（或以 root 编辑后 chown 回去）；MantisBT 每次请求都会重新读取配置，改完保存即生效，无需重启 Web 服务。

三、参数查看与修改方式

3.1 三层配置体系

MantisBT 的参数按以下优先级从低到高覆盖（官方 config_defaults_inc.php 头注与 Admin Guide「Configuration」章口径，查询日期 2026-10-21）：

1. 发行包默认值：/var/www/html/mantisbt/config_defaults_inc.php——全部参数的官方默认值与逐项注释都在这里，是「这个参数默认是多少」的唯一权威答案。
2. 实例配置：/var/www/html/mantisbt/config/config_inc.php——安装向导生成，运维自定义参数写这里；不存在于实例文件中的参数自动回落到第 1 层。
3. 库内动态配置：管理界面「管理 → 管理配置」（adm_config_report.php）写入 mantis_config_table，可按项目/用户维度生效；与文件配置同名时优先于文件层。

字符串层另有专门机制：/var/www/html/mantisbt/config/custom_strings_inc.php 在每次加载语言包后追加执行，可覆盖任意 $s_* 界面文案（含本地化枚举标签），是实现「改界面文字」「自定义访问级别名」的标准入口。

💡 说明：mantis_config_table 里的动态配置对排查很隐蔽——界面上改过一次的参数会进库并覆盖文件值。遇到「改了 config_inc.php 不生效」先到「管理配置」页确认同名键是否已在库内。

3.2 查看参数默认值

直接在默认值文件里查（以 $g_smtp_port 为例）：

grep -n -B2 'g_smtp_port = ' /var/www/html/mantisbt/config_defaults_inc.php | head -5

实测输出：

 * @global int $g_smtp_port
$g_smtp_port = 25;

3.3 环境体检

官方健康检查页 admin/check/index.php 会逐项校验配置合理性（PHP 扩展、目录权限、邮箱三项、上传上限等），每项输出 PASS/WARN/FAIL。安装刚完成时的实测警告节选：

webmaster_email configuration option has a valid email address specified
You need to specify a valid email address for the webmaster_email configuration option

from_email configuration option has a valid email address specified
You need to specify a valid email address for the from_email configuration option

max_file_size MantisBT option is less than or equal to the upload_max_filesize directive in php.ini
max_file_size is currently 5,242,880 bytes which i...

这三类警告分别在本文 5.2、5.3 节的配置闭环中处理。

四、参数总览

本文实测涉及的核心参数与默认值（默认值均来自发行包 config_defaults_inc.php 实查）：

关键差异/选型解读：界面与邮件类参数改实例文件即可；附件要同时满足 MantisBT 与 php.ini 两侧上限；权限枚举是「全局枚举 + 本地化标签」成对出现的特殊参数，单独改一半会显示异常（见 5.4 实测排障）。

五、核心参数分类详解

5.1 站点与界面参数

这组参数控制系统对外呈现的名称、语言与基准 URL。在 config_inc.php 追加：

$g_window_title   = '内部缺陷跟踪平台';
$g_default_language = 'chinese_simplified';
$g_show_version   = ON;

逐项说明：$g_window_title 出现在每个页面 <title> 尾部与导航栏；$g_default_language='auto' 表示跟随浏览器 Accept-Language，固定为 chinese_simplified 后所有未自选语言的用户直接使用简体中文；$g_show_version=ON 允许界面展示版本号（默认 OFF 不显示）。

验证（改完直接刷新登录页，无需重启）：

curl -s -m 30 http://localhost:8132/mantisbt/login_page.php | grep -oE '<title>[^<]*'

实测输出（同时验证了窗口标题与语言包两项：标题前半段「登录」来自中文语言包）：

<title>登录 - 内部缺陷跟踪平台

基准 URL 与时区：$g_path 由安装向导按访问地址生成（本文实测值 http://localhost:8132/mantisbt/），反向代理或换域名后必须手工修正，否则页面内绝对链接与邮件里的跳转链接全部指错；$g_default_timezone 向导写入 UTC，国内部署建议改 'Asia/Shanghai'。加密盐 $g_crypto_master_salt 是实例唯一秘密（实测生成的样例 MQskrbUlDb7M+55PKtk7VLtKH44X21FhkbC8trXH0Vk=），跨实例复制它等于共享密钥，升级换机时必须原样迁移同一实例的盐。

界面文案覆盖：登录页右下角的注册入口默认文案是「注册一个新帐号」，用 custom_strings_inc.php 覆盖：

<?php
/* 自定义字符串：登录页注册入口文案 */
$s_signup_link = '注册内部平台账号';

验证：

curl -s -m 30 http://localhost:8132/mantisbt/login_page.php | grep -oE '注册内部平台账号|注册一个新帐号'

实测输出：

注册内部平台账号

5.2 邮件通知参数

MantisBT 通过 PHPMailer 发信，三种通道由 $g_phpMailer_method 决定：PHPMAILER_METHOD_MAIL（PHP mail()）、PHPMAILER_METHOD_SENDMAIL（直接调 sendmail）、PHPMAILER_METHOD_SMTP（网络 SMTP，默认 host localhost:25）。生产建议 SMTP。三个发件身份参数是健康检查的重点（默认 example.com 会被判 WARN）。

第一步：改实例配置（config_inc.php）：

$g_from_email       = 'mantisbt@mantis.local';
$g_webmaster_email  = 'admin@mantis.local';
$g_return_path_email = 'admin@mantis.local';
$g_phpMailer_method = PHPMAILER_METHOD_SMTP;
$g_smtp_host        = 'localhost';
$g_smtp_port        = 25;

逐项说明：$g_from_email 是所有通知邮件的 From；$g_return_path_email 承接退信；$g_webmaster_email 显示在页脚「联系管理员」。SMTP 三项指向本机 Postfix。

第二步：准备本机 Postfix（Ubuntu 安装时选「Local only」，mydestination 实测包含 localhost）：

postconf -h mydestination

实测输出：

$myhostname, mantisbt-server, localhost.localdomain, localhost

第三步：触发三封真实邮件并验证投递。实测过程依次发生：

1. 创建用户 dev1（邮箱 dev1@localhost）→ MantisBT 发「账号创建」邮件；
2. 修改 administrator 邮箱 → 触发「Verify Email Address」验证邮件（新地址 + 旧地址抄送）；
3. 把问题 #1 指派给 dev1 → 发指派通知。

本机无 dev1 系统用户，用标准邮件别名把 dev1@localhost 归到 root 邮箱：

echo 'dev1: root' >> /etc/aliases && newaliases

等投递完成后查看 root 邮箱：

grep -E '^(Subject|To|X-Original-To):' /var/mail/root | tail -4

实测输出：

Subject: =?utf-8?B?W+WGhemDqOe8uumZt+i3n+i4quW5s+WPsF0g6aqM6K+B55S15a2Q6YKu5Lu2?=
X-Original-To: dev1@localhost
To: dev1@localhost
Subject: =?utf-8?B?W2RlbW8tYXBwIDAwMDAwMDFdOiDnmbvlvZXpobXpqozor4E=?=

解码 Base64 主题（实测解码结果）：

[内部缺陷跟踪平台] 电子邮件验证
[demo-app 0000001]: 登录页验证

验证结论：SMTP 通道（localhost:25）→ Postfix 本地投递 → /var/mail/root 全链路打通；邮件主题带实例窗口标题前缀「[内部缺陷跟踪平台]」，说明 5.1 的 $g_window_title 已作用于通知邮件。

⚠️ 注意：实测发现「邮箱变更」有两层行为要记住——新邮箱需点验证链接才生效，旧邮箱在验证前继续收信；验证邮件同时抄送新旧两个地址。给用户换邮箱前先确保新域名可收信，否则验证链接会丢在半路。

5.3 附件存储参数

附件有三个关键参数：$g_allow_file_upload（总开关，默认 ON）、$g_file_upload_method（默认 DATABASE 存库；可改 DISK 落盘）、$g_absolute_path_default_upload_folder（DISK 模式的落盘目录，默认空）。切到磁盘模式的理由：库文件不膨胀、可直接用文件系统备份与去重。

第一步：建目录 + 改配置：

mkdir -p /var/www/html/mantisbt/upload
chown www-data:www-data /var/www/html/mantisbt/upload

$g_file_upload_method = DISK;
$g_absolute_path_default_upload_folder = '/var/www/html/mantisbt/upload/';

逐项说明：目录属主必须是 Web 运行用户 www-data，否则上传报错；DISK 模式下文件以哈希名落盘，原文件名与类型存 mantis_bug_file_table。

第二步：上传实测。在问题 #1 的备注表单里随备注上传 step.txt（内容两行复现步骤，58 字节），curl 等价（multipart，文件字段名 ufile[]）：

curl -s -b /tmp/mantis-ck.txt 'http://localhost:8132/mantisbt/bugnote_add.php' \
  -F "bugnote_add_token=$TOKEN" -F "bug_id=1" \
  -F "bugnote_text=复现步骤文件见附件" \
  -F "ufile[]=@/opt/data/quzuo/tmp/mantisbt/step.txt" \
  -o /dev/null -w '%{http_code}\n'

实测输出：302（跳回 view.php?id=1）。

第三步：验证落盘与落库：

ls -l /var/www/html/mantisbt/upload/
mariadb -u mantisbt -pq1w2e3r4 bugtracker -N -e 'SELECT bug_id,filename,filesize,file_type FROM mantis_bug_file_table;'

实测输出：

-r-------- 1 www-data www-data 58 Oct 21 07:23 394c7313c01a2a5b9a776ddf38657d79
1       step.txt        58      text/plain; charset=us-ascii

解读：磁盘文件用内容哈希命名且权限 400（只读，防篡改）；数据库行记录原文件名、大小与 MIME 类型，两边对得上即为闭环。

上限联动：附件最大值取 min($g_max_file_size, php.ini 的 upload_max_filesize)。实测发行包默认 $g_max_file_size = 5 * 1024 * 1024（5 MB），而 Ubuntu PHP 默认 upload_max_filesize=2M——健康检查与上传页（实测显示「最大文件大小: 2,048 KiB」）都会如实反映这个 2 MB 短板。放大附件时三处一起改：php.ini 的 upload_max_filesize 与 post_max_size、实例文件的 $g_max_file_size。

5.4 权限与访问级别参数

访问级别是「全局枚举串 + 本地化标签枚举串」成对工作的参数。默认值（发行包实测）：

$g_access_levels_enum_string = '10:viewer,25:reporter,40:updater,55:developer,70:manager,90:administrator';

业务上想加一个「测试负责人」级别（65），第一步改 config_inc.php：

$g_access_levels_enum_string = '10:viewer,25:reporter,40:updater,55:developer,65:tester_lead,70:manager,90:administrator';

此时实测效果（管理 → 用户 → dev1 的「访问级别」下拉）：

[('10', '观察者'), ('25', '报告者'), ('40', '升级者'), ('55', '开发人员'), ('65', 'tester_lead'), ('70', '经理'), ('90', '管理员')]

⚠️ 排障实录：65 级显示的是原始名 tester_lead 而非中文。根因是标签解析走 get_enum_element() → MantisEnum::getLocalizedLabel(全局枚举串, 本地化枚举串, 值)——本地化枚举串（语言包里的 $s_access_levels_enum_string）没有 65 的映射时回退显示原始名。单独在 custom_strings_inc.php 里加 $s_access_tester_lead 也无效（实测验证过），必须同步扩展本地化枚举串。

第二步在 custom_strings_inc.php 里同步本地化枚举串：

<?php
/* 自定义字符串：登录页注册入口文案 */
$s_signup_link = '注册内部平台账号';

/* 自定义访问级别的本地化标签：必须在本地化枚举串中同步加入 65 级 */
$s_access_levels_enum_string = '10:观察者,25:报告者,40:升级者,55:开发人员,65:测试负责人,70:经理,90:管理员';

再次验证下拉（实测输出）：

[('10', '观察者'), ('25', '报告者'), ('40', '升级者'), ('55', '开发人员'), ('65', '测试负责人'), ('70', '经理'), ('90', '管理员')]

65 级已显示「测试负责人」，权限定制闭环完成。逐项说明：全局枚举串决定「有哪些级别可用、谁能用」（权限判定用它）；本地化枚举串只管「怎么显示」，两者级别号必须一致。

5.5 注册与账号安全参数

这组参数控制自助注册与新建账号的默认权限，默认值实测（发行包）：

grep -nE '\$g_(send_reset_password|default_new_account_access_level|anonymous_account) = ' /var/www/html/mantisbt/config_defaults_inc.php

实测输出：

$g_send_reset_password = ON;
$g_default_new_account_access_level = REPORTER;
$g_anonymous_account = '';

逐项说明：$g_send_reset_password=ON 表示新建账号通过邮件里的链接自设密码（这也是管理后台建用户表单不出现密码框的原因，见安装指南 FAQ Q3）；$g_default_new_account_access_level=REPORTER（25）是新账号的初始级别；$g_anonymous_account 默认空即关闭匿名访问，填入专用账号名可开只读匿名浏览（内网缺陷库公开场景）。

一次性邮箱拦截（实测行为）：2.28 起注册/改邮箱会校验一次性邮箱域名，命中即拒绝。实测把 administrator 邮箱改成 example.com 域时报：

APPLICATION ERROR #1201 It is not allowed to use disposable e-mail addresses.

该检查由发行包依赖 DisposableEmailChecker（官方 composer 依赖 vboctor/disposable_email_checker）实现，无简单开关；内网无真实邮件域的部署用 .local 等自定域名即可通过（实测 administrator@mantis.local、dev1@localhost 均正常）。

六、生产配置模板

适用场景：50 人以下研发/测试团队、单机 4 GB 内存 + SSD、内网部署、要求中文界面与磁盘附件。将以下内容合入 config_inc.php（数据库五要素、$g_crypto_master_salt、$g_path 保留向导生成值）：

<?php
/* —— 站点与界面 —— */
$g_window_title     = '内部缺陷跟踪平台';
$g_default_language = 'chinese_simplified';
$g_default_timezone = 'Asia/Shanghai';

/* —— 邮件（本机 Postfix 或内网 SMTP 中继） —— */
$g_from_email          = 'mantisbt@yourdomain.internal';
$g_webmaster_email     = 'admin@yourdomain.internal';
$g_return_path_email   = 'admin@yourdomain.internal';
$g_phpMailer_method    = PHPMAILER_METHOD_SMTP;
$g_smtp_host           = 'smtp.yourdomain.internal';
$g_smtp_port           = 25;

/* —— 附件（磁盘模式） —— */
$g_file_upload_method                = DISK;
$g_absolute_path_default_upload_folder = '/var/www/html/mantisbt/upload/';
$g_max_file_size                     = 8 * 1024 * 1024;   /* 与 php.ini upload_max_filesize=8M 配套 */

/* —— 权限与注册 —— */
$g_access_levels_enum_string = '10:viewer,25:reporter,40:updater,55:developer,65:tester_lead,70:manager,90:administrator';
$g_anonymous_account = '';                                  /* 保持匿名关闭 */

配套动作：php.ini 中 upload_max_filesize=8M、post_max_size=16M；建立并授权 /var/www/html/mantisbt/upload/；在 custom_strings_inc.php 提供 65 级的本地化标签（见 5.4）；生产环境移除或加固 admin/ 目录。模板中 yourdomain.internal 替换为你的内网邮件域（须可收信，否则验证邮件会丢）。

七、常见问题（FAQ）

Q1：改了 config_inc.php 参数没生效？ 按 3.1 的优先级排查：先查「管理 → 管理配置」里同名键是否已写入库内动态配置（库内优先于文件）；再确认改的是当前实例的 config/ 目录（Nginx 方案 B 的副本在 /var/www/mantisbt-nginx/config/）。文件配置每请求重载，无需重启服务。

Q2：健康检查一直报 webmaster_email / from_email / return_path_email 无效？ 默认值是 example.com 域。改为你的真实域名（内网用可收信的自定域名）即可消除 WARN，这也是邮件能正常发出去的前提之一。

Q3：改邮箱后旧邮箱还在收信？ 设计行为：新邮箱验证通过前旧地址保持有效，验证邮件同时抄送新旧地址（5.2 实测）。要立即生效需用户本人点击验证链接。

Q4：加了自定义访问级别但下拉显示英文名？ 见 5.4 排障实录：本地化枚举串缺该级映射，回退显示原始名。在 custom_strings_inc.php 同步扩展 $s_access_levels_enum_string 即可，单加 $s_access_<名> 无效。

Q5：附件上传按钮显示 2,048 KiB 但想传 20 MB？ 上限取 min($g_max_file_size, upload_max_filesize)。同时调 php.ini（方案 A 改 /etc/php/8.1/apache2/php.ini，方案 B 改 fpm 的并重启 php8.1-fpm）与 $g_max_file_size。

Q6：SMTP 发信失败如何定位？ 依次核对：$g_phpMailer_method=SMTP 与 $g_smtp_host/$g_smtp_port 指向真实可达的 SMTP；本机 Postfix 场景确认 postconf -h mydestination 覆盖目标域；收件地址必须是 MantisBT 里登记的邮箱；本机投递场景善用 /etc/aliases 把应用邮箱归到真实系统用户（5.2 的 dev1: root 即此法）。

八、参考链接

• 发行包默认值文件：mantisbt-2.28.4/config_defaults_inc.php
• 官方 Admin Guide「Configuration」章：https://mantisbt.org/documentation.php
• 本专栏相关篇目：《MantisBT 2.28.4 介绍与选型指南》《Ubuntu 22.04 安装 MantisBT 指南》《MantisBT 2.28.4 REST API 使用详解》