Webhook 触发的即时同步(替代轮询)

[yangflow]

问题

当前按 frequency(manual / 每 N 分钟 / 每天)轮询源仓库,无论源是否有新提交。对活跃仓库,用户希望"push 后几秒内就镜像完成"; 对不活跃仓库,定时 polling 又浪费 API 配额和电力。Webhook 推送模型是正解,但 Mac 客户端做 webhook 接收需要暴露本地端口。

建议改动

• 内嵌轻量 HTTP listener(127.0.0.1:随机端口),接收 POST /hook/<repo-id> 请求
• 支持两种外网暴露模式:
  • Cloudflare Tunnel / Tailscale Funnel:用户已有这些服务时零摩擦,app 只需生成 webhook URL 模板
  • 轮询+长连接回落:Cloudflare Worker / GitHub App 中继到本机,延迟秒级
• Provider 端:自动调 API 给仓库注册 webhook(需要额外 scope,UI 要明示)
• 校验 payload 的 HMAC 签名,防止任意人触发
• 收到 push 事件后立刻执行该仓库的同步,独立于 frequency 调度

备选方案

• 只做手动同步:保持现状,失去"实时镜像"叙事
• 轮询间隔降到 1 分钟:API 配额容易撞墙,且电池友好度差

作用域检查

• 与 GitRelay 的单向镜像模型兼容
• 不需要在 Keychain 以外存储凭证(HMAC secret 可进 Keychain)
• 若启用 Cloudflare/Tailscale 模式,运行时需要这些外部服务; 默认关闭,开启由用户主动承担