主题
运行与日志
run / logs / runs / stop 四个命令对项目与任务通用(任务触发用 task run,见 任务命令)。日志的服务端存储与实时推送机制见 日志与实时跟随。
run:触发项目运行
bash
deploy run my-app # 触发并立刻返回 runId
deploy run my-app -f # 先补历史日志,再实时跟随到结束
deploy run my-app --wait # 不打印日志,只等结果
deploy run my-app -f -e TAG=v1.2.3 --branch main
deploy run my-app --command-id 10 --command-id 11 # 只跑指定命令
deploy run my-app -f --cancel-on-interrupt # Ctrl+C 时取消运行
deploy run my-app --with-dependencies --wait --json # 先构建依赖项目| flag | 说明 |
|---|---|
-f, --follow | 先回放历史日志,再经 WebSocket 实时跟随到运行结束 |
--wait | 不打印日志,轮询等待终态后返回 |
-e K=V | 触发时覆盖环境变量(可重复;项目需允许 env override) |
--branch REF | 本次运行使用的分支/ref(写入 requestedRef) |
--command-id ID | 只跑指定命令 ID(可重复;ID 来自 project get,update 后会变) |
--cancel-on-interrupt | Ctrl+C 时调取消接口并等终态(默认只断开跟随) |
--with-dependencies | 先按依赖顺序构建前置项目,再跑目标项目 |
不带 -f 也不带 --wait 时立刻返回,--json 输出 {runId, projectKey, buildNumber, status, logUrl, statusUrl}。进入队列不代表部署成功,自动化流程应使用 -f 或 --wait 等待最终结果。
运行 ID 与构建号
收尾摘要里有两个数字,不要混淆:
text
== my-app 构建开始 ==
npm ci
npm run build
构建成功
运行 ID #88(构建号 #13) success 退出码 0 耗时 8.1s → CLI 退出码 0
运行 ID #87(构建号 #7) failed 退出码 1 耗时 2.3s → CLI 退出码 1- 运行 ID(
#88)是全局运行 ID:deploy logs/deploy stop/runs list都用它。 - 构建号(
#13)是项目内第几次部署,即服务端日志头部=== Deploy Run #13 ===里的那个数字。
摘要会同时标出两者;拿不到构建号时退化为只显示 运行 ID #88。摘要里的「退出码」是脚本自身的退出码,箭头后的才是 CLI 进程的退出码。
logs:查看与跟随日志
bash
deploy logs 88 # 一次性拉全部历史日志(回放完即返回 0)
deploy logs 88 -f # 实时跟随(断线自动重连 + 按 offset 续拉)
deploy logs 88 --offset 4096 # 从指定字节偏移开始| flag | 说明 |
|---|---|
-f, --follow | 回放历史后实时跟随到运行结束,给出终态摘要 |
--offset N | 起始字节偏移(默认 0,从头开始;不能为负) |
不带 -f 只回放历史日志并返回 0(即使运行失败);带 -f 会给出终态摘要,运行失败时返回 1。
JSONL 跟随
--json 跟随时 stdout 每行一个 JSON,可逐行解析:日志事件若干行 + 最后一行结果对象:
json
{"data":"构建开始\n","type":"log"}
{"data":"构建成功\n","type":"log"}
{"buildNumber":13,"durationMs":8123,"exitCode":0,"runId":88,"status":"success"}Ctrl+C 语义
run -f / logs -f 下按 Ctrl+C 默认只断开日志跟随,不取消运行(退出码 0),stderr 会提示可用 deploy logs <runId> -f 再次跟随。只有 deploy run --cancel-on-interrupt 才会先调 POST /runs/{id}/cancel,等终态后按状态返回。--wait 下 Ctrl+C 同样只停止等待(退出码 0),运行继续。中间件操作的跟随也固定为「只断开不取消」。
断线重连
跟随日志时若 HTTP/WebSocket 断开,会退避重连(0.5s 起、5s 封顶,不设次数上限,直到运行结束或 Ctrl+C)。每次重连前先用 GET /runs/{id}/log?offset=<nextOffset> 补齐历史;服务端重发更早内容时按 offset 裁掉重复前缀——不丢日志、不重复刷屏。鉴权失败(401)不会盲目重试。
runs list:运行历史
bash
deploy runs list
deploy runs list --project my-app --status failed --page 2| flag | 默认 | 说明 |
|---|---|---|
--project KEY | 空 | 按项目 key 过滤 |
--status S | 空 | queued/running/success/failed/canceled/timeout/error |
--page N | 1 | 页码 |
--page-size N | 20 | 每页条数(最大 200) |
表格列出 RUN(全局运行 ID)/ project / build(构建号)/ 状态 / 触发方式 / 触发人 / 开始时间 / 耗时 / 脚本退出码。项目与任务共用 Run 表,不带过滤时两类运行都会列出;CLI 目前没有按任务过滤的 flag(服务端 API 支持 taskKey,见 认证与通用约定 所在的 API 章)。
stop:取消运行
bash
deploy stop 88 # 幂等取消;cancel 是别名调 POST /runs/{id}/cancel。接口幂等:运行已结束或已取消时也返回成功。取消后的终态是 canceled,跟随中的 CLI 会以退出码 1 收尾。