快速开始
本页面向部署者。需要 Docker 与 Docker Compose v2、Git、Node.js ≥ 20(运行预检脚本), 以及 GitHub App、OAuth App 和对应配置。耗时取决于凭据与网络入口准备情况。 已有实例的受邀成员请读首次使用。
以下步骤固定到当前推荐自托管版本 rc.35.6-rc8.5(事件投递+入口预检版)
(源码 3879e390;镜像 OCI index
sha256:f8bc369f5b046536103d75ba53c4863871abb3ecddbdfe920baf29c6428afe9a),
完整校验与供应链档案见
下载与校验与
该版 Release。
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. 首任管理员登录,再邀请成员
- 管理员登录:用第 2 步
MU_BOOTSTRAP_ADMIN_SUBJECT绑定的同一 GitHub 账号访问http://127.0.0.1:48500/login完成 OAuth;登录后右上角显示你的账号且角色为「平台管理员」。生产保持MU_ALLOW_FIXTURE_LOGIN=0(默认关闭);邀请永不授予platform_admin。 - 邀请业务成员:在「组织与成员权限」按平台数字 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。
下一步:Docker 自托管细节 · 仓库内完整部署指南。