mirror

Goldsky Mirror Pipeline

Mirror 是 Goldsky 的原始流式 Pipeline 产品。它从源（子图实体或直接索引数据集）读取链上数据，可选择应用转换，然后将结果写入接收端（你的数据库或消息队列）。

Mirror 与 Turbo——该使用哪个？

	Mirror	Turbo
子图源	是	否
速度与可靠性	良好	更快、更可靠
接收端选项	请参阅下方的常见 Mirror 接收端	请参阅 Turbo 接收端目录
配置复杂度	中等	YAML 更简单
数据集覆盖范围	130+ 条链	130+ 条链，目录更丰富

除非你需要子图源，否则请使用 Turbo。 Turbo 更快、更可靠，并且正在积极补齐与 Mirror 的功能差距，尤其是接收端支持。如果你不需要子图，请说“帮我构建一个 Turbo Pipeline”，/turbo-builder 技能会引导你更快地完成设置。

---

Mirror Pipeline 的工作原理

Source (subgraph entity or direct-indexing dataset)
  ↓
Transforms (optional SQL or external handlers)
  ↓
Sink (PostgreSQL, ClickHouse, Kafka, S3, etc.)

Pipeline 定义在 YAML 文件中（apiVersion: 3），并使用 goldsky pipeline apply 部署。

---

Pipeline YAML 结构

顶层字段：

字段	类型	必填	描述
name	string	是	只能包含小写字母、数字和连字符。长度少于 50 个字符。
apiVersion	number	是	始终为 3
resource_size	string	否	s（默认值）、m、l、xl、xxl
description	string	否	Pipeline 描述
sources	object	是	至少一个源
transforms	object	否	如果不需要，请使用 {}
sinks	object	是	至少一个接收端

---

源

源类型	YAML type 值	描述
子图实体	subgraph_entity	从 Goldsky 托管的子图镜像数据
数据集（直接索引）	dataset	原始链上数据集（区块、日志、交易、调用轨迹、转账）

子图实体源

sources:
  subgraph_account:
    type: subgraph_entity
    name: account                # Entity name in your subgraph
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter: ""                   # Optional SQL WHERE clause for fast scan
    subgraphs:
      - name: my-subgraph        # Deployed subgraph name
        version: 1.0.0
      - name: my-subgraph-arb    # Cross-chain: add more subgraphs
        version: 1.0.0

字段：type（必填：subgraph_entity）、name（必填：实体名称）、subgraphs（必填：{name, version} 列表）、start_at（可选）、filter（可选）、description（可选）。

数据集源

sources:
  base_logs:
    type: dataset
    dataset_name: base.logs      # Use `goldsky dataset list --output json` to discover names
    version: 1.0.0               # Use `goldsky dataset get <name>` for versions
    start_at: latest             # "earliest" or "latest" (default: latest)
    filter: "address = '0x...'"  # Optional — enables Fast Scan for backfills

字段：type（必填：dataset）、dataset_name（必填）、version（必填）、start_at（可选）、filter（可选）、description（可选）。

**快速扫描：**当数据集源定义了 filter，且 start_at: earliest 时，过滤条件会预先应用于源级别，从而大幅加快历史数据回填速度。请使用数据集架构中存在的属性（运行 goldsky dataset get <dataset_name> 查看）。

请参阅 docs.goldsky.com/mirror/sources/supported-sources。

---

汇

常见的 Mirror 目标位置如下；这并非支持的目标类型的完整列表。请根据用户需要的具体目标位置进行比较，不要根据这些示例推断整个产品支持的目标类型数量。

目标位置	YAML type 值	备注
PostgreSQL	postgres	最常见 — OLTP，自动创建表，通过 INSERT ON CONFLICT 执行 upsert。可通过 NeonDB 使用托管选项。
ClickHouse	clickhouse	OLAP — 默认使用 ReplacingMergeTree，append_only_mode 可获得最佳性能
MySQL	mysql	OLTP 工作负载
Elasticsearch	elasticsearch	实时搜索和分析
Kafka	kafka	高吞吐量地将数据流式传输到一个主题，topic_partitions 可配置
对象存储	file	S3、GCS 或 R2 — Parquet 格式，只追加，支持 partition_columns
AWS SQS	sqs	消息队列
Webhook	webhook	向外部端点发送 HTTP POST

所有写入用户管理目标位置的目标都需要 Goldsky Secret（secret_name）。使用 goldsky secret create 创建。

目标支持 schema_override，可在目标层级转换列类型（例如，将 string 转换为 jsonb）。

目标示例

# PostgreSQL
sinks:
  my_pg:
    type: postgres
    table: transfers
    schema: public
    secret_name: MY_PG_SECRET
    from: my_transform

# ClickHouse
sinks:
  my_ch:
    type: clickhouse
    table: transfers
    database: my_db
    secret_name: MY_CH_SECRET
    from: my_source

# Kafka
sinks:
  my_kafka:
    type: kafka
    topic: accounts
    topic_partitions: 2
    secret_name: MY_KAFKA_SECRET
    from: my_source

# Object Storage (S3/GCS/R2)
sinks:
  my_s3:
    type: file
    path: s3://bucket/path/
    format: parquet
    secret_name: MY_S3_SECRET
    from: my_source

# SQS
sinks:
  my_sqs:
    type: sqs
    url: https://sqs.us-east-1.amazonaws.com/123456/my-queue
    secret_name: MY_SQS_SECRET
    from: my_source

参见 docs.goldsky.com/mirror/sinks/supported-sinks。

---

转换

类型	YAML type 值	描述
SQL	(none — default)	使用 SQL 筛选、联接或重塑记录
External handler	handler	将记录 POST 到 HTTP 端点以执行自定义逻辑

SQL 转换

transforms:
  filtered_logs:
    sql: SELECT id, block_number, address FROM base_logs WHERE block_number > 1000
    primary_key: id

SQL 转换会将源或转换名称作为表名引用。支持链式调用（一个转换读取另一个转换的数据）。

内置解码函数：

• _gs_log_decode(abi, topics, data) — 解码原始日志事件
• _gs_tx_decode(abi, input, output) — 解码原始跟踪／交易数据
• _gs_fetch_abi(url, type) — 从 URL 获取 ABI（兼容 etherscan 或原始 JSON）；在管道启动时获取一次

外部处理器转换

transforms:
  my_handler:
    type: handler
    primary_key: id
    url: http://example.com/transform
    from: my_source
    batch_size: 100              # Records per batch (default: 100)
    batch_flush_interval: 1s     # Flush interval (default: 1s)
    payload_columns: [col1,col2] # Optional: send subset of columns
    headers:                     # Optional custom headers
      X-Api-Key: my-key

• 至少一次投递，失败时采用指数退避
• 最长响应时间：5 分钟；最长连接时间：1 分钟
• 支持使用 schema_override 转换返回类型

参见 docs.goldsky.com/mirror/transforms/sql-transforms。

---

完整 YAML 示例

将子图实体写入 PostgreSQL

name: my-subgraph-sync
apiVersion: 3
resource_size: s
sources:
  subgraph_transfer:
    type: subgraph_entity
    name: Transfer
    subgraphs:
      - name: uniswap-v3
        version: 1.0.0
transforms: {}
sinks:
  my_postgres:
    type: postgres
    table: transfers
    schema: public
    secret_name: MY_PG_SECRET
    from: subgraph_transfer

使用 SQL 转换将数据集（直接索引）写入 PostgreSQL

name: base-logs-filtered
apiVersion: 3
resource_size: s
sources:
  base_logs:
    type: dataset
    dataset_name: base.logs
    version: 1.0.0
    start_at: earliest
    filter: "address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'"
transforms:
  select_fields:
    sql: SELECT id, block_number, transaction_hash, data FROM base_logs
    primary_key: id
sinks:
  pg_logs:
    type: postgres
    table: base_logs
    schema: public
    secret_name: MY_PG_SECRET
    from: select_fields

没有子图源？ 几乎可以肯定你应该使用 Turbo — 它速度更快、更可靠，数据集目录也更丰富，语法还更简单。使用 /turbo-builder 开始使用。

---

CLI 参考 — 所有管道命令

每个命令均可使用以下全局选项：--token <string>（CLI 身份验证令牌）、--color（为输出添加颜色，默认值为 true）、-h, --help。

goldsky pipeline apply <config-path>

根据 YAML 配置文件创建或更新管道。具备幂等性。

标志	类型	描述
--status	ACTIVE | INACTIVE | PAUSED	期望的管道状态
--from-snapshot	string	指定起始快照：last、new、none 或快照 ID。last = 最新可用快照。new = 先创建新的快照。none = 从头开始。默认值：new
--force	boolean	跳过确认提示（适用于 CI）
--skip-transform-validation	boolean	更新时跳过转换验证
--save-progress	boolean	(deprecated, use --from-snapshot) 应用前尝试创建快照
--use-latest-snapshot	boolean	(deprecated, use --from-snapshot) 从最新快照开始
--skip-validation	boolean	(deprecated) 等同于 --skip-transform-validation

goldsky pipeline apply my-pipeline.yaml --status ACTIVE
goldsky pipeline apply my-pipeline.yaml --status ACTIVE --from-snapshot last
goldsky pipeline apply my-pipeline.yaml --force   # CI/CD usage

goldsky pipeline start <nameOrConfigPath>

启动管道（等同于使用 --status ACTIVE 执行 apply）。

标志	类型	描述
--from-snapshot	string	last、new、none 或快照 ID
--use-latest-snapshot	boolean	（已弃用，请改用 --from-snapshot）

goldsky pipeline stop <nameOrConfigPath>

停止管道，不创建快照。将状态设为 INACTIVE，运行时设为 TERMINATED。

除全局选项外，没有其他标志。

goldsky pipeline pause <nameOrConfigPath>

暂停管道并创建快照，以便从暂停处恢复。将状态设为 PAUSED，运行时设为 TERMINATED。

除全局选项外，没有其他标志。

goldsky pipeline restart <nameOrConfigPath>

在不更改配置的情况下重启管道。当接收器数据库重启、连接卡住等情况时，此操作很有用。

标志	类型	描述
--from-snapshot	string	必填。 last、new、none 或快照 ID
--disable-monitoring	boolean	重启后跳过监控（默认值：false）

goldsky pipeline restart my-pipeline --from-snapshot last
goldsky pipeline restart my-pipeline --from-snapshot none  # restart from scratch

goldsky pipeline get <nameOrConfigPath>

获取管道配置和状态。

标志	类型	描述
--outputFormat, --output	json | table | yaml	输出格式（默认值：yaml）
--definition	boolean	仅打印管道定义（数据源、转换、接收器）
-v, --version	string	管道版本（默认值：latest）

goldsky pipeline list

列出项目中的所有管道。

标志	类型	描述
--output, --outputFormat	json | table | yaml	输出格式（默认值：table）
--outputVerbosity	summary | usablewithapplycmd | all	详细程度（默认值：summary）
--include-runtime-details	boolean	包含运行时状态和错误（默认值：false）

goldsky pipeline list --output json
goldsky pipeline list --include-runtime-details

goldsky pipeline info <nameOrConfigPath>

显示管道信息（状态、配置、运行时详细信息）。

标志	类型	描述
-v, --version	string	管道版本（默认值：latest）

goldsky pipeline monitor <nameOrConfigPath>

监控管道运行时信息——状态、指标（接收／写入的记录数）和错误。每 10 秒刷新一次。

标志	类型	描述
--update-request	boolean	监控正在进行的更新请求
--max-refreshes, --maxRefreshes	number	最大数据刷新次数
-v, --version	string	管道版本（默认值：latest）

goldsky pipeline delete <nameOrConfigPath>

永久删除管道。

标志	类型	描述
-f, --force	boolean	强制删除，不显示确认提示（默认值：false）

goldsky pipeline resize <nameOrConfigPath> <resourceSize>

更改管道的计算资源。

位置参数	描述
resourceSize	可选值：s、m、l、xl、xxl（默认值：s）

goldsky pipeline resize my-pipeline l

goldsky pipeline validate [config-path]

验证管道 YAML 配置，但不进行部署。

标志	类型	描述
--definition	string	（已弃用） 内联 JSON 定义
--definition-path	string	（已弃用） JSON/YAML 定义的路径

goldsky pipeline validate my-pipeline.yaml

goldsky pipeline export [name]

导出管道配置。

标志	类型	描述
--all	boolean	导出所有管道的配置

goldsky pipeline cancel-update <nameOrConfigPath>

取消正在进行的更新或快照请求。当长时间运行的快照阻碍了必要的更新时，此操作很有用。

除全局选项外，没有其他标志。

goldsky pipeline create <name> (交互式／引导式)

通过引导式 CLI 交互创建管道。

标志	类型	描述
--resource-size, --resourceSize	s | m | l | xl | xxl	资源规格（默认值：s）
--use-dedicated-ip	boolean	使用专用出口 IP（默认值：false）
--skip-transform-validation	boolean	跳过转换验证
--status	ACTIVE | INACTIVE	(已弃用，请使用 pipeline start/stop/pause)
--description	string	(已弃用，请使用 pipeline apply)
--definition	string	(已弃用，请使用 pipeline apply)
--definition-path	string	(已弃用，请使用 pipeline apply)
--output, --outputFormat	json | table | yaml	输出格式（默认值：yaml）

goldsky pipeline get-definition <name> (已弃用)

获取可分享的管道定义。请改用 goldsky pipeline get <name> --definition。

快照命令

# List snapshots for a pipeline
goldsky pipeline snapshots list <nameOrConfigPath> [-v <version>]

# Create a snapshot manually
goldsky pipeline snapshots create <nameOrConfigPath>

snapshots list 支持使用 -v, --version 按管道版本筛选（默认：所有版本）。

---

生命周期速查

操作	命令
部署／启动	goldsky pipeline apply <file.yaml> --status ACTIVE
启动（现有管道）	goldsky pipeline start <name>
暂停（创建快照）	goldsky pipeline pause <name>
停止（不创建快照）	goldsky pipeline stop <name>
重启（不更改配置）	goldsky pipeline restart <name> --from-snapshot last
更新配置	goldsky pipeline apply <file.yaml>（先编辑 YAML）
调整规格	goldsky pipeline resize <name> <size>
验证 YAML	goldsky pipeline validate <file.yaml>
监控	goldsky pipeline monitor <name>
获取配置	goldsky pipeline get <name> --definition
导出配置	goldsky pipeline export <name>
删除	goldsky pipeline delete <name> -f
取消进行中的操作	goldsky pipeline cancel-update <name>
列出快照	goldsky pipeline snapshots list <name>
创建快照	goldsky pipeline snapshots create <name>
列出所有管道	goldsky pipeline list

暂停与停止：

• pause — 创建快照并暂停管道（状态：PAUSED + TERMINATED）。之后可以从暂停处恢复。
• stop — 停止管道，但不创建快照（状态：INACTIVE + TERMINATED）。恢复时可能会重新处理数据。

期望状态： ACTIVE、INACTIVE、PAUSED 运行时状态： STARTING、RUNNING、FAILING、TERMINATED

---

快照

快照记录 RUNNING 管道在某一时刻的状态，以便恢复运行。快照包含读取数据源的进度和 SQL 转换状态，不包含接收端状态。

• 自动快照：健康的 RUNNING 管道每 4 小时创建一次快照。
• 更新前： 对 RUNNING 管道应用配置更改前，会自动创建快照。
• 暂停时： 暂停管道时会创建快照。
• 手动创建： goldsky pipeline snapshots create <name>。
• 恢复： 只能使用最新快照。如需使用较早的快照，请联系支持团队。

--from-snapshot 标志（用于 apply、start、restart）用于控制快照行为：

• new — 创建新快照，然后从该快照启动（默认值）
• last — 使用最新的现有快照（不创建新快照）
• none — 从头开始，不使用快照
• <snapshot-id> — 使用指定快照

---

资源规格

通过 YAML 中的 resource_size 或 goldsky pipeline resize <name> <size> 设置。

规格	描述
s	默认规格。适用于大多数场景、小型链的回填、每秒最多 300K 条记录，以及最多约 8 个子图数据源
m、l、xl、xxl	更大的计算资源，适用于大型链回填或大型 JOIN

建议从较小规格开始，并按需扩容。资源规格会影响定价。

---

Networking

• Mirror 流水线会从 AWS us-west-2 写入数据。请确保你的接收端允许来自该区域的入站连接。
• IP 地址默认是动态的。
• 可按需提供专用出口 IP——在 pipeline create 中使用 --use-dedicated-ip，或联系 [email protected]。
• 可按需提供 VPC 对等连接。
• 对于外部处理器转换，请部署在靠近 us-west-2 的位置以获得最佳性能（目标为 p95 < 100ms）。

---

数据集发现

# List available datasets (non-interactive)
goldsky dataset list --output json

# Get schema for a specific dataset
goldsky dataset get <dataset_name>

---

常见问题

Mirror 流水线可以使用子图作为来源吗？ 可以——这是 Mirror 相较于 Turbo 的主要优势。在来源中设置 type: subgraph_entity，并引用已部署的子图。

Mirror 可以处理多个来源或跨链数据吗？ 可以——在 YAML 中定义多个来源，并使用 SQL 转换进行联接或合并。对于子图，你可以在单个来源的 subgraphs 数组中列出多个子图（来自不同链）。

我的流水线需要更多资源／速度太慢，怎么办？ 运行 goldsky pipeline resize <name> l（或 xl、xxl）。先从较小规格开始，再逐步扩容。

我的流水线处于 ACTIVE 状态，但已 TERMINATED——发生了什么？ 期望状态为 ACTIVE，但运行时发生故障（例如密钥错误、接收端不可用或资源问题）。运行 goldsky pipeline monitor <name> --include-runtime-details 检查错误，或查看仪表板。修复问题后重启。

如何在不丢失进度的情况下更新流水线？ 编辑 YAML 并运行 goldsky pipeline apply <file.yaml>。默认情况下，应用更新前会创建快照。使用 --from-snapshot last 可跳过创建新快照，并使用最新的现有快照。

长时间运行的快照阻碍了更新，该怎么办？ 运行 goldsky pipeline cancel-update <name> 取消正在进行的操作，然后使用 --from-snapshot last 或 --from-snapshot none 重新应用。

---

相关内容

• /turbo-builder — 构建新的 Turbo 流水线（适用于不使用子图来源的新项目，推荐）
• /subgraph-builder — 构建并部署你想通过 Mirror 同步的子图
• /secrets — 为接收端凭据创建密钥
• /datasets — 浏览可用的数据集名称和链前缀
• Goldsky 文档： docs.goldsky.com/mirror/introduction
• 流水线配置参考： docs.goldsky.com/mirror/reference/config-file/pipeline