简介这份资源面向需要搭建代码评审服务器的开发与运维人员围绕 Git、Repo 与 Gerrit 三大工具提供从零构建完整代码服务器的实践指引。内容涵盖服务器端与客户端角色划分、Git 与 Gitosis 的安装配置、管理员账户与公钥生成、gitosis.conf 权限管理、Repo 服务器搭建及 git-daemon 守护进程启停以及 Gerrit 的下载与配置帮助读者理解多仓库代码评审环境的整体架构与关键配置点。资源包为 1 个 docx 文档约 294KB以文字步骤与命令示例为主便于对照操作与查阅。目前已有 3136 人学习适合希望快速掌握代码服务器搭建流程、需要一份可跟随的配置参考的中级开发者。1. 从一台裸机到团队能推代码gitrepogerrit 代码服务器搭建到底在搭什么很多团队第一次搞代码服务器以为装个 Git 就完事结果人一多就翻车有人强推覆盖了别人的提交有人把没评审的代码直接合进主干分支乱得像一团麻。gitrepogerrit 这套组合解决的正是这个问题——Git 管版本Repo 管几十上百个仓库的批量拉取与提交Gerrit 管代码评审和权限闸门。它适合谁适合需要多仓库协同、又要求每次合入都过评审的中大型团队尤其是 Android 类多仓项目的开发场景。这套东西搭起来不算玄学但顺序和参数错一个后面全是坑。下面按我实际搭过的路径从零讲清楚每一步怎么落地。2. 装之前先把三件套的职责边界划清楚2.1 Git、Repo、Gerrit 各自管什么别混着用Git 是底层版本控制每个仓库独立存在提交、分支、合并都由它完成。Repo 是 Google 写的一个 Python 脚本本质是对 Git 的批量封装它读一个 manifest.xml 文件里面列出几十上百个 Git 仓库的地址和分支然后一次性帮你 clone 或 sync 全部仓库。Gerrit 则是架在 Git 之上的代码评审服务器它拦截 push 请求把提交变成待评审的 change评审通过后才真正合入分支。三者关系可以这样理解Repo 负责“把一堆 Git 仓库按清单拉到本地”Gerrit 负责“你推上来的代码先别进主干等人点 2 再说”。很多新手把 Repo 当成版本控制工具其实它只是批量操作器真正的版本数据全在 Git 里。Gerrit 也不是替代 Git它只是给 Git 加了一道评审门禁。选型上如果团队只有一两个仓库直接用 Git Gerrit 就够了Repo 反而增加复杂度。但仓库数量超过十个、且需要统一版本快照时Repo 的 manifest 机制就是刚需。我一般会先问一句你们是单仓还是多仓多仓且要统一发版才上 Repo。2.2 系统环境与依赖版本怎么定搭建前先定基础环境。我习惯用 Ubuntu 20.04 或 22.04 LTS内核稳定包管理成熟。Java 是 Gerrit 的硬依赖Gerrit 3.x 需要 Java 11Gerrit 3.4 以上建议 Java 11 或 17。Git 版本至少 2.20 以上Repo 需要 Python 3.6。先更新系统并装基础包# 更新包索引并安装基础依赖 sudo apt update sudo apt install -y git openjdk-11-jdk python3 python3-pip curl wget # 验证版本确保满足最低要求 git --version # 应 2.20 java -version # 应显示 11.x python3 --version # 应 3.6逻辑说明openjdk-11-jdk是 Gerrit 3.x 的推荐运行时python3用于跑 Repo 脚本。参数上注意如果系统默认 Java 是 8需要用update-alternatives切换否则 Gerrit 启动会直接报 UnsupportedClassVersionError。Repo 工具本身是一个 Python 脚本官方推荐从源码仓库拉取但为了内网可控我一般直接下载单文件版本放到/usr/local/bin/repo然后加执行权限。这样不依赖外部网络后续团队统一用同一份脚本。提示所有节点的时间必须同步Gerrit 对时间戳敏感偏差超过几分钟会导致认证失败。装个 chrony 或 ntp 是基本操作。2.3 数据库与认证方式的选择Gerrit 支持 H2、PostgreSQL、MySQL 三种数据库。小团队或测试环境用 H2 足够它内嵌在 Gerrit 里零配置。但生产环境我强烈建议上 PostgreSQL因为 H2 在并发写入和备份恢复上明显吃力一旦 change 数量上万查询会变慢。认证方式上Gerrit 支持 HTTP、LDAP、OAuth 等。内网团队最省事的是 HTTP 认证配合 Nginx 做反向代理和 Basic Auth。如果公司已有 LDAP直接接 LDAP 更统一。我下面以 HTTP 认证为例因为不依赖外部目录服务复现门槛最低。数据库选 PostgreSQL 时先建库建用户-- 创建 Gerrit 专用数据库和用户 CREATE USER gerrit WITH PASSWORD your_strong_password; CREATE DATABASE reviewdb OWNER gerrit; -- 授予必要权限 GRANT ALL PRIVILEGES ON DATABASE reviewdb TO gerrit;逻辑说明Gerrit 不会自动建库必须提前准备好。密码要复杂因为 Gerrit 配置文件里会明文存储后续可用环境变量或加密方式缓解。参数上数据库字符集建议 UTF8排序规则用 en_US.UTF-8避免中文提交信息乱码。3. 从零把 Gerrit 跑起来初始化、配置、启动3.1 下载与初始化 Gerrit 站点Gerrit 以 war 包形式发布下载后用一个空目录做站点根。我一般把站点放在/home/gerrit/site独立用户运行避免权限混乱。# 创建专用用户和站点目录 sudo useradd -m -s /bin/bash gerrit sudo mkdir -p /home/gerrit/site sudo chown -R gerrit:gerrit /home/gerrit # 下载 Gerrit war 包以 3.8.0 为例实际按需选稳定版 cd /home/gerrit sudo -u gerrit wget https://gerrit-releases.storage.googleapis.com/gerrit-3.8.0.war # 初始化站点-d 指定站点目录 sudo -u gerrit java -jar gerrit-3.8.0.war init -d /home/gerrit/site初始化过程是交互式的会问数据库类型、认证方式、监听地址等。关键选择数据库选 PostgreSQL 并填入前面建好的库信息认证选 HTTP监听地址填*:8080或127.0.0.1:8080如果前面有 Nginx。初始化完成后站点目录下会生成etc/gerrit.config和etc/secure.config。逻辑说明init命令会创建目录结构、初始化数据库表、生成默认配置。参数-d指定站点根所有后续操作都基于这个目录。如果中途选错可以删掉站点目录重来但数据库里的表需要手动清理。3.2 gerrit.config 里必须改的五个参数初始化后别急着启动先打开etc/gerrit.config逐项检查。下面五个参数是我踩过坑后每次必改的[gerrit] basePath git # Git 仓库存储根目录相对站点根 canonicalWebUrl http://your-server-ip/ # 对外访问地址影响邮件链接和回调 [ database ] type postgresql hostname localhost database reviewdb username gerrit [auth] type HTTP # 认证方式与 Nginx 配合 [ httpd ] listenUrl proxy-http://127.0.0.1:8081/ # 只监听本地由 Nginx 转发 [sendemail] enable true smtpServer smtp.your-domain.com smtpUser notifyyour-domain.com from notifyyour-domain.com逻辑说明canonicalWebUrl必须和用户浏览器访问的地址完全一致否则登录后跳转会丢 session。listenUrl用proxy-http表示前面有反向代理Gerrit 只处理本地请求。sendemail用于发送评审通知不配的话用户收不到提醒评审流程会卡住。参数上basePath默认是git所有仓库会存在site/git/下。如果磁盘空间紧张可以改成绝对路径挂到大盘。smtpServer如果公司有内部邮件中继填内网地址更稳。3.3 启动、验证与第一个管理员账号配置改完后启动 Gerrit# 以 gerrit 用户启动 sudo -u gerrit /home/gerrit/site/bin/gerrit.sh start # 查看启动日志确认无报错 tail -f /home/gerrit/site/logs/error_log启动后用浏览器访问canonicalWebUrl第一次访问会要求注册。第一个注册的账号需要手动在数据库里提权为管理员-- 连接 reviewdb把第一个账号加入管理员组 UPDATE account_external_ids SET external_id username:admin WHERE external_id LIKE %admin%; -- 更稳妥的方式是通过 Gerrit 的 SSH 命令加权限实际上更规范的做法是用 SSH 登录 Gerrit 后执行gerrit set-members。先配置 SSH 公钥到etc/ssh_host_rsa_key对应的账号然后# 添加管理员到 Administrators 组 ssh -p 29418 adminlocalhost gerrit set-members --add admin Administrators逻辑说明Gerrit 的权限模型基于组第一个管理员必须手动提权否则没人能审批。SSH 端口默认 29418在gerrit.config的sshd段可改。参数--add后跟用户名和组名组名区分大小写。注意如果 SSH 连不上检查sshd.listenAddress是否配置正确以及防火墙是否放行 29418 端口。4. 把 Repo 和 Gerrit 接起来manifest 仓库与推送流程4.1 创建 manifest 仓库并写第一个清单Repo 的核心是 manifest 仓库它本身也是一个 Git 仓库里面放default.xml文件列出所有子仓库的路径和地址。这个仓库通常也托管在 Gerrit 上方便统一管理。先在 Gerrit 里建一个空仓库叫manifest然后本地初始化# 克隆 manifest 仓库此时为空 git clone ssh://adminlocalhost:29418/manifest cd manifest # 创建 default.xml定义两个子仓库 cat default.xml EOF ?xml version1.0 encodingUTF-8? manifest remote nameorigin fetchssh://gitlocalhost:29418 / default remoteorigin revisionmain / project nameproject-a pathsrc/project-a / project nameproject-b pathsrc/project-b / /manifest EOF # 提交并推送 git add default.xml git commit -m Add initial manifest git push origin HEAD:refs/heads/main逻辑说明remote定义仓库的拉取基地址default定义默认分支project每行一个子仓库。path是拉到本地后的相对目录。参数上revision可以写分支名或 tag团队发版时通常锁 tag。推送时注意Gerrit 默认拦截直接推送到refs/heads/main需要走评审。第一次初始化 manifest 仓库时可以临时给管理员开Push权限直接推或者用refs/for/main走评审。我一般先直接推因为此时还没有评审流程。4.2 用 repo init 和 repo sync 拉取全部仓库manifest 仓库准备好后开发者机器上装好 repo 脚本就可以一键拉取所有子仓库# 初始化 repo指定 manifest 仓库地址和分支 repo init -u ssh://adminlocalhost:29418/manifest -b main # 同步所有子仓库 repo sync -j4 # 查看当前 manifest 管理的仓库列表 repo list逻辑说明repo init会克隆 manifest 仓库到.repo/manifests并生成.repo/manifest.xml。repo sync根据清单逐个克隆或更新子仓库。参数-j4表示并行 4 个任务网络好可以调大但别超过 CPU 核数太多。repo list输出所有仓库路径和对应的 Git 目录用来确认清单是否生效。如果某个仓库拉不下来先检查 manifest 里的fetch地址是否拼对Gerrit 的 SSH 端口是否写对。4.3 推代码到 Gerrit 走评审的完整命令子仓库拉下来后修改代码提交时走 Gerrit 评审# 进入某个子仓库 cd src/project-a # 创建本地分支并修改文件 git checkout -b feature/login echo new feature feature.txt git add feature.txt git commit -m Add login feature # 推送到 Gerrit 的 refs/for/main触发评审 git push origin HEAD:refs/for/main逻辑说明refs/for/main是 Gerrit 的特殊引用表示“推送到 main 分支的评审队列”。Gerrit 收到后会创建一个 change返回一个 Change-Id。评审人点 2 并 submit 后代码才真正合入 main。参数上如果目标分支不是 main把refs/for/main改成对应分支名。如果推送报错missing Change-Id需要装 commit-msg 钩子# 从 Gerrit 下载 commit-msg 钩子 scp -p -P 29418 adminlocalhost:hooks/commit-msg .git/hooks/这个钩子会自动在提交信息末尾生成 Change-IdGerrit 靠它追踪同一个 change 的多个补丁集。5. 避坑与排查搭建过程中最容易翻车的五件事5.1 现象Gerrit 启动后浏览器访问 502原因Nginx 反向代理配置和 Gerrit 的listenUrl不匹配。Gerrit 配了proxy-http://127.0.0.1:8081但 Nginx 转发到了 8080或者路径没带对。解决检查 Nginx 配置确保proxy_pass指向 Gerrit 实际监听地址并且带上X-Forwarded-For和Host头。Gerrit 的canonicalWebUrl必须和浏览器地址一致否则登录跳转丢 session。5.2 现象repo sync 报错 “Cannot fetch project”原因manifest 里的fetch地址用了 HTTP但 Gerrit 只开了 SSH或者 SSH 端口不是默认 22而 manifest 里没写端口。解决在remote的fetch里显式写端口如ssh://gitlocalhost:29418。同时确认 Gerrit 的sshd.listenAddress配置正确防火墙放行。5.3 现象推送代码时提示 “prohibited by Gerrit: not permitted”原因当前账号没有目标分支的 Push 权限或者推错了引用直接推了refs/heads/main而不是refs/for/main。解决在 Gerrit 的All-Projects仓库里检查refs/for/refs/heads/main的 Push 权限确保对应用户组有权限。推代码时统一用refs/for/前缀。5.4 现象评审通过后代码没合入主干原因change 虽然 2 了但没点 Submit或者分支被锁submit 规则要求 rebase。解决检查 change 页面是否显示 “Submit” 按钮可用。如果提示 “Not current”需要先 rebase 到最新。Gerrit 的 submit 策略在project.config里可配默认是 Fast Forward Only要求线性历史。5.5 现象邮件通知收不到原因sendemail配置的 SMTP 服务器拒绝转发或者from地址和认证用户不匹配。解决先用swaks或telnet手动测试 SMTP 连通性。Gerrit 的邮件日志在logs/error_log里搜 “sendemail” 能看到具体报错。如果公司 SMTP 需要 TLS在gerrit.config里加smtpEncryption TLS和端口 587。6. 进阶技巧用 replication 做异地备份与只读镜像6.1 配置 replication.config 实现自动推送Gerrit 自带 replication 插件可以把每个仓库的变更自动推送到另一个 Git 服务器做异地备份或只读镜像。配置文件在etc/replication.config[remote backup] url ssh://gitbackup-server:/data/git/${name}.git push refs/heads/*:refs/heads/* push refs/tags/*:refs/tags/* mirror true threads 4逻辑说明url里的${name}会被替换成仓库名push定义推送的引用范围mirror true表示强制同步删除也会同步。threads控制并发数备份服务器性能好可以调大。参数上如果备份服务器也是 Gerrit推送目标要写成refs/for/吗不用replication 是直接推分支不走评审。所以备份服务器上要有对应的直接推送权限通常用管理员账号或专用密钥。6.2 验证 replication 是否生效配置改完后重启 Gerrit然后随便推一个提交观察备份服务器上是否出现对应仓库和分支# 在备份服务器上查看仓库列表 ls /data/git/ # 查看 replication 日志 tail -f /home/gerrit/site/logs/replication_log如果日志里出现 “Replication to backup completed”说明成功。如果报权限错误检查 SSH 密钥是否配置到备份服务器的 authorized_keys以及备份仓库的权限。6.3 一个我踩过的坑replication 和 Gerrit 的 refs 冲突有次备份服务器上手动建了一个同名仓库导致 replication 推送时提示 “refusing to update checked out branch”。原因是备份仓库的HEAD指向了当前分支而 Git 默认拒绝更新已检出的分支。解决备份服务器上的仓库必须用裸仓库bare repo即git init --bare。如果已经建错了删掉重建或者把receive.denyCurrentBranch设为ignore。但最稳妥的还是裸仓库这也是我后来所有备份节点的标准做法。注意replication 是异步的有延迟。如果要求强一致得用共享存储或同步复制方案那是另一个话题了。这套东西搭完团队就能在统一入口下管多仓、走评审、做备份。我自己的习惯是每次新搭一套先跑通一个最小仓库的完整评审流程再批量导入其他仓库。别一上来就全量迁移出问题不好定位。希望帮到你。本文还有配套的精品资源点击获取