企业官网建设流程全解析

1. 整体设计思路：为什么我会选择自建一套代码审查流程

代码审查这件事，团队里永远有人觉得它是形式主义，也有人觉得它是质量保障的最后一道防线。我个人的看法是：代码审查本身绝对有用，但很多团队之所以觉得它没用，是因为审查流程设计得太粗糙，要么是走过场式地点个赞，要么是等代码合并之后才有人认真看，发现问题已经晚了。

"open-code-review"这个项目，说白了就是一套基于开源组件自建的代码审查基础设施。它不是某个单一软件，而是一整套流程和工具链的组合，覆盖了从提交代码、触发审查、人工评审、自动检查到最终合并的完整链路。我在实际落地的时候，参考过GitHub的Pull Request流程，也研究过Gerrit的集中式审查模型，最后结合团队规模和技术栈做了一套适合自己的方案。

先说清楚这套东西解决了什么问题。在没有规范化审查流程的时候，团队里最常见的场景是：开发者在功能分支上写完代码，直接推到主干，然后测试环境开始报错；或者Code Review变成了事后诸葛亮，代码已经上线了，Reviewer才在群里说"这个写法有问题"。而有了open-code-review这套流程之后，每次合入必须经过两部分检查，一是机器自动跑的静态检查、单元测试、构建验证，二是人工Reviewer的明确批准。任何一步不通过，代码就合不进去，这就从机制上堵住了"先上线再补票"的漏洞。

那这套东西适合谁来用呢？我觉得主要适合三类人：一是刚起步的中小型研发团队，想在GitHub或GitLab上建立规范的代码合入流程但又不想花钱买企业版；二是已经受够了开发流程混乱、想用开源方案快速搭建内部研发基础设施的技术负责人；三是对Gerrit这类集中式审查工具有兴趣、想在自己的服务器上跑一套完整环境来学习的开发者。不管你是哪种情况，下面这些内容都是我这几个月踩坑踩出来的经验，可以直接照着用。

可能有人会问，为什么不直接用GitHub或GitLab官方提供的代码审查功能？这个问题的答案其实也是我当初决定做这个项目的核心原因。先说GitHub，免费版对私有仓库的审查支持其实够用，但有些团队代码必须放在内网，不允许推到公网服务，这就不得不自建。再说GitLab，社区版确实自带Merge Request和代码审查功能，但它对"强制审查"的约束比较弱，比如管理员可以绕过审批直接合并，自动检查的集成配置也需要一定经验。Gerrit则正好相反，它的审查模型非常严格，每一行代码都可以被逐行评论，没有Reviewer的打分合入就永远无法进行，但它也有问题，就是对Git工作流做了比较大的改动，开发者需要额外学习。

所以这套open-code-review的设计哲学是：不要盲目追求工具的功能多强大，而是根据团队的实际协作模式选择最合适的方案。在我这套流程里，我同时兼容了两种主流的代码审查模型，一种是基于Merge或Pull Request的轻量级审查，适合快速迭代的互联网团队；另一种是基于Gerrit的集中式审查，适合对代码质量要求极高、甚至需要审计记录的团队。下面我会把这两种方案的搭建过程和踩坑经验都写出来。

2. 核心细节解析与方案选型考量

2.1 代码审查的两种核心模型，到底怎么选

代码审查工具虽然多，但底层的协作模型基本只有两种。理解这两种模型的差异，是在做选型之前最重要的事。

第一种是基于分支合并的审查模型，代表是GitHub Flow和GitLab Flow。它的工作方式是：开发者从主干拉出一个功能分支，在功能分支上提交代码，然后把功能分支推送到远端，发起一个Merge Request或者Pull Request。审查者在这个Request里查看代码差异，留下评论，开发者可以针对评论继续添加提交。所有人都同意之后，把功能分支合并回主干。这种模型的优点是贴近大多数开发者的日常习惯，分支即隔离，冲突处理相对简单，适合每天多次发布、追求迭代速度的产品团队。缺点也很明显，因为合并之后通常不会对每个提交做严格的线性化处理，历史记录里会有比较多的合并节点，而且逐行审查的精度不如Gerrit那么细。

第二种是集中式的审查模型，代表是Gerrit。Gerrit的核心思想是"没有审查就没有提交"。开发者的提交不会直接进入仓库主干，而是先进入Gerrit的一个暂存区，Gerrit为每个提交生成一个Change，审查者在网页界面上逐行评论打分，分数达到要求后，Gerrit才把这个提交真正合入目标分支。这种模型的好处是审查粒度极细、强制力极强，每一行代码都有人看过，而且任何绕过审查的动作几乎不可能发生。缺点是学习成本高，开发者需要改变推送方式，使用git push origin HEAD:refs/for/master这样的命令而不是普通的git push，新手很容易在这里被卡住。

我在实际项目中是这样取舍的：如果团队人数在20人以下，产品迭代速度很快，那么用GitLab或Gitea的Merge Request就足够了，不要引入Gerrit增加团队负担。如果团队做的是底层基础设施、支付系统、安全相关的高风险项目，或者在合规审计上有硬性要求，那么直接上Gerrit，它能提供的审计记录和强制流程是GitLab很难替代的。

2.2 开源方案横评：GitLab、Gitea、Gerrit、Review Board

不卖关子，我直接把对比结果放在下面这张表格里，这是我搭建open-code-review时做了大量调研之后总结出来的。

GitLab CE是我个人最推荐的首选。它的社区版虽然砍掉了一些企业功能，但代码审查核心链路全部保留，比如Merge Request、Inline Comment、Approval Rules（部分版本通过配置文件支持）、CI集成等。部署方式也友好，有官方Omnibus安装包，也有Docker镜像。我在生产环境用的就是Docker版的GitLab CE，搭配Runner跑自动化检查。

Gitea的优势是极轻量，一台1核2G的服务器就能跑得很流畅，界面响应速度比GitLab快很多。但它的问题在于代码审查功能比较弱，虽然支持Pull Request和评论，但在审查规则、权限约束、CI集成方面差得比较远，适合个人项目或者极小的团队，不适合作为企业级审查基础设施。

Gerrit的部署和配置确实是四者里最复杂的，它依赖Java环境，底层用JGit实现，数据库默认用H2，实际生产建议换成MySQL或PostgreSQL。但它也是唯一一个能把"强制审查"做到极致的开源方案。如果你需要的是"没有批准绝对无法合入"这种硬约束，Gerrit是唯一的选择。

2.3 审查流程设计中的三个关键原则

工具选好了，流程设计更重要。我在open-code-review里遵循了三个核心原则，这三个原则也是我踩过坑之后总结出来的。

第一个原则是"机器能干的活绝对不让人工干"。代码风格检查、重复代码检测、单元测试、编译构建这些完全可以自动化的检查，一定要在代码进入人工审查之前就全部跑完。人工Reviewer的时间和精力是最宝贵的资源，应该只用来关注逻辑正确性、代码可读性、架构合理性这些机器难以判断的问题。我在CI流水线里配置了静态检查、单元测试和代码覆盖率采集，任何一个环节失败，Merge Request的合入按钮就会自动置灰。

第二个原则是"审查结果必须有明确的状态和记录"。审查不能只是口头说说，所有的批准、驳回、评论意见都必须有系统记录。这不仅是审计的需要，也是防止"我明明说过了但他没改"这种扯皮事件的关键。Gerrit天然具备这个能力，GitLab则需要通过配置Approval Rules来实现，比如要求至少两名指定Reviewer批准、代码所有者必须参与审查等。

第三个原则是"流程要有弹性，不能一刀切"。我见过一些团队把审查流程搞得极其严格，改一行注释也需要两位高级工程师批准，结果就是大家为了绕过流程开始投机取巧。合理的做法是区分变更等级：比如普通Bug修复只需要1个Reviewer批准；涉及公共接口变更、数据库结构变更的高风险MR，则必须2个Reviewer批准，并且要求架构组相关成员参与。这种弹性设计能让团队的审查效率和质量达到一个最佳的平衡点。

3. 实操过程：从零搭建基于GitLab的开源代码审查环境

3.1 快速部署GitLab，我的Docker Compose配置

这一节我把最常用的方案写出来，就是基于GitLab CE自建代码仓库和审查环境。如果你已经有现成的GitLab，可以直接跳到3.2节看审查规则配置。

我这边生产环境用的是Docker Compose部署，配置文件可以直接抄作业。先建立一个docker-compose.yml，内容如下：

version: '3.8' services: gitlab: image: gitlab/gitlab-ce:16.10.2-ce.0 container_name: gitlab restart: always hostname: gitlab.example.com environment: GITLAB_OMNIBUS_CONFIG: | external_url 'https://gitlab.example.com' gitlab_rails['gitlab_shell_ssh_port'] = 2222 gitlab_rails['initial_root_password'] = 'YourStrongRootPassword' gitlab_rails['smtp_enable'] = true gitlab_rails['smtp_address'] = 'smtp.example.com' gitlab_rails['smtp_port'] = 465 gitlab_rails['smtp_user_name'] = 'gitlab@example.com' gitlab_rails['smtp_password'] = 'smtp_password' gitlab_rails['smtp_domain'] = 'example.com' gitlab_rails['smtp_authentication'] = 'login' gitlab_rails['smtp_tls'] = true ports: - '80:80' - '443:443' - '2222:22' volumes: - /srv/gitlab/config:/etc/gitlab - /srv/gitlab/logs:/var/log/gitlab - /srv/gitlab/data:/var/opt/gitlab shm_size: '256m'

几个关键点说一下。initial_root_password只在首次初始化时生效，如果容器已经运行过再修改这个环境变量是没用的，必须在启动后登录后台改，或者直接在/etc/gitlab/gitlab.rb里改。GITLAB_OMNIBUS_CONFIG这个环境变量里的配置会被Omnibus在容器启动时自动读取和应用，比进容器敲命令方便得多。shm_size一定要显式配置，GitLab的PostgreSQL和Redis对共享内存有一定需求，默认值太小会导致启动时随机出现异常。

启动命令很简单：

docker compose up -d docker compose logs -f gitlab

等待日志中出现类似gitlab Reconfigured!的提示，就可以通过浏览器访问了。首次启动可能需要三到五分钟，不要急着刷新页面，GitLab在后台做初始化，期间页面返回502是正常现象。

3.2 配置Merge Request审批规则，让"强制审查"真正生效

GitLab CE版本的Approval Rules在Web界面里默认不可见，因为GitLab把可视化的审批规则配置做进了付费版。但有个隐藏的能力，CE版的审批规则可以通过项目配置文件.gitlab/merge_request_approvals.yml来管理，或者通过API调用开启。我在部署时就通过API把审批规则配置好了。

先拿API开启一个项目的审批功能，这里的PROJECT_ID是项目主页URL里的数字ID，PRIVATE_TOKEN需要在用户设置里生成一个有api权限的Personal Access Token：

curl --request POST \ --header "PRIVATE-TOKEN: <your_private_token>" \ --header "Content-Type: application/json" \ --data '{"approvals_required": 1, "reset_approvals_on_push": true}' \ "https://gitlab.example.com/api/v4/projects/<PROJECT_ID>/approvals"

这个接口的作用是设置该项目合并请求需要的最少审批人数。approvals_required设成1意味着至少有一名有权限的成员点击Approve之后才能合并。reset_approvals_on_push设为true，意思是如果开发者新推送了提交，之前的审批自动失效，必须重新审批。这个配置非常关键，能防止"我先批准了，开发者又偷偷改代码比如加了一行删库逻辑，然后直接合并"这种安全漏洞。

如果你不想用API，也可以用Web界面操作。进入项目后，点击"Settings > Merge requests"，在"Approval settings"里勾选"Enable approval rules"，然后添加规则。比如我常用的配置是：

这个配置的原理是：大多数业务代码的MR有一个人认真看就够了，但数据库结构变更和CI配置变更影响面很大，必须至少两个人同时确认。GitLab的审批规则支持按文件路径匹配，所以我能做到这种精细化控制。

3.3 接入GitLab CI，让自动化检查成为合入的前置条件

审批规则只解决了"人"的约束，还差"机器"这道关卡。GitLab CI可以让你在MR创建和代码更新时自动执行检查任务，检查结果会直接显示在MR页面上，如果检查失败，Merge按钮同样是灰的。我把CI配置简化成下面这个例子：

stages: - lint - test - coverage variables: IMAGE_BASE: registry.example.com/ci-images lint: stage: lint image: ${IMAGE_BASE}/node:20-alpine script: - npm ci - npm run lint only: - merge_requests test: stage: test image: ${IMAGE_BASE}/node:20-alpine services: - postgres:15 variables: POSTGRES_DB: app_test POSTGRES_USER: tester POSTGRES_PASSWORD: testpass DATABASE_URL: postgresql://tester:testpass@postgres/app_test script: - npm ci - npm run test:ci artifacts: when: always reports: junit: junit.xml only: - merge_requests coverage: stage: coverage image: ${IMAGE_BASE}/node:20-alpine script: - npm ci - npx jest --coverage --coverageReporters=cobertura after_script: - curl -X POST -F "token=$COVERAGE_TOKEN" -F "commit=$CI_COMMIT_SHA" "https://coverage.example.com/api/upload" only: - merge_requests

这里有个特别重要的细节：only: [merge_requests]这个字段限定了这些任务只在MR存在时才执行。如果你不写这个限制，每次push代码到分支都会跑一遍完整流水线，对服务器资源是个不小的浪费。另外only和rules建议用rules代替，因为only/except在新版GitLab中已被标记为弱化语法，不过它是最好理解的，这里就不展开绕了。

对于没有CI/CD系统的团队，你完全可以把这一整套open-code-review简化成"GitLab + Shell脚本"的组合。在GitLab服务器上挂一个crontab脚本，每五分钟轮询一次处于open状态的MR，把每个MR对应的分支拉到临时目录执行语法检查和单元测试，然后把结果通过GitLab API写到MR的讨论区。这种方案虽然简陋，但能解决很多小团队"没有CI基础设施"的尴尬。

4. 常见问题与排查技巧实录

4.1 GitLab部署和权限相关的问题

问题1：GitLab启动后一直502，或者过几分钟就挂一次。

这个最常见的原因有两个。第一，服务器内存不足，GitLab全家桶加上PostgreSQL、Redis、Prometheus，4G内存是最低配置，8G才比较舒适。如果你只有2G内存，建议把Prometheus和Grafana关掉，在gitlab.rb里设置prometheus_monitoring['enable'] = false。第二，shm_size太小导致PostgreSQL崩溃，Docker Compose里显式设置shm_size: 256m就能解决。

问题2：用户无法通过SSH协议推拉代码。

GitLab的SSH默认监听22端口，但主机的SSH服务通常也占用了22端口。看我的Compose配置，把容器内的22端口映射到了宿主机的2222端口，这时候需要在GitLab的gitlab.rb里修改gitlab_shell_ssh_port为2222，否则用户克隆代码时生成的SSH URL端口是错的。还要注意，所有用户的克隆地址需要手动带上端口号，比如ssh://git@gitlab.example.com:2222/group/project.git。

问题3：MR提交后没有触发CI任务。

先检查.gitlab-ci.yml是不是放在项目根目录，文件名是否正确；再检查Runner是否在线，在"Settings > CI/CD > Runners"里查看有没有可用的Runner；最后检查你的only或rules条件是不是漏掉了merge_requests。

4.2 审查流程落地中的协调问题

工具层面的问题好解决，人在流程中的问题更难搞。我在open-code-review落地的过程中遇到最大的挑战，不是技术，而是组织行为。

一开始我们把审批人数设为2人，结果发现很多MR因为等第二个Reviewer而阻塞，一阻塞就是一整天。原因很简单，团队里不同成员负责的模块不一样，别人不敢随便批准自己不了解的代码。后来我把审批规则改成了按风险分级，普通代码1人批准即可，高风险变更才需要2人，整个流程的效率提升非常明显。

还有一个细节值得分享：给Reviewer配置邮件通知和待办提醒。GitLab支持在MR被分配给某个用户时，给该用户发送邮件，同时该MR会自动出现在他个人的"To Do"列表中。我要求团队里每个人都养成"看到待办就处理"的习惯，不管是通过还是驳回，至少要在当天给出反馈。代码审查最大的敌人是拖延，一旦拖上两天，开发者可能已经切到别的任务，再回来改就是额外的上下文切换成本。

5. 高阶玩法：基于Gerrit搭建更严格的集中式审查流程

如果你觉得GitLab的MR审查还不够"硬核"，那可以试试Gerrit。我在open-code-review项目里同时也部署了一套Gerrit环境，专门用于那些对代码质量要求极高的核心仓库。下面我把部署和基本使用流程写出来，方便有兴趣的读者直接照着操作。

5.1 用Docker快速启动Gerrit

Gerrit的官方Docker镜像在gerritcodereview/gerrit下，但直接跑一个单独的Gerrit容器会遇到一个问题，它默认使用H2数据库，性能一般而且数据备份麻烦。我建议用Docker Compose把Gerrit和PostgreSQL放在一起：

version: '3.8' services: postgres: image: postgres:15 container_name: gerrit-postgres environment: POSTGRES_DB: reviewdb POSTGRES_USER: gerrit POSTGRES_PASSWORD: gerritpass volumes: - pg_data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U gerrit"] interval: 10s timeout: 5s retries: 5 gerrit: image: gerritcodereview/gerrit:3.9 container_name: gerrit ports: - "8080:8080" - "29418:29418" depends_on: postgres: condition: service_healthy environment: CANONICAL_WEB_URL: http://gerrit.example.com:8080 GERRIT_INIT_ARGS: > --install-plugin=reviewnotes --install-plugin=delete-project volumes: - git_data:/var/gerrit/git - etc_data:/var/gerrit/etc - db_data:/var/gerrit/db command: init volumes: pg_data: git_data: etc_data: db_data:

这里有个坑需要提醒：Gerrit容器首次启动时用init命令初始化，它会自动生成/var/gerrit/etc/gerrit.config文件，然后退出。你需要在宿主机上修改生成的配置文件，把数据库相关配置指向PostgreSQL，然后再重启容器。具体来说，编辑etc_data卷里etc/gerrit.config，把[database]部分改成：

[database] type = POSTGRESQL hostname = postgres database = reviewdb username = gerrit

改完配置文件后，把容器命令从init改成空或者daemon，再docker compose up -d，Gerrit就会以正常模式启动。

5.2 完成一次Gerrit审查，从创建项目到Change合并

Gerrit中首次使用需要完成几个步骤。登录后点击"New Project"，填一个仓库名，设计权限组时要注意，项目分为两个层级：refs/heads/*是目标分支的引用，refs/for/*是开发者提交代码时推送的特殊引用路径。在权限配置里，把refs/for/*的Push权限授予普通开发者，把refs/heads/*的Push权限只授予管理员或集成负责人。这样开发者的代码永远不能直接推入主干，只能推送到审查暂存区。

完成项目配置后，克隆代码的命令与GitLab有所不同：

git clone http://gerrit.example.com:8080/YourProject cd YourProject git config remote.origin.push refs/heads/*:refs/for/* git config remote.origin.receivepack git receive-pack

这里把push refspec配置成refs/heads/*:refs/for/*，以后执行git push时，代码会自动进Gerrit的Change队列。如果是第一次推送某个新的change，Gerrit会返回一个类似http://gerrit.example.com:8080/c/YourProject/+/123的URL，这就是需要分享给Reviewer的Change页面地址。

在Reviewer端，打开Change页面后，会给每个Commit生成一个Patch Set。Reviewer点击"Reply"可以对Response进行打分，分数规则是：+2表示"可以合入"，+1表示"我没意见但不算批准"，-1表示"有意见但不反对"，-2表示"强烈反对"。只有得到某个具备Code Review +2权限的用户打出+2，Change才满足合入条件。

任何一个在Gerrit上审查过的开发者，都会对它的审查精度印象深刻。它对每一行代码都能单独评论，支持在提交的间隙继续追加修正，change的每一次更新都会产生新的Patch Set，同时保留之前的版本，方便对比。这种体验是GitLab MR难以做到的，也因此我建议所有追求代码质量的团队，都可以在核心仓库上尝试引入Gerrit，哪怕只做试点也行。

6. 常见问题与排查技巧实录（Gerrit篇与通用篇）

6.1 我在Gerrit上遇到的三个典型问题

问题1：普通开发者直接把代码push到了refs/heads/master，绕过了审查。

排查后发现是权限没配好。我在Gerrit的refs/heads/*权限里只允许Administrators组Push，但开发者使用的是同一个账号，所以问题不在账号，而在于权限继承。解决方法是，在项目配置里取消"继承自父项目"的权限选项，针对refs/heads/*明确拒绝非管理员组的Push权限。配置完成后，普通开发者push到主干时会被拒收，并收到一条"Push to refs/heads/master denied"的提示。

问题2：开发者提交了新的Patch Set后，原来的+2审批变成了+1或消失。

这是Gerrit的默认安全机制，新的Patch Set意味着代码内容发生了变化，旧的审批意见不再适用。Gerrit会根据新Patch Set与上一版的差异逐行重算，涉及改动的区域会重新进入"未审批"状态。这个特性安全设计是对的，但容易让开发者困惑，尤其是当一位Reviewer已经打完+2、开发者又修了一个小小的拼写错误时。我的建议是在团队规范里约定：有新Patch Set推送后，原Reviewer应重新审查，如果只是无关紧要的改动，应该顺手重新打分，不要因此卡住流程。

问题3：Gerrit服务器重启后，某些Change消失了或者项目列表为空。

这是H2数据库的常见问题，容器异常退出时H2可能损坏。解决办法就是从一开始就不用H2，而是配置外部PostgreSQL。我已经在5.1节里给出了完整的Compose配置，照抄即可。

6.2 审查流程的ROI，我算过一笔账

做代码审查基础设施，最大的顾虑往往是"投入产出比"。我也被问过很多次："搞这么复杂，到底值不值？"这里我分享一组自己在团队里记录的数据。在open-code-review落地之前，我们线上故障平均每月3次，其中约40%的故障根因是低质量代码合入，比如空指针、错误的分支合并、缺少异常处理等。落地审查流程之后的六个月，线上故障平均每月降到1次左右，而且再也没有出过因为代码合并顺序问题导致的事故。

当然，任何数据都有幸存者偏差，代码审查的核心价值在于"预防"，而预防的效果很难量化。但有一点我很确定：当团队中每个人都知道自己写的代码一定会被另一个人认真看一遍的时候，提交之前的自测和自审程度会有明显提升，这才是审查流程带来的最大隐性收益。

6.3 把open-code-review继续扩展下去

如果你的团队已经跑通了基础的审查流程，下面这几个方向是下一步可以考虑的：

第一个方向是接入更多自动化能力。比如增加一个机器人，在MR创建时自动分配Reviewer，根据文件变更路径匹配模块负责人；比如在CI里增加SonarQube扫描，自动把重复代码、坏味道和严重漏洞报告贴到MR评论中。我和团队目前在做的是给CI增加一个容器镜像安全扫描步骤，镜像构建完成后自动执行漏洞扫描，有问题就不允许合入，这能在代码进入生产环境前更早发现供应链风险。

第二个方向是做好审查数据度量。GitLab和Gerrit都提供了API，可以定期拉取审查相关的数据，比如MR的平均审查时长、每个开发者的MR被驳回率、单笔MR的平均评论数、每个Reviewer的响应时间。通过这些指标，你可以发现流程中的瓶颈。比如某个模块的MR平均审查时长特别长，大概率是该模块只有一个人能审，这时就该考虑备份Reviewer了。

第三个方向是沉淀审查清单。我见过最好的做法是，把团队在历史事故中总结出的常见问题做成一份检查清单，挂在项目Wiki里，同时让机器人把这份清单直接放到每个MR的描述模板里。审查者照着清单一项项对，既不容易漏项，也能让新加入的开发者尽快掌握团队关注的重点。

就我的实际感受来说，无论用GitLab还是Gerrit，审查工具都只是辅助，真正的核心是人的习惯和团队的文化。如果工具能创造一个环境，让每次代码提交都被认真对待，让每个问题都能在合入前被发现和解决，那这套基础设施就值回了全部搭建成本。