首页 / 多租户与 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 来源)
- GitHub → Settings → Developer settings → GitHub Apps → New GitHub App;
- 权限按能力分档:审查只读档 Metadata、Contents、Pull requests、Checks、Statuses、 Administration:read;仅当启用应用修复与合并时另勾 Contents:read+write (机器人推送修复提交)与 Pull requests:read+write(合并)。缺权限时对应能力在界面报告 unsupported,不影响审查;系统不用个人 PAT 绕过, Administration:write / Members / Actions 一律不申请;
- 订阅事件五种:
installation、installation_repositories、pull_request、check_run、status; - Webhook URL:
https://你的域名/api/mu/github/webhook; secret 填MU_GITHUB_WEBHOOK_SECRET的同值; - 把 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(可选)
- OAuth 登录:在 Gitee 第三方应用创建应用,回调填
https://你的域名/api/mu/auth/oauth/gitee/callback,将 Client ID / Secret / Callback URL 填入MU_GITEE_OAUTH_*(三项任一缺失时登录页不渲染 Gitee 入口),并配置MU_GITEE_PAT用于仓库连接与受控写入。 - 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白名单中补充该路径。 - 能力边界: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 账号/组织安装, 同名仓库天然按租户隔离。
邀请与认领
- 管理员按目标用户的 GitHub 数字 user id 创建邀请
(
POST /api/mu/invitations,role + TTL); - 目标用户走 GitHub OAuth 登录,系统按 subject 自动认领唯一待认领邀请;
- 同一 subject 多条待认领邀请时会显式拒绝(
invitation_ambiguous), 不会静默选择; platform_admin不可经邀请授予——API 403、claim 拒绝、DB 约束三层拦截。
撤权语义
管理员撤销成员后,该用户所有会话下一请求立即 403 (逐请求活成员校验);其租户内数据保留不动。
事件→审查管线
PR 事件 → webhook(HMAC 验签+投递去重) → 事件入队 → 自动 consumer
→ 审查流水线 → 结论与证据落租户 → 维护者逐次确认远端写(评论/应用/合并)
投递去重:同一 delivery 重复投递返回 duplicate,不重复处理;
远端写共三类(发布评论、机器人提交修复、合并 PR),均需维护者逐次「预览 → 确认」,
写入身份固定为机器人;CI 状态只读读取、作为合并资格输入;结论与审计落在你的 Console。