主题
运行详情与日志终端
运行 ID 与构建号
每次执行(项目或任务)产生一条运行记录,有两个编号:
- 运行 ID:全局唯一的数据库 ID,出现在 URL
/runs/:id与 API 路径中; - 构建号(buildNumber):同一项目 / 任务内从 1 递增的序号,界面显示为
#12, 用于人读与沟通。列表与详情页点击构建号即进入对应运行详情。
运行状态共七种:queued 排队、running 运行中、success 成功、failed 失败、 canceled 已取消、timeout 超时、error 错误。后五种为终态。
运行列表(/runs)
项目与任务的运行混排在同一张表,「执行对象」列用标签区分并链接到对应详情页。
| 过滤项 | 说明 |
|---|---|
| 执行对象关键字 | 按项目 / 任务 Key 过滤 |
| 类型 | project 项目 / task 任务 |
| 状态 | 上述七种状态任选 |
表格列还包括构建号、触发方式(web / api / cli / hook / rerun)、触发人与来源 IP、 请求分支、耗时、退出码(0 绿非 0 红)、开始时间。默认每页 20 条,可调整。
运行详情页结构
- 概要:运行 ID、构建号、触发方式 / 触发人 / 来源 IP、请求分支、 Git 提交(短 sha @ 分支、完整 sha、提交说明、作者与时间)、准备阶段状态与耗时、 起止时间、总耗时、退出码、日志大小;Hook / API 触发时还展示触发参数。
- 依赖构建流水线(含依赖执行时):同一流水线内各项目的角色(依赖构建 / 目标项目)、 构建号、状态、耗时,可点击跳到任一成员的日志。
- 实时日志终端:见下节。
- 步骤表:阶段(准备 / 命令)、顺序、名称、状态、耗时、退出码、开始时间。
- 准备阶段失败时给出黄色警告:不会执行任何用户命令,请检查仓库地址 / 分支 / 凭据。
运行未结束时详情页每 5 秒轮询一次状态与步骤进度,结束后自动停止轮询。
xterm 日志终端
终端基于 xterm.js,只读(不接受键盘输入),保留 ANSI 颜色与进度条的 \r 覆盖语义, 回滚缓冲 20000 行,随窗口尺寸自适应。工具栏按钮:
| 按钮 | 作用 |
|---|---|
| 暂停滚动 / 恢复滚动 | 手动开关自动滚底 |
| 回到底部 | 立即滚底并恢复自动滚动 |
| 清屏 | 只清终端显示,不删服务端日志 |
| 重连 | 立即按当前偏移重连日志流(运行已结束也可用来补日志) |
| 重载日志 | 清空终端与去重状态,从偏移 0 重新拉取,终端空白 / 错乱时用 |
| 搜索 | 终端内关键字搜索,支持上一个 / 下一个 |
| 下载日志 | 下载完整日志文件 |
实时跟随与断线续传
- 运行进行中通过 WebSocket 跟随:
/api/v1/ws/runs/{id}?token=<JWT>&offset=<n>。 浏览器 WebSocket 不能自定义请求头,token 走 query 参数。 - 打开页面时先经 HTTP 分块拉取历史日志(每块 256 KiB,拉到 eof 为止), 再叠加 WebSocket 增量;两条路径按字节偏移去重,重叠内容不会重复刷屏, 中文日志也不会因字符 / 字节差异而缺行。
- 断线后按已收到的 nextOffset 指数退避重连(1s 起、封顶 10s),补齐缺失日志; 服务端因订阅者读得慢而主动截断(truncated)时,以 250ms 起的短延迟快速续传。
- 只有收到终态 exit 帧才算收工;运行刚结束时会继续把日志尾巴补完, 最多补收 6 次,避免日志被清理后无限重连。
- 终端上方有连接状态徽标:连接中 / 已连接 / 重连中 / 已结束。
协议与服务器端实现见日志与实时跟随。
自动滚底
默认新日志自动滚到底部。手动向上滚动即自动暂停(显示「自动滚动已暂停」), 滚回底部自动恢复;也可用工具栏按钮显式切换。翻阅历史输出时不会被新日志打断。
取消运行
运行未结束时,页面右上角显示红色「取消运行」按钮:
- 点击后二次确认,提示「会终止整个进程树」。
- 确认后发送取消请求,运行状态变为 canceled,终端收到终态帧后收尾。
取消是请求式的:脚本若捕获了信号,退出可能略有延迟。
重新执行与下载日志
- 重新执行:运行结束后原取消按钮位置变为「重新执行」,按原参数再触发一次, 生成新构建号并跳转到新运行详情(终端随运行 ID 重建,不会串日志)。
- 下载日志:随时可用,浏览器保存为
run-<key>-<构建号>.log; HTTP 历史接口不可用时页面也会提示改用下载获取完整日志。