turbo-lifecycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Turbo Pipeline Lifecycle Reference

Turbo 管道生命周期参考文档

CLI commands for managing pipeline lifecycle. Covers streaming and job-mode differences. For interactive pipeline troubleshooting, use

/turbo-doctor

instead.

用于管理管道生命周期的CLI命令，涵盖流式与任务模式的差异。如需交互式管道故障排查，请使用

/turbo-doctor

。

Quick Reference

快速参考

Action	Command
List all pipelines	`goldsky turbo list`
Delete by name	`goldsky turbo delete <pipeline-name>`
Delete by YAML	`goldsky turbo delete -f <pipeline.yaml>`
Pause pipeline	`goldsky turbo pause <pipeline-name>`
Resume pipeline	`goldsky turbo resume <pipeline-name>`
Restart pipeline	`goldsky turbo restart <pipeline-name>`
Restart fresh	`goldsky turbo restart <pipeline-name> --clear-state`

操作	命令
列出所有管道	`goldsky turbo list`
按名称删除	`goldsky turbo delete <pipeline-name>`
按YAML文件删除	`goldsky turbo delete -f <pipeline.yaml>`
暂停管道	`goldsky turbo pause <pipeline-name>`
恢复管道	`goldsky turbo resume <pipeline-name>`
重启管道	`goldsky turbo restart <pipeline-name>`
全新重启	`goldsky turbo restart <pipeline-name> --clear-state`

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

流式与任务模式的生命周期差异

Streaming and job-mode pipelines behave differently for lifecycle operations:

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

in YAML) are one-time batch processes. They:

Start — process data from
```
start_at
```
(or
```
earliest
```
) to
```
end_block
```
(or chain tip)
Run — process the bounded data range
Complete — automatically stop when the range is fully processed
Auto-cleanup — ~1 hour after completion, the pipeline is automatically removed

Key rules for job-mode pipelines:

Cannot pause, resume, or restart — these commands return an error for job pipelines
Cannot update in place — must delete the old job, then apply a new one

Redeploying a job — if you need to re-run:

bash

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

If the job errors, it still auto-deletes ~1 hour after termination — same as successful jobs.

任务型管道（YAML中设置

job: true

）是一次性批处理流程，流程如下：

启动 — 从
```
start_at
```
（或最早区块）处理数据至
```
end_block
```
（或链端）
运行 — 处理指定范围内的有限数据
完成 — 数据范围处理完毕后自动停止
自动清理 — 完成后约1小时，管道会被自动移除

任务型管道的核心规则：

无法暂停、恢复或重启 — 对任务管道执行这些命令会返回错误
无法原地更新 — 必须删除旧任务，再部署新任务

重新部署任务 — 如需重新运行：

bash

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

若任务报错 — 终止后约1小时仍会自动删除，与成功完成的任务规则相同。

Pause, Resume, and Restart

暂停、恢复与重启

Pause a Pipeline

暂停管道

Temporarily stop processing without deleting:

bash

goldsky turbo pause <pipeline-name>

临时停止处理但不删除管道：

bash

goldsky turbo pause <pipeline-name>

or by YAML:

或通过YAML文件：

goldsky turbo pause -f <pipeline.yaml>


This sets deployment replicas to 0, preserving all state for later resumption.

goldsky turbo pause -f <pipeline.yaml>


此操作会将部署副本数设为0，保留所有状态以便后续恢复。

Resume a Pipeline

恢复管道

Restore a paused pipeline to its running state:

bash

goldsky turbo resume <pipeline-name>

将已暂停的管道恢复至运行状态：

bash

goldsky turbo resume <pipeline-name>

or by YAML:

或通过YAML文件：

goldsky turbo resume -f <pipeline.yaml>


> You can only resume a **paused** pipeline. Attempting to resume an already running pipeline returns an error.

goldsky turbo resume -f <pipeline.yaml>


> 仅能恢复**已暂停**的管道。尝试恢复已在运行的管道会返回错误。

Restart a Pipeline

重启管道

Trigger a pod restart for a running or paused pipeline:

bash

goldsky turbo restart <pipeline-name>

To clear all checkpoints and reprocess from the beginning:

bash

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

Restart vs Resume: Use
resume
to restore a paused pipeline without restarting pods. Use
restart
when you need a fresh pod restart (e.g., after configuration changes or to recover from issues). Restart is not supported for Job-mode pipelines — use
delete
+
apply
instead.

触发运行中或已暂停管道的Pod重启：

bash

goldsky turbo restart <pipeline-name>

若要清除所有检查点并从头开始处理：

bash

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

重启vs恢复：使用
resume
可恢复已暂停的管道，无需重启Pod；当需要全新Pod重启时（例如配置变更后或恢复故障）使用
restart
。任务型管道不支持重启操作 — 请使用
delete
+
apply
替代。

Important Notes

重要说明

Deletion is Permanent

删除操作不可撤销

All checkpoints are lost
Pipeline configuration is removed
Cannot be undone

所有检查点将丢失
管道配置会被移除
操作无法撤销

Data in Sinks is Preserved

目标存储中的数据会被保留

Data already written to PostgreSQL, ClickHouse, etc. remains
Only the pipeline itself is deleted
You may need to manually clean up sink data if desired

已写入PostgreSQL、ClickHouse等目标存储的数据不会丢失
仅会删除管道本身
若需清理目标存储数据，需手动操作

Checkpoints and Restarts

检查点与重启

Deleting a pipeline removes its checkpoints
If you recreate a pipeline with the same name, it starts fresh
To preserve checkpoints, use
```
goldsky turbo apply
```
to update instead of delete/recreate

删除管道会移除其检查点
若重新创建同名管道，会从头开始运行
若要保留检查点，请使用
```
goldsky turbo apply
```
进行更新，而非删除后重新创建

Job-Mode Pipelines Cannot Be Updated In Place

任务型管道无法原地更新

Job pipelines (
```
job: true
```
) must be deleted before redeploying
Attempting
```
goldsky turbo apply
```
on an existing job returns an error:
```
pipeline already exists
```
Jobs auto-cleanup ~1 hour after termination regardless of success or failure

Always delete the old job first if redeploying:

goldsky turbo delete <name>

, then

goldsky turbo apply <file.yaml>

任务型管道（
```
job: true
```
）必须先删除再重新部署
对已存在的任务执行
```
goldsky turbo apply
```
会返回错误：
```
pipeline already exists
```
无论成功或失败，任务终止后约1小时都会自动清理

重新部署时务必先删除旧任务：

goldsky turbo delete <name>

，再执行

goldsky turbo apply <file.yaml>

Project Scope

项目范围

```
goldsky turbo list
```
shows pipelines in your current project only
Use
```
goldsky project list
```
to see available projects
Pipelines are isolated per project

```
goldsky turbo list
```
仅显示当前项目中的管道
使用
```
goldsky project list
```
查看可用项目
管道在不同项目间相互隔离

Common Patterns

常见操作模式

Delete and Recreate

删除并重新创建

If you need to restart a pipeline from scratch:

Delete the existing pipeline:
bash
```
goldsky turbo delete my-pipeline
```
Deploy fresh:
bash
```
goldsky turbo apply my-pipeline.yaml
```

This resets all checkpoints and starts processing from the configured

start_at

position.

若需让管道从头开始运行：

删除现有管道：
bash
```
goldsky turbo delete my-pipeline
```
全新部署：
bash
```
goldsky turbo apply my-pipeline.yaml
```

此操作会重置所有检查点，并从配置的

start_at

位置开始处理数据。

Rename Instead of Delete

重命名而非删除

To keep checkpoints but change the pipeline name:

Update the
```
name
```
field in your YAML
Apply the new configuration:
bash
```
goldsky turbo apply my-pipeline-v2.yaml
```
Delete the old pipeline:
bash
```
goldsky turbo delete my-pipeline
```

Note: This creates a new pipeline; checkpoints don't transfer between names.

若要保留检查点但修改管道名称：

在YAML文件中更新
```
name
```
字段
部署新配置：
bash
```
goldsky turbo apply my-pipeline-v2.yaml
```
删除旧管道：
bash
```
goldsky turbo delete my-pipeline
```

注意：此操作会创建新管道；检查点不会在不同名称的管道间转移。

Clean Up Test Pipelines

清理测试管道

For development, use a naming convention like

test-*

dev-*

yaml

name: test-usdc-transfers # Easy to identify for cleanup

Then clean up all test pipelines when done.

开发时可使用

test-*

或

dev-*

这类命名规范：

yaml

name: test-usdc-transfers # 便于识别和清理

完成后即可清理所有测试管道。

Troubleshooting

故障排查

Issue	Action
Pipeline not found	Check spelling; use `goldsky turbo list` to see names
Permission denied	Verify you have Editor or Admin role in the project
Delete failed	Check logs for errors; pipeline may be in transition
Wrong project	Use `goldsky project list` to verify current project
`pipeline already exists`	Job-mode pipeline — delete first, then re-apply
Cannot pause/resume job	Job-mode pipelines don't support pause/resume; use delete
Cannot restart job	Job-mode pipelines don't support restart; delete + re-apply

问题	解决方法
管道未找到	检查拼写；使用 `goldsky turbo list` 查看所有管道名称
权限不足	确认你在项目中拥有编辑者或管理员权限
删除失败	查看日志排查错误；管道可能处于过渡状态
项目错误	使用 `goldsky project list` 确认当前项目
`pipeline already exists`	任务型管道 — 请先删除旧任务，再重新部署
无法暂停/恢复任务管道	任务型管道不支持暂停/恢复；请使用删除操作
无法重启任务管道	任务型管道不支持重启；请删除后重新部署

Error: Pipeline Not Found

错误：管道未找到

Error: Pipeline 'wrong-name' not found

Fix: Run

goldsky turbo list

to see exact pipeline names. Names are case-sensitive.

Error: Pipeline 'wrong-name' not found

解决方法：运行

goldsky turbo list

查看准确的管道名称，名称区分大小写。

Error: Permission Denied

错误：权限不足

Error: Permission denied

Fix: You need Editor or Admin role. Contact a project Owner to upgrade your role.

Error: Permission denied

解决方法：你需要拥有编辑者或管理员权限，请联系项目所有者升级你的角色。

turbo-lifecycle

Original

Translation

Turbo Pipeline Lifecycle Reference

Turbo 管道生命周期参考文档

Quick Reference

快速参考

Pipeline States

管道状态

Streaming vs Job Mode Lifecycle

流式与任务模式的生命周期差异

Job-Mode Pipeline Lifecycle

任务型管道生命周期

Pause, Resume, and Restart

暂停、恢复与重启

Pause a Pipeline

暂停管道

or by YAML:

或通过YAML文件：

Resume a Pipeline

恢复管道

or by YAML:

或通过YAML文件：

Restart a Pipeline

重启管道

Important Notes

重要说明

Deletion is Permanent

删除操作不可撤销

Data in Sinks is Preserved

目标存储中的数据会被保留

Checkpoints and Restarts

检查点与重启

Job-Mode Pipelines Cannot Be Updated In Place

任务型管道无法原地更新

Project Scope

项目范围

Common Patterns

常见操作模式

Delete and Recreate

删除并重新创建

Rename Instead of Delete

重命名而非删除

Clean Up Test Pipelines

清理测试管道

Troubleshooting

故障排查

Error: Pipeline Not Found

错误：管道未找到

Error: Permission Denied

错误：权限不足

Related

相关工具