主题
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 '{}'请求体字段
| 字段 | 类型 | 说明 |
|---|---|---|
branch | string | 覆盖 Git 分支(传递给依赖) |
env | map | 触发变量覆盖(需目标 allowEnvOverride) |
commandIds | int[] | 选择性执行:项目为命令 ID(先读 get),任务为步骤位置 |
withDependencies | bool | 先建依赖(任务传 true 报 400) |
async | bool? | 显式异步/同步;与 ?wait=true 等价语义 |
idempotencyKey | string | 幂等键(预留字段:当前版本解析但不去重) |
同步与异步
- 默认异步: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 静默失效。