mirror-doctor

Mirror Pipeline Doctor

通过运行 CLI 命令、找出根本原因并执行修复，诊断并修复现有 Mirror 流水线问题。

边界

• 诊断并修复现有 Mirror 流水线问题。
• 不要构建新流水线——配置参考请使用 /mirror，构建新的 Turbo 流水线请使用 /turbo-builder。
• 不要充当命令参考——查询 CLI 语法和标志请使用 /mirror。
• 不要处理 Turbo 流水线——goldsky turbo 问题请使用 /turbo-doctor。
• 不要创建密钥——凭据管理请使用 /secrets。但在诊断过程中，务必检查密钥是否存在。

诊断工作流

按顺序执行以下步骤。每一步都基于前一步的结果。

Step 1：验证身份验证

运行 goldsky project list 2>&1，确认用户已登录。

• 如果已登录： 记下项目名称并继续。
• 如果未登录： 引导用户前往 /auth-setup。身份验证正常前不要继续。

Step 2：识别流水线

运行 goldsky pipeline list --include-runtime-details 2>&1，列出所有 Mirror 流水线及其状态。

如果用户已经指定了流水线，请确认它存在于列表中。如果没有，请显示列表并询问用户要诊断哪个流水线。

记录期望状态（ACTIVE、INACTIVE、PAUSED）和运行时状态（STARTING、RUNNING、FAILING、TERMINATED）——Mirror 流水线同时具有这两种状态，二者的组合可以说明问题所在。

Step 3：根据状态分类

期望状态与运行时状态的组合决定诊断路径：

期望状态	运行时	含义	操作
ACTIVE	RUNNING	正常——流水线正在处理数据	询问用户遇到了什么症状。继续执行 Step 4。
ACTIVE	STARTING	流水线正在初始化	询问已持续多久。如果超过 10 分钟，继续执行 Step 4。
ACTIVE	FAILING	流水线正在遇到错误，但尚未终止	立即继续执行 Step 4——此情况需要及时处理。
ACTIVE	TERMINATED	**最常见的故障。**流水线原本应运行，但发生崩溃。	继续执行 Step 4。
PAUSED	TERMINATED	用户暂停了流水线（已创建快照）。	询问是否要恢复：goldsky pipeline start <name> --from-snapshot last
INACTIVE	TERMINATED	用户停止了流水线（没有快照）。	询问是否要启动：goldsky pipeline start <name>

**ACTIVE + TERMINATED 是最常见的情况。**流水线的期望状态为 ACTIVE（应处于运行状态），但由于错误，运行时已终止。请重点诊断这种情况。

Step 4：收集诊断数据

运行以下命令以了解出了什么问题：

# Get error details and runtime metrics
goldsky pipeline monitor <name> 2>&1

# Check for in-flight requests blocking operations
goldsky pipeline monitor <name> --update-request 2>&1

# Get the pipeline definition to check for misconfig
goldsky pipeline get <name> --definition 2>&1

# Get pipeline info including version
goldsky pipeline info <name> 2>&1

# Check available snapshots
goldsky pipeline snapshots list <name> 2>&1

按顺序运行这些命令，并在继续之前分析输出。监控输出最重要——它会显示错误消息、接收/写入记录的指标以及运行时状态转换。

Step 5：匹配错误模式

根据诊断数据，与以下已知模式进行匹配：

密钥错误或缺失

**症状：**流水线启动后不久便终止。监控中显示凭据或身份验证错误。

**验证：**运行 goldsky secret list 2>&1，并与 Step 4 中流水线定义里的 secret_name 值交叉核对。

修复：

1. 如果密钥不存在，请引导用户前往 /secrets 创建密钥。
2. 如果密钥存在但凭据有误，请使用 goldsky secret update 原地更新；有关所需的 JSON 格式和凭据处理，请参阅轮换凭据。不要删除并重新创建正在使用的密钥。
3. 重启：goldsky pipeline restart <name> --from-snapshot last

接收端不可达

**症状：**监控输出中出现连接超时、连接被拒绝或网络错误。管道可能会在 FAILING 和 TERMINATED 之间循环。

常见原因：

• 防火墙未允许来自 AWS us-west-2 的入站流量（Mirror 管道从此区域写入）
• 数据库已停止运行或重启
• 连接池已耗尽
• 密钥中的端口或主机填写错误

修复方法：

1. 验证从 us-west-2 是否可以访问接收端。
2. 检查密钥中的主机、端口和凭据是否正确。
3. 恢复连接后，重启：goldsky pipeline restart <name> --from-snapshot last

资源耗尽

**症状：**管道运行一段时间后终止。监控可能会显示记录数很高或处理速度缓慢。大型回填或源/JOIN 较多的管道中常见此问题。

修复方法：

1. 调整大小：goldsky pipeline resize <name> <size> — 可选大小为 s、m、l、xl、xxl。
2. 从较小规格开始，逐步增大。s 可处理大多数工作负载（最高 300K 条记录/秒，约 8 个子图源）。大型链回填或繁重的 JOIN 可使用 l 或更大的规格。

正在处理的请求阻塞

**症状：**用户尝试更新、删除或重启管道时，收到“Cannot process request, found existing request in-flight.”错误。

诊断：goldsky pipeline monitor <name> --update-request — 此命令会显示正在进行的操作（通常是快照）。

修复方法：

1. 如果正在进行的操作是仍在正常推进的快照，请等待其完成。
2. 如果操作卡住或不需要：goldsky pipeline cancel-update <name>
3. 然后重试原操作。

快照卡住

**症状：**由于快照创建耗时过长或失败，无法暂停、更新或重启管道。--update-request 监控显示快照进度停滞在某个百分比。

修复方法：

1. 取消卡住的快照：goldsky pipeline cancel-update <name>
2. 重启时不等待新快照：goldsky pipeline restart <name> --from-snapshot last
3. 如果没有可用快照：goldsky pipeline restart <name> --from-snapshot none（从头开始 — 请告知用户这会重新处理数据）

转换 SQL 错误

**症状：**管道因 SQL 相关错误消息而终止。可能是语法错误、引用了不存在的列或类型不匹配。

**诊断：**检查管道定义（goldsky pipeline get <name> --definition），并查看 transforms 部分。

修复方法：

1. 从监控输出中找出 SQL 错误。
2. 修复管道 YAML 文件中的 SQL。
3. 验证：goldsky pipeline validate <file.yaml>
4. 重新应用：goldsky pipeline apply <file.yaml> --status ACTIVE --from-snapshot last

如需 SQL 转换语法参考，请使用 /mirror。

管道陷入重启循环

**症状：**管道反复经历 STARTING → FAILING → TERMINATED 状态。监控显示相同错误重复出现。

这通常是其他根本原因导致的症状 — 密钥错误、接收端不可达或资源问题。管道不断尝试启动，但总是遇到同样的阻碍。

修复方法：

1. 从监控中找出根本错误（通常属于上述某种情况）。
2. 先解决根本原因。
3. 然后重启：goldsky pipeline restart <name> --from-snapshot last

接收端停机引发的级联故障

**症状：**管道原本运行正常，随后接收端（数据库）暂时停止运行。管道自动重试并重启写入器，最终终止。

这是预期行为 — Mirror 会自动处理接收端的暂时性错误（重试批次 → 重启写入器 → 问题持续较长时间后失败）。

修复方法：

1. 确认接收端已恢复运行且状态正常。
2. 从上一个快照重启：goldsky pipeline restart <name> --from-snapshot last
3. 管道会从中断处继续运行，而不是重新处理所有数据。

步骤 6：呈现诊断结果

确定问题后，清楚地呈现诊断结果：

## Diagnosis

**Pipeline:** <name>
**Status:** <desired> + <runtime>
**Issue:** <one-line summary>

**Root cause:**
<What's wrong and why>

**Evidence:**
- <Error message or observation from monitor>
- <Relevant detail from pipeline definition>

**Recommended fix:**
1. <Step 1>
2. <Step 2>

**Prevention:**
<How to avoid this in the future, if applicable>

步骤 7：执行修复

提出直接运行修复命令。执行前务必先征得用户确认：

• 重启： goldsky pipeline restart <name> --from-snapshot last
• 调整大小： goldsky pipeline resize <name> <size>
• 取消阻塞的操作： goldsky pipeline cancel-update <name>
• 从头重启： goldsky pipeline restart <name> --from-snapshot none（警告：会重新处理数据）
• 重新应用配置： goldsky pipeline apply <file.yaml> --status ACTIVE --from-snapshot last
• 删除并重新创建： goldsky pipeline delete <name> -f，然后运行 goldsky pipeline apply <file.yaml> --status ACTIVE（最后手段）

执行后，运行 goldsky pipeline monitor <name> 验证是否恢复，并观察状态是否从 STARTING 转为 RUNNING。

重要规则

• 诊断前务必先收集数据。切勿猜测问题所在。
• 检查期望状态和运行时状态，两者的组合很重要。
• 运行任何破坏性命令（删除、从头重启）前，务必先征得用户确认。
• --from-snapshot last 会保留进度。--from-snapshot none 会从头开始。除非有特殊原因，否则默认使用 last。
• 瞬时错误会自动重试，最长可达 6 小时。非瞬时错误会立即终止。如果流水线启动后很快就终止，可能是配置问题（密钥错误、SQL 有误），而非短暂的网络中断。
• 如果问题超出 CLI 的诊断范围，建议用户联系 [email protected]，并提供流水线名称、错误消息和项目 ID。

Bash 不可用时

如果你没有 Bash 工具，请输出供用户运行的诊断命令，并按以下方式清晰组织：

1. 每次只提供一条命令。
2. 说明需要查看输出中的哪些内容。
3. 根据用户对输出的描述，继续进行诊断。

这是备用方案——只要 Bash 可用，就应始终优先直接运行命令。

相关内容

• /mirror — 流水线 YAML 配置、CLI 标志参考、sink 设置
• /secrets — 创建和管理 sink 凭据
• /auth-setup — CLI 安装和身份验证
• /turbo-doctor — 诊断 Turbo 流水线问题（非 Mirror）