Skip to content

运行与日志接口 ​

项目与任务共用 Run 表与日志接口。触发入口分两个(/projects/{key}/run 与 /tasks/{key}/run),其余 runs 接口完全通用。运行生命周期背景见 核心概念。

触发项目运行 ​

POST /projects/{key}/run(owner/admin)。body 可省略:

json
{
  "branch": "main",
  "env": { "TAG": "v1.2.3" },
  "commandIds": [10, 11],
  "commandId": 10,
  "withDependencies": false
}
字段说明
branch分支/Tag,透传给 Git 准备阶段;缺省用项目 gitBranch
env触发参数覆盖,仅当项目 allowEnvOverride=true 时生效
commandIds只跑指定命令(数据库行 ID,见 项目与任务接口)
commandId单命令简写,非 0 时并入 commandIds
withDependenciestrue 时先按拓扑序构建依赖,默认 false

约束:项目已归档 → 40000;commandIds 与 withDependencies 同时使用 → 40000;依赖缺失/成环/归档 → 40000。

响应 data(HTTP 200,立即返回,不等待执行):

json
{
  "runId": 88, "buildNumber": 13, "status": "queued",
  "projectKey": "my-app",
  "pipelineId": "", "dependencies": [], "dependencyCount": 0,
  "logUrl": "/api/v1/runs/88/log"
}

带依赖触发时 pipelineId 为 pl_ 前缀串,dependencies 列出各依赖的 {key, runId, buildNumber},dependencyCount 为其数量。注意此响应不含 targetKind(任务触发响应才有)。

triggerType 由请求标识决定:User-Agent 以 deploy-cli 开头或带 X-Deploy-Client 头记为 cli,否则记为 web(用 API Token 的普通脚本也算 web)。

触发任务运行 ​

POST /tasks/{key}/run(owner/admin)。body 同上,但:

  • branch 无意义(任务没有 Git 准备阶段);
  • withDependencies=true 一律 40000(任务没有依赖);
  • commandIds/commandId 是步骤位置序号(1 起),引用不存在的步骤 → 40000;
  • 任务已归档 → 40000。
json
{
  "runId": 90, "buildNumber": 3, "status": "queued",
  "taskKey": "clean-cache", "targetKind": "task",
  "logUrl": "/api/v1/runs/90/log"
}

依赖流水线语义 ​

  • 一次带依赖触发产生多条 Run(每个依赖一条 + 目标一条),共享 pipelineId:目标 pipelineRole=main、pipelineOrder=0,依赖 pipelineRole=dependency、pipelineOrder 从 1 起。
  • 依赖用同一 branch,但不继承触发 env(那是目标项目的参数)。
  • 目标 Run 在依赖构建期间保持 queued,不占全局并发闸门。
  • 任一依赖非 success:后续依赖与目标都不执行,目标直接落终态(依赖被取消 → canceled,其余 → failed),errorMsg 写明原因并写一条日志。
  • 取消流水线中任意一条 Run 会连带取消同流水线里还在跑/排队的其它 Run。

Run 对象 ​

GET /runs/{id} 的 data(列表接口同构但不含 steps/pipeline):

字段组字段
标识id、projectId、projectKey、projectName、buildNumber(项目/任务内自增)
执行对象taskId、targetKind(project/task)、targetKey、targetName;projectKey/projectName 为兼容保留,任务运行时与 target* 相同
状态status、exitCode、errorMsg、startedAt、finishedAt、durationMs、logSize、createdAt
触发triggerType、triggerUserId、triggerUserName(hook 时为 hook:<令牌名>)、triggerIp、triggerUa、requestedRef、params
Git 准备prepareStatus、prepareDurationMs、gitCommit、gitCommitShort、gitBranchResolved、gitMessage、gitAuthor、gitCommitAt
流水线pipelineId、pipelineRole、pipelineOrder(非流水线 Run 为空);详情另含 pipeline 数组
步骤steps(仅详情)

status 七态:queued | running | success | failed | canceled | timeout | error。终态为后五者,自动化必须等终态再判定。

triggerType:web | cli | hook | rerun。契约还列了 api,但源码保留该常量却从不写入,实际不会出现。

prepareStatus:skipped | running | success | failed。

RunStep 对象(steps[]):

字段说明
id / runId步骤行 ID / 所属 Run
phaseprepare(Git 准备)/ command
commandId项目命令行 ID;任务步骤为位置序号
name / sortOrder / status名称 / 顺序 / 状态
script该步执行的脚本(契约未列,源码返回)
startedAt / finishedAt / durationMs / exitCode时间与结果
logOffsetStart / logOffsetEnd该步日志在文件中的字节区间

运行列表与详情 ​

GET /runs(登录),按 id 降序,查询参数:

参数说明
page / pageSize分页
projectKey按项目 key 精确过滤
taskKey按任务 key 过滤(契约未列,源码支持)
targetKindproject / task(历史空值算 project)
projectId / taskId按数字 ID 过滤
status按状态精确过滤

ownerOnly 模式下非 admin 只能看到自己项目/任务的运行。

GET /runs/{id}(可见):详情含 steps;若 pipelineId 非空,pipeline 数组列出同流水线全部 Run 摘要(runId/projectKey/projectName/buildNumber/status/pipelineRole/pipelineOrder/durationMs),依赖在前、目标排最后。

取消与重跑 ​

POST /runs/{id}/cancel(可见即可取消,幂等):已结束的运行直接返回当前状态。data:

json
{ "runId": 88, "status": "canceled", "canceled": true }

canceled 表示本次调用是否真的终止了进程/排队(已终态时为 false)。

POST /runs/{id}/rerun(owner/admin):用原 params 与 requestedRef 再跑一次,triggerType=rerun。原项目/任务已删除 → 40400;已归档 → 40000。响应 data:

json
{ "runId": 92, "buildNumber": 14, "status": "queued", "projectKey": "my-app" }

任务重跑返回 {runId, buildNumber, status, taskKey, targetKind:"task"}。注意:rerun 响应不含 logUrl/pipelineId(契约写「同 /run 响应」,源码更简),日志地址需自行拼 /api/v1/runs/<runId>/log。

HTTP 增量日志 ​

GET /runs/{id}/log?offset=0&limit=65536(可见):

参数默认说明
offset0起始字节偏移
limit65536单次上限 1048576(1 MiB);≤0 或超限回落 65536
json
{ "offset": 0, "nextOffset": 2048, "eof": false, "data": "=== Deploy Run #13 ===\n..." }

data 为原始日志字符串(保留 ANSI 转义),nextOffset 是下次拉取的起点,eof=true 表示已读到文件末尾(运行未结束时后续仍可能增长)。轮询跟随就是循环 offset=nextOffset 直到终态且 eof。

GET /runs/{id}/log/download(可见):text/plain 附件,文件名 <key>-<buildNumber>.log。日志文件已被清理时返回 40400(HTTP 200 信封)。

WebSocket 实时日志 ​

text
GET /api/v1/ws/runs/{id}?token=<jwt 或 dk_xxxxxxxx>&offset=<n>
  • 浏览器 WS 不能自定义 Header,token 走 query;JWT 与 API Token 均可。鉴权失败在升级前返回 HTTP 401 信封;run 不存在/不可见返回 40400 信封。
  • offset 缺省 0(负数按 0):连接后先把文件中该偏移之后的已有内容按 128 KiB 分块补发(history 帧),再持续推增量。
  • 服务端约每 700 ms 检查一次状态并发 Ping 心跳,防代理掐空闲连接。

帧结构(服务端 → 客户端,JSON 文本,核实自 handlers_ws.go):

json
{"type":"history","runId":88,"seq":1,"offset":0,"data":"已有日志","nextOffset":2048}
{"type":"log","runId":88,"seq":45,"offset":2048,"data":"新日志块","nextOffset":4096}
{"type":"status","runId":88,"status":"running","steps":[{"id":900,"runId":88,"phase":"command","commandId":10,"name":"构建","sortOrder":2,"status":"running","startedAt":"...","finishedAt":null,"durationMs":0,"exitCode":0,"logOffsetStart":2048,"logOffsetEnd":2048,"script":"make build"}]}
{"type":"truncated","runId":88,"nextOffset":4096,"status":"running","reason":"subscriber too slow"}
{"type":"exit","runId":88,"status":"success","exitCode":0,"durationMs":8123,"errorMsg":"","nextOffset":4096}
{"type":"error","runId":88,"message":"failed to read the log: ..."}

与契约示例的差异:status 帧带的是完整 steps 数组(RunStep 对象),不是单个 step:{name,sortOrder};history 帧也有 seq;exit 帧多 errorMsg 与 nextOffset。

客户端状态机(必须遵守,否则丢日志):

  • history/log:按帧内 offset 去重后落屏。去重用 offset 字节偏移,不要用 nextOffset - data.length 推算——JS string.length 是 UTF-16 码元数,日志含中文时推算会错。服务端保证每帧落在字符边界。
  • status:状态/步骤变化时推送(连接建立时必发一帧)。
  • truncated:本连接因读得太慢被服务端踢掉,运行未结束,带 nextOffset 立即重连补齐。
  • exit:运行已终态且日志已补完,收到即可收工。status 非终态的 exit 一律按 truncated 处理(兼容老服务端),绝不能就此停止。
  • 连接随时可能被关闭(慢订阅、写超时、代理超时):一律按最后收到的 nextOffset 重连。

断线续传示例(重连时带上次的 nextOffset):

text
wss://deploy.example.com/api/v1/ws/runs/88?token=dk_xxxxxxxx&offset=4096