MantisBT部署实战：用LAMP搭建轻量级缺陷跟踪系统

1. 这个工具是什么为什么要折腾它先直接说结论Mantis 是目前开源领域里非常成熟的 Bug 追踪管理系统很多人习惯叫它 MantisBT。它的定位很明确就是给软件开发团队一个统一的地方去记录、跟踪、指派和闭环处理缺陷从测试人员提交第一个 bug 开始到开发修复、QA 回归验证、最后关闭整个生命周期都在里面流转。我第一次接触它是在七八年前当时团队从 Excel 表格管理缺陷的状态切到 MantisBT 上最大的感受就是终于不用天天问“那个 bug 改了没有”所有状态变化都有记录谁在处理、处理到什么程度、卡在哪个环节打开页面一眼就能看到。这个项目折腾的价值在于MantisBT 足够轻部署门槛低一台普通的 1 核 2G 的服务器就能跑得很稳而且它对 PHP 和 MySQL 的依赖都是非常成熟稳定的技术栈几乎没有特殊的系统要求。跟 Jira 这类商业产品相比MantisBT 最大的优势是开源免费、结构简单、上手成本低特别适合中小型研发团队、外包项目组、学生毕设团队甚至是个人开发者管理自己的 side project 缺陷清单。如果你是团队的测试负责人或者研发 leader想在半天内搭好一套够用的缺陷管理系统不用花一分钱买授权这篇文章就是给你准备的。MantisBT 的功能覆盖很全面缺陷生命周期管理、自定义字段、邮件通知、附件上传、多种角色权限、统计报表这些核心能力都有还支持通过插件扩展。文章后面我会把整个安装部署、配置调整、日常使用串起来讲一遍包括我实际踩过的坑和调整过的参数尽量让你照着操作就能跑起来。2. 安装前的核心思路与准备2.1 为什么要用 LAMP 这套组合MantisBT 是 PHP 写的数据存储走 MySQL官方推荐的运行环境就是 Linux Apache MySQL PHP也就是大家常说的 LAMP 组合。这套组合的好处是组件都很常见遇到任何问题都能搜到大量解决方案而且 Apache 的 mod_php 加载方式在兼容性上最稳定。如果你对 Nginx 更熟悉也可以换成 Nginx PHP-FPM但初次部署我建议先按官方文档的推荐来减少变量。这里多提一句版本选择。MantisBT 2.x 是当前主流的大版本对 PHP 的要求是 5.5 以上推荐 7.x 或 8.x。我在实际部署中用的是 PHP 7.4搭配 MariaDB 10.3两者兼容性比较好。PHP 8.0 之后有些旧插件会出现弃用函数警告所以如果不想折腾兼容问题按 7.4 走最稳当。2.2 环境选型和服务器准备我这次演示用的是一台 Ubuntu 20.04 的云服务器干净系统只做了基础安全组配置开放了 80 和 22 端口。内存 2G磁盘 40G说实话这配置跑 MantisBT 完全足够了它本身非常节省资源后续团队用到一百人以内都不会有压力。安装前先把系统软件源更新一下顺便把 wget、unzip 这类基础工具装上后面会用到sudo apt update sudo apt upgrade -y sudo apt install -y wget unzip vim接下来安装 Apache 和 MySQLUbuntu 默认源里没直接带 MySQL我用的是 MariaDB兼容性完全没问题sudo apt install -y apache2 mariadb-server mariadb-client sudo systemctl enable --now apache2 sudo systemctl enable --now mariadb装完顺手确认一下两个服务的状态都是 running 就继续走。2.3 安装 PHP 及关键扩展MantisBT 对 PHP 扩展有明确要求缺了会直接在安装页面报红常见的必要扩展包括pdo_mysql、mysqli、gd、mbstring、xml、curl、zip、json。其中 gd 主要负责验证码图片生成mbstring 用来处理多语言字符zip 在导入导出功能里会用到。用 apt 一口气装齐sudo apt install -y php php-cli php-common php-mysql php-gd php-mbstring php-xml php-curl php-zip php-json php-intlPHP 装完以后需要微调两个常见参数让上传和支持能力更舒服一点。打开 /etc/php/7.4/apache2/php.ini把下面几个值改掉file_uploads On upload_max_filesize 16M post_max_size 20M max_execution_time 120 max_input_time 120 memory_limit 256M这里解释一下为什么调整这些值。MantisBT 默认允许附件上传测试人员在提交 bug 时经常会附带截图、日志等文件默认的 2M 上传限制太小动不动就把上传卡住我把它调整到 16M对绝大多数场景都够用。memory_limit 调大到 256M 是为了跑报表和批量操作时更从容避免数据量大时内存溢出。改完以后记得重启 Apache 让配置生效sudo systemctl restart apache2PHP 环境是不是正常可以写一个探针页面来确认在 /var/www/html/info.php 里放一行最简单的代码浏览器里访问看到信息页就代表 PHP 和 Apache 配合没问题。?php echo phpinfo();3. 核心安装与配置详解3.1 数据库创建与账号授权MantisBT 安装过程中需要一个数据库我习惯是先手动创建好数据库和专用账号这样权限可以控制得更细避免直接用 root 账号跑应用。登入 MariaDB 控制台sudo mysql -u root然后在数据库命令行里执行下面这段 SQLCREATE DATABASE mantisbt DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; CREATE USER mantislocalhost IDENTIFIED BY S0meStr0ngPassw0rd; GRANT ALL PRIVILEGES ON mantisbt.* TO mantislocalhost; FLUSH PRIVILEGES; EXIT;这里有两个细节需要说明。第一字符集我特意选了 utf8mb4 而不是老旧的 utf8因为 utf8mb4 能完整支持 emoji 和更多特殊字符团队里总有人在 bug 描述里贴一些特殊符号用 utf8 可能报 Incorrect string value 的错。第二密码强度尽量不要低于 12 位MantisBT 的登录页面没有复杂的防爆破机制如果部署在公网弱密码很容易被扫描器撞库。3.2 下载 MantisBT 并部署到 Web 目录MantisBT 的官方下载地址是 GitHub 的 release 页面可以直接下载最新稳定版。我这里以 2.25.7 版本为例实际使用中你去官网下载一个比你用的时候更新的版本就行安装逻辑完全一样cd /tmp wget https://github.com/mantisbt/mantisbt/releases/download/2.25.7/mantisbt-2.25.7.tar.gz sudo mkdir -p /var/www/mantisbt sudo tar -xzf mantisbt-2.25.7.tar.gz -C /var/www/mantisbt --strip-components1 sudo chown -R www-data:www-data /var/www/mantisbt注意这个步骤里的 --strip-components1 参数它的作用是把压缩包里的顶层目录剥掉直接把文件解压到 /var/www/mantisbt 下避免出现 /var/www/mantisbt/mantisbt-2.25.7 这样的嵌套目录。另外文件属主必须改成 www-data否则后续安装页面在写入配置文件时会因为权限不足卡住。3.3 配置 Apache 虚拟主机为了让访问路径更专业一些我建议给 MantisBT 配置独立的虚拟主机而不是直接放在默认站点目录下。新建一个配置文件 /etc/apache2/sites-available/mantisbt.conf内容如下VirtualHost *:80 ServerName bug.example.com DocumentRoot /var/www/mantisbt Directory /var/www/mantisbt Options FollowSymLinks AllowOverride All Require all granted /Directory ErrorLog ${APACHE_LOG_DIR}/mantisbt_error.log CustomLog ${APACHE_LOG_DIR}/mantisbt_access.log combined /VirtualHost启用站点和 URL 重写模块sudo a2ensite mantisbt.conf sudo a2dissite 000-default.conf sudo a2enmod rewrite sudo systemctl reload apache2AllowOverride All 一定要保留MantisBT 依赖 .htaccess 文件实现短链接和访问控制。如果你没有域名想用 IP 直接访问那就把 ServerName 改成服务器的公网 IP或者干脆注释掉 ServerName 这一行Apache 默认就能匹配到。3.4 执行图形化安装向导一切准备就绪后浏览器里访问 http://你的服务器地址/系统会自动跳转到安装向导页面。安装向导分为几个步骤核心是填写数据库连接信息和管理员账号。数据库配置信息按前面创建的内容填写数据库类型MySQL Improved数据库主机名localhost数据库名称mantisbt数据库用户名mantis数据库密码你自己设置的强密码数据库表前缀mantis_默认即可管理员的默认账号是 administrator密码需要你设置一个这也以后登录系统的超级管理员账号建议用独立的安全邮箱方便后续找回密码。安装过程中有一个配置项需要留意Timezone 时区。如果你的服务器时区已经设置成 Asia/Shanghai这里直接选 UTC8 就可以免得以后报表里的时间比实际时间差了 8 个小时。提交安装以后系统会自动创建表结构并写入初始数据正常几秒钟就能完成。安装成功后会提示你删除 admin 目录下的 install 文件这是个安全提醒。回到服务器上执行sudo rm -rf /var/www/mantisbt/admin如果不删除别人访问 admin 目录可能重新触发安装流程这是非常危险的事情。我在给客户做安全巡检时见过几次没删 install 目录导致被恶意重置数据的情况务必记得清理。3.5 初始化配置文件的微调安装完成后MantisBT 在 /var/www/mantisbt/ 下生成一个 config_inc.php 文件这是整个系统的核心配置文件。大部分默认配置可以直接用但有几个值我建议手动调整。打开 config_inc.php在文件末尾增加以下几项?php $g_default_language chinese_simplified; $g_default_timezone Asia/Shanghai; $g_allow_signup OFF; $g_enable_email_notification ON; $g_phpMailer_method 2; $g_smtp_host smtp.example.com; $g_smtp_port 465; $g_smtp_username noreplyexample.com; $g_smtp_password your_smtp_password; $g_smtp_connection_mode ssl; $g_mail_allow_user_pref_notify ON;逐个解释这些配置的意义。默认语言设置成简体中文省得每个用户注册后还要手动切语言。关闭自助注册是因为缺陷管理系统只面向内部团队成员注册入口开着容易被垃圾账号骚扰。邮件通知是 MantisBT 很重要的功能配置好 SMTP 后有人提交 bug 或修改状态时相关人会自动收到邮件提醒这个能力可以大大减少沟通成本。SMTP 这一项我建议你根据自己公司实际的邮件服务商填写我用的是企业邮箱的 SMTP端口 465 配 SSL。没有邮件服务器的话可以先跳过邮件配置系统完全能正常运行只是少了提醒功能。3.6 Nginx 环境下的适配备选方案前面讲的是 Apache 方案如果你坚持用 Nginx配置方式也很简单。Nginx 的站点配置核心是正确配置 PHP 解析和伪静态规则。下面是能跑通的 location 配置片段server { listen 80; server_name bug.example.com; root /var/www/mantisbt; index index.php; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php7.4-fpm.sock; } }Nginx 下出现 404 大概率是伪静态规则没配对检查 try_files 这一行是不是配置正确。另外记得确保 php-fpm 服务是启动状态否则 PHP 文件下载而不是执行。4. 日常使用的核心环节4.1 项目管理与用户角色分配MantisBT 安装完以后第一件事是创建项目然后添加成员。只有先把这两个基础数据建好后续的缺陷流转才有地方落地。创建项目的路径是“管理”菜单 → “项目管理”需要填的关键信息包括项目名称、项目状态开发中/发布等、可见性公开/私有。这里有一个原则如果是同一个项目给多个子团队共用可以考虑在项目下再创建子项目MantisBT 支持子项目继承和独立并行的模式。用户管理在“管理”菜单 → “用户管理”点击“创建用户”进入添加页面。MantisBT 的角色权限从低到高大致分为查看者、报告者、更新者、开发人员、项目经理、管理员。只需要关注几类核心角色的用法就够了测试人员一般分配“报告者”可以提交缺陷、补充信息。开发人员分配“开发人员”角色可以修改缺陷状态、提交处理说明。项目经理分配“项目经理”能看所有统计数据、调整优先级和分派。管理员只给系统维护人员即可尽量不要泛滥。我在团队里踩过一个坑为了省事把所有成员全部设成管理员。短时间看起来没差别时间一长配置文件被乱改、字段被删除、报表数据被误清理再排查出来的时候已经很难追溯责任。权限最小化原则在缺陷管理系统里同样适用。4.2 提交缺陷的完整流程演示日常使用中最高频的操作就是提交缺陷。点击顶部菜单“提交缺陷”按钮进入提交页面。这里有几个关键字段的填写是有讲究的字段“类别”用来标记缺陷属于哪个功能模块这个需要在项目管理里先定义好。字段“优先级”我建议按业务真实影响程度来选不要人手一个“紧急”否则紧急就失去意义了。字段“操作系统”和“平台”对做桌面端或移动端兼容性测试的团队尤其重要实际填写时这些字段会自动带出检测信息或者手动选择。“重现步骤”是一个值得认真写的字段。很多测试人员提交 bug 时只写一句“页面报错了”开发人员拿到之后还得反复确认前置步骤和操作路径一来一回浪费大量时间。我自己的习惯是写清楚三块前置条件登录什么账号、处于什么页面、操作步骤一步步怎么做、实际结果和期望结果发生了什么 vs 应该发生什么。信息足够完整开发处理速度能快不少。提交完成后缺陷默认状态是“新建”。测试人员后续发现有补充信息可以直接在缺陷详情页添加备注或者追加新的附件不必重新开一条新缺陷。4.3 缺陷状态流转与开发协作MantisBT 的缺陷状态机设计得比较直白核心流转路径是新建 → 已确认 → 已分派处理中→ 已解决 → 已关闭中间还夹杂着“重新打开”这个环节对应的是 QA 验证发现还没修好、打回去让开发继续处理的情况。项目实践中开发人员的操作路径一般是这样的在“查看问题”列表里找到分派给自己的缺陷确认可以处理后把状态改成“处理中”同时在备注里写上处理计划完成后把状态改成“已解决”并选择“解决方案”字段字段值有“已修复”“重复问题”“无法重现”“无法修复”等。QA 收到解决通知后进行回归验证通过就点击“关闭缺陷”有问题就点“重新打开”。这里要特别提醒一个环节解决方案的选择一定要如实填写。如果开发明明没有找到问题根因只是重新启动了服务然后选了“已修复”这个缺陷后续还会再出现反而影响整个团队对数据质量的信任。真实记录问题处理过程比急着关闭缺陷更重要。4.4 邮件通知与报表统计邮件通知配好后MantisBT 能做的事情比我预期的多。当缺陷状态变化时系统会向关注这个缺陷的成员发送通知邮件包括报告者、指派人、回复了备注的人、项目管理员等。邮件内容默认是纯文本形式的变更摘要虽然不华丽但足够用。报表模块是 MantisBT 被低估的功能之一。点击“查看问题”页面底部有“报表”相关入口可以看到按状态、优先级、指派人分布等维度的统计报表。日常管理上我比较常用的是按指派人的缺陷负载表可以直观看到每个人手上堆积了多少未解决的问题发现某个人长期超载就该及时协调资源了。4.5 自定义字段与工作流扩展如果团队需要额外记录一些业务属性比如需求编号、测试环境版本、bug 来源渠道等MantisBT 可以在管理后台里创建自定义字段。路径是“管理” → “自定义字段管理”创建后在“项目管理”里把字段关联到具体项目上。自定义字段提供了文本框、下拉列表、日期等多种类型。我见过不少团队把“版本号”做成自定义下拉列表每周发版后更新一次选项这样测试人员在提交 bug 时就能准确地标注出问题出现的版本后续统计版本质量时非常有用。对于更复杂的工作流变化MantisBT 支持在插件市场上找现成的扩展也可以改 workflow 配置实现状态机调整。不过如果团队没有专门的人维护我不建议一开始就过度定制先把默认流程用透再慢慢迭代。5. 常见问题与排查技巧实录5.1 安装页面出现中文乱码安装向导的中文显示乱码大多数情况是配置文件里默认字符集和数据库不一致导致的。第一步先检查 config_inc.php 里有没有设置默认语言为 chinese_simplified没有就补上。第二步检查数据库和表的字符集是不是 utf8mb4如果建库的时候用了默认的 latin1需要重新建库或者用 ALTER 语句转换ALTER DATABASE mantisbt CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;另外要确认 Apache 的配置文件里有没有强制输出旧的 Content-Type 头如果加了 AddDefaultCharset utf-8可以考虑注释掉这一行试试。5.2 SMTP 邮件发不出去邮件发不出去是最常见的问题。排查步骤按顺序来第一步确认服务器能否连通 SMTP 服务器的 465 或 587 端口telnet smtp.example.com 465如果端口不通检查云服务器的安全组出方向是否放行了对应端口。第二步确认 config_inc.php 里 SMTP 配置是否正确尤其是 ssl/tls 模式的选择。有些邮件服务商要求 ssl有些用 tls错了就连接失败。第三步打开 MantisBT 管理页面查看“系统日志”里有没有详细报错。日志里能看到连接超时、认证失败这类更精确的提示。我实际遇到最多的坑是 $g_smtp_connection_mode 和端口不匹配用 ssl 却配了 587 端口。这个对应关系要记清楚ssl 配 465tls 配 587。另外很多企业邮箱服务商要求发件人地址必须和认证账号一致否则拒绝发送也得顺手检查。5.3 忘记管理员密码怎么办MantisBT 管理员密码忘了不需要重装系统直接操作数据库就能解决。用管理员身份进入 MariaDB执行下面的 SQL 语句UPDATE mantis_user_table SET password MD5(NewPassword123) WHERE username administrator;在 MantisBT 的默认实现里密码字段存储的是明文密码的 MD5 值。执行完刷新一下登录页用新密码登进去再在个人账户设置里改成正式密码。这里延展说一下这个机制也意味着管理员账号的密码安全性非常重要因为开发者可以拿到数据库哈希后做离线暴力破解。建议生产环境不要让太多人掌握数据库 root 权限同时开启管理员账号的双因素认证MantisBT 支持基于 TOTP 的两步验证在“我的账户” → “双因素认证”里可以启用。5.4 上传附件失败或报错上传附件失败一般有三种原因。第一种是 PHP 的 upload_max_filesize 配置太小按前面的方法调大。第二种是服务器磁盘满了MantisBT 默认附件存在文件系统上用 df -h 检查一下磁盘空间。第三种是权限问题attachment 目录的属主不是 www-data导致写不进去。快速排查上面三个点90% 的附件问题都能解决。还不行的看一下 Apache 的 error logsudo tail -100 /var/log/apache2/mantisbt_error.log5.5 服务器安全加固的几个实用动作MantisBT 部署到公网服务器安全配置不能省。我自己总结的最低安全清单用 HTTPS 替换 HTTP。全站的密码和敏感信息如果明文传输很容易在局域网或者运营商层面被截获。申请免费的 SSL 证书或者用内建的反代工具配合 Lets Encrypt 搞定。定期备份数据库和附件目录。MantisBT 的表结构不复杂用 mysqldump 做每日备份足够附件目录可以用 rsync 同步到其他存储。修改 config_inc.php 里的错误报告级别生产环境不要开 debug 模式避免暴露服务器路径和数据库信息。关闭匿名访问。默认情况下未登录用户访问登录页可以看项目概况按需关闭这个入口减少信息暴露面。5.6 数据库连接丢失的问题用了一段时间后偶尔会出现“数据库连接丢失”或者 “Connection failed” 的报错。排查方向有二一是 MariaDB 服务是不是被 OOM killer 杀掉了低配服务器上内存不足时会发生二是清空 MySQL 连接数的限制设置看是不是连接被耗尽了。如果服务器内存非常小可以给 MariaDB 加上 swap 或者限制 InnoDB 缓冲池的大小[mysqld] innodb_buffer_pool_size 256M max_connections 100在 /etc/mysql/mariadb.conf.d/50-server.cnf 的 [mysqld] 段落下补充以上配置重启数据库服务生效。这个优化对低配服务器非常友好。6. 扩展玩法让 MantisBT 更适合你的团队6.1 用插件补齐 DevOps 工作流MantisBT 有一个插件生态比较常用的包括Timesheet 插件用来统计工时、Source Integration 插件对接 Git/SVN 代码仓库、Excel 导出插件方便测试组做周报数据整理、PDF 导出发送报告等等。插件的安装方式很简单下载插件包后放到 plugins 目录登录管理员后台启用即可。我在团队里实际接入过 Source Integration 插件把 GitLab 提交记录和缺陷 ID 绑定起来开发在提交代码时备注 “refs #12345”以后打开缺陷详情就能直接看到相关代码提交追溯线上问题非常方便。这个联动能力对研发过程管理帮助很大值得优先安装。6.2 对接第三方登录系统团队规模大了以后每套系统一套账密的弊端会越来越明显。MantisBT 通过插件支持 LDAP 和 CAS 登录企业里有统一认证系统的话可以直接对接。配置时主要是在 config_inc.php 中填写 LDAP 服务器地址、base dn、bind 账号等信息。这个操作的核心好处是员工入职时统一开通账号离职时一键抽象账号不必逐个系统手动清理。6.3 定制缺陷字段和流程序有些团队的缺陷管理流程比较严格比如线上的 hotfix 和普通迭代的流程完全不同。MantisBT 默认是单套流程但通过调整工作流配置 $g_status_enum_workflow你可以自定义每个角色在每种状态之间的转换权限。配合自定义字段完全可以模拟出适合自己团队的审批流。一个常见的例子把“紧急缺陷”做成优先级字段的特殊值通过自定义字段标记是否属于线上问题再配合邮件提醒设置不同的指派规则。这样同一套 MantisBT 可以兼顾常规 bug 和线上紧急修复两条不同的协作路径。7. 我的一点使用体会MantisBT 到今天为止依然是我认为最适合中小团队自建缺陷管理系统的工具之一。它的学习曲线平缓功能覆盖度高对服务器配置要求极低而且社区文档丰富遇到问题几乎都能找到答案。跟那些重量级的商业产品相比它缺少的并不是基本能力而是一些锦上添花的企业级集成对大多数团队来说这些短板完全可以通过插件和少量开发来弥补。根据我的经验团队引入 MantisBT 最关键的地方不在安装配置而在于执行的纪律性。系统搭得再好如果测试人员不认真填写重现步骤开发人员不维护解决方案字段缺陷管理很快就会退化成一个登记本失去追踪和度量的价值。所以我建议你部署完成后抽半小时给团队做一次简单的使用培训把角色权限、字段填写规范、状态流转约定讲清楚这套系统的价值才能真正发挥出来。最后再分享一个小技巧给 MantisBT 配置一个单独的数据库账号和严格的权限日常操作只用这个受限账号不要用 root。这不仅能让数据更安全排查问题的时候也能从权限维度缩小范围少踩很多坑。