turbo-operations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Turbo Pipeline Operations

Turbo 流水线操作

Lifecycle commands, monitoring, and error reference for running Turbo pipelines. This is a lookup reference — for interactive troubleshooting of a broken pipeline, use

/turbo-doctor

. For building new pipelines, use

/turbo-builder

针对运行中的Turbo流水线的生命周期命令、监控和错误参考文档。本文档是查询参考——如果需要对故障流水线进行交互式故障排查，请使用

/turbo-doctor

。如果要构建新流水线，请使用

/turbo-builder

。

Pipeline States

流水线状态

State	Description
running	Pipeline is actively processing data
starting	Pipeline is initializing
paused	Pipeline is paused (replicas set to 0)
stopped	Pipeline is not running (manually stopped)
error	Pipeline encountered an error
completed	Job-mode pipeline finished processing range

状态	描述
running	流水线正在主动处理数据
starting	流水线正在初始化
paused	流水线已暂停（副本数设置为0）
stopped	流水线未运行（手动停止）
error	流水线遇到了错误
completed	任务模式流水线已完成指定范围的处理

Streaming vs Job Mode Lifecycle

流模式与任务模式生命周期对比

Operation	Streaming Pipeline	Job-Mode Pipeline ( `job: true` )
List	Shows as `running` / `paused`	Shows as `running` / `completed`
Pause	Supported	Not supported
Resume	Supported	Not supported
Restart	Supported	Not supported — use delete + apply
Delete	Supported	Supported (auto-cleanup ~1hr after done)
Apply	Updates in place	Must delete first, then re-apply

操作	流模式流水线	任务模式流水线 ( `job: true` )
列表展示	展示为 `running` / `paused`	展示为 `running` / `completed`
暂停	支持	不支持
恢复	支持	不支持
重启	支持	不支持 — 请使用删除+重新创建
删除	支持	支持（完成后约1小时自动清理）
应用配置	原地更新配置	必须先删除，再重新应用

Job-Mode Pipeline Lifecycle

任务模式流水线生命周期

Job-mode pipelines (

job: true

) are one-time batch processes:

Start — process data from
```
start_at
```
to
```
end_block
```
Run — process the bounded data range
Complete — automatically stop when range is processed
Auto-cleanup — ~1 hour after completion, automatically removed

Cannot pause, resume, or restart. Must delete before redeploying.

任务模式流水线 (

job: true

) 是一次性批量处理流程：

启动 — 处理从
```
start_at
```
到
```
end_block
```
的数据
运行 — 处理指定范围内的有限数据
完成 — 范围数据处理完成后自动停止
自动清理 — 完成后约1小时，自动被移除

任务模式流水线不支持暂停、恢复或重启，重新部署前必须先删除。

Lifecycle Commands

生命周期命令

List Pipelines

列出流水线

bash

goldsky turbo list

bash

goldsky turbo list

Pause a Pipeline

暂停流水线

Temporarily stop processing without deleting. Preserves all state for later resumption.

bash

goldsky turbo pause <pipeline-name>

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

bash

goldsky turbo pause <pipeline-name>

Resume a Pipeline

恢复流水线

Restore a paused pipeline. Can only resume a paused pipeline.

bash

goldsky turbo resume <pipeline-name>

恢复已暂停的流水线，仅可恢复paused状态的流水线。

bash

goldsky turbo resume <pipeline-name>

Restart a Pipeline

重启流水线

Trigger a pod restart for a running or paused pipeline.

bash

goldsky turbo restart <pipeline-name>

触发运行中或已暂停流水线的Pod重启。

bash

goldsky turbo restart <pipeline-name>

To clear all checkpoints and reprocess from the beginning:

如需清除所有检查点，从头开始重新处理：

goldsky turbo restart <pipeline-name> --clear-state

undefined

goldsky turbo restart <pipeline-name> --clear-state

undefined

Delete a Pipeline

删除流水线

Permanently remove a pipeline. All checkpoints are lost. Data already written to sinks is preserved.

bash

goldsky turbo delete <pipeline-name>

永久移除流水线，所有检查点会丢失，但已经写入数据出口（sink）的数据会保留。

bash

goldsky turbo delete <pipeline-name>

Delete and Recreate (Fresh Start)

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

bash

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

bash

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

Checkpoint Behavior

检查点机制

Deleting a pipeline removes its checkpoints permanently
Recreating with the same name starts fresh (no checkpoint recovery)
To preserve checkpoints, use
```
apply
```
to update instead of delete/recreate
Checkpoint state is tied to source names — renaming a source resets its checkpoint
Checkpoint state is tied to pipeline names — renaming a pipeline resets all checkpoints

删除流水线会永久移除其检查点
使用相同名称重新创建的流水线会全新启动（不会恢复检查点）
如需保留检查点，请使用
```
apply
```
更新配置，不要删除/重新创建
检查点状态与数据源名称绑定 — 重命名数据源会重置其检查点
检查点状态与流水线名称绑定 — 重命名流水线会重置所有检查点

Monitoring Commands

监控命令

Action	Command
List pipelines	`goldsky turbo list`
View live data	`goldsky turbo inspect <name>`
Inspect specific node	`goldsky turbo inspect <name> -n <node>`
View logs	`goldsky turbo logs <name>`
Follow logs	`goldsky turbo logs <name> --follow`
Logs with timestamps	`goldsky turbo logs <name> --timestamps`
Last N lines	`goldsky turbo logs <name> --tail N`
Logs since N seconds ago	`goldsky turbo logs <name> --since N`

操作	命令
列出流水线	`goldsky turbo list`
查看实时数据	`goldsky turbo inspect <name>`
检查指定节点	`goldsky turbo inspect <name> -n <node>`
查看日志	`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`

Live Inspect TUI Shortcuts

实时检查TUI快捷键

Key	Action
`Tab` / `→` , `Shift+Tab` / `←`	Next/prev tab
`1` - `9`	Jump to tab number
`j` / `k` / `↑` / `↓`	Scroll
`g` / `Home` , `G` / `End`	Top/bottom
`Page Up` / `Page Down`	Scroll by page
`/` → `Enter`	Search
`n` / `N`	Next/prev match
`Esc`	Clear search
`d`	Toggle definition
`w`	Open web dashboard
`e`	Open web editor
`q` / `Ctrl+C`	Quit
`Shift` + mouse	Select and copy text

The TUI automatically reconnects when the pipeline is updated, paused, resumed, or temporarily unavailable. It has a 30-minute timeout before closing.

按键	操作
`Tab` / `→` , `Shift+Tab` / `←`	下一个/上一个标签页
`1` - `9`	跳转到对应编号的标签页
`j` / `k` / `↑` / `↓`	滚动
`g` / `Home` , `G` / `End`	到顶部/底部
`Page Up` / `Page Down`	按页滚动
`/` → `Enter`	搜索
`n` / `N`	下一个/上一个匹配结果
`Esc`	清除搜索
`d`	切换定义显示
`w`	打开网页面板
`e`	打开网页编辑器
`q` / `Ctrl+C`	退出
`Shift` + 鼠标	选中并复制文本

当流水线更新、暂停、恢复或暂时不可用时，TUI会自动重连，关闭前有30分钟超时时间。

Log Analysis Script

日志分析脚本

Use the helper script to quickly analyze pipeline logs:

bash

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

The script checks for common error patterns and reports findings with recommendations.

使用辅助脚本快速分析流水线日志：

bash

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

该脚本会检查常见错误模式，并返回结果和修复建议。

Common Error Patterns

常见错误模式

Detailed error patterns and solutions are in
data/error-patterns.json
.

Error Pattern	Likely Cause	Fix
`connection refused`	Database unreachable	Check network/firewall settings
`authentication failed`	Wrong credentials	Update secret with correct credentials
`secret not found`	Missing secret	Create secret with `goldsky secret create`
`SQL syntax error`	Invalid transform SQL	Fix SQL in YAML and redeploy
`duplicate key`	Primary key collision	Ensure unique primary key in transform
`script transform error`	TypeScript runtime failure	Check script logic, null handling, return types
`dynamic_table` error	Backend connection issue	Verify dynamic table secret/table exists
`WASM execution failed`	Script crash in sandbox	Debug script — check for undefined access
`handler timeout`	External HTTP endpoint slow	Increase `timeout_ms` or fix handler endpoint

详细错误模式和解决方案存放在
data/error-patterns.json
。

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

Script Transform Issues

脚本转换问题

Issue	Fix
`undefined` property access	Add null checks: `input.field ?? ''`
Wrong return type	Ensure returned object matches `schema` exactly
Missing return fields	All `schema` fields must be present in returned object
`invoke is not a function`	Ensure script defines `function invoke(data)`
BigInt errors	Use `BigInt()` constructor, not direct number literals

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

Dynamic Table Issues

动态表问题

Issue	Fix
Table not found	Create the table in PostgreSQL before deploying
No matches from check	Verify data exists in the backing table
Stale data	For postgres backend, verify rows are actually there
Memory pressure	Large in_memory tables → switch to postgres backend

问题	修复方案
表未找到	部署前先在PostgreSQL中创建对应表
检查无匹配结果	验证后台表中存在对应数据
数据陈旧	对于postgres后端，验证行实际存在
内存压力	过大的in_memory表 → 切换到postgres后端

Troubleshooting Quick Reference

故障排查快速参考

Symptom	Likely Cause	Quick Fix
No data flowing	`start_at: latest`	Wait for new data or use `earliest`
Auth failed	Wrong credentials	Update secret with correct password
Connection refused	Network/firewall	Check host, whitelist Goldsky IPs
Storage exceeded	Neon free tier (512MB)	Upgrade plan or clear data
SQL error	Bad transform syntax	Validate YAML first
Pipeline not found	Name mismatch	Run `goldsky turbo list` to check names
Permission denied	Role insufficient	Verify Editor or Admin role in the project
`pipeline already exists`	Job-mode stale	Delete first, then re-apply
Cannot pause/resume job	Job-mode limitation	Job pipelines don't support pause/resume
Cannot restart job	Job-mode limitation	Delete + re-apply instead
Can't connect to inspect	Pipeline not running	Check status with `goldsky turbo list`
Logs are empty	Pipeline just started	Wait for data or check `start_at`
TUI disconnects	Pipeline interrupted	Auto-reconnects within 30 min; check status

现象	可能原因	快速修复
无数据流动	`start_at: latest`	等待新数据或使用 `earliest`
认证失败	凭证错误	更新密钥为正确密码
连接被拒绝	网络/防火墙问题	检查主机，将Goldsky IP加入白名单
存储超限	Neon免费 tier (512MB)	升级套餐或清理数据
SQL错误	转换语法错误	先验证YAML配置
流水线未找到	名称不匹配	运行 `goldsky turbo list` 检查名称
权限拒绝	角色权限不足	验证项目内的Editor或Admin角色
`pipeline already exists`	任务模式流水线残留	先删除，再重新应用
无法暂停/恢复任务	任务模式限制	任务流水线不支持暂停/恢复
无法重启任务	任务模式限制	改为删除+重新应用
无法连接到inspect	流水线未运行	用 `goldsky turbo list` 检查状态
日志为空	流水线刚启动	等待数据或检查 `start_at` 配置
TUI断开连接	流水线被中断	30分钟内会自动重连；检查流水线状态

turbo-operations

Original

Translation

Turbo Pipeline Operations

Turbo 流水线操作

Pipeline States

流水线状态

Streaming vs Job Mode Lifecycle

流模式与任务模式生命周期对比

Job-Mode Pipeline Lifecycle

任务模式流水线生命周期

Lifecycle Commands

生命周期命令

List Pipelines

列出流水线

Pause a Pipeline

暂停流水线

Resume a Pipeline

恢复流水线

Restart a Pipeline

重启流水线

To clear all checkpoints and reprocess from the beginning:

如需清除所有检查点，从头开始重新处理：

Delete a Pipeline

删除流水线

Delete and Recreate (Fresh Start)

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

Checkpoint Behavior

检查点机制

Monitoring Commands

监控命令

Live Inspect TUI Shortcuts

实时检查TUI快捷键

Log Analysis Script

日志分析脚本

Common Error Patterns

常见错误模式

Script Transform Issues

脚本转换问题

Dynamic Table Issues

动态表问题

Troubleshooting Quick Reference

故障排查快速参考

Related

相关内容