turbo-operations

Turbo Pipeline 运维

运行 Turbo pipeline 的生命周期命令、监控和错误参考。这是一份查询参考；如需交互式排查损坏的 pipeline，请使用 /turbo-doctor。如需构建新的 pipeline，请使用 /turbo-builder。

Pipeline 状态

状态	说明
running	Pipeline 正在处理数据
starting	Pipeline 正在初始化
paused	Pipeline 已暂停（副本数设为 0）
stopped	Pipeline 未运行（已手动停止）
error	Pipeline 遇到错误
completed	作业模式的 pipeline 已完成范围内的数据处理

流式模式与作业模式的生命周期

操作	流式 Pipeline	作业模式 Pipeline（job: true）
列出	显示为 running/paused	显示为 running/completed
暂停	支持	不支持
恢复	支持	不支持
重启	支持	不支持——请使用删除 + 应用
删除	支持	支持（完成后约 1 小时自动清理）
应用	原地更新	必须先删除，然后重新应用

作业模式 Pipeline 生命周期

作业模式 Pipeline（job: true）是一次性批处理流程：

1. 启动——处理从 start_at 到 end_block 的数据
2. 运行——处理限定范围内的数据
3. 完成——处理完范围内的数据后自动停止
4. 自动清理——完成后约 1 小时自动移除

无法暂停、恢复或重启。重新部署前必须先删除。

生命周期命令

列出 Pipeline

goldsky turbo list

暂停 Pipeline

暂时停止处理，但不删除 Pipeline。保留所有状态，以便之后恢复。

goldsky turbo pause <pipeline-name>

恢复 Pipeline

恢复已暂停的 Pipeline。只能恢复已暂停的 Pipeline。

goldsky turbo resume <pipeline-name>

重启 Pipeline

触发运行中或已暂停 Pipeline 的 Pod 重启。

goldsky turbo restart <pipeline-name>
# To clear all checkpoints and reprocess from the beginning:
goldsky turbo restart <pipeline-name> --clear-state

删除 Pipeline

永久移除 Pipeline。所有检查点都会丢失。已写入接收端的数据会保留。

goldsky turbo delete <pipeline-name>

删除并重新创建（全新启动）

goldsky turbo delete my-pipeline
goldsky turbo apply my-pipeline.yaml

检查点行为

• 删除 Pipeline 会永久移除其检查点
• 使用相同名称重新创建时会从头开始（不恢复检查点）
• 如需保留检查点，请使用 apply 更新，而不要删除并重新创建
• 检查点状态与源名称绑定——重命名源会重置其检查点
• 检查点状态与 Pipeline 名称绑定——重命名 Pipeline 会重置所有检查点

监控命令

操作	命令
列出 Pipeline	goldsky turbo list
查看实时数据	goldsky turbo inspect <name> -p
检查特定节点	goldsky turbo inspect <name> -n <node> -p
查看日志	goldsky turbo logs <name>
持续查看日志	goldsky turbo logs <name> --follow
查看带时间戳的日志	goldsky turbo logs <name> --timestamps
查看最后 N 行	goldsky turbo logs <name> --tail N
查看最近 N 秒的日志	goldsky turbo logs <name> --since N

goldsky turbo inspect 标志

标志	短标志	描述
--print	-p	将记录打印到 stdout
--topology-node-keys	-n	用逗号分隔的节点键进行筛选（例如，某个 transform 名称）
--buffer-size	-b	缓冲区最多保留的记录数（默认值：10000）

始终使用 -p。建议的每条 inspect 命令都必须包含它。

日志分析脚本

使用辅助脚本快速分析管道日志：

./scripts/analyze-logs.sh <pipeline-name>
./scripts/analyze-logs.sh <pipeline-name> --tail 100

该脚本会检查常见错误模式，并提供相应建议。

常见错误模式

详细的错误模式和解决方案见 data/error-patterns.json。

错误模式	可能原因	修复方法
connection refused	无法访问数据库	检查网络／防火墙设置
authentication failed	凭据错误	使用正确的凭据更新密钥
secret not found	缺少密钥	使用 goldsky secret create 创建密钥
SQL syntax error	transform SQL 无效	修复 YAML 中的 SQL 并重新部署
duplicate key	主键冲突	确保 transform 中的主键唯一
script transform error	TypeScript 运行时故障	检查脚本逻辑、空值处理和返回类型
dynamic_table error	后端连接问题	确认动态表密钥／表存在
WASM execution failed	脚本在沙盒中崩溃	调试脚本——检查是否访问了未定义的值
handler timeout	外部 HTTP 端点响应缓慢	增加 timeout_ms 或修复处理程序端点

脚本 transform 问题

问题	修复方法
访问 undefined 属性	添加空值检查：input.field ?? ''
返回类型错误	确保返回的对象与 schema 完全匹配
缺少返回字段	返回的对象必须包含所有 schema 字段
invoke is not a function	确保脚本定义了 function invoke(data)
BigInt 错误	使用 BigInt() 构造函数，而不是直接使用数字字面量

动态表问题

问题	修复方法
找不到表	部署前在 PostgreSQL 中创建该表
检查无匹配项	确认底层表中存在数据
数据过时	对于 postgres 后端，确认行确实存在
内存压力	大型 in_memory 表 → 切换到 postgres 后端

故障排查速查表

症状	可能原因	快速修复
没有数据流动	start_at: latest	等待新数据，或使用 earliest
身份验证失败	凭据错误	使用正确的密码更新密钥
连接被拒绝	网络/防火墙	检查主机，允许 Goldsky IP 访问
存储空间超出限制	Neon 免费套餐（512MB）	升级套餐或清除数据
SQL 错误	转换语法错误	先验证 YAML
未找到管道	名称不匹配	运行 goldsky turbo list 检查名称
权限被拒绝	角色权限不足	确认在项目中拥有 Editor 或 Admin 角色
pipeline already exists	Job 模式状态过期	先删除，再重新应用
无法暂停/恢复作业	Job 模式限制	Job 管道不支持暂停/恢复
无法重启作业	Job 模式限制	改为删除并重新应用
无法连接以进行检查	管道未运行	使用 goldsky turbo list 检查状态
日志为空	管道刚启动	等待数据，或检查 start_at
TUI 断开连接	管道中断	30 分钟内会自动重新连接；检查状态

相关内容

• /turbo-doctor — 用于诊断管道问题的交互式技能
• /turbo-builder — 构建并部署新管道
• /turbo-pipelines — YAML 配置和架构参考