Skip to content

HTTP Hook 触发 ​

Hook 让外部系统(Git 托管方 webhook、监控告警、上游 CI、AI Agent)免登录触发运行。 项目与任务共用同一套 Hook 机制;目标需开启 hookEnabled。

令牌管理 ​

在网页项目/任务详情页创建 Hook Token(hk_ 前缀):

  • 服务端只存哈希,明文仅创建时展示一次——当场保存,丢失只能重置。
  • 创建时可设有效期(expiresInDays);管理操作为重置与删除(无独立禁用/改期接口)。
  • 每令牌独立限流;令牌与目标绑定:一个令牌只触发它所属的项目/任务。

两种调用形式 ​

推荐请求头形式(令牌不进 URL 访问日志):

bash
curl -X POST 'https://deploy.example.com/api/v1/hooks' \
  -H 'X-Deploy-Token: hk_xxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"branch":"main","withDependencies":true}'

路径形式(便于只支持 URL 配置的 webhook 发送方):

bash
curl -X POST 'https://deploy.example.com/api/v1/hooks/hk_xxxxxxxx' \
  -H 'Content-Type: application/json' -d '{}'

请求体字段 ​

字段类型说明
branchstring覆盖 Git 分支(传递给依赖)
envmap触发变量覆盖(需目标 allowEnvOverride)
commandIdsint[]选择性执行:项目为命令 ID(先读 get),任务为步骤位置
withDependenciesbool先建依赖(任务传 true 报 400)
asyncbool?显式异步/同步;与 ?wait=true 等价语义
idempotencyKeystring幂等键(预留字段:当前版本解析但不去重)

同步与异步 ​

  • 默认异步:HTTP 202 + {runId,buildNumber,status,...},运行在服务端继续。
  • ?wait=true 或 "async": false:同步等待终态,上限 30 分钟;超时返回当前状态而非失败终态,调用方需继续查询。
  • 无论同步异步,HTTP 200/202 仍要检查 success 与运行终态:业务错误也可能 200。

限流与幂等 ​

  • 每令牌默认 60 次/分钟(hookRateLimitPerMinute 全局可调);超限 429(CLI 退出码 4)。
  • idempotencyKey 为预留字段:当前服务端解析但不做去重,webhook 重投仍会新建运行;调用方需自行去重,或配合 cancelPrev/队列策略控制堆积。
  • Git 托管方 push 事件高频时,配合 cancelPrev 或队列策略避免堆积。

安全清单 ​

  • 令牌按 secret 管理:不进 Git、不进前端代码、URL 形式注意访问日志脱敏。
  • 公网实例必须 HTTPS;Hook 端点免登录,令牌即全部凭据。
  • 给外部系统最小权限:只发它该触发的目标令牌;离职/泄露即删除或重置。
  • 监控 429 与失败终态告警,避免 webhook 静默失效。

延伸阅读 ​