首页 / 多租户与 webhook

多租户与 webhook

公网入口要求:自动 Webhook 必须有公网可达的 HTTPS 入口,由部署者自己的反向代理或隧道 (Nginx、Caddy、Cloudflare Tunnel 等均可,仓库不绑定特定实现)转发至本机回环端口: GitHub Webhook 指向 127.0.0.1:48590(webhook-ingress),Console/OAuth(及 Gitee Webhook)指向 127.0.0.1:48500。完整 Nginx / Caddy / Cloudflare Tunnel 模板与两种暴露拓扑见 安全加固清单。没有任何公网入口时,webhook 无法自动进入审查管线(本机管理与健康检查不受影响)。

GitHub App(webhook 来源)

  1. GitHub → Settings → Developer settings → GitHub Apps → New GitHub App;
  2. 权限按能力分档:审查只读档 Metadata、Contents、Pull requests、Checks、Statuses、 Administration:read;仅当启用应用修复与合并时另勾 Contents:read+write (机器人推送修复提交)与 Pull requests:read+write(合并)。缺权限时对应能力在界面报告 unsupported,不影响审查;系统不用个人 PAT 绕过, Administration:write / Members / Actions 一律不申请;
  3. 订阅事件五种:installation、installation_repositories、 pull_request、check_run、status;
  4. Webhook URL:https://你的域名/api/mu/github/webhook; secret 填 MU_GITHUB_WEBHOOK_SECRET 的同值;
  5. 把 App ID 与私钥填入 .env 的 MU_GITHUB_APP_ID / MU_GITHUB_APP_PRIVATE_KEY。

OAuth App(用户登录)

另建一个 OAuth App(Settings → Developer settings → OAuth Apps), callback 填 https://你的域名/api/mu/auth/oauth/github/callback, 凭据填 MU_GITHUB_OAUTH_CLIENT_ID/SECRET。

Gitee OAuth 与 Webhook(可选)

  1. OAuth 登录:在 Gitee 第三方应用创建应用,回调填 https://你的域名/api/mu/auth/oauth/gitee/callback,将 Client ID / Secret / Callback URL 填入 MU_GITEE_OAUTH_*(三项任一缺失时登录页不渲染 Gitee 入口),并配置 MU_GITEE_PAT 用于仓库连接与受控写入。
  2. Webhook 路由注意(避坑):仓库默认自托管模板中的 deploy/selfhost/webhook-proxy.js(监听 48590)仅放行 POST /api/mu/github/webhook 与 GET /api/health。 若将 Gitee Webhook(POST /api/mu/gitee/webhook)直接指向 48590 会返回 404 path_not_exposed—— 请在 Nginx / Caddy 中将 /api/mu/gitee/webhook 精确路由至 127.0.0.1:48500(示例见 安全加固清单),或按需在 webhook-proxy.js 白名单中补充该路径。
  3. 能力边界:Gitee 当前连接器不支持读取 CI 状态,因此 Gitee 仓库的合并会被资格门阻塞(审查、评论、应用修复正常可用)。

公网入口端到端验证

配好反代或 Cloudflare Tunnel 并启动容器后,按以下两步核验公网连通性:

# 1. 验证 HTTPS 入口与健康门(应返回 ok: true 且 version 为当前部署版本)
curl -fsS https://你的域名/api/health

# 2. 验证最小暴露面(若采用仅暴露 48590 的拓扑,访问未放行路径应返回 404 path_not_exposed)
curl -i https://你的域名/multiuser

随后在 GitHub App 设置页 → Advanced → Recent Deliveries 中点击任意一条投递执行 Redeliver, 确认响应状态码为 2xx,并在 Console 对应租户的 PR 列表看到审查记录入队。

installation → 租户注册

用户安装 App 后跳转回控制台,系统把该 installation 注册到当前会话所属租户。 事件租户随 installation 走:不同租户应使用不同 GitHub 账号/组织安装, 同名仓库天然按租户隔离。

邀请与认领

  1. 管理员按目标用户的 GitHub 数字 user id 创建邀请 (POST /api/mu/invitations,role + TTL);
  2. 目标用户走 GitHub OAuth 登录,系统按 subject 自动认领唯一待认领邀请;
  3. 同一 subject 多条待认领邀请时会显式拒绝(invitation_ambiguous), 不会静默选择;
  4. platform_admin 不可经邀请授予——API 403、claim 拒绝、DB 约束三层拦截。

撤权语义

管理员撤销成员后,该用户所有会话下一请求立即 403 (逐请求活成员校验);其租户内数据保留不动。

事件→审查管线

PR 事件 → webhook(HMAC 验签+投递去重) → 事件入队 → 自动 consumer
→ 审查流水线 → 结论与证据落租户 → 维护者逐次确认远端写(评论/应用/合并)

投递去重:同一 delivery 重复投递返回 duplicate,不重复处理; 远端写共三类(发布评论、机器人提交修复、合并 PR),均需维护者逐次「预览 → 确认」, 写入身份固定为机器人;CI 状态只读读取、作为合并资格输入;结论与审计落在你的 Console。