首页 / 快速开始

快速开始

本页面向部署者。需要 Docker 与 Docker Compose v2、Git、Node.js ≥ 20(运行预检脚本), 以及 GitHub App、OAuth App 和对应配置。耗时取决于凭据与网络入口准备情况。 已有实例的受邀成员请读首次使用。

以下步骤固定到当前推荐自托管版本 rc.35.6-rc8.5(事件投递+入口预检版) (源码 3879e390;镜像 OCI index sha256:f8bc369f5b046536103d75ba53c4863871abb3ecddbdfe920baf29c6428afe9a), 完整校验与供应链档案见 下载与校验与 该版 Release。

先读·这是什么形态:MergePilot 是用户自托管产品—— Console、数据库、OAuth 配置与业务数据全部运行在部署者自己的环境中。 本机/内网部署适合本地评估与受限使用;GitHub OAuth 回调(本机评估除外)、自动 Webhook、 跨机器邀请认领需要部署者自己的公网 HTTPS Console 地址或其他可被 GitHub 与受邀用户访问的安全入口。GHCR 镜像为 Public 仅表示可匿名拉取镜像,不表示提供托管 Console 或公网入口。详见 多租户与 webhook。
觉得安装手续太多? 本页步骤本身已按「可逐条执行+可校验」书写——你可以直接把下面第 5 节的 AI 指令卡整段复制给任意 AI 编码助手(Claude Code / Codex / Cursor 等),由它带你 执行:每一步都有明确成功判据,失败时把报错贴回给它即可。同版指令卡也在仓库 INSTALL-WITH-AI.md。

1. 获取源码与模板

git clone https://github.com/nghqqa/MergePilot.git
cd MergePilot && git checkout v0.2.0-beta.6-rc.35.6-rc8.5
cd deploy/selfhost
cp .env.example .env && chmod 600 .env

2. 填写配置

最小必填集(先跑起来看面板;审查接入可后补): POSTGRES_PASSWORD(openssl rand -hex 16)、 CONSOLE_SESSION_SECRET(openssl rand -base64 32)、 MU_BOOTSTRAP_ADMIN_SUBJECT=github-oauth:<你的GitHub数字id>—— 必须带 github-oauth: 前缀,数字 id 见 https://api.github.com/users/<你的用户名> 的 id 字段。 这是初始管理员(platform_admin)的登录身份绑定;首次启动自动完成建库建表与 bootstrap(幂等),无需手工 SQL。

审查接入(可后补):GitHub App 四项、OAuth App 两项、LLM 四项 (openai 兼容端点),创建步骤见 多租户与 webhook;Gitee 全段可选。 完整键说明见 配置参考与仓库内 deploy/selfhost/.env.example 注释。

可选组件:bge-m3(RAG 知识库检索)不放入模型文件会健康检查失败——不用 RAG 就 docker compose stop bge-m3,不影响审查主功能。

3. 一键检查后启动

node preflight.mjs                    # 只读检查,关键项失败即退出(无 Node 可跳过)
docker compose --env-file .env up -d
node preflight.mjs --live             # 启动后活体探测
curl http://127.0.0.1:48500/api/health

健康门判据:ok: true、data_mode: live、 mu_schema_ready: true、 version: v0.2.0-beta.6-rc.35.6-rc8.5——四项齐了才算装好。 (可选)镜像一致性核对:docker buildx imagetools inspect ghcr.io/nghqqa/mergepilot-console:v0.2.0-beta.6-rc.35.6-rc8.5 的 Digest 行 应等于上方 index digest。

4. 首任管理员登录,再邀请成员

  1. 管理员登录:用第 2 步 MU_BOOTSTRAP_ADMIN_SUBJECT 绑定的同一 GitHub 账号访问 http://127.0.0.1:48500/login 完成 OAuth;登录后右上角显示你的账号且角色为「平台管理员」。生产保持 MU_ALLOW_FIXTURE_LOGIN=0(默认关闭);邀请永不授予 platform_admin。
  2. 邀请业务成员:在「组织与成员权限」按平台数字 user id 创建邀请 (GitHub 或 Gitee);受邀者用对应 OAuth 账号登录认领。审批、应用修复与合并需 maintainer,platform_admin 无这些权限,见 角色矩阵(五角色边界已在真实浏览器逐角色验收)。

本机登录入口为 http://127.0.0.1:48500/login;受邀成员的日常操作见 首次使用。健康检查成功只说明容器就绪,还需验证仓库绑定、webhook 与审查链路。

5. 安装手续太多?把这段复制给 AI 助手

下卡为同一安装流程的「AI 可执行版」:包含全部命令、每步成功判据与硬性边界。 整段复制给你的 AI 编码助手即可;它失败时会向你要报错输出。

点开复制:MergePilot 自托管 AI 安装指令卡(rc.35.6-rc8.5)
你是用户的部署助手。请带用户完成 MergePilot(自托管多用户 PR 审查工作台)的安装。
严格按步骤执行;每步完成后向用户索取校验输出,确认通过再进入下一步;任何一步失败就停下,
让用户把完整错误输出贴回给你分析,不要猜测性修复。

环境前提:Linux amd64 或 Windows/macOS + Docker Desktop;Docker Engine ≥ 24 且有 docker compose v2;
可选 Node.js ≥ 20(仅预检脚本需要,没有可跳过预检但不得跳过健康门)。默认只监听 127.0.0.1,本机评估无需公网。

第 0 步(唯一需要用户人工做的准备):
1. GitHub 数字 id:访问 https://api.github.com/users/<GitHub用户名>,记下 id 字段(纯数字)——初始管理员登录身份绑定用;
2. 两把随机值:openssl rand -hex 16(数据库口令)、openssl rand -base64 32(会话密钥);
3. 可后补:LLM API key(openai 兼容)、GitHub App/OAuth App、Gitee PAT——没有也能先装起来看面板。

第 1 步 取模板:
  git clone https://github.com/nghqqa/MergePilot.git
  cd MergePilot && git checkout v0.2.0-beta.6-rc.35.6-rc8.5
  cd deploy/selfhost
  cp .env.example .env && chmod 600 .env
判据:checkout 指向 tag v0.2.0-beta.6-rc.35.6-rc8.5;.env 存在。

第 2 步 填最小必填集(审查接入可后补):编辑 .env 至少设置——
  POSTGRES_PASSWORD=<第0步口令>
  CONSOLE_SESSION_SECRET=<第0步密钥>
  MU_BOOTSTRAP_ADMIN_SUBJECT=github-oauth:<第0步数字id>
  (必须带 github-oauth: 前缀——这是初始管理员的身份绑定,不带前缀生产模式无法登录)
可选:bge-m3(RAG 检索)不放模型文件会健康检查失败——不用 RAG 就 docker compose stop bge-m3,不影响审查主功能。

第 3 步 启动与健康门(硬性判据):
  node preflight.mjs                        (无 Node 可跳过)
  docker compose --env-file .env up -d
  docker compose ps                         (console 与 postgres 应 running/healthy)
  curl -s http://127.0.0.1:48500/api/health
判据(全部满足才算过):"ok": true、"data_mode": "live"、"mu_schema_ready": true、
"version": "v0.2.0-beta.6-rc.35.6-rc8.5"。首次启动自动建库建表,无需手工 SQL。
(可选)镜像一致性:docker buildx imagetools inspect ghcr.io/nghqqa/mergepilot-console:v0.2.0-beta.6-rc.35.6-rc8.5
的 Digest 行应等于 sha256:f8bc369f5b046536103d75ba53c4863871abb3ecddbdfe920baf29c6428afe9a。

第 4 步 首次登录(用户本人操作,AI 不得代输凭据):
浏览器打开 http://127.0.0.1:48500/login → 「使用 GitHub 登录」→ 必须用第 2 步绑定的同一 GitHub 账号。
判据:登录后页面右上角显示该账号且角色为「平台管理员」。被拒或角色不符→把页面提示贴回分析。

第 5 步(可后补)接入审查能力:按 .env 注释段填 MU_LLM_* 与 GitHub App/OAuth App
(App 创建见仓库 deploy/selfhost/README.md「多租户与 webhook」节),改后 docker compose --env-file .env up -d。

硬性边界(任何情况下都不要做):
1. 不要把 48500 直接暴露公网;对外必须前置 TLS 反代并改回调为 https 域名;
2. 不要把 .env 内容发到对话之外或提交进 git;
3. 不要跳过健康门,健康门通过前不做任何业务操作;
4. 升级前先 pg_dump 备份;镜像升级=改 compose 里的 digest 引用(不用浮动 tag)。

失败处置:停下→要完整输出/容器日志(docker compose logs console --tail 50)→按输出定位;
常见:端口被占(改 .env 端口段)、postgres 未就绪即访问(等 healthcheck)、忘记 MU_BOOTSTRAP_ADMIN_SUBJECT 前缀。

同版卡片(便于复制为文件): INSTALL-WITH-AI.md。

生产对外暴露:必须前置 TLS 反向代理并把回调地址改为 https 域名。 生产 Webhook 地址必须公网 HTTPS 可达(转发到本机 48590,入口实现不限—— 见 多租户与 webhook)。 明文 HTTP 不允许承载已认证会话(会话 Cookie 自带 Secure 属性)。详见 安全加固。升级与回滚(pg_dump + digest 换版)见 升级与回滚。

下一步:Docker 自托管细节 · 仓库内完整部署指南。