Gerrit 配置参数详解

目标：以 Gerrit 3.14.4 站点实测生成的 etc/gerrit.config 为底本，逐节讲解各配置段（gerrit、container、auth、database、sshd、httpd、sendemail、receive、index、cache、change 等）的参数含义、默认值与生产调整建议，并单独说明 etc/secure.config 密钥配置与站点目录体系。参数语义以官方 config-gerrit 文档为准（3.14 版，查询日期 2026-10-27），配置文件内容为本环境实测。

一、环境信息

• Gerrit 版本：3.14.4（官方镜像 gerritcodereview/gerrit:3.14.4，站点目录 /var/gerrit，自动 init 生成）
• 配置文件路径：/var/gerrit/etc/gerrit.config（主配置）、/var/gerrit/etc/secure.config（密钥配置），宿主 bind mount 于部署目录 etc/
• JVM：OpenJDK 21（镜像内置），Gerrit 进程用户 gerrit
• 参数语义参考：官方文档 https://gerrit-review.googlesource.com/Documentation/config-gerrit.html（查询日期 2026-10-27）
• 实测环境配套部署篇：《Gerrit 3.14 Docker Compose 部署实战》（发布后可互链），本篇在该站点上直接取材

二、配置文件体系总览

Gerrit 站点目录 /var/gerrit 结构（实测 ls 回显）：

bin      cache    data     db       etc      git
index    lib      logs     plugins  static   tmp

etc/ 内与配置相关的文件（实测清单）：

关键机制：

1. 修改即生效方式：除个别段外（如 [plugins] 热装载），改 gerrit.config 后需重启服务生效（部署篇的 docker compose restart；裸机为 bin/gerrit.sh restart）；
2. 敏感信息分离：口令类写 secure.config（[database] password、[ldap] password、[sendemail] smtpPass 等，段名与主配置同名对应），文件权限收紧到 600；
3. 继承体系：项目级配置（project.config）继承 All-Projects，All-Projects 又可被 gerrit.config 的默认值兜底——三层覆盖顺序为：项目配置 > All-Projects > gerrit.config。

实测自动 init 生成的 secure.config 内容：

[auth]
	registerEmailPrivateKey = zIz+P9F8yvaqfT1ULS8lEotHfzsc7hJjtz0=

registerEmailPrivateKey 用于邮箱验证链接签名，init 自动生成，勿改勿丢（丢失后历史待验证邮箱链接全部失效）。

三、gerrit.config 逐节详解

以下底本为实测站点的初始 gerrit.config（自动 init 生成，详见部署篇第七节），逐节展开参数表。每节先列实测初始值，再列生产常用可调项。

3.1 [gerrit]：站点全局参数

[gerrit]
	basePath = git
	canonicalWebUrl = http://localhost:8141
	serverId = 4019fa49-0f3f-41c3-b794-5405c7edbb13

生产要点：canonicalWebUrl 必须与用户实际访问地址（含反代后的域名/端口）一致；多站点/灾备复制场景 serverId 保持主站原值。

3.2 [container]：进程与 JVM

[container]
	javaOptions = "-Dflogger.backend_factory=com.google.common.flogger.backend.log4j.Log4jBackendFactory#getInstance"
	javaOptions = "-Dflogger.logging_context=com.google.gerrit.server.logging.LoggingContext#getInstance"
	user = gerrit
	javaHome = /usr/lib/jvm/java-21-openjdk-21.0.12.1.1-1.2.el9.alma.1.x86_64
	javaOptions = -Djava.security.egd=file:/dev/./urandom
	javaOptions = --add-opens java.base/java.net=ALL-UNNAMED
	javaOptions = --add-opens java.base/java.lang.invoke=ALL-UNNAMED

注意：官方镜像的 JAVA_OPTS 环境变量会被入口脚本覆盖（部署篇 13.2 排障实录），JVM 参数只认这里。

3.3 [auth]：认证体系

[auth]
	type = OPENID

type 全枚举（3.14 官方文档）：

其他常用参数：

相关凭据：HTTP 模式下账户密码走 REST /accounts/<user>/password.http 设置（部署篇实测），3.13 起 HTTP 密码机制逐步废弃、转向 token，新建站点优先考虑 token 方案。

3.4 [database]：元数据库

H2 默认形态（自动 init 不写 [database] 段，全部走默认值：站点目录 db/ 下 H2 文件库）。显式配置示例：

[database]
	type = postgresql
	hostname = db
	database = reviewdb
	username = gerrit

H2 专属：3.12 起 H2 升级 v2 后端，3.10 引入可配置的 H2 缓存裁剪。切换数据库属站点级决策（无在线迁移），新站直接选定（部署篇第十节给过 PostgreSQL 完整三步）。

3.5 [sshd]：SSH 服务（Git 推拉 + 命令面）

[sshd]
	listenAddress = *:29418

主机密钥自动生成于 etc/ssh_host_*（实测含 rsa/ecdsa/ed25519 三族），换机器迁移站点时必须带走，否则全部客户端报 host key 变更告警。

3.6 [httpd]：HTTP 服务（Web UI + REST API）

[httpd]
	listenUrl = http://*:8080/

与本篇部署形态对应：listenUrl 保持 http://*:8080/，TLS 与 Basic 认证由 nginx 网关层承担（部署篇 4.4）。

3.7 [sendemail]：邮件通知

[sendemail]
	smtpServer = localhost

评审通知邮件是团队感知 Gerrit 的第一界面，上线前务必用真实 SMTP 联调（表单触发：评审打分 → 收件人收到 Change-URL 邮件）。

3.8 [receive]：推送接收策略

[receive]
	enableSignedPush = false

3.9 [index]：二级索引

[index]
	type = lucene

索引可随时全量重建：java -jar gerrit.war reindex -d /var/gerrit（镜像内入口脚本每次启动自动跑）。index 目录整体可删（重启自动重建），升级版本后如遇查询异常先 reindex 再排查。

3.10 [cache]：运行缓存

[cache]
	directory = cache

内置缓存族（实测 gerrit show-caches 回显的条目即来自这些定义，见部署篇第十三节）：

调优写法（内存权重模式）：

[cache "change_notes"]
	memoryLimit = 1024

directory 持久化缓存目录可整体清空（重启自动重建），排障常用手段。

3.11 [change]：评审行为

3.12 [user]：匿名显示

[user]
	anonymousCoward = Anonymous Coward

anonymousCoward：未登录用户的展示名（内核社区梗），企业内网一般不改。

3.13 [plugins]：插件装载

本站实测默认装载的官方插件（init 日志）：gitiles、hooks、plugin-manager、replication、reviewnotes、singleusergroup、uploadvalidator、webhooks、delete-project。

四、secure.config 详解

secure.config 与 gerrit.config 段结构同构，专放口令/私钥。常用键位：

[database]
	password = <DB 口令>

[ldap]
	password = <LDAP bind 口令>

[sendemail]
	smtpPass = <SMTP 口令>

实测站点当前内容仅有 init 自动生成的邮箱签名私钥：

[auth]
	registerEmailPrivateKey = zIz+P9F8yvaqfT1ULS8lEotHfzsc7hJjtz0=

管理规范：

1. 权限收紧 chmod 600 etc/secure.config（bind mount 到宿主后在宿主侧执行）；
2. 口令轮换只改此文件 + 重启，主配置不动；
3. 备份策略与 gerrit.config 同级但渠道隔离（口令不进代码库、不进通用配置仓库）。

五、典型场景配置示例

5.1 企业内网标准站（PostgreSQL + LDAP + SMTP）

[gerrit]
	canonicalWebUrl = https://gerrit.example.com
[auth]
	type = LDAP
[ldap]
	server = ldap://ldap.example.com
	accountBase = ou=people,dc=example,dc=com
	accountPattern = (&(objectClass=person)(uid=${username}))
	groupBase = ou=groups,dc=example,dc=com
[database]
	type = postgresql
	hostname = pg.internal
	database = reviewdb
	username = gerrit
[sendemail]
	smtpServer = smtp.example.com
	smtpEncryption = starttls
	smtpUser = gerrit@example.com
	from = SERVER
[sshd]
	listenAddress = *:29418
[httpd]
	listenUrl = proxy-http://*:8080/

配套 secure.config：

[database]
	password = xxxxxxxx
[ldap]
	password = xxxxxxxx
[sendemail]
	smtpPass = xxxxxxxx

5.2 大规模站点（ES 索引 + JVM 调优）

[index]
	type = elasticsearch
[elasticsearch]
	hostname = es.internal
	port = 9200
[container]
	javaOptions = -Xms4g -Xmx4g
	javaOptions = -XX:+UseG1GC

5.3 反代 TLS 卸载（httpd 感知代理）

[httpd]
	listenUrl = proxy-http://*:8080/

配合 nginx proxy_set_header X-Forwarded-Proto $scheme;，Gerrit 生成链接自动带 https（部署篇 4.4 的网关配置已含该头）。

六、配置生效与校验

1. 语法校验：启动日志是第一校验器——配置段名/键名写错时启动即报 FATAL（如未知段落直接拒绝启动），改配置后 docker logs gerrit-3.14.4-app 观察到 Gerrit Code Review 3.14.4 ready 即合法且生效；
2. REST 读取验证：运行时配置片段可通过 REST 校验：

curl -s -u admin:q1w2e3r4 http://localhost:8141/config/server/version
curl -s -u admin:q1w2e3r4 http://localhost:8141/config/server/info | head -5

实测回显：

)]}'
"3.14.4"

)]}'
{"gerrit":{"all_projects":"All-Projects","all_users":"All-Users",...}}

3. SSH 面验证：gerrit show-caches（部署篇回显）输出的 uptime 行可确认当前进程是否已带新配置重启；
4. 回滚：改坏配置导致起不来时，直接回滚 etc/gerrit.config 后重启即可（配置与数据分离，改配置本身不破坏站点数据）。

七、常见配置错误（排障实录）

7.1 canonicalWebUrl 写错导致页面/链接异常

现象：页面能开，但点 Change 通知邮件链接 404，或登录后重定向回错误端口。根因：canonicalWebUrl 与实际访问地址不一致（实测环境 init 按 CANONICAL_WEB_URL=http://localhost:8141 生成，改对外域名后未同步此项）。解决：canonicalWebUrl 改为用户真实访问地址后重启。

7.2 JAVA_OPTS 环境变量不生效

现象：Compose 里设 JAVA_OPTS=-Xmx512m，进程实际未按此运行。根因：镜像入口脚本覆盖了该变量（部署篇 13.2 实录）。解决：堆参数写入 [container] javaOptions，验证方式见部署篇第七节（-Xms256m -Xmx512m 回显）。

7.3 [sshd] 端口冲突启动失败

现象：BindException: Address already in use。根因：29418 在宿主侧已被占用（本环境实测：同宿主并行组件已占 29418）。解决：保持 Gerrit 内部 listenAddress = *:29418 不动，在编排层把宿主侧映射换到空闲端口（部署篇 4.3 映射 8148 的口径）。

7.4 sendemail 指向 localhost 但无本机 MTA

现象：评审操作正常，邮件收不到；日志出现 MailException / 连接拒绝。根因：smtpServer = localhost 是 init 默认值，站点没有本机 SMTP。解决：指向真实 SMTP 并配齐 smtpEncryption/smtpUser（口令进 secure.config）。

7.5 auth.type 改错值启动 FATAL

现象：[auth] type = http（小写/拼写错）后启动报非法枚举。根因：type 值是枚举常量，大小写敏感。解决：按 3.3 节枚举表写标准值（HTTP、LDAP、DEVELOPMENT_BECOME_ANY_ACCOUNT…）。

八、参考链接

1. config-gerrit 官方参数文档（3.14）：https://gerrit-review.googlesource.com/Documentation/config-gerrit.html
2. 认证配置：https://gerrit-review.googlesource.com/Documentation/config-authentication.html
3. 反向代理配置：https://gerrit-review.googlesource.com/Documentation/config-reverseproxy.html
4. 数据库配置：https://gerrit-review.googlesource.com/Documentation/config-database.html
5. 站内《Gerrit 3.14 Docker Compose 部署实战》：https://www.quzuo.net/document/ypUmjOG83Lt8
6. 站内《Gerrit 介绍与选型指南》：https://www.quzuo.net/document/jBzSHXoP3n0J