PR-Agent 私有部署：GitHub、GitLab 排错

执行 docker compose up -d 后服务仍打不开，先别急着改模型配置。最有效的检查顺序是：

docker compose config
docker compose ps
docker compose logs --tail=200 <service>
curl -v http://127.0.0.1:<mapped-port>/

先确认 Compose 最终解析出的配置，再确认容器是否仍在运行，然后读取启动日志，最后从宿主机访问映射端口。docker compose config 能解析但本机不通，问题多在端口或反向代理；本机正常而 GitHub、GitLab 没有回调，才继续查公网入口、证书和平台鉴权。下文以热点来源中的开源 PR-Agent 官方仓库为准。

容器与端口

PR-Agent 私有化部署最容易踩的坑，是把 YAML 解析失败、容器退出和端口不可达都叫作“服务启动失败”。这三层应该分开查。

先选定一个 release tag，并从同一版本取得 Compose 示例、配置文件和镜像。不要让 Compose 文件来自一个版本、配置说明来自另一个版本，更不要长期使用 latest。镜像名、服务名、端口和配置键都应以所选 release 的官方文件为准。Compose 适合这类交付，是因为服务、网络、依赖和数据卷都能写进同一份声明式配置，也方便按版本回滚。

拿到对应版本后，可以先执行：

docker compose config
docker compose pull
docker compose up -d
docker compose ps -a
docker compose logs --tail=200 <service>

docker compose config 主要检查 YAML 语法、变量插值、挂载路径和端口映射。如果环境变量没有加载，这里通常能看到变量为空或使用了意外默认值；如果 Compose 使用 .env，还要确认当前执行目录和文件名称符合该 release 的说明。这个命令可能直接显示令牌、私钥和模型密钥，不能把未经脱敏的结果贴到工单、聊天群或公开日志里。

容器持续退出时，日志比状态列表更重要。常见方向包括启动命令不适用于当前镜像、配置文件格式错误、GitHub 私钥在环境变量插值后换行被破坏、挂载目录权限不足，以及配置键与当前 release 不匹配。不同版本的配置解析器行为可能不同，不能只凭某个固定报错文本套答案。

容器显示运行但宿主机访问失败，则检查 Compose 是否真正映射端口，以及进程是否只在容器内部地址监听：

docker compose port <service> <container-port>
curl -v http://127.0.0.1:<mapped-port>/

这里不要求根路径一定返回业务数据；根路径可能是 404，但能收到 HTTP 响应仍说明端口链路已经建立。若映射正确而反向代理仍报 502，应核对代理的 upstream 是否指向正确的宿主机端口。如果反向代理本身也在容器网络中，upstream 通常要使用对应 Compose 服务名或容器地址，不能照搬 127.0.0.1。

本机访问正常、GitHub 或 GitLab 回调失败时，排查重点才转到公网入口：域名解析是否指向当前机器、防火墙和安全组是否放行、反向代理是否转发当前 release 要求的回调路径、HTTPS 证书是否完整，以及平台服务器能否建立 TLS 连接。平台配置的回调地址不能使用 127.0.0.1 或仅限内网访问的地址。

GitHub/GitLab 接入

PR-Agent GitHub 接入和 GitLab 接入的触发链路并不相同，先确定自己使用的是哪一种模式：

具体权限、配置键和回调路径需要按所选 release 核对。

GitHub App/Webhook 模式下，先确认 App 确实安装到了目标仓库或组织，当前版本需要的权限已经开启，私钥没有被 YAML 转义或换行处理破坏，Webhook Secret 与 PR-Agent 两侧完全一致。随后打开 GitHub 的事件投递记录：如果没有投递记录，先查 DNS、TLS、防火墙和回调路径；如果有记录但 PR-Agent 日志没有对应请求，检查反向代理是否吞掉请求或转到了错误上游；如果日志显示鉴权失败，再回到 App 安装范围、凭据和 Secret。

GitHub Action 模式不需要套用公网 Webhook 的排查路径。任务在哪里执行，就在对应的 Actions 运行日志里检查凭据、配置和模型调用；workflow 中配置的 Secret 名称也要与 Action 读取的配置一致。PAT、SSH 密钥和 App 凭据解决的是不同认证环节，不能互相替代。

GitLab 需要区分 GitLab.com 和自建实例。自建 GitLab 要核对 API 服务地址、项目路径、PAT、Webhook Secret 和目标项目；PAT 用于后续读取或发布 PR 信息，Webhook Secret 用于验证回调，两者不是同一个凭据。GitLab Webhook 由 GitLab 服务器主动发出，因此测试地址必须从 GitLab 所在网络访问，而不是只在运维电脑的浏览器里打开。

自建 GitLab 的外部 URL、域名解析和用户实际访问地址不一致时，也会影响 Webhook 等回调功能。排查时可用平台提供的 Webhook 测试功能，再对照 PR-Agent 日志。即使响应中出现 401、403 或 404，也不要只凭状态码判断是 Token、权限、路径还是对象不可见，必须结合响应正文和对应阶段日志。

最后检查是否同时启用了 GitHub App、Webhook 和 Action。这三条入口都能触发任务时，同一个 PR 出现多条重复评论并不代表模型异常。

评论与模型调用

有回调却没有 PR 评论，可以沿五段链路定位：

1. 先确认事件是否到达。GitHub 看 App 投递记录，GitLab 看 Webhook 测试或投递记录，同时在 PR-Agent 容器日志中确认是否出现对应事件。没有投递记录时，先修网络、证书和路径。

2. 再确认平台身份是否通过。核对凭据类型、安装或项目范围、所需权限以及 Secret 是否一致。凭据缺失或轮换后未同步，比模型故障更常见，应先处理这一层。

3. 确认 PR 信息是否可读取。确认仓库、项目、目标分支和 PR 编号在当前身份可见范围内。私有仓库中，Webhook 能送达不代表当前凭据一定能读取目标 PR。

4. 确认模型是否可用。按当前 release 核对模型密钥、Base URL、模型名称和连接方式。使用本地模型时，要从容器内部验证网络：同一 Compose 网络中的服务通常通过服务名访问，容器里的 127.0.0.1 指向容器自身，并不是宿主机或宿主机上的模型服务。

5. 确认评论是否成功发布。区分模型没有返回有效内容、平台拒绝写入，以及多个触发入口造成重复发布。只有模型调用成功且平台 API 返回成功，才算完整走通。

代理环境也要一起核对。容器是否继承 HTTP_PROXY、HTTPS_PROXY、NO_PROXY，内部模型地址是否被错误代理，以及 HTTPS 拦截环境使用的 CA 证书是否已装入容器并受信任，都可能造成“平台回调成功、模型调用失败”。不要为了绕过证书错误直接关闭 TLS 校验。

生产环境还应固定 release，升级前备份实际挂载的配置、缓存和日志目录，修改密钥后按变更范围重建或重启服务。PR-Agent 私有化部署的难点，是把容器、平台身份、回调链路和模型配置四层逐层对齐；仅确认容器启动并不够。本文讨论的是热点来源中的开源 PR Reviewer 项目 The-PR-Agent/pr-agent，不是 Qodo 免费层。