在代码审查这件事上我折腾过不少工具。从最开始的 GitLab 自带 MR 讨论到 Gerrit 那种强制 push 到 refs/for 的流程再到后来引入 SonarQube 做静态扫描说实话每家团队对“代码审查”这四个字的理解都不一样。有的想要严格的门禁有的只想要个能评论的地方有的则希望机器人能先把低级问题过滤掉让人类 Reviewer 集中精力看逻辑。如果你也在找一套能完全掌控、能随意改造、又不被厂商绑定的代码审查方案那“open-code-review”这个方向值得认真研究一下。这里要说的 open-code-review不是某个特定产品的名字而是一类“开放源代码的代码审查系统”的通称同时也可以指代你自己在团队内部搭建的、基于开源组件组合出来的审查工作流。它的核心价值在于你可以拥有整个审查链路的源码和配置从收到提交、触发规则、调用静态分析、通知 Reviewer到最后的合入门禁每一个环节都能按团队需求去定制。这篇文章我会从整体设计、核心模块、部署实操、平台集成、AI 辅助审查这几个角度把我实际搭建和维护这套系统时踩过的坑、验证过的方案尽量完整地分享出来。1. 为什么要折腾一套自己的代码审查系统很多人第一反应是GitHub 和 GitLab 自带的 Review 功能已经够用了为什么还要自己搭这个问题的答案取决于团队处在什么阶段。1.1 平台自带审查能力的边界在哪里GitHub 的 Pull Request 和 GitLab 的 Merge Request 确实解决了“人审”的基本流程谁提的、改了什么、谁 Approved、能不能合并。但当你对工程品质有更高要求时自带功能的短板就显现出来了。规则不灵活平台自带的 Branch Protection 只能卡“是否通过检查”“是否有人 Approve”很难表达“前端文件必须由前端 owner 审”“数据库迁移文件必须由 DBA 审”“改动超过 500 行必须由 tech lead 二次确认”这类复杂规则。静态检查集成成本高虽然平台有 Marketplace 或者说可以挂 CI但要做深度定制比如按目录跑不同规则集、按文件类型跳过某些检查配置会越来越绕最后变成一个谁都看不懂的 yaml 大杂烩。数据不出内网不少团队对代码托管有合规要求必须部署在内网。内网 GitLab 不是说不能用但你要把外部那些好用的 Review 机器人能力搬进去就要自己写集成层。审查数据难以沉淀平台自带的评论和 Approve 记录很难变成结构化的数据去做分析。比如“哪个模块的缺陷密度最高”“哪个 Reviewer 的平均响应时间最长”这些指标在自带功能里基本拿不到。1.2 open-code-review 这类方案解决什么问题我理解的 open-code-review 方案核心是把“代码审查”从一个平台功能拆解成一组可编程的、可组合的服务。你有一个 Web 界面做人工 Review有一组 API 接收代码托管平台的 Webhook有一个规则引擎决定“谁来审”“审什么”“怎么算通过”再挂上静态分析、AI 辅助、通知机器人这些外围服务。所有东西都是代码都放在你的仓库里谁想改都能改。这套思路带来的直接好处有三个。第一审查规则版本化规则变更走 MRMerge Request有审计记录。第二工具链可替换今天用 ESLint明天想换 Biome只改配置不动流程。第三可以逐步演进刚开始只接一个 Webhook 做自动评论后面再加门禁团队不会因为一次大改造而抵触。2. open-code-review 的核心架构与功能拆解一个完整的 open-code-review 系统不管代码怎么写涉及哪些组件逻辑上都能拆成六个模块。把这六个模块想清楚再去选型或开发才不会走偏。2.1 六个核心模块模块职责典型实现事件接入层接收代码托管平台的 Push、PR/MR 事件做验签和转发GitHub App、GitLab Webhook、Gitea Webhook规则引擎判断当前变更该走什么审查流程、需要哪些 Reviewer自定义 DSL、JSON 规则集、Open Policy Agent静态分析执行器拉取代码、按语言执行 linter/扫描器、汇总结果ESLint、RuboCop、SonarQube CLI、Semgrep审查数据存储保存 MR 信息、扫描结果、Review 记录、门禁状态PostgreSQL、SQLite、Redis缓存通知与交互在 MR 评论区输出机器人评论、 人、更新检查状态GitHub Checks API、GitLab Discussions API、飞书/钉钉/邮件Web 控制台查看审查历史、配置规则、管理成员角色React/Vue 前端 REST API这里要特别说一句不要一上来就追求大而全。我见过不少团队想自己写一个 Gerrit 出来结果折腾半年还没上线。更务实的路径是先写一个能跑通“Webhook - 扫描 - 评论 - 门禁”的最小闭环然后根据团队反馈逐步加模块。2.2 规则引擎该怎么设计规则引擎是整个系统的灵魂也是最容易被过度设计的地方。我建议先想清楚你要支持哪几类规则再决定写法。人员规则谁有权限 Approve、特定路径需要额外 Reviewer、作者不能 Approve 自己的 MR。变更规则最大改动行数、最大文件数、禁止改动的目录、必须包含对应测试文件。状态规则所有检查必须通过、必须解决所有阻塞评论、目标分支必须是最新的。规则表达上我踩过一个坑一开始用 JSON 配置写了几十条之后根本没法维护。后来切成“规则即代码”每一条规则就是一个函数输入是 MR 的上下文作者、改动文件、diff 内容、当前检查状态输出是“pass / fail / block”三种结果加一条人类可读的说明。def rule_max_lines(context): threshold context.repo_config.get(max_lines_per_mr, 500) added context.diff_stats[added] if added threshold: return RuleResult( statusblock, messagef本次变更新增 {added} 行超过阈值 {threshold} 行请拆分提交。 ) return RuleResult(statuspass)用代码写规则测试也好写。每条规则配一个单元测试传不同的 mock 数据进去能保证规则本身是被 Review 过的。2.3 为什么“门禁”和“提示”要分开这是我在实际使用中特别深刻的一个体会。对机器发现的问题要区分“必须修”和“建议改”两档。如果所有扫描结果都设成阻塞团队每天会被低优先级警告淹没最后反而把门禁当成摆设直接跳过。我的做法是把规则输出分成三个等级error阻塞合并、warning显示提醒但不阻塞、info仅在机器人评论中列出。这样既有底线又不至于让开发者觉得系统在故意找茬。3. 部署实操用 Docker Compose 快速跑起一套基础版选型阶段建议先别碰 Kubernetes单机 Docker Compose 足够跑一个小团队的量。下面是我验证过的一套最小部署方案可以直接照抄。3.1 服务编排与数据存储准备先准备好目录结构把不同服务的配置分开后面好维护。open-code-review/ ├── docker-compose.yml ├── .env ├── services/ │ ├── api/ # 审查后端服务 │ ├── worker/ # 异步执行扫描任务的队列消费者 │ ├── web/ # 前端控制台 │ └── bot/ # 机器人服务负责评论和状态上报 └── config/ └── rules.yamldocker-compose.yml 的核心内容大致是这样数据库先用 PostgreSQL队列用 Redis 加 RQ比 Kafka 之类的轻很多也够用。version: 3.8 services: db: image: postgres:16-alpine environment: POSTGRES_DB: code_review POSTGRES_USER: review POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U review] interval: 5s timeout: 5s retries: 5 redis: image: redis:7-alpine volumes: - redisdata:/data api: build: ./services/api env_file: .env depends_on: db: condition: service_healthy redis: condition: service_started ports: - 8080:8080 worker: build: ./services/worker env_file: .env depends_on: - api bot: build: ./services/bot env_file: .env depends_on: - api启动顺序有个细节一定要让 api 等服务 db 健康检查通过再启动否则第一次启动大概率会因为连不上数据库而崩溃。3.2 初始化数据库与第一个项目接入服务起来之后要先初始化数据库表结构。这里用 Alembic 做迁移管理所有表结构变更都走迁移脚本不要手动改表。docker compose up -d docker compose exec api alembic upgrade head接着在 Web 控制台创建一个“项目”填上仓库地址和 Webhook 密钥。这一步本质上是告诉系统以后这个仓库的 Push 和 MR 事件都按这套规则来审。验证接入是否成功有个简单方法往测试仓库提交一个包含明显风格问题的 MR看机器人有没有在 MR 里评论。如果评论内容里包含具体的行号和规则名说明全链路已经通了。4. 与 GitHub / GitLab / Gitea 的集成细节open-code-review 要真正用起来必须和代码托管平台打好配合。这一节说三个平台各自需要注意的点。4.1 GitHub用 Checks API 而不是评论流刷屏GitHub 的集成方式推荐做成 GitHub App而不是传统的个人 Token Webhook。GitHub App 的好处是权限粒度细可以只申请“Checks: Read Write”和“Pull requests: Read Write”不用把整个仓库的代码权限交给机器人。集成的核心是调用三个接口POST /repos/{owner}/{repo}/check-runs创建一个检查任务GitHub 会把状态显示在 MR 页面的 Checks 区域。PATCH /repos/{owner}/{repo}/check-runs/{id}更新检查任务的结论queued、in_progress、completed。POST /repos/{owner}/{repo}/issues/{issue_number}/comments输出行内评论只在有阻塞问题时才用避免刷屏。GitHub 对 Check 的并发和频率有限制建议任务尽量异步处理。Worker 拿到事件后立刻把 Check 状态置为queued等扫描完再更新成completed这样开发者体验最好。4.2 GitLab注意 Merge Request 的版本差异GitLab 的 Merge Request 和 GitHub 的 Pull Request 在事件模型上有个重要区别每次 push 到源分支GitLab 都会生成一个新的 MR 版本diff 版本。如果你的机器人要评论具体代码行必须关联正确的diff_refs否则评论会挂到过期的代码位置。推荐用 GitLab 的 Discussions API 来发评论同时在评论里带上 commit SHA这样即使后续有新的 pushReviewer 也能看到你评论的是哪个版本上的问题。GitLab 没有直接对应 Checks API 的能力但可以通过“Merge Request Status”功能实现门禁机器人服务的返回结果作为外部状态检查GitLab 在状态未通过时会阻止合并。4.3 内网 Gitea轻量但没有现成的 Check 概念内网团队常用 GiteaAPI 风格和 GitHub 很像但没有 Checks API。退而求其次的做法是用 Commit Status 的context字段模拟 Check把“open-code-review/static-analysis”和“open-code-review/ai-review”分别作为两个 context 上报状态。Gitea 会在 MR 页面显示这两个状态的图标也能起到门禁作用。5. 让 AI 做第一轮审查原理、提示词与实测效果现在很多团队关心 AI 辅助代码审查。open-code-review 架构里接入 AI 审查模块要比想象中简单但要想效果好也不是甩一个提示词就行。5.1 AI 在审查流水线上扮演什么角色我目前的实践是把 AI 审查放在“静态规则扫描之后、人工 Reviewer 之前”。它做的不是替代人类而是先把以下工作做完发现潜在的逻辑漏洞比如空指针、资源未释放、边界条件缺失。识别与当前上下文不符的改动比如改了 API 的参数但没有同步修改调用方。检查提交信息是否与改动内容一致防止“标题写修 bug实际在加功能”这类情况。对大型 MR 做摘要帮 Reviewer 快速了解改动全貌。实现时最大的坑是diff 太大导致上下文超限。超过上下文窗口时必须做切片或者按文件分组逐个调用模型再汇总结果。直接截断会导致模型看不到关键改动评论质量断崖式下降。5.2 建议的 Prompt 结构我试了很长时间最终的 Prompt 结构基本稳定为“角色 输入数据 输出要求 禁止事项”四段式。你是一个资深软件工程师正在进行代码审查。 以下是某个 Merge Request 的 diff 信息。 diff_info {diff_content} /diff_info 请从以下维度给出意见 1. 逻辑正确性重点关注边界条件和并发问题。 2. 与现有代码风格的一致性。 3. 潜在的性能风险。 4. 安全漏洞特别是注入类和权限绕过类问题。 输出要求 - 以 JSON 数组格式输出每个元素包含 line、severity、message 三个字段。 - line 是对应 diff 中的行号无法定位到具体行的输出 null。 - severity 只有 error 和 warning 两个值。 - 不要输出泛泛而谈的建议比如“建议增加日志”“注意代码规范”这类没有具体指向的内容。 禁止事项 - 不要对不存在的代码发表评论。 - 不要把静态分析工具已经报过的问题重复一遍。5.3 实测效果与人工 Review 的配合我拿一个中型 Java 项目跑了三个月的 AI 审查大致的数据是AI 评论中被人工 Reviewer 标记为“有效”的比例大约在 60% 到 70%剩下的 30% 属于误报或可改可不改的意见。这个准确率已经足够做辅助参考了但不能作为唯一的门禁依据。我的最终做法是AI 的意见全部先进入“待确认”状态不直接阻塞合并只有人工 Reviewer 点“确认”之后才变成正式评论或门禁失败项。这样一来AI 帮忙抓漏洞但决策权始终在人手里团队接受度也高很多。6. 常见问题与调优心得最后把这段时间运维 open-code-review 遇到的高频问题整理一下如果你照着搭大概率也会碰到。6.1 Webhook 收不到事件这是接入时最常遇到的问题排查思路按顺序来现象可能原因排查动作Webhook 请求根本没到服务网络不通、端口未放行在服务日志里看有没有 request 记录没有就先查安全组和防火墙有请求但验签失败Secret 不匹配、签名算法不一致对比两边配置的 Secret确认平台用的哈希算法GitHub 是 HMAC-SHA256验签通过但不触发任务事件类型没订阅去平台检查 Webhook 有没有勾选 pull_request / merge_request 事件只有一部分仓库能触发项目配置里的仓库匹配规则不对检查系统里创建的项目是否覆盖了当前仓库验签这个环节一定不要自己造轮子直接用官方 SDK。GitHub 推荐用octokit/webhooksGitLab 的gitlabPython 库自带签名校验能省下很多不必要的调试时间。6.2 大量 MR 同时触发导致任务堆积团队一到发布日经常出现几十个 MR 同时更新如果所有扫描都是同步执行任务队列会被打爆。我在实践里用两层削峰第一层每个 MR 在同一时间只保留一个最新任务。新事件到达时如果该 MR 的旧任务还没执行完毕直接标记为 superseded只处理最新版本。第二层消费端做并发控制worker 数量按 CPU 核数设置避免资源争抢导致扫描本身变慢。# worker 入口的伪代码展示去重逻辑 def process_event(event): mr_id event[mr_id] current_job get_running_job(mr_id) if current_job: current_job.cancel() create_job(mr_id, event[commit_sha])6.3 评论噪音太多团队想关掉机器人这个问题不在技术在规则调优。出现这种情况几乎都是因为规则集里 warning 和 info 级别太多开发者打开 MR 满屏都是机器人的红字正常 Review 根本没法开展。解决办法是分阶段放宽先把所有规则调到 error 级别跑两个迭代后挑出哪些 warning 实际引发了线上问题再降级为 warning。规则的加严要像加测试用例一样每一条都要有对应的“真实事故”支撑否则就是在制造噪音。6.4 性能优化增量扫描而不是全量扫描项目变大之后全量扫描一次可能要几分钟MR 一多体验就很差。优化方向是只对变更的文件做增量扫描。比如前端项目只对git diff --name-only --diff-filterAM列出的文件跑 ESLint并开启--cache可以显著缩短扫描时间。对需要全局上下文才准确的语言比如 Java 的跨文件类型检查没办法简单做增量这时可以用“分层策略”快速规则做增量重规则在 CI 的主分支上定时全量跑MR 阶段不阻塞发现问题的下一个 MR 再要求修复。7. 关于工具链扩展的一点个人建议open-code-review 的价值不在于它是一套多牛的软件而在于它给了团队一个“可以持续演进的审查基础设施”。今天接了一个静态扫描器明天加了一个 AI 审阅后天接了一套内部的安全检测平台这些在传统代码托管平台里都很难做到这么灵活。如果你想动手我的建议是从一个最小的闭环开始写一个能监听 Webhook 的服务收到 MR 事件后跑一次 ESLint把结果以评论的形式发回 MR。这个流程跑通之后后面加规则引擎、加门禁、加 AI都是水到渠成的事。我自己在维护这套系统的过程中最大的体会是代码审查工具做得好不好不取决于功能多少而取决于它能不能让团队觉得“有用且不烦人”。这中间需要不断根据反馈调规则、降噪音、优化评论的精准度。把有限的力气花在减少无效干扰、提升有效意见的转化率上这件事本身就比工具本身更值得长期投入。