如果团队已经使用 GitLab、Forgejo 或 GitHub 管理代码那么“合并请求被反复人工检查”通常是研发流程里最耗时也最不稳定的环节。代码审查 agent 解决的问题是把“代码变更的初步审视”交给一套自动化程序来完成它读取 MR/PR 的 diff结合仓库上下文、提交历史、规范要求甚至历史审查记录给出结构化的审查意见。Proval 正是这类工具中的自托管方案它没有把代码提交到第三方平台而是让审查逻辑运行在团队自己的服务器上同时兼容 GitLab、Forgejo 和 GitHub 三种常见的 Git 托管平台。自托管的意义很直接代码和审查数据留在自己手里审查规则可以由团队自由定制调用的是企业内部可访问的模型服务而不是每次把完整 diff 发送给外部 SaaS。代价同样明显部署、升级、排错、权限维护、模型调用成本都需要自己负责。这篇文章会围绕“自托管代码审查 agent”这条主线拆解它背后的架构模块、部署方式、平台接入差异、端到端验证方法以及上线前必须关注的排查点和最佳实践。内容以 Proval 这类工具为背景但多数架构判断可以复用到类似的代码审查 agent 项目上。1. 先理解自托管代码审查 agent 到底是什么1.1 它和静态检查、CI 检查、人工审查的区别很多团队早就接入了 ESLint、Checkstyle、golangci-lint 这类静态检查工具也把单元测试、构建任务放进了 CI。代码审查 agent 和它们最大的不同在于它不强调“确定性规则匹配”而是模拟一个熟悉项目的资深工程师在收到 MR/PR 事件后主动读取变更内容并基于大模型或本地模型生成审查建议。静态检查工具的优点是确定性强、速度快、误报可控但它只能发现模式匹配到的问题。代码审查 agent 的优势是能处理“跨文件关联”“边界条件遗漏”“并发安全”“业务语义不一致”这类原本需要人脑判断的问题。它并不能替代人工审查而是把人工审查中最耗时的“通读 diff、找明显缺陷、补充规范检查”这层工作接手过去让人只聚焦在真正需要判断力和上下文的问题上。在实现上代码审查 agent 通常不是简单地把“diff 文本 提示词”发给模型就结束。它会先做一系列预处理过滤非必要文件、按变更级别排序、拼接相关函数定义、检索相似历史问题最后才形成结构化 prompt。这也是它和“一个调用 ChatGPT API 的脚本”的本质区别。1.2 为什么选择自托管而不是 SaaS如果使用托管式代码审查服务团队只需要安装一个 GitHub App 或 GitLab 集成然后在网页上配置规则几十分钟就能跑通。它的便利性很明显但几个问题会让一些团队犹豫。代码安全是第一道坎。托管服务默认会读取仓库内容、diff、评论、成员信息。对于闭源商业项目、金融系统、医疗系统很多团队无法接受第三方服务持续读取源码。自托管方案把“读取代码”和“生成评论”的过程放在自己控制的服务器或内网环境里代码不会离开公司边界至少在数据流向层面有了明确控制点。第二个原因是规则定制。SaaS 服务通常只提供有限的规则模板比如“禁止密钥提交”“限制函数长度”“检测 TODO 残留”。但不同团队对“什么是好的代码”定义完全不同有的团队要求所有新代码附带测试文件有的团队要求错误处理必须使用统一异常类有的团队要求数据库字段变更必须同步迁移脚本。自托管方案可以把这些规则写进配置文件或提示词模板纳入版本管理和团队规范保持同步。第三个原因是成本模型。SaaS 服务通常按仓库数或 API 调用量收费仓库增长后费用会快速上升。自托管虽然要自己承担服务器和模型调用成本但成本边界更清晰也可以使用本地部署的模型来降低单位调用费用。当然自托管也要付出运维代价需要处理容器升级、数据库迁移、Token 过期、Webhook 丢失、模型服务抖动等问题。选择自托管本质是用运维成本换取数据控制权和规则自由度。1.3 “兼容三个平台”这句话背后的工程含义标题中的“for GitLab, Forgejo, and GitHub”看上去只是列出三个平台名但工程上相当于一套核心引擎对接三种不同的外部 API。这三个平台的 API 体系并不统一。GitHub 的接口以 REST 和 GraphQL 为主GitHub App 通过安装 Token 交互GitLab 提供成熟的 Project Access Token 和 Webhook 签名机制Forgejo 是从 Gitea 发展而来的轻量级托管平台API 风格与 GitHub 有相似之处但权限模型、Webhook 事件结构、评论接口都有差异。一个跨平台代码审查 agent 在设计时必须抽象出三层平台适配层、核心审查层、评论回写层。平台适配层负责把三个平台的 Webhook 转换成统一的中立事件结构比如PullRequestEvent{ repository, title, headSha, baseSha, author, changedFiles, additions, deletions }。核心审查层只依赖这个中立结构工作不关心事件来自哪个平台。评论回写层再根据目标平台调用不同 API把审查结果转换为本地评论、review thread 或 check run。如果架构缺少这层抽象最常见的结果是GitHub 上能跑通的流程迁移到 GitLab 后需要改大量业务代码每接入一个平台都要重写一遍审查逻辑。自托管项目要做多平台兼容第一步就是要求团队明确“哪些逻辑是平台无关的哪些逻辑必须放适配层”。2. 部署自托管代码审查 agent 需要准备什么2.1 服务器与运行环境基准在没有官方明确版本的前提下先按通用自托管服务的目标来估算资源。代码审查 agent 的负载模型主要是事件驱动没有 MR 时基本空闲MR 集中出现时需要在短时间内分析大量 diff因此关注点不是“平均 CPU”而是“峰值扩缩容能力”和“任务排队机制”。从最小可运行环境出发可以按下面的标准准备项目学习/试用环境生产推荐环境服务器2 vCPU / 4 GB 内存 / 40 GB 磁盘4 vCPU 起 / 8 GB 内存起 / 按日志与数据增长扩容操作系统Ubuntu 22.04 LTS 或等效 Linux与团队基础设施一致的 Linux 发行版容器Docker Engine 24Docker Engine 镜像仓库 版本标签管理编排docker-composeKubernetes 或按团队标准管理必须支持健康检查和回滚数据库PostgreSQL 或 SQLite取决于项目支持PostgreSQL开启备份任务队列内存队列试运行Redis 或等效消息队列持久化任务状态模型服务团队可用的大模型 API内网模型服务或受信任的云模型 API需评估数据出网策略这里要区分一个容易混淆的概念agent 本体是“审查逻辑的执行器”它不一定内置大模型。它更接近一个编排进程接收事件、组装上下文、调用模型接口、解析结果、回写平台。模型可以是 OpenAI-compatible 的远程 API也可以是 vLLM、Ollama、llama.cpp 等本地服务。选择本地模型时GPU 或 NPU 资源要按照模型参数量单独评估不能和 agent 本体共用一台 2 vCPU 的机器。2.2 三个平台的接入凭证需要配齐哪些权限自托管 agent 要读取 MR/PR 内容并在讨论区发评论最少需要两类权限读仓库内容、写 MR/PR 评论。不同平台配置入口不同但权限原则一致不要给全局管理员权限尽量使用最小权限。GitHub 的推荐方式是创建 GitHub App而不是使用个人 Token。GitHub App 的权限可以精确到某个仓库集合并单独定义 Permissions。典型配置项包括Pull requests: Read and write读取 PR diff 并创建 review 评论。Contents: Read读取仓库文件内容用于补全上下文。Checks: Read and write如果需要以 Check Run 形式上报审查状态。Metadata: ReadGitHub App 基础元数据权限系统强制要求。GitHub App 安装后返回的 Installation Token 是短期 Tokenagent 需要使用私钥动态签发不能硬编码在配置文件里长期使用。GitLab 可以使用 Project Access Token 或 Group Access Token。关键 scope 通常是api、read_repository。其中api权限能力较大如果项目只要求读代码和写评论也可以尝试read_api加评论接口所需的最小写权限组合但部分评论接口仍依赖apiscope落地时要根据项目文档验证。更稳妥的做法是创建一个专用于审查 agent 的 GitLab 用户给它目标项目的 Developer 角色再基于该用户创建 Token避免 Token 泄漏后影响整个组。Forgejo 的 Token 体系与 GitHub 较接近。在用户设置里创建 Token 时勾选read:repository、write:issue和write:pull_request等权限。Forgejo 的权限命名在不同版本间有调整配置前要确认当前版本支持的 scope 名称。平台推荐凭证类型主要权限更换成本GitHubGitHub AppPull requests R/W、Contents R、Checks R/W中需配置私钥和安装 IDGitLabProject/Group Access Tokenapi、read_repository低Token 可随时撤销Forgejo用户 Tokenread:repository、write:pull_request 等低Token 可随时撤销2.3 Webhook 地址、签名和任务持久化接入三个平台都离不开 Webhook。agent 需要提供一个公网可访问的 HTTPS 地址或者通过反向代理暴露到目标平台。生产环境必须配置 Webhook 签名校验而不是直接信任请求来源。GitHub 的 Webhook 使用X-Hub-Signature-256头由请求体加 Secret 经过 HMAC 生成。GitLab 会在回调中携带X-Gitlab-Token如果配置了 Secret Token 就必须比对。Forgejo 与 GitHub 类似同样可以使用 Secret 校验。agent 在入口处应该先校验签名再做业务处理避免伪造请求消耗模型资源。任务持久化也是部署前要设计的点。Webhook 到达后agent 不能直接在请求处理函数里同步执行一次完整审查。因为代码审查可能涉及几十个文件、多次模型调用耗时会超过平台 HTTP 超时限制。正确做法是Webhook 入口只校验签名、解析事件、把任务写入队列立即返回 200后台 worker 从队列里取任务执行分析最后异步调用平台 API 回写评论。这样即使模型服务超时Webhook 也不会重试导致重复评论。3. 拆解代码审查 agent 的核心工作链路3.1 事件接入层Webhook 路由与事件去重跨平台 agent 的第一步是统一事件。无论来自 GitHub 的pull_request事件、GitLab 的Merge Request Hook还是 Forgejo 的pull_request事件进入核心层之前都要转换成统一的中立事件结构。一个最小事件对象大致如下{ event_id: evt_20250115_abc123, source: github, repo: org/backend-service, action: opened, pull_request: { number: 142, title: feat: add user profile cache, head_sha: 3f2a9c1e, base_sha: 7d3e5502, author: zhangsan }, sender: zhangsan }事件去重要在队列写入前完成。三个平台在 Webhook 重试机制上行为不一致GitHub 会重试失败的 WebhookGitLab 也支持自定义重试如果入口处理时间过长平台可能连续推送多次。建议以source repo pull_request.number action作为幂等键在处理记录表里判断是否已经消费过。常见的一个坑是只用merge_request的action做判断导致 reopen、synchronize、opened 事件处理逻辑分支混乱。推荐在事件适配层把平台原始action映射成三类内部动作OPENED、UPDATED、CLOSED后续所有规则只依赖内部动作不直接判断平台字符串。3.2 分析执行层Diff 提取、上下文组装、模型调用这是整个 agent 技术含量最高的部分。拿到 MR/PR 后agent 要做的不只是把 diff 原样贴给模型而是尽可能让模型看到“变更真正影响的范围”。常见流程如下从平台 API 拉取 diff 全文按files/removed/added/context结构拆分。过滤噪声文件锁定文件package-lock.json、pnpm-lock.yaml、生成的 protobuf、纯格式化变更。对每个变更文件识别新增函数和修改函数向上查找函数的上下文片段。如果模型支持更大上下文把相关文件的关键定义一并拼入。组装 prompt包含系统提示、仓库规范、diff、上下文片段、审查要求。调用模型得到结构化审查结果文件、行号、严重级别、问题描述、修复建议。对结果去重过滤明显误报再进入回写层。这个链路里最容易出错的是上下文组装。直接把 5000 行的完整文件全塞给模型既浪费 token又会引入与本次变更无关的历史代码干扰。推荐先做“变更函数定位”只提取新增或修改函数附近的定义比如函数的签名、返回类型、异常声明、最近的注释就能明显改善模型的判断质量。3.3 结果回写层评论、线程和状态检查模型输出的结果不是最终可用的评论需要二次处理。首先把结果按文件、行号映射到现有 diff 行只有落在本次变更范围内的行号才值得评论避免出现“在未修改的旧代码处出现审查提示”的突兀情况。回写形式主要有三种单条总结评论适合新接入团队对 MR 页面侵入小但定位不精确。行内评论线程体验最好读者能在具体代码行看到审查意见但 API 要求和幂等处理更复杂。Check Run / 状态报告适合与 CI 流程集成但需要处理好“失败是否阻止合并”的门禁策略。实际项目会组合使用小问题走行内评论整体评价和统计信息放在总结评论里。回写前还要做幂等控制如果同一 SHA 的审查任务已经回写过第二次运行时只更新已有评论不新增重复评论。这个能力在 GitLab 的 Merge Request Discussion API 里尤其要重视否则一次synchronize事件就可能造成多条重复评论。3.4 安全边界Token 存储、沙箱执行和数据脱敏自托管 agent 的安全边界比普通 Web 服务更复杂因为它同时持有代码平台的写权限和模型服务的调用权限。Token 存储必须避免明文硬编码。推荐使用环境变量、Docker Secret、Kubernetes Secret 或专门的密钥管理服务。把 GitHub App 私钥直接提交到仓库是在自托管项目中最常见的严重事故。模型调用时还要注意数据脱敏。代码里可能包含数据库连接串、内部域名、手机号、身份证测试数据。在还没有真正理解模型服务的数据保留策略前至少要做一个常规脱敏步骤识别明显的密钥、Token、高熵字符串替换成占位符后再送入模型。这个环节不能依赖模型自觉要在 agent 代码里做规则过滤。如果 agent 允许执行仓库内脚本或拉取构建产物就要把执行环境放进容器或沙箱限制网络访问和文件系统写入权限。审查 agent 的目的不是代跑 CI绝大多数场景下不应执行未经审查的仓库脚本。4. 自托管部署一份可复用的最小配置示例4.1 用 docker-compose 把 agent 本体和依赖跑起来下面的 docker-compose 文件是通用示意用来表达自托管代码审查 agent 常见的最小运行拓扑。实际项目需要根据官方镜像名、版本和自身依赖做调整不能假设镜像默认存在。version: 3.8 services: agent-web: image: your-registry/proval-agent:latest restart: unless-stopped ports: - 8080:8080 env_file: - .env depends_on: - postgres - redis agent-worker: image: your-registry/proval-agent-worker:latest restart: unless-stopped env_file: - .env depends_on: - postgres - redis postgres: image: postgres:16-alpine restart: unless-stopped environment: POSTGRES_USER: proval POSTGRES_PASSWORD: change-me POSTGRES_DB: proval volumes: - pg_data:/var/lib/postgresql/data redis: image: redis:7-alpine restart: unless-stopped volumes: pg_data:在这份配置里agent-web负责接收 Webhook 事件并写入队列agent-worker负责消费任务、调用模型、回写评论。两者必须读取同一套环境变量和数据库配置否则会出现“Webhook 接收了但 worker 找不到任务”这种问题。生产环境还应该在两个服务前增加反向代理由 Nginx 或 Ingress 负责 HTTPS 终止和 Webhook 签名转发。4.2 核心配置项与环境变量自托管 agent 的配置通常分为三层平台凭证、模型服务、行为开关。下面用.env的格式列出一份通用配置示例。# Webhook 接收端口 PORT8080 # 数据库与队列 POSTGRES_URLpostgres://proval:change-mepostgres:5432/proval REDIS_URLredis://redis:6379/0 # Webhook 签名密钥三个平台各一个 GITHUB_WEBHOOK_SECRETreplace-with-a-long-random-string GITLAB_WEBHOOK_TOKENreplace-with-another-random-string FORGEJO_WEBHOOK_SECRETreplace-with-third-random-string # GitHub App 凭证 GITHUB_APP_ID123456 GITHUB_APP_INSTALLATION_ID987654 GITHUB_APP_PRIVATE_KEY_PATH/run/secrets/github-app-private-key.pem # GitLab Token GITLAB_TOKENglpat-xxxxx GITLAB_API_URLhttps://gitlab.example.com # Forgejo Token FORGEJO_TOKENforgejo-xxxxx FORGEJO_API_URLhttps://git.example.com # 模型服务OpenAI-compatible 协议 MODEL_BASE_URLhttps://llm.internal.example.com/v1 MODEL_API_KEYsk-local-xxxxx MODEL_NAMEqwen2.5-72b-instruct # 行为开关 MAX_FILE_SIZE_KB200 MAX_FILES_PER_REVIEW60 ENABLE_INLINE_COMMENTStrue ENABLE_SUMMARY_COMMENTtrue关键配置点有三个。WEBHOOK_SECRET必须和平台侧配置保持一致否则签名校验失败后任务根本进不了队列。GITHUB_APP_PRIVATE_KEY_PATH指向的是私钥文件而不是私钥内容不要把私钥直接写进.env。MODEL_BASE_URL和MODEL_API_KEY指向内部模型服务如果是远程模型 API要评估 diff 内容出网风险。4.3 GitLab、Forgejo、GitHub 的接入配置差异下面用表格对比三个平台在接入侧最常见的差异方便部署时直接对照。配置项GitHubGitLabForgejoWebhook 入口Settings - WebhooksSettings - WebhooksSettings - Webhooks签名方式HMACX-Hub-Signature-256Secret TokenX-Gitlab-TokenSecretHmac 校验与 GitHub 接近PR/MR 事件名pull_requestMerge Request Hookpull_request主要评论 APIGraphQL addPullRequestReview / REST issue commentsMerge Request Notes APIIssue/Comment API 或 Pull Review APIToken 类型GitHub App 安装 TokenAccess Token用户 Token / Bot Token是否需要私钥签发是否否三个平台里 GitHub 的集成最重但能力边界也最清晰。GitLab 的 Token 体系最简单适合先做试用。Forgejo 如果版本较新API 与 GitHub 的相似度会比较高适配成本通常低于 GitLab。在配置 Webhook 时事件选择要尽量减少无效触发。GitHub 侧只勾选Pull requests即可GitLab 侧如果只关心 MR 审查也不要选择全部 Hook 类型避免 Push、Tag 事件全部涌入队列。5. 从创建 MR 到收到审查评论走通一次完整流程5.1 准备最小验证仓库部署完成后不要直接在自己最核心的业务仓库上做首次验证否则可能产生大量噪音评论。建议新建一个测试仓库加入两个简单文件制造一个“有明显问题”的变更。例如准备一个 Python 文件def calculate_discount(price, rate, user): # 这里故意缺少 rate 范围校验 return price * rate def get_user_name(user): # 这里故意抛出裸异常 return user.profile.name[ :100 ]然后创建 MR/PR。仓库里再放一份简单的审查规则文件至少包含“新增函数必须包含 docstring”和“禁止裸 except”两条规则。这样可以快速判断 agent 是否真正读取了项目规则而不是只依赖模型常识。5.2 观察 Webhook 到 worker 的日志链路创建 MR/PR 后按下面的顺序检查链路平台 Webhook 发送记录确认请求返回 2xx。agent-web 日志确认签名校验通过、事件转换为内部结构。队列状态确认任务进入 queue 并被 worker 消费。worker 日志确认 diff 拉取成功、模型调用成功、返回结果解析正常。平台 MR 页面确认评论或 review 已创建。一份正常的 worker 日志大致是这样的2025-01-15 10:02:11 INFO taskreview_task event_idevt_20250115_abc123 repotest/repo pr142 statusstarted 2025-01-15 10:02:12 INFO diff fetched files2 additions18 deletions4 2025-01-15 10:02:13 INFO context assembled tokens1234 files2 2025-01-15 10:02:20 INFO model response ok latency_ms7042 2025-01-15 10:02:21 INFO comments prepared inline2 summary1 2025-01-15 10:02:22 INFO review created urlhttps://github.com/test/repo/pull/142#pullrequestreview-123456如果日志卡在某一步优先看对应阶段的异常信息。平台事件没有出现时先看 Webhook 是否配置成功diff 拉取失败时优先检查 Token 权限模型调用超时时检查模型服务本身的状态和超时配置。5.3 验证结果是否符合预期收到评论后不能只看“有没有评论”还要验证评论质量评论是否落在本次变更的行上还是出现在未修改的历史代码行。同一事件重复触发时是否产生重复评论。新增文件、删除文件、重命名文件是否都被正确分类。包含 secrets 的 diff 是否被脱敏后才发送给模型。审查结果是否包含严重级别和可操作建议而不是泛泛的“这里可能有问题”。一个可复用的验证清单如下验证项预期结果Webhook 请求返回码2xx而不是 502 或超时worker 日志任务同一 event_id 只消费一次diff 统计与平台展示的文件数、增删行数基本一致评论行号落在 diff 变更行内重复触发同 SHA 重复事件不会新增评论令牌最小权限Token 无法删除分支或修改仓库设置6. 常见问题与排查路径6.1 Webhook 收到了但 MR 评论区没有反应现象是平台 Webhook 页面显示请求已经发送MR/PR 页面却一直没有 agent 评论。按下面的顺序排查先看 agent-web 的访问日志确认请求是否到达应用。如果没有任何记录检查反向代理路由和端口映射。确认签名校验是否通过。GitHub 使用 HMAC如果 Secret 不一致请求会在入口被拒绝并返回 401。看队列消费情况。web 把任务写入队列worker 如果没有启动或消费失败任务会一直积压。检查 worker 日志中的模型调用部分。模型服务超时会直接导致任务失败。检查 Token 权限是否足够创建评论。很多平台对评论 API 有额外权限要求光是read权限不够。最常见的根因是 Token 权限不足。GitHub App 的Pull requests权限没有设置成 Read and writeGitLab Token 缺少apiscopeForgejo Token 缺少评论相关权限都会造成“diff 能读、评论写不回去”的诡异现象。6.2 agent 执行中提示 provider did not respond in time日志里出现the agent execution provider did not respond in time这类信息时通常不是普通代码 bug而是执行链路的某个 provider 整体超时。它可能来自模型 API、平台 API 或内部任务调度器。先确认是哪一层超时模型服务超时检查MODEL_BASE_URL对应的服务负载和响应耗时。本地模型如果排队任务过多单次推理可能超过 60 秒。平台 API 超时仓库很大时拉取完整 diff 或某个大文件内容可能超过平台接口限制。内部 agent 超时可能是任务队列 worker 并发数过低大量任务排成串行。处理方向是分层设置超时而不是依赖默认值。Webhook 接口应设置短超时比如 10 秒保证平台侧不会重复推送模型调用设置中长超时比如 120 秒并开启重试去重整体任务可以设置最终超时超时后标记为 failed 并进入可重试队列。还要注意重试策略。模型超时重试可以增加指数退避但重试成功后要能识别原始任务 ID避免同一次审查产生两份评论。6.3 评论产生了但误报太多自托管代码审查 agent 上线后最常见的“业务问题”不是不工作而是“什么都要说”让开发者逐渐习惯性忽略评论。误报通常来自三个原因第一提示词没有明确“只报告确定有问题的高置信度发现”。需要把过滤责任放在前端规则不能只靠模型自觉。第二上下文不足。模型只看到了散落的 diff 片段没有看到函数定义和调用关系就会把“方法不存在”当成问题。第三项目规则文件没有正确加载。agent 声称支持团队自定义规则但规则配置没有放入预期路径或者格式解析失败最终模型只能靠通用知识审查。推荐做法是给每个审查结果增加置信度和严重级别。error级别用于确定性问题比如密钥提交、裸密码、明显越界suggestion级别用于可优化项默认收敛数量不能每个文件输出十几条。同时提供规则配置的测试命令让团队在修改规则后能立刻验证规则是否被正确解析。6.4 三个平台都接入但只有其中一个平台行为异常这类问题基本指向适配层没有按平台隔离状态。排查时先对比三个平台同一 MR 的日志差异把问题分成事件转换、API 调用、回写三块。如果事件转换正常但 API 调用失败查看该平台的基础地址配置。GitLab 是自托管的GITLAB_API_URL必须指向实际部署地址Forgejo 同样需要确认 API URL 是否带/api/v1前缀。GitHub App 则要确认 Installation ID 对应的是目标仓库所在的账号App 安装在不同组织下会有不同的 ID。# 手动验证 GitLab 是否能读取 MR 列表 curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \ $GITLAB_API_URL/api/v4/projects/:id/merge_requests?stateopened手动调用一次目标平台 API能快速区分是 agent 代码问题、Token 权限问题还是平台版本兼容问题。7. 生产环境落地建议与扩展方向7.1 部署上线前的检查清单在把自托管代码审查 agent 推向正式仓库之前建议逐项确认下面的清单检查项完成标准密钥隔离GitHub App 私钥、Token 均存放在 Secret 管理机制中不进仓库Webhook 签名三个平台均配置 Secret 且代码校验通过HTTPS 访问Webhook 入口只接受 HTTPS反向代理证书有效数据库备份PostgreSQL 定时备份已配置并完成一次恢复演练任务幂等同一 MR 重复事件不会产生重复评论评论权限Token 只能读写 MR/PR不能删除分支或修改仓库设置规则版本化审查规则文件纳入 Git 管理改动可追溯超时与重试模型调用、平台 API、Webhook 入口分别配置了合理超时日志采集日志能按 event_id 串联完整链路并进入统一日志平台回滚方案关闭 agent 回调或撤销 Webhook 后能立即恢复原有人工审查流程7.2 审查规则应该当成代码来管理自托管方案的价值很大程度体现在规则可定制上但定制能力也会带来混乱。团队如果通过网页临时改规则三个月后就没有人知道当前配置为什么存在。规则文件应采用“基础通用规则 按语言/模块拆分的扩展规则”结构# review-rules.yaml 示意 version: 1.0 rules: - id: NO_CREDENTIALS severtiy: error description: 禁止在代码中提交密钥、Token、连接串 patterns: - password\\s*\\s*[\][^\][\] - api_key\\s*\\s*[\][^\][\] - id: REQUIRED_DOCSTRING severity: suggestion description: 新增的函数应包含 docstring languages: - python - id: NO_NAKED_EXCEPT severity: error description: 禁止裸 except应捕获具体异常类型 languages: - python规则变更要走 MR 流程先提交规则变更再让规则本身接受一次小范围仓库的测试最后才推广到所有仓库。这样既能保证团队规范沉淀也能避免某人临时关闭所有错误级规则后无人知晓。7.3 安全与数据治理的底线自托管不等于自动安全。审查 agent 拿到的是代码平台的高权限 Token一旦被外部利用攻击者可以读取整个项目的源码并伪造机器人评论诱导开发者点击恶意链接。因此要按“高权限服务”的标准建设独立运行账号不能复用管理员个人账号的 Token。网络隔离agent 只能访问目标 Git 平台、数据库、Redis 和模型服务不允许直接访问公网包注册源。模型服务选择要考虑数据留存策略。如果代码保密级别高优先使用本地部署模型。评论内容要做基本校验防止模型输出被提示注入。攻击者可能在代码注释或 PR 描述中写入恶意指令诱导 agent 在评论中输出钓鱼链接或泄露上下文内容。提示注入是代码审查 agent 特有的安全风险。diff 本身是不可信输入不能把仓库内容当作普通文本直接塞进提示词。至少有两个防御手段在系统提示词中强调仓库内容是待审查数据而非指令对模型输出中的链接和可执行命令做白名单过滤。7.4 从“评论工具”走向“审查助手”代码审查 agent 的最终形态不是“每次 MR 输出几十条评论”而是逐步变成团队的审查助手。初期可以只做错误级问题的自动提示等高置信度结果稳定后再扩展到“自动补全测试用例”“自动生成变更摘要”“标记最需要人工关注的函数”等能力。从工程路线上看有几个值得关注的方向多轮对话式审查开发者可以对某条审查评论追问理由agent 结合上下文再解释。失败模式学习把人工标记为误报的评论收集起来沉淀成负样本规则持续降低噪音。跨 MR 状态跟踪同一文件在不同 MR 中反复出现同类问题说明是设计层面问题应该生成团队级的规范修订建议。与内部知识库对接让 agent 在审查时引用团队内部的设计文档和已知故障记录而不仅仅依赖代码上下文。这些方向都会把 agent 从“一次性命令工具”变成“持续参与研发流程的系统”。但要注意任何对规则和模型行为的修改都应遵循同样的验证流程在测试仓库验证、观察误报率、评审效果后再发布到全量仓库。代码审查 agent 是手段团队代码质量和开发体验才是最终目的。自托管给了团队更多控制权也不会自动降低代码问题数量真正决定上限的是团队如何把审查规则、模型能力和人工判断组织成一条顺畅的协作链路。 自托管代码审查Agent：兼容GitLab、Forgejo与GitHub的架构与实践
如果团队已经使用 GitLab、Forgejo 或 GitHub 管理代码那么“合并请求被反复人工检查”通常是研发流程里最耗时也最不稳定的环节。代码审查 agent 解决的问题是把“代码变更的初步审视”交给一套自动化程序来完成它读取 MR/PR 的 diff结合仓库上下文、提交历史、规范要求甚至历史审查记录给出结构化的审查意见。Proval 正是这类工具中的自托管方案它没有把代码提交到第三方平台而是让审查逻辑运行在团队自己的服务器上同时兼容 GitLab、Forgejo 和 GitHub 三种常见的 Git 托管平台。自托管的意义很直接代码和审查数据留在自己手里审查规则可以由团队自由定制调用的是企业内部可访问的模型服务而不是每次把完整 diff 发送给外部 SaaS。代价同样明显部署、升级、排错、权限维护、模型调用成本都需要自己负责。这篇文章会围绕“自托管代码审查 agent”这条主线拆解它背后的架构模块、部署方式、平台接入差异、端到端验证方法以及上线前必须关注的排查点和最佳实践。内容以 Proval 这类工具为背景但多数架构判断可以复用到类似的代码审查 agent 项目上。1. 先理解自托管代码审查 agent 到底是什么1.1 它和静态检查、CI 检查、人工审查的区别很多团队早就接入了 ESLint、Checkstyle、golangci-lint 这类静态检查工具也把单元测试、构建任务放进了 CI。代码审查 agent 和它们最大的不同在于它不强调“确定性规则匹配”而是模拟一个熟悉项目的资深工程师在收到 MR/PR 事件后主动读取变更内容并基于大模型或本地模型生成审查建议。静态检查工具的优点是确定性强、速度快、误报可控但它只能发现模式匹配到的问题。代码审查 agent 的优势是能处理“跨文件关联”“边界条件遗漏”“并发安全”“业务语义不一致”这类原本需要人脑判断的问题。它并不能替代人工审查而是把人工审查中最耗时的“通读 diff、找明显缺陷、补充规范检查”这层工作接手过去让人只聚焦在真正需要判断力和上下文的问题上。在实现上代码审查 agent 通常不是简单地把“diff 文本 提示词”发给模型就结束。它会先做一系列预处理过滤非必要文件、按变更级别排序、拼接相关函数定义、检索相似历史问题最后才形成结构化 prompt。这也是它和“一个调用 ChatGPT API 的脚本”的本质区别。1.2 为什么选择自托管而不是 SaaS如果使用托管式代码审查服务团队只需要安装一个 GitHub App 或 GitLab 集成然后在网页上配置规则几十分钟就能跑通。它的便利性很明显但几个问题会让一些团队犹豫。代码安全是第一道坎。托管服务默认会读取仓库内容、diff、评论、成员信息。对于闭源商业项目、金融系统、医疗系统很多团队无法接受第三方服务持续读取源码。自托管方案把“读取代码”和“生成评论”的过程放在自己控制的服务器或内网环境里代码不会离开公司边界至少在数据流向层面有了明确控制点。第二个原因是规则定制。SaaS 服务通常只提供有限的规则模板比如“禁止密钥提交”“限制函数长度”“检测 TODO 残留”。但不同团队对“什么是好的代码”定义完全不同有的团队要求所有新代码附带测试文件有的团队要求错误处理必须使用统一异常类有的团队要求数据库字段变更必须同步迁移脚本。自托管方案可以把这些规则写进配置文件或提示词模板纳入版本管理和团队规范保持同步。第三个原因是成本模型。SaaS 服务通常按仓库数或 API 调用量收费仓库增长后费用会快速上升。自托管虽然要自己承担服务器和模型调用成本但成本边界更清晰也可以使用本地部署的模型来降低单位调用费用。当然自托管也要付出运维代价需要处理容器升级、数据库迁移、Token 过期、Webhook 丢失、模型服务抖动等问题。选择自托管本质是用运维成本换取数据控制权和规则自由度。1.3 “兼容三个平台”这句话背后的工程含义标题中的“for GitLab, Forgejo, and GitHub”看上去只是列出三个平台名但工程上相当于一套核心引擎对接三种不同的外部 API。这三个平台的 API 体系并不统一。GitHub 的接口以 REST 和 GraphQL 为主GitHub App 通过安装 Token 交互GitLab 提供成熟的 Project Access Token 和 Webhook 签名机制Forgejo 是从 Gitea 发展而来的轻量级托管平台API 风格与 GitHub 有相似之处但权限模型、Webhook 事件结构、评论接口都有差异。一个跨平台代码审查 agent 在设计时必须抽象出三层平台适配层、核心审查层、评论回写层。平台适配层负责把三个平台的 Webhook 转换成统一的中立事件结构比如PullRequestEvent{ repository, title, headSha, baseSha, author, changedFiles, additions, deletions }。核心审查层只依赖这个中立结构工作不关心事件来自哪个平台。评论回写层再根据目标平台调用不同 API把审查结果转换为本地评论、review thread 或 check run。如果架构缺少这层抽象最常见的结果是GitHub 上能跑通的流程迁移到 GitLab 后需要改大量业务代码每接入一个平台都要重写一遍审查逻辑。自托管项目要做多平台兼容第一步就是要求团队明确“哪些逻辑是平台无关的哪些逻辑必须放适配层”。2. 部署自托管代码审查 agent 需要准备什么2.1 服务器与运行环境基准在没有官方明确版本的前提下先按通用自托管服务的目标来估算资源。代码审查 agent 的负载模型主要是事件驱动没有 MR 时基本空闲MR 集中出现时需要在短时间内分析大量 diff因此关注点不是“平均 CPU”而是“峰值扩缩容能力”和“任务排队机制”。从最小可运行环境出发可以按下面的标准准备项目学习/试用环境生产推荐环境服务器2 vCPU / 4 GB 内存 / 40 GB 磁盘4 vCPU 起 / 8 GB 内存起 / 按日志与数据增长扩容操作系统Ubuntu 22.04 LTS 或等效 Linux与团队基础设施一致的 Linux 发行版容器Docker Engine 24Docker Engine 镜像仓库 版本标签管理编排docker-composeKubernetes 或按团队标准管理必须支持健康检查和回滚数据库PostgreSQL 或 SQLite取决于项目支持PostgreSQL开启备份任务队列内存队列试运行Redis 或等效消息队列持久化任务状态模型服务团队可用的大模型 API内网模型服务或受信任的云模型 API需评估数据出网策略这里要区分一个容易混淆的概念agent 本体是“审查逻辑的执行器”它不一定内置大模型。它更接近一个编排进程接收事件、组装上下文、调用模型接口、解析结果、回写平台。模型可以是 OpenAI-compatible 的远程 API也可以是 vLLM、Ollama、llama.cpp 等本地服务。选择本地模型时GPU 或 NPU 资源要按照模型参数量单独评估不能和 agent 本体共用一台 2 vCPU 的机器。2.2 三个平台的接入凭证需要配齐哪些权限自托管 agent 要读取 MR/PR 内容并在讨论区发评论最少需要两类权限读仓库内容、写 MR/PR 评论。不同平台配置入口不同但权限原则一致不要给全局管理员权限尽量使用最小权限。GitHub 的推荐方式是创建 GitHub App而不是使用个人 Token。GitHub App 的权限可以精确到某个仓库集合并单独定义 Permissions。典型配置项包括Pull requests: Read and write读取 PR diff 并创建 review 评论。Contents: Read读取仓库文件内容用于补全上下文。Checks: Read and write如果需要以 Check Run 形式上报审查状态。Metadata: ReadGitHub App 基础元数据权限系统强制要求。GitHub App 安装后返回的 Installation Token 是短期 Tokenagent 需要使用私钥动态签发不能硬编码在配置文件里长期使用。GitLab 可以使用 Project Access Token 或 Group Access Token。关键 scope 通常是api、read_repository。其中api权限能力较大如果项目只要求读代码和写评论也可以尝试read_api加评论接口所需的最小写权限组合但部分评论接口仍依赖apiscope落地时要根据项目文档验证。更稳妥的做法是创建一个专用于审查 agent 的 GitLab 用户给它目标项目的 Developer 角色再基于该用户创建 Token避免 Token 泄漏后影响整个组。Forgejo 的 Token 体系与 GitHub 较接近。在用户设置里创建 Token 时勾选read:repository、write:issue和write:pull_request等权限。Forgejo 的权限命名在不同版本间有调整配置前要确认当前版本支持的 scope 名称。平台推荐凭证类型主要权限更换成本GitHubGitHub AppPull requests R/W、Contents R、Checks R/W中需配置私钥和安装 IDGitLabProject/Group Access Tokenapi、read_repository低Token 可随时撤销Forgejo用户 Tokenread:repository、write:pull_request 等低Token 可随时撤销2.3 Webhook 地址、签名和任务持久化接入三个平台都离不开 Webhook。agent 需要提供一个公网可访问的 HTTPS 地址或者通过反向代理暴露到目标平台。生产环境必须配置 Webhook 签名校验而不是直接信任请求来源。GitHub 的 Webhook 使用X-Hub-Signature-256头由请求体加 Secret 经过 HMAC 生成。GitLab 会在回调中携带X-Gitlab-Token如果配置了 Secret Token 就必须比对。Forgejo 与 GitHub 类似同样可以使用 Secret 校验。agent 在入口处应该先校验签名再做业务处理避免伪造请求消耗模型资源。任务持久化也是部署前要设计的点。Webhook 到达后agent 不能直接在请求处理函数里同步执行一次完整审查。因为代码审查可能涉及几十个文件、多次模型调用耗时会超过平台 HTTP 超时限制。正确做法是Webhook 入口只校验签名、解析事件、把任务写入队列立即返回 200后台 worker 从队列里取任务执行分析最后异步调用平台 API 回写评论。这样即使模型服务超时Webhook 也不会重试导致重复评论。3. 拆解代码审查 agent 的核心工作链路3.1 事件接入层Webhook 路由与事件去重跨平台 agent 的第一步是统一事件。无论来自 GitHub 的pull_request事件、GitLab 的Merge Request Hook还是 Forgejo 的pull_request事件进入核心层之前都要转换成统一的中立事件结构。一个最小事件对象大致如下{ event_id: evt_20250115_abc123, source: github, repo: org/backend-service, action: opened, pull_request: { number: 142, title: feat: add user profile cache, head_sha: 3f2a9c1e, base_sha: 7d3e5502, author: zhangsan }, sender: zhangsan }事件去重要在队列写入前完成。三个平台在 Webhook 重试机制上行为不一致GitHub 会重试失败的 WebhookGitLab 也支持自定义重试如果入口处理时间过长平台可能连续推送多次。建议以source repo pull_request.number action作为幂等键在处理记录表里判断是否已经消费过。常见的一个坑是只用merge_request的action做判断导致 reopen、synchronize、opened 事件处理逻辑分支混乱。推荐在事件适配层把平台原始action映射成三类内部动作OPENED、UPDATED、CLOSED后续所有规则只依赖内部动作不直接判断平台字符串。3.2 分析执行层Diff 提取、上下文组装、模型调用这是整个 agent 技术含量最高的部分。拿到 MR/PR 后agent 要做的不只是把 diff 原样贴给模型而是尽可能让模型看到“变更真正影响的范围”。常见流程如下从平台 API 拉取 diff 全文按files/removed/added/context结构拆分。过滤噪声文件锁定文件package-lock.json、pnpm-lock.yaml、生成的 protobuf、纯格式化变更。对每个变更文件识别新增函数和修改函数向上查找函数的上下文片段。如果模型支持更大上下文把相关文件的关键定义一并拼入。组装 prompt包含系统提示、仓库规范、diff、上下文片段、审查要求。调用模型得到结构化审查结果文件、行号、严重级别、问题描述、修复建议。对结果去重过滤明显误报再进入回写层。这个链路里最容易出错的是上下文组装。直接把 5000 行的完整文件全塞给模型既浪费 token又会引入与本次变更无关的历史代码干扰。推荐先做“变更函数定位”只提取新增或修改函数附近的定义比如函数的签名、返回类型、异常声明、最近的注释就能明显改善模型的判断质量。3.3 结果回写层评论、线程和状态检查模型输出的结果不是最终可用的评论需要二次处理。首先把结果按文件、行号映射到现有 diff 行只有落在本次变更范围内的行号才值得评论避免出现“在未修改的旧代码处出现审查提示”的突兀情况。回写形式主要有三种单条总结评论适合新接入团队对 MR 页面侵入小但定位不精确。行内评论线程体验最好读者能在具体代码行看到审查意见但 API 要求和幂等处理更复杂。Check Run / 状态报告适合与 CI 流程集成但需要处理好“失败是否阻止合并”的门禁策略。实际项目会组合使用小问题走行内评论整体评价和统计信息放在总结评论里。回写前还要做幂等控制如果同一 SHA 的审查任务已经回写过第二次运行时只更新已有评论不新增重复评论。这个能力在 GitLab 的 Merge Request Discussion API 里尤其要重视否则一次synchronize事件就可能造成多条重复评论。3.4 安全边界Token 存储、沙箱执行和数据脱敏自托管 agent 的安全边界比普通 Web 服务更复杂因为它同时持有代码平台的写权限和模型服务的调用权限。Token 存储必须避免明文硬编码。推荐使用环境变量、Docker Secret、Kubernetes Secret 或专门的密钥管理服务。把 GitHub App 私钥直接提交到仓库是在自托管项目中最常见的严重事故。模型调用时还要注意数据脱敏。代码里可能包含数据库连接串、内部域名、手机号、身份证测试数据。在还没有真正理解模型服务的数据保留策略前至少要做一个常规脱敏步骤识别明显的密钥、Token、高熵字符串替换成占位符后再送入模型。这个环节不能依赖模型自觉要在 agent 代码里做规则过滤。如果 agent 允许执行仓库内脚本或拉取构建产物就要把执行环境放进容器或沙箱限制网络访问和文件系统写入权限。审查 agent 的目的不是代跑 CI绝大多数场景下不应执行未经审查的仓库脚本。4. 自托管部署一份可复用的最小配置示例4.1 用 docker-compose 把 agent 本体和依赖跑起来下面的 docker-compose 文件是通用示意用来表达自托管代码审查 agent 常见的最小运行拓扑。实际项目需要根据官方镜像名、版本和自身依赖做调整不能假设镜像默认存在。version: 3.8 services: agent-web: image: your-registry/proval-agent:latest restart: unless-stopped ports: - 8080:8080 env_file: - .env depends_on: - postgres - redis agent-worker: image: your-registry/proval-agent-worker:latest restart: unless-stopped env_file: - .env depends_on: - postgres - redis postgres: image: postgres:16-alpine restart: unless-stopped environment: POSTGRES_USER: proval POSTGRES_PASSWORD: change-me POSTGRES_DB: proval volumes: - pg_data:/var/lib/postgresql/data redis: image: redis:7-alpine restart: unless-stopped volumes: pg_data:在这份配置里agent-web负责接收 Webhook 事件并写入队列agent-worker负责消费任务、调用模型、回写评论。两者必须读取同一套环境变量和数据库配置否则会出现“Webhook 接收了但 worker 找不到任务”这种问题。生产环境还应该在两个服务前增加反向代理由 Nginx 或 Ingress 负责 HTTPS 终止和 Webhook 签名转发。4.2 核心配置项与环境变量自托管 agent 的配置通常分为三层平台凭证、模型服务、行为开关。下面用.env的格式列出一份通用配置示例。# Webhook 接收端口 PORT8080 # 数据库与队列 POSTGRES_URLpostgres://proval:change-mepostgres:5432/proval REDIS_URLredis://redis:6379/0 # Webhook 签名密钥三个平台各一个 GITHUB_WEBHOOK_SECRETreplace-with-a-long-random-string GITLAB_WEBHOOK_TOKENreplace-with-another-random-string FORGEJO_WEBHOOK_SECRETreplace-with-third-random-string # GitHub App 凭证 GITHUB_APP_ID123456 GITHUB_APP_INSTALLATION_ID987654 GITHUB_APP_PRIVATE_KEY_PATH/run/secrets/github-app-private-key.pem # GitLab Token GITLAB_TOKENglpat-xxxxx GITLAB_API_URLhttps://gitlab.example.com # Forgejo Token FORGEJO_TOKENforgejo-xxxxx FORGEJO_API_URLhttps://git.example.com # 模型服务OpenAI-compatible 协议 MODEL_BASE_URLhttps://llm.internal.example.com/v1 MODEL_API_KEYsk-local-xxxxx MODEL_NAMEqwen2.5-72b-instruct # 行为开关 MAX_FILE_SIZE_KB200 MAX_FILES_PER_REVIEW60 ENABLE_INLINE_COMMENTStrue ENABLE_SUMMARY_COMMENTtrue关键配置点有三个。WEBHOOK_SECRET必须和平台侧配置保持一致否则签名校验失败后任务根本进不了队列。GITHUB_APP_PRIVATE_KEY_PATH指向的是私钥文件而不是私钥内容不要把私钥直接写进.env。MODEL_BASE_URL和MODEL_API_KEY指向内部模型服务如果是远程模型 API要评估 diff 内容出网风险。4.3 GitLab、Forgejo、GitHub 的接入配置差异下面用表格对比三个平台在接入侧最常见的差异方便部署时直接对照。配置项GitHubGitLabForgejoWebhook 入口Settings - WebhooksSettings - WebhooksSettings - Webhooks签名方式HMACX-Hub-Signature-256Secret TokenX-Gitlab-TokenSecretHmac 校验与 GitHub 接近PR/MR 事件名pull_requestMerge Request Hookpull_request主要评论 APIGraphQL addPullRequestReview / REST issue commentsMerge Request Notes APIIssue/Comment API 或 Pull Review APIToken 类型GitHub App 安装 TokenAccess Token用户 Token / Bot Token是否需要私钥签发是否否三个平台里 GitHub 的集成最重但能力边界也最清晰。GitLab 的 Token 体系最简单适合先做试用。Forgejo 如果版本较新API 与 GitHub 的相似度会比较高适配成本通常低于 GitLab。在配置 Webhook 时事件选择要尽量减少无效触发。GitHub 侧只勾选Pull requests即可GitLab 侧如果只关心 MR 审查也不要选择全部 Hook 类型避免 Push、Tag 事件全部涌入队列。5. 从创建 MR 到收到审查评论走通一次完整流程5.1 准备最小验证仓库部署完成后不要直接在自己最核心的业务仓库上做首次验证否则可能产生大量噪音评论。建议新建一个测试仓库加入两个简单文件制造一个“有明显问题”的变更。例如准备一个 Python 文件def calculate_discount(price, rate, user): # 这里故意缺少 rate 范围校验 return price * rate def get_user_name(user): # 这里故意抛出裸异常 return user.profile.name[ :100 ]然后创建 MR/PR。仓库里再放一份简单的审查规则文件至少包含“新增函数必须包含 docstring”和“禁止裸 except”两条规则。这样可以快速判断 agent 是否真正读取了项目规则而不是只依赖模型常识。5.2 观察 Webhook 到 worker 的日志链路创建 MR/PR 后按下面的顺序检查链路平台 Webhook 发送记录确认请求返回 2xx。agent-web 日志确认签名校验通过、事件转换为内部结构。队列状态确认任务进入 queue 并被 worker 消费。worker 日志确认 diff 拉取成功、模型调用成功、返回结果解析正常。平台 MR 页面确认评论或 review 已创建。一份正常的 worker 日志大致是这样的2025-01-15 10:02:11 INFO taskreview_task event_idevt_20250115_abc123 repotest/repo pr142 statusstarted 2025-01-15 10:02:12 INFO diff fetched files2 additions18 deletions4 2025-01-15 10:02:13 INFO context assembled tokens1234 files2 2025-01-15 10:02:20 INFO model response ok latency_ms7042 2025-01-15 10:02:21 INFO comments prepared inline2 summary1 2025-01-15 10:02:22 INFO review created urlhttps://github.com/test/repo/pull/142#pullrequestreview-123456如果日志卡在某一步优先看对应阶段的异常信息。平台事件没有出现时先看 Webhook 是否配置成功diff 拉取失败时优先检查 Token 权限模型调用超时时检查模型服务本身的状态和超时配置。5.3 验证结果是否符合预期收到评论后不能只看“有没有评论”还要验证评论质量评论是否落在本次变更的行上还是出现在未修改的历史代码行。同一事件重复触发时是否产生重复评论。新增文件、删除文件、重命名文件是否都被正确分类。包含 secrets 的 diff 是否被脱敏后才发送给模型。审查结果是否包含严重级别和可操作建议而不是泛泛的“这里可能有问题”。一个可复用的验证清单如下验证项预期结果Webhook 请求返回码2xx而不是 502 或超时worker 日志任务同一 event_id 只消费一次diff 统计与平台展示的文件数、增删行数基本一致评论行号落在 diff 变更行内重复触发同 SHA 重复事件不会新增评论令牌最小权限Token 无法删除分支或修改仓库设置6. 常见问题与排查路径6.1 Webhook 收到了但 MR 评论区没有反应现象是平台 Webhook 页面显示请求已经发送MR/PR 页面却一直没有 agent 评论。按下面的顺序排查先看 agent-web 的访问日志确认请求是否到达应用。如果没有任何记录检查反向代理路由和端口映射。确认签名校验是否通过。GitHub 使用 HMAC如果 Secret 不一致请求会在入口被拒绝并返回 401。看队列消费情况。web 把任务写入队列worker 如果没有启动或消费失败任务会一直积压。检查 worker 日志中的模型调用部分。模型服务超时会直接导致任务失败。检查 Token 权限是否足够创建评论。很多平台对评论 API 有额外权限要求光是read权限不够。最常见的根因是 Token 权限不足。GitHub App 的Pull requests权限没有设置成 Read and writeGitLab Token 缺少apiscopeForgejo Token 缺少评论相关权限都会造成“diff 能读、评论写不回去”的诡异现象。6.2 agent 执行中提示 provider did not respond in time日志里出现the agent execution provider did not respond in time这类信息时通常不是普通代码 bug而是执行链路的某个 provider 整体超时。它可能来自模型 API、平台 API 或内部任务调度器。先确认是哪一层超时模型服务超时检查MODEL_BASE_URL对应的服务负载和响应耗时。本地模型如果排队任务过多单次推理可能超过 60 秒。平台 API 超时仓库很大时拉取完整 diff 或某个大文件内容可能超过平台接口限制。内部 agent 超时可能是任务队列 worker 并发数过低大量任务排成串行。处理方向是分层设置超时而不是依赖默认值。Webhook 接口应设置短超时比如 10 秒保证平台侧不会重复推送模型调用设置中长超时比如 120 秒并开启重试去重整体任务可以设置最终超时超时后标记为 failed 并进入可重试队列。还要注意重试策略。模型超时重试可以增加指数退避但重试成功后要能识别原始任务 ID避免同一次审查产生两份评论。6.3 评论产生了但误报太多自托管代码审查 agent 上线后最常见的“业务问题”不是不工作而是“什么都要说”让开发者逐渐习惯性忽略评论。误报通常来自三个原因第一提示词没有明确“只报告确定有问题的高置信度发现”。需要把过滤责任放在前端规则不能只靠模型自觉。第二上下文不足。模型只看到了散落的 diff 片段没有看到函数定义和调用关系就会把“方法不存在”当成问题。第三项目规则文件没有正确加载。agent 声称支持团队自定义规则但规则配置没有放入预期路径或者格式解析失败最终模型只能靠通用知识审查。推荐做法是给每个审查结果增加置信度和严重级别。error级别用于确定性问题比如密钥提交、裸密码、明显越界suggestion级别用于可优化项默认收敛数量不能每个文件输出十几条。同时提供规则配置的测试命令让团队在修改规则后能立刻验证规则是否被正确解析。6.4 三个平台都接入但只有其中一个平台行为异常这类问题基本指向适配层没有按平台隔离状态。排查时先对比三个平台同一 MR 的日志差异把问题分成事件转换、API 调用、回写三块。如果事件转换正常但 API 调用失败查看该平台的基础地址配置。GitLab 是自托管的GITLAB_API_URL必须指向实际部署地址Forgejo 同样需要确认 API URL 是否带/api/v1前缀。GitHub App 则要确认 Installation ID 对应的是目标仓库所在的账号App 安装在不同组织下会有不同的 ID。# 手动验证 GitLab 是否能读取 MR 列表 curl -H PRIVATE-TOKEN: $GITLAB_TOKEN \ $GITLAB_API_URL/api/v4/projects/:id/merge_requests?stateopened手动调用一次目标平台 API能快速区分是 agent 代码问题、Token 权限问题还是平台版本兼容问题。7. 生产环境落地建议与扩展方向7.1 部署上线前的检查清单在把自托管代码审查 agent 推向正式仓库之前建议逐项确认下面的清单检查项完成标准密钥隔离GitHub App 私钥、Token 均存放在 Secret 管理机制中不进仓库Webhook 签名三个平台均配置 Secret 且代码校验通过HTTPS 访问Webhook 入口只接受 HTTPS反向代理证书有效数据库备份PostgreSQL 定时备份已配置并完成一次恢复演练任务幂等同一 MR 重复事件不会产生重复评论评论权限Token 只能读写 MR/PR不能删除分支或修改仓库设置规则版本化审查规则文件纳入 Git 管理改动可追溯超时与重试模型调用、平台 API、Webhook 入口分别配置了合理超时日志采集日志能按 event_id 串联完整链路并进入统一日志平台回滚方案关闭 agent 回调或撤销 Webhook 后能立即恢复原有人工审查流程7.2 审查规则应该当成代码来管理自托管方案的价值很大程度体现在规则可定制上但定制能力也会带来混乱。团队如果通过网页临时改规则三个月后就没有人知道当前配置为什么存在。规则文件应采用“基础通用规则 按语言/模块拆分的扩展规则”结构# review-rules.yaml 示意 version: 1.0 rules: - id: NO_CREDENTIALS severtiy: error description: 禁止在代码中提交密钥、Token、连接串 patterns: - password\\s*\\s*[\][^\][\] - api_key\\s*\\s*[\][^\][\] - id: REQUIRED_DOCSTRING severity: suggestion description: 新增的函数应包含 docstring languages: - python - id: NO_NAKED_EXCEPT severity: error description: 禁止裸 except应捕获具体异常类型 languages: - python规则变更要走 MR 流程先提交规则变更再让规则本身接受一次小范围仓库的测试最后才推广到所有仓库。这样既能保证团队规范沉淀也能避免某人临时关闭所有错误级规则后无人知晓。7.3 安全与数据治理的底线自托管不等于自动安全。审查 agent 拿到的是代码平台的高权限 Token一旦被外部利用攻击者可以读取整个项目的源码并伪造机器人评论诱导开发者点击恶意链接。因此要按“高权限服务”的标准建设独立运行账号不能复用管理员个人账号的 Token。网络隔离agent 只能访问目标 Git 平台、数据库、Redis 和模型服务不允许直接访问公网包注册源。模型服务选择要考虑数据留存策略。如果代码保密级别高优先使用本地部署模型。评论内容要做基本校验防止模型输出被提示注入。攻击者可能在代码注释或 PR 描述中写入恶意指令诱导 agent 在评论中输出钓鱼链接或泄露上下文内容。提示注入是代码审查 agent 特有的安全风险。diff 本身是不可信输入不能把仓库内容当作普通文本直接塞进提示词。至少有两个防御手段在系统提示词中强调仓库内容是待审查数据而非指令对模型输出中的链接和可执行命令做白名单过滤。7.4 从“评论工具”走向“审查助手”代码审查 agent 的最终形态不是“每次 MR 输出几十条评论”而是逐步变成团队的审查助手。初期可以只做错误级问题的自动提示等高置信度结果稳定后再扩展到“自动补全测试用例”“自动生成变更摘要”“标记最需要人工关注的函数”等能力。从工程路线上看有几个值得关注的方向多轮对话式审查开发者可以对某条审查评论追问理由agent 结合上下文再解释。失败模式学习把人工标记为误报的评论收集起来沉淀成负样本规则持续降低噪音。跨 MR 状态跟踪同一文件在不同 MR 中反复出现同类问题说明是设计层面问题应该生成团队级的规范修订建议。与内部知识库对接让 agent 在审查时引用团队内部的设计文档和已知故障记录而不仅仅依赖代码上下文。这些方向都会把 agent 从“一次性命令工具”变成“持续参与研发流程的系统”。但要注意任何对规则和模型行为的修改都应遵循同样的验证流程在测试仓库验证、观察误报率、评审效果后再发布到全量仓库。代码审查 agent 是手段团队代码质量和开发体验才是最终目的。自托管给了团队更多控制权也不会自动降低代码问题数量真正决定上限的是团队如何把审查规则、模型能力和人工判断组织成一条顺畅的协作链路。