Bugzilla 配置参数详解
Bugzilla 5.2 双文件配置体系实测详解：localconfig 机器级参数（db_driver 合法值/webservergroup/site_wide_secret）与 data/params.json 运行参数（urlbase/mail_delivery_method/认证与默认值），含 admin UI 与 CLI SetParam 双路径及排障实录。
Bugzilla 配置参数详解
目标：讲清 Bugzilla 5.2 的双文件配置体系——低层的
localconfig（机器级连接参数，checksetup 消费）与运行层的data/params.json（管理员参数，admin UI 管理）——并按官方参数面板逐组解读高频参数。本文所有取值、命令与报错均为 Ubuntu 24.04 + PostgreSQL 16 实测环境（部署过程见《Bugzilla 5.2 部署实战》）的真实记录，实测日期 2026-10-27。
一、环境信息
| 项目 | 取值 |
|---|---|
| Bugzilla | 5.2，部署于 /var/www/html/bugzilla |
| 后端 | PostgreSQL 16.15（localconfig db_driver='pg'） |
| Web | Apache 2.4.58 + mod_cgi，访问路径 /bugzilla/ |
| 管理员 | admin@example.com / q1w2e3r4 |
| 参数管理入口 | Web：Administration → Parameters（editparams.cgi）；CLI：perl -I. -M... -e 直调 SetParam/write_params |
二、双文件参数体系总览
Bugzilla 的配置分为两个物理文件、两个抽象层级，混用是新手最常见的误区：
| 维度 | localconfig | data/params.json |
|---|---|---|
| 抽象层级 | 机器/连接层：装在哪、连哪个库、以什么身份 | 应用/运行层：站点叫什么、邮件怎么发、谁登录 |
| 生成者 | 首次运行 checksetup.pl 生成 | 第三轮 checksetup.pl 建库时以默认值写入 |
| 消费者 | 仅 checksetup.pl（每次运行读取） | 所有 Web/CLI/API 运行时代码 |
| 修改后生效方式 | 必须重跑 ./checksetup.pl | 保存即生效（下次请求读到新值），无需重启 |
| 管理方式 | 手工编辑（root） | Web 参数页（管理员），或 CLI |
| 修改历史 | 无记录（本质是部署清单） | 无版本化，但全部有类型与取值校验 |
| 定义源码 | checksetup.pl 内嵌默认模板 | Bugzilla/Config/*.pm 按面板定义 |
数据流：checksetup.pl 读 localconfig → 连数据库 → 把「站点运行参数」按 Bugzilla/Config/*.pm 中的默认值写进 data/params.json → 运行时代码经 Bugzilla->params 只读访问 params.json。理解这个流向就能回答「为什么改了 localconfig 没生效」「为什么 params 面板里没有数据库连接项」这类问题。
实测的 data/ 目录布局（params.json 的邻居们，均为运行时产物）：
assets attachments db extensions mailer.testfile mining params.json template webdot
三、localconfig：机器级连接参数
localconfig 是 Perl 语法变量清单。实测环境修改后的关键项（完整实测值）：
$create_htaccess = 1;
$webservergroup = 'www-data';
$use_suexec = 0;
$db_driver = 'pg';
$db_host = 'localhost';
$db_name = 'bugs';
$db_user = 'bugs';
$db_pass = 'q1w2e3r4';
$db_port = 0;
$db_sock = '';
$db_check = 1;
$index_html = 0;
$interdiffbin = '';
$diffpath = '/usr/bin';
$site_wide_secret = 'jkQAvrtw8SggPzzWWDSN0sCaEdM3yvKfP0kN2zOJT0lDmUkiOH4t2vwcQ84wQfGc';
逐项说明（结合实测行为）：
- $create_htaccess：1 = checksetup 生成并维护各目录的 .htaccess（保护 data/、localconfig 等不被 HTTP 拉取）。实测部署中它生成的 .htaccess 依赖 Apache
AllowOverride All，否则首页 500（实录见部署篇排障 3）。 - $webservergroup：checksetup 将以此组修复文件权限。Ubuntu/Debian 必须改为
www-data（默认模板值apache是 RHEL 系的组名，实测不改会在权限修复阶段出问题）。 - $db_driver：合法值只有
mysql/mariadb/pg/oracle。写成pgsql的实测报错原文：
pgsql is not a valid choice for $db_driver in./localconfig at Bugzilla/DB.pm line 193, <DATA> line 960.
- $db_host / $db_name / $db_user / $db_pass / $db_port：数据库连接五件套。同机 PostgreSQL 填 localhost；
db_port = 0表示使用数据库默认端口。 - $db_check：1 = checksetup 连库并校验版本；PostgreSQL 实测要求 ≥ 8.03.0000（16.15 通过）。
- $site_wide_secret：自动生成的随机密钥，用于会话签名等。不要与别的 Bugzilla 实例共享，泄露等同会话伪造风险。
- $index_html：0 = index.cgi 为默认入口（Apache DirectoryIndex 配合）。
- $interdiffbin / $diffpath：补丁对比工具路径，影响 Patch Viewer 增强。
修改流程铁律：编辑 localconfig 后必须重跑 ./checksetup.pl。checksetup 幂等，重复执行安全。
四、data/params：运行参数体系
4.1 参数的物理形态与读取
运行参数持久化为 JSON 文件 data/params.json。实测样例（部署后按需修改过的两项以实际值展示：urlbase、mail_delivery_method）：
"createemailregexp": ".*",
"defaultpriority": "---",
"defaultseverity": "enhancement",
"duplicate_or_move_bug_status": "RESOLVED",
"mail_delivery_method": "Test",
"mailfrom": "bugzilla-daemon",
"maintainer": "admin@example.com",
"maxattachmentsize": "1000",
"rememberlogin": "on",
"requirelogin": "0",
"shutdownhtml": "",
"smtpserver": "localhost",
"upgrade_notification": "latest_stable_release",
"urlbase": "http://localhost/bugzilla/",
"use_mailer_queue": "0",
"user_info_class": "CGI",
"user_verify_class": "DB",
"utf8": "1",
"whinedays": "7"
所有运行代码通过 Bugzilla->params->{'urlbase'} 这样的哈希访问读取，进程内缓存、请求间重读——因此参数改完即生效，不需要重启 Apache。
4.2 管理界面：Parameters 面板
管理员登录后经 Administration → Parameters（editparams.cgi）管理。参数在界面上按功能分组，分组与源码定义一一对应（实测 Bugzilla/Config/ 下的 18 个面板模块）：
Admin.pm Advanced.pm Attachment.pm Auth.pm BugChange.pm BugFields.pm
Common.pm Core.pm DependencyGraph.pm General.pm GroupSecurity.pm
LDAP.pm MTA.pm Memcached.pm Query.pm RADIUS.pm ShadowDB.pm UserMatch.pm
界面对应的分组即：Core（核心）、General（常规）、Auth（用户认证）、User Match（用户匹配）、User Verification（认证后端）、Group Security（组安全）、Bug Change Policies（变更策略）、Bug Fields（字段）、Attachments（附件）、Duplicate/Move、Dependency Graphs、MTA（邮件）、LDAP、RADIUS、Query（默认查询）、Shadow Database、Memcached、Admin（管理员组）等。每个参数在源码里声明类型（s=单选、b=布尔、t=文本、o=多选排序等）、默认值与校验器，保存时做严格校验。
4.3 CLI 修改实测（免 Web 的运维路径）
管理脚本/自动化场景可直接调用 Perl API 修改并落盘。实测命令（设置 urlbase 与邮件投递方式）：
cd /var/www/html/bugzilla
perl -I. -e 'use Bugzilla; use Bugzilla::Config qw(SetParam write_params);
SetParam("urlbase", "http://localhost/bugzilla/");
SetParam("mail_delivery_method", "Test");
write_params(); print "PARAMS_SAVED\n";'
实测回显：
PARAMS_SAVED
SetParam 带强校验，非法值直接拒绝（实测把 mail_delivery_method 设为 Bogus）：
DIE: Param mail_delivery_method is not valid: Invalid choice 'Bogus' for single-select list param 'mail_delivery_method' at Bugzilla/Config.pm line 92.
⚠️ 注意：CLI 修改与 Web 界面等价（同样写 data/params.json），但 CLI 不触发 Web 端的权限与会话检查，仅限 root 运维使用。
五、高频参数详解（按面板分组）
以下每项均在实测环境验证过行为。
5.1 Core（核心）
| 参数 | 实测值 | 说明 |
|---|---|---|
| urlbase | http://localhost/bugzilla/ | 必设项。站点对外 URL，邮件正文的 bug 链接、REST 文档引用全部基于它。不设会导致通知邮件链接残缺 |
| sslbase | （空） | HTTPS 站点填 https://host/bugzilla/，与 urlbase 二选一非空 |
| cookiepath | / | 会话 Cookie 路径；同域多应用时收紧到 /bugzilla/ |
| cookiedomain | （空） | 跨子域共享会话才需要，默认空最安全 |
| requirelogin | 0 | 0=匿名可浏览；内网保密库设 1 强制登录 |
| utf8 | 1 | 库与页面统一 UTF-8；建库后不可反转（涉及存量数据转码），PostgreSQL 部署保持 1 |
| maintainer | admin@example.com | 页脚「Maintained by」与异常页联系邮箱 |
| shutdownhtml | （空） | 非空即进入维护模式：全站只读公告页。升级/迁移时常用 |
| upgrade_notification | latest_stable_release | 管理首页的版本更新提示源 |
5.2 MTA（邮件投递）
| 参数 | 实测值 | 说明 |
|---|---|---|
| mail_delivery_method | Test | 合法取值实测自源码：Sendmail / SMTP / Test / None。Sendmail 调本机 sendmail 程序；SMTP 走 smtpserver 直连投递；Test 把所有信件追加到 data/mailer.testfile（调试神器）；None 关闭所有出站邮件 |
| mailfrom | bugzilla-daemon | 发件人本地部分，配合 urlbase 域名成地址（Test/SMTP 模式）；Sendmail 模式由 MTA 自己补全 |
| smtpserver | localhost | SMTP 服务器，支持 host:port 写法 |
| smtp_username / smtp_password | （空） | SMTP 认证（需认证的中继才填） |
| smtp_ssl | 0 | SMTP over SSL/TLS |
| use_mailer_queue | 0 | 1=邮件入队异步发（需 TheSchwartz + jobqueue 守护进程）；实测环境未装队列依赖，保持 0 同步发 |
| whinedays | 7 | Whine 催办的过期天数阈值（未处理 bug 提醒） |
实测验证 mail_delivery_method=Test 的投递效果：触发 bug 评论后，data/mailer.testfile 增长，内含完整 multipart 消息（HTML+纯文本两个部件、boundary、Message-ID、X-Bugzilla-* 头），可直接用邮件客户端打开回放。
5.3 Auth（用户认证）
| 参数 | 实测值 | 说明 |
|---|---|---|
| user_info_class | CGI | 合法取值实测：CGI / Env / Env,CGI。CGI=表单登录会话；Env=信 Web 服务器环境变量（企业 SSO 场景）；Env,CGI=先 Env 后 CGI |
| user_verify_class | DB | 合法取值实测：DB / RADIUS / LDAP（可组合）。DB=本地密码库；LDAP/RADIUS 对接企业目录/认证 |
| createemailregexp | .* | 允许自助注册的邮箱正则；. 表示全放行。收紧内网注册可改为 @example\.com$；置空则完全关闭自助注册 |
| emailregexp | ^[\w\.\+\-\=']+@[\w\.\-]+\.[\w\-]+$ | 邮箱格式校验正则 |
| password_complexity | no_constraints | 密码复杂度策略（可改为要求字母+数字等） |
| rememberlogin | on | 会话持久化策略：on/defaulton/defaultoff/off |
| allowemailchange | 1 | 允许用户自助改邮箱 |
5.4 General（默认值）
| 参数 | 实测值 | 说明 |
|---|---|---|
| defaultpriority | --- | 新 bug 默认优先级。实测发现：5.2 全新安装的优先级选项不含 P1-P5，REST 提单显式传 priority: "P3" 会报非法值——默认体系是 ---/Lowest/Low/Normal/High/Highest，按实际工作流在字段值管理里调整 |
| defaultseverity | enhancement | 新 bug 默认严重级 |
| defaultopsys / defaultplatform | （空） | 默认操作系统/平台（空=提单时必选） |
| letsubmitterchoosepriority | 1 | 提交者可选优先级 |
| duplicate_or_move_bug_status | RESOLVED | 重复/移动操作的目标状态 |
5.5 Query（查询）与 Group Security（权限组绑定）
| 参数 | 实测值 | 说明 |
|---|---|---|
| defaultquery | （长串，按指派人等过滤未解决 bug） | 首页默认查询 |
| default_search_limit | 500 | 默认单次查询返回上限 |
| max_search_results | 10000 | 查询导出上限 |
| search_allow_no_criteria | 1 | 1=允许无条件全库查询（大库建议 0 防拖库） |
| chartgroup / querysharegroup / timetrackinggroup / debug_group | 均为 editbugs/admin | 各功能绑定的组；insidergroup（机密评论组）实测为空=禁用 |
5.6 Attachment（附件）与 Memcached / ShadowDB
| 参数 | 实测值 | 说明 |
|---|---|---|
| maxattachmentsize | 1000 | 单附件上限（KB） |
| maxlocalattachment | 0 | 本地磁盘大附件上限（0=禁用） |
| allow_attachment_display | 0 | 浏览器内联展示附件（XSS 面板，谨慎开启） |
| memcached_servers | （空） | Memcached 地址；填入即启用对象缓存（需 Cache-Memcached 模块） |
| shadowdb* | （空） | 读从库拆分；大流量站点才启用 |
六、参数体系排障实录
实录 1：改 localconfig 不生效。现象：改了 localconfig 里的数据库密码后应用行为未变。原因：params.json 与 localconfig 职责混淆——运行参数在 params.json，localconfig 只有 checksetup 消费。正确流程：localconfig 改完重跑 checksetup.pl；params.json 走界面或 CLI SetParam。
实录 2：REST 无法读写参数。实测 GET /rest/params 与 PUT /rest/params/<name> 均返回：
{"code":32614,"message":"A REST API resource was not found for 'GET /params'.","error":true}
5.2 的 REST API 没有暴露参数资源，参数管理只能走 Web 界面或 CLI（4.3 节），自动化场景请用 CLI 方案。
实录 3：邮件排障的 Test 模式。上线前不想真发邮件又要验证邮件内容：mail_delivery_method=Test 后触发任意 bug 变更，读 data/mailer.testfile；验证完记得切回真实投递方式，否则所有通知都会静默落到这个文件（无告警）。
七、参考链接
- 官方参数文档（Parameters 章节随版本内置于管理界面，每参数带说明）：https://www.bugzilla.readthedocs.io/
- 站内延伸：《Bugzilla 介绍与选型指南》、《Bugzilla 5.2 部署实战》、《Bugzilla 常用命令与运维实战》