自托管代码审查代理Proval：从部署到多平台落地的完整指南

Proval 是一个自托管的代码审查代理核心场景是把 GitLab、Forgejo、GitHub 上的合并请求MR/PR自动拉取、分析并把评审意见作为评论或 review 回复到对应平台。跟很多托管在云上的代码审查服务不同Proval 这类自托管方案最大的价值在于代码不出自己的服务器平台凭证自己保管模型服务也可以按需切换。这篇文章适合正在给团队选型自托管 review bot、或者已经部署但被回调、权限、队列问题反复折腾的人。我按实际落地顺序写了一份偏工程向的记录从环境准备讲到多仓库批量使用也会把最容易踩的坑一起列出来。1. 先搞清楚它到底解决什么问题和云端 Review 工具有什么区别1.1 自托管代码审查代理的定位自动代码审查不是新概念。很多团队已经用 CI 里的静态检查、Lint、单元测试来做第一道关卡但这类工具只能检查“代码是否规范、是否通过测试”很难回答“这个改动逻辑上有没有问题、边界有没有漏掉、命名和结构是否合理”。Proval 这类 agent 做的事情更像是“让一个机器 review bot 把 MR/PR 的 diff 完整读一遍再按问题类型给出意见”。它需要完成几个动作接收平台推送的合并请求事件。拉取对应的 diff 或补丁内容。把 diff 交给配置好的模型服务进行分析。把结果整理成评论通过平台 API 回写到对应文件、对应行或作为一个总结评论。这个流程看起来简单实际落地时会涉及 Webhook 回调、Token 权限、平台 API 差异、模型响应解析、并发队列和失败重试任何一个环节断了都很容易出现“什么都没发生”的结果。1.2 同时支持 GitLab、Forgejo、GitHub 意味着什么标题里把三个平台并排写对使用者来说是一个很实际的卖点团队不需要为每个平台各维护一套 review 机器人。统一的配置、统一的规则、统一的输出格式能省掉不少重复工作。但也正因为支持三个平台落地时必须理解一个事实三个平台的 Webhook 事件结构、API 字段、注释方式、权限体系并不完全一致。GitHub 用pull_request事件GitLab 用Merge Request HookForgejo 虽然和 GitHub 风格接近但很多字段和接口细节有自己的差异。一个项目能“支持”三个平台不等于三个平台上的行为完全一样。我的建议是不要同时接入三个平台做首次验证。先选团队主力使用的那个平台把单条 review 跑通再复制到另外两个平台。这样排查范围小很多。1.3 适用边界它适合谁不适合谁适合的情况团队使用自建 GitLab 或 Forgejo代码仓库必须留在内网。已经有模型 API 或本地模型服务希望把它接入代码审查场景。希望让 review bot 完成第一轮“粗查”把明显问题过滤掉减轻人工 review 负担。对代码数据出公有云有顾虑需要自己控制日志、配置和审查记录。不适合的情况仓库数量很多但团队没有人力维护 bot 的日志、Token 和模型费用。希望 review bot 完全替代人工 review。目前这类工具更适合做辅助直接“一键批准合并”仍需要谨慎。对每条评审意见的准确性要求极高容不得误报。如果你的团队会把机器评论当最终结论建议先在小范围跑一段时间看看。2. 部署前先确认环境服务器、平台账号、Token 权限和网络2.1 运行环境与资源预期这类自托管服务通常有两种运行方式直接跑二进制进程或者用容器跑。从运维角度看容器方式更省心日志、重启、版本升级都容易管理。资源上纯粹支撑一个 review bot 本身并不重真正的资源消耗在模型调用上。如果模型是外部 API服务端只是转发请求那么一台 2 核 4G 的 Linux 机器在测试环境就够跑如果模型部署在本地就要单独评估模型自身的显存和内存需求。先不要按生产标准买配置。我一般会先用最小配置跑通链路服务器Linux x86_642 核 4G 起步。Docker 和 docker compose或者直接运行编译好的二进制。一个测试仓库一个专用 bot 账号。配置好模型 API 地址和密钥。等确认评论能正常回写、并且并发任务不会压垮服务之后再根据日志里的内存、CPU 占用决定是否升级。2.2 平台侧账号和 Token 权限这是整个部署里最容易出问题的一步。很多人图省事直接用个人账号的 Token 去接 Webhook结果评论都是以个人身份发出的权限还被平台限制后续换人维护还得重新授权。更稳妥的做法是在代码平台上单独创建一个 bot 账号。给这个账号申请最小权限的 Token。在项目或组织级别把 bot 账号加为成员通常只需要读代码和写评论/审查意见的权限。三个平台的权限路径不同但原则一致GitLab需要api权限来读取 MR、写评论如果是私有仓库还要确保 bot 能看到项目。GitHub推荐使用 fine-grained token只授权目标仓库的 Pull requests 读写权限。Forgejo权限模型接近 GitLab/GitHub 的混合体以平台文档为准先给最小范围再逐步扩大。注意不要把 Token 直接写进仓库配置文件。环境变量、密钥管理工具、容器 secret 都可以但最常见的就是有人提交.env把 Token 带上版本库这是迟早要出事的。2.3 回调地址、端口和网络Proval 要接受到平台推送的事件代码平台必须能访问到 Proval 的 Webhook 地址。这里有几种情况GitLab 和 Forgejo 如果和 Proval 在同一台服务器或同一内网可以直接用内网地址。GitHub 如果是 SaaS 版本那 Proval 服务必须有公网可访问的 HTTPS 地址。如果团队用的是 GitHub Enterprise 或公司内部 GitLab就按内网策略配置。生产环境不建议用明文 HTTP 地址做 Webhook 回调。大多数平台支持 Webhook Secret用来对回调请求签名配置时要把它和平台侧保持一致防止伪造请求。这里还涉及一个方向问题先确认是平台无法回调还是 Proval 收到了但处理失败。不要一上来就改代码、改参数。先去平台侧看 Webhook 投递记录再去 Proval 日志看有没有对应请求两个信息一对问题范围就缩小了。3. 落地步骤从配置到第一条 Review 评论3.1 第一步准备配置文件和密钥具体配置项要以项目当前文档为准但这类服务通常会包含以下几类配置平台类型PLATFORM_TYPE例如gitlab、forgejo、github。平台地址如果是自建平台需要BASE_URL指向 GitLab 或 Forgejo 的域名。平台 Tokenbot 账号的访问令牌。Webhook 回调路径和 Secret平台推送事件时要访问的路径以及验签用密钥。模型服务地址和密钥模型 API 的API_KEY、BASE_URL、模型名称。服务监听端口Proval 自身对外服务的端口。可以先用一个.env文件管理但记得把.env加入.gitignore。PLATFORM_TYPEgitlab GITLAB_URLhttps://gitlab.example.com GITLAB_TOKENreplace-me WEBHOOK_SECRETreplace-me MODEL_API_KEYreplace-me MODEL_BASE_URLhttps://api.example-model.com/v1 MODEL_NAMEyour-model-name LISTEN_PORT8080这是一个示意不是所有项目都叫这些变量名。实际配置时先看 README再对照示例文件改。3.2 第二步启动服务并验证健康状态启动之前先确认几个前置条件服务器能访问到模型 API 地址网络层要通。bot 账号的 Token 有权限读取测试仓库的 MR/PR 内容。端口没有被占用。启动后先不要急着配置 Webhook。先把服务日志打开确认启动过程没有报错再看它是否暴露健康检查接口。如果服务本身没起来后面所有排查都是浪费。docker compose up -d docker compose logs -f日志正常后用 curl 检查健康接口具体路径以项目文档为准curl http://127.0.0.1:8080/health返回正常后再进入下一步。3.3 第三步接入一个最小样例在测试仓库上创建一个很小的 MR/PR比如只改一个文件、加几行代码。这个步骤的目的是验证完整链路而不是验证 review 质量所以改动越小越好。操作顺序在平台侧创建 Webhook指向 Proval 的回调地址并填上 Webhook Secret。选择触发事件。GitHub 一般是pull_requestGitLab 是 Merge Request 事件Forgejo 看具体版本支持。创建一个带改动的新分支并提交 MR/PR。观察平台 Webhook 投递记录有没有成功。观察服务日志有没有收到事件、有没有调用模型、有没有回写评论。如果平台显示回调成功但 PR 上没有评论就按这个顺序查服务日志有没有请求记录模型调用有没有返回评论 API 有没有被 Token 权限拦截。3.4 第四步判断 Review 输出质量评论出现之后先不要急着批量化。先判断输出是否可用评论是整体总结还是针对具体代码行不同模式对应的使用体验差别很大。评论里提到的行号和文件是否与 diff 对应如果行号错位说明 diff 上下文解析可能有问题。是否有明显误报“这段代码有 bug”这种泛泛结论对开发者没有帮助。同一份 MR 被推送多次后会不会重复评论重复评论会很快刷屏让人想立刻关闭 bot。第一个样例的目的就是定义“成功标准”。如果只是“看到评论”就急着接入所有仓库后面会被重复评论和误报淹没。4. 三个平台接入时的差异和注意点4.1 GitLabWebhook 配置相对清晰GitLab 在项目设置里有 Webhook 管理页可以填 URL、Secret、选择触发事件。回调和评论都有比较完整的日志页面排查时可以直接看投递状态。GitLab 的常见坑是权限模型。如果你的仓库是私有的而 bot 账号不是项目成员那么即使 Token 有api权限也可能无法读取代码内容。此时要确认 bot 账号被加入项目并且至少拥有 Reporter 级别权限能读代码才能 review 代码。4.2 Forgejo接口接近 GitHub但文档相对少Forgejo 是轻量级的自托管 Git 服务API 风格和 GitHub 有些接近但版本迭代快不同版本的 Webhook 字段可能有差异。如果你的目标平台上跑的是 Forgejo我建议先确认 Forgejo 版本再看项目 README 里有没有针对 Forgejo 的已知限制。Forgejo 社区规模比 GitLab、GitHub 小遇到问题时可参考的文档少一些所以在 Forgejo 上做首次验证时更要把日志打清楚。4.3 GitHub事件类型和权限要仔细核对GitHub 的 Webhook 事件类型很多pull_request一个事件下面还有opened、synchronize、ready_for_review等 action。如果 Proval 对所有 action 都处理可能会出现“每次 push 都触发一次 review”的情况。这不是 bug是事件过滤没做好。GitHub 侧排查还有一层方便之处仓库 Settings 里的 Webhook 页面能看到每次投递的请求和响应结果。如果投递失败先看这里比直接翻服务日志更快。GitHub 的 Token 权限建议用 fine-grained token只勾选目标仓库的 Pull requests 读写避免给整个账号过大的权限。4.4 一个平台跑通后再复制实测中跨平台最常见的错误是“假设字段一致”。GitHub 的pull_request和 GitLab 的merge_request在事件 payload 里字段名不同比如评论 API 的端点、获取 diff 的方式都不一样。所以正确的做法是在主力平台跑通单条 review。记录日志里成功请求的完整流程。换第二个平台时先看投递记录和日志而不是直接套用第一个平台的配置。以项目文档和示例配置为基准不要根据另一个平台的字段去猜。5. 批量评审、并发队列和失败重试5.1 并发不是越大越好单条 review 跑通之后很多人会立刻把所有仓库的 Webhook 都接进来然后把并发开到最大。这是最容易翻车的地方。模型 API 通常有并发限制平台 API 也有频率限制。并发开大了可能出现三种结果模型返回变慢、平台拒绝评论请求、服务内存涨到被系统杀掉。我的建议是先按低并发验证先同时跑 2 到 3 个 MR。观察每个任务从接收到评论完成的时间。观察内存、CPU 和模型 API 返回状态。确认稳定后再按 1.5 到 2 倍逐步增加。不要一上来就开最大并发。要理解“能跑”和“能稳定批量跑”是两回事。5.2 重复触发和去重批量场景下最容易遇到的是重复评论。一个 PR 从推到合并可能触发多次synchronize如果服务没有去重逻辑每次事件都会产生一轮 review评论区很快就乱了。解决思路通常有两类事件过滤只处理opened和指定条件的synchronize减少无效触发。请求去重以仓库 MR/PR 编号 commit SHA 作为任务标识同一个 SHA 不重复处理。具体实现要看 Proval 是否内置如果不内置可以通过外部队列或入口脚本控制。判断是否去重正常最简单的方式是连续推送两次同分支代码看是否会生成两轮内容不同的评论。5.3 失败重试和日志生产场景里网络抖动、模型 API 超时、平台限流都很常见。失败后怎么做比“能不能跑”更重要。建议至少在配置里确认几件事是否有失败重试机制重试次数多少。超时时间是多少模型响应慢时会不会导致整个任务卡住。日志里能否看到每个任务的处理阶段收到事件、拉取 diff、调用模型、回写评论。失败的任务是否会在重新推送后自动恢复还是需要人工介入。如果项目暂时没有成熟的队列和重试机制也不要硬塞给生产。可以先在入口做一层简单的控制和日志保证出问题时能定位。注意批量跑之前先给输出目录、日志文件、队列状态单独建目录避免多个任务同时写同一个临时文件导致输出互相覆盖。这个问题看起来低级但在实际部署中非常常见。6. 常见问题排查先看现象再按链路定位6.1 现象MR/PR 上没有任何评论这是出现频率最高的问题。排查顺序不是先改代码而是按链路从外向里看平台侧 Webhook 投递记录是否成功。GitHub 有 Webhook 投递历史GitLab 也有相关日志。如果投递失败看回调地址、Secret、网络是否可达。如果投递成功看 Proval 日志是否收到事件。如果收到事件看是否有模型调用记录。如果模型调用成功看评论 API 返回是否被平台拒绝。整个过程看下来问题往往不是出在最后一步而是前面某一环断了。比如 Webhook 地址填错、Secret 不匹配、bot 账号没有项目权限。6.2 现象评论出现但行号不对或者评论内容很空这类问题通常不在网络层而在数据处理层。行号不对diff 里的行号上下文没有被正确解析或者模型返回的行号与原始 diff 不匹配。评论很空模型返回的内容没被正确解析可能是模型输出格式和预期不一致。评论明明有观点但不具体需要检查提示词里是否要求给出文件、函数名和具体行为建议。如果输出质量不稳定先看模型 API 的原始返回再对照最终评论这样能快速判断是模型输出问题还是后处理解析问题。6.3 现象处理很慢甚至卡住慢的常见原因有三个模型 API 响应慢尤其请求排队时间很长时。diff 太大单次请求的内容过多模型处理时间长。平台拉取代码或 diff 时受到网络限制。排查时先看是哪个阶段耗时最长。最简单的方法是先用一个小 diff 测试如果小 diff 也慢基本是模型 API 或网络问题如果只有大 diff 慢就要考虑对超大 MR 做拆分或跳过。6.4 现象Token 权限报错权限报错最常见的表现是服务能收到事件但评论写不回去。排查顺序确认 Token 属于 bot 账号不是个人账号。确认 Token 的权限范围覆盖读取仓库和写评论。确认 bot 账号被加入目标项目且项目是私有仓库时尤其重要。确认 Token 没有过期平台没有强制轮换。日志里通常会有 HTTP 状态码403 基本是权限不够401 是 Token 无效或过期404 可能是仓库路径错误或 bot 没有访问权限。7. 我的实测建议和上线前检查清单7.1 最少可用配置如果想快速验证 Proval 是否适合团队我建议不要从“接入所有仓库”开始而是搭一个最小闭环一台轻量 Linux 服务器2 核 4G。一个测试仓库最好是小的内部项目。一个专用 bot 账号最小 Token 权限。一个可用的模型 API 配置。只在一个平台上做验证比如 GitLab 或 GitHub。这个闭环跑通后你才能准确判断评论质量能否接受、模型成本多高、维护成本多少。7.2 上线前检查清单在正式接入团队仓库之前按这个清单过一遍配置和密钥是否已从仓库代码中剥离。bot 账号是否有最小权限是否会被误删或误改。Webhook 是否配置了 Secret是否启用了 HTTPS 回调。服务日志是否持久化能否追溯每个任务的完整处理过程。是否已设置并发上限和超时时间。是否了解失败任务如何重试是否需要人工干预。是否准备好模型 API 的费用预算或本地模型的资源开销。是否有人负责定期升级服务版本处理平台 API 变动。不要把这些当成“以后再说”的事情。自托管方案的一大优势是可控但可控的前提是配置、日志、密钥、升级都有人管。7.3 什么时候该停下来最后说几句边界感的话。自托管 review agent 确实能减少一部分重复评审工作但它不是万能的。如果你发现团队实际使用时长里大部分时间花在处理误报和 bot 配置上那就说明当前阶段的产出收益不划算。这时不要急着加更多规则、换更强的模型而是应该先确认是提示词不够好是 diff 太大导致理解不准还是团队根本没有把 bot 的输出当成有效信息如果只是学习或小团队使用默认配置通常够用。如果要长期在生产环境跑就要把日志、输出目录、任务队列、失败重试和权限回收都提前整理好。踩过几次之后你会发现很多问题不是工具能力不够而是前置环境和输入材料没有处理干净。Proval 作为一个自托管项目具体细节还在快速迭代落地时一定要以你当前部署版本的 README 为准先把最小闭环跑稳再逐步扩展。