Skip to content

日志与实时跟随 ​

落盘布局 ​

text
<dataDir>/logs/
  <projectKey>/<runId>.log      # 项目运行
  tasks/<taskKey>/<runId>.log   # 任务运行

日志头部含 === Deploy Run #<buildNumber> === 与触发信息;按命令分段输出标题、内容与退出码。 保留策略:logRetentionDays(默认 30 天)过期清理;logMaxBytes(默认 100MB)是单次运行日志上限,超限截断丢弃后续输出——不是磁盘总量配额。

读取接口 ​

  • GET /api/v1/runs/{id}/log?offset=N:从字节偏移读取,响应带 nextOffset 与 eof 标记。
  • WebSocket GET /api/v1/ws/runs/:id?token=<JWT或API token>&offset=N:增量推送,帧带 offset/nextOffset。

两者组合实现「不丢不重」:断线后先用 HTTP 按 nextOffset 补齐历史,再重连 WS;服务端重发更早内容时按 offset 裁掉重复前缀。

CLI 跟随行为 ​

bash
deploy logs 88            # 一次性回放历史,返回 0
deploy logs 88 -f         # 实时跟随到终态,失败返回 1
deploy logs 88 --offset 4096
deploy run my-app -f      # 触发 + 跟随
  • 断线退避重连:0.5s → 5s 封顶,不限次数,直到运行结束或 Ctrl+C。
  • Ctrl+C 默认只断开跟随(退出码 0),不取消运行;--cancel-on-interrupt 才先取消再按终态返回。
  • ANSI:TTY 原样保留颜色;非 TTY / --no-color / NO_COLOR=1 剥离(跨数据块切分的转义序列也能正确剥离)。
  • --json:stdout 为 JSONL,{"type":"log","data":"..."} 事件 + 一行终态对象 {runId,buildNumber,status,exitCode,durationMs};提示全走 stderr。

网页终端 ​

运行详情页为 xterm 终端:WS 实时跟随、自动滚底(可切换)、HTTP 补历史去重、5s 轮询运行状态、取消按钮、日志下载。 反代必须转发 WebSocket 升级头并关闭缓冲,否则实时日志不刷新(systemd 部署与反向代理)。

Secret 遮蔽 ​

已配置 Secret 的值在日志写入时替换为掩码。注意:

  • 遮蔽只覆盖 Secret 值本身;脚本自行打印的其他敏感内容不在范围。
  • 中间件安装生成的随机密码可能在安装日志出现一次(非项目 Secret),限制日志访问权限。
  • 日志文件权限随 dataDir(建议 0750);公网暴露前检查反代是否泄露日志路径。

排查日志问题 ​

现象检查
实时不刷新反代 Upgrade/Connection 头、proxy_buffering off
日志缺失一段是否超 logMaxBytes 被截断;是否过期清理
跟随重复刷屏客户端是否按 offset 去重(官方 CLI/网页已处理)
颜色乱码非 TTY 未剥离 ANSI;加 --no-color

详见 故障排查。