主题
日志与实时跟随
落盘布局
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 |
详见 故障排查。