apollo-router

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apollo Router Config Generator

Apollo Router配置生成器

Apollo Router is a high-performance graph router written in Rust for running Apollo Federation 2 supergraphs. It sits in front of your subgraphs and handles query planning, execution, and response composition.

This skill generates version-correct configuration. Router v1 and v2 have incompatible config schemas in several critical sections (CORS, JWT auth, connectors). Always determine the target version before generating any config.

Apollo Router是用Rust编写的高性能图路由工具，用于运行Apollo Federation 2超图。它位于子图前端，负责查询规划、执行和响应组合。

本技能可生成适配对应版本的配置。Router v1和v2在多个关键配置区域（CORS、JWT认证、连接器）的配置模式不兼容。生成任何配置前，请务必确定目标版本。

Step 1: Version Selection

步骤1：版本选择

Ask the user before generating any config:

Which Apollo Router version are you targeting?

  [1] Router v2.x (recommended — current LTS, required for Connectors)
  [2] Router v1.x (legacy — end-of-support announced, security patches only)
  [3] Not sure — help me decide

If the user picks [3], display:

Quick guide:

  • Pick v2 if: you're starting fresh, using Apollo Connectors for REST APIs,
    or want backpressure-based overload protection.
  • Pick v1 if: you have an existing deployment and haven't migrated yet.
    Note: Apollo ended active support for v1.x. The v2.10 LTS (Dec 2025)
    is the current baseline. Migration is strongly recommended.

  Tip: If you have an existing router.yaml, you can auto-migrate it:
    router config upgrade router.yaml

Store the selection as

ROUTER_VERSION=v1|v2

to gate all subsequent template generation.

在生成任何配置前，询问用户：

你目标使用的Apollo Router版本是？

  [1] Router v2.x（推荐——当前LTS版本，使用Connectors必需）
  [2] Router v1.x（旧版本——已宣布停止主动支持，仅提供安全补丁）
  [3]不确定——帮我选择

如果用户选择**[3]**，展示：

快速指南：

  • 若你是全新搭建、使用Apollo Connectors对接REST API，或需要基于背压的过载保护，请选择v2。
  • 若你已有现有部署且尚未迁移，请选择v1。
    注意：Apollo已终止对v1.x的主动支持。当前基准版本是v2.10 LTS（支持至2025年12月），强烈建议迁移。

  提示：若你已有router.yaml文件，可通过以下命令自动迁移：
    router config upgrade router.yaml

将用户选择存储为

ROUTER_VERSION=v1|v2

，用于后续所有模板生成的版本控制。

Step 2: Environment Selection

步骤2：环境选择

Ask: Production or Development?

Production: security-hardened defaults (introspection off, sandbox off, homepage off, subgraph errors hidden, auth required, health check on)
Development: open defaults (introspection on, sandbox on, errors exposed, text logging)

Load the appropriate base template from:

```
templates/{version}/production.yaml
```
```
templates/{version}/development.yaml
```

询问：生产环境还是开发环境？

生产环境：安全加固的默认配置（关闭自省、关闭沙箱、关闭首页、隐藏子图错误、要求认证、启用健康检查）
开发环境：开放的默认配置（开启自省、开启沙箱、暴露错误、文本日志）

从以下路径加载对应基础模板：

```
templates/{version}/production.yaml
```
```
templates/{version}/development.yaml
```

Step 3: Feature Selection

步骤3：功能选择

Ask which features to include:

JWT Authentication
CORS (almost always yes for browser clients)
Operation Limits
Traffic Shaping / Rate Limiting
Telemetry (Prometheus, OTLP tracing, JSON logging)
APQ (Automatic Persisted Queries)
Connectors (REST API integration — Router v2 only; GA key is
```
connectors
```
, early v2 preview key was
```
preview_connectors
```
)
Subscriptions
Header Propagation

询问用户需要包含哪些功能：

JWT认证
CORS（浏览器客户端几乎都需要开启）
操作限制
流量整形/速率限制
遥测（Prometheus、OTLP追踪、JSON日志）
APQ（自动持久化查询）
连接器（REST API集成——仅Router v2支持；正式版配置键为
```
connectors
```
，v2早期预览版配置键为
```
preview_connectors
```
）
订阅
请求头传播

Step 4: Gather Parameters

步骤4：收集参数

For each selected feature, collect required values.

Use section templates from

templates/{version}/sections/

for

auth

cors

headers

limits

telemetry

, and

traffic-shaping

For Connectors in v2, use
```
templates/v2/sections/connectors.yaml
```
as the source.
For APQ and subscriptions, copy the snippet from the selected base template (
```
templates/{version}/production.yaml
```
or
```
templates/{version}/development.yaml
```
) or from references.
Only offer Connectors when
```
ROUTER_VERSION=v2
```
.

针对每个选中的功能，收集所需参数。

从

templates/{version}/sections/

路径加载

auth

、

cors

、

headers

、

limits

、

telemetry

和

traffic-shaping

的分段模板。

对于v2版本的连接器，使用
```
templates/v2/sections/connectors.yaml
```
作为模板源。
对于APQ和订阅，从选中的基础模板（
```
templates/{version}/production.yaml
```
或
```
templates/{version}/development.yaml
```
）或参考文档中复制代码片段。
仅当
```
ROUTER_VERSION=v2
```
时，才提供连接器选项。

CORS

List of allowed origins (never use
```
"*"
```
for production)

允许的源列表（生产环境绝不要使用
```
"*"
```
）

JWT Authentication

JWT认证

JWKS URL
Issuer(s) — note: v1 uses singular
```
issuer
```
, v2 uses plural
```
issuers
```
array

JWKS URL
签发者——注意：v1使用单数
```
issuer
```
，v2使用复数数组
```
issuers
```

Connectors (v2 only)

连接器（仅v2支持）

Subgraph name and source name (used as
```
connectors.sources.<subgraph>.<source>
```
)
Optional
```
$config
```
values for connector runtime configuration
If migrating old v2 preview config, rename
```
preview_connectors
```
to
```
connectors
```

子图名称和源名称（用于
```
connectors.sources.<subgraph>.<source>
```
）
可选的
```
$config
```
值，用于连接器运行时配置
若迁移旧版v2预览版配置，需将
```
preview_connectors
```
重命名为
```
connectors
```

Operation Limits

操作限制

Present the tuning guidance:

Operation depth limit controls how deeply nested a query can be.

  Router default: 100 (permissive — allows very deep queries)
  Recommended starting point: 50

  Lower values (15–25) are more secure but will reject legitimate queries
  in schemas with deep entity relationships or nested fragments.
  Higher values (75–100) are safer for compatibility but offer less
  protection against depth-based abuse.

  Tip: Run your router in warn_only mode first to see what depths your
  real traffic actually uses, then tighten:
    limits:
      warn_only: true

What max_depth would you like? [default: 50]

The same principle applies to

max_height

max_aliases

, and

max_root_fields

展示调优指南：

操作深度限制用于控制查询的嵌套深度。

  Router默认值：100（宽松设置——允许极深的查询）
  推荐起始值：50

  较低的值（15–25）安全性更高，但会在具有深度实体关系或嵌套片段的 schema 中拒绝合法查询
  较高的值（75–100）兼容性更好，但对基于深度的攻击防护较弱

  提示：先以warn_only模式运行Router，查看实际流量的查询深度，再收紧限制：
    limits:
      warn_only: true

你想要设置的max_depth是多少？[默认值：50]

该原则同样适用于

max_height

、

max_aliases

和

max_root_fields

。

Telemetry

遥测

OTEL collector endpoint (default:
```
http://otel-collector:4317
```
)
Prometheus listen port (default:
```
9090
```
)
Trace sampling rate (default:
```
0.1
```
= 10%)

OTEL收集器端点（默认：
```
http://otel-collector:4317
```
）
Prometheus监听端口（默认：
```
9090
```
）
追踪采样率（默认：
```
0.1
```
= 10%）

Traffic Shaping

流量整形

Client-facing rate limit capacity (default: 1000 req/s)
Router timeout (default: 60s)
Subgraph timeout (default: 30s)

客户端侧速率限制容量（默认：1000 请求/秒）
Router超时时间（默认：60秒）
子图超时时间（默认：30秒）

Step 5: Generate Config

步骤5：生成配置

Load the correct version template from
```
templates/{version}/
```
Assemble section templates for supported sectioned features, then merge base-template snippets for APQ/subscriptions as needed
Inject user-provided parameters
Add a comment block at the top stating the target version

从
```
templates/{version}/
```
加载对应版本的模板
为支持的分段功能组装分段模板，再根据需要合并基础模板中的APQ/订阅代码片段
注入用户提供的参数
在配置顶部添加注释块，说明目标版本

Step 6: Validate

步骤6：验证

Run the post-generation checklist:

All env vars referenced in config are documented
CORS origins don't include wildcards (production)
Rate limiting is on
```
router:
```
(client-facing), not only
```
all:
```
(subgraph)
JWT uses
```
issuers
```
(v2) not
```
issuer
```
(v1), or vice versa
If production: introspection=false, sandbox=false, subgraph_errors=false
Health check is enabled
Homepage is disabled (production)
Run:
```
router config validate <file>
```
if Router binary is available

执行生成后检查清单：

配置中引用的所有环境变量均已文档化
CORS源不包含通配符（生产环境）
速率限制配置在
```
router:
```
（客户端侧），而非仅在
```
all:
```
（子图侧）
JWT配置在v2中使用
```
issuers
```
，v1中使用
```
issuer
```
，版本对应正确
若为生产环境：introspection=false、sandbox=false、subgraph_errors=false
已启用健康检查
已禁用首页（生产环境）
若Router二进制文件可用，执行：
```
router config validate <file>
```

Required Validation Gate (always run)

必须执行的验证关卡（始终运行）

After generating or editing any

router.yaml

, you MUST:

Run
```
validation/checklist.md
```
and report pass/fail for each checklist item.

Run

router config validate <path-to-router.yaml>

if Router CLI is available.

If Router CLI is unavailable, state that explicitly and still complete the checklist.
Do not present the configuration as final until validation is completed.

在生成或编辑任何

router.yaml

后，你必须：

执行
```
validation/checklist.md
```
并报告每个检查项的通过/失败情况。

若Router CLI可用，执行

router config validate <path-to-router.yaml>

。

若Router CLI不可用，需明确说明，并仍需完成检查清单。
在验证完成前，不得将配置作为最终版本交付。

Step 7: Conditional Next Steps Handoff

步骤7：条件式后续步骤交接

After answering any Apollo Router request (config generation, edits, validation, or general Router guidance), decide whether the user already has runnable prerequisites:

GraphOS-managed path:
```
APOLLO_KEY
```
+
```
APOLLO_GRAPH_REF
```
, or
Local path: a composed
```
supergraph.graphql
```
plus reachable subgraphs

If prerequisites are already present, do not add extra handoff text.

If prerequisites are missing or unknown, end with a concise Next steps handoff (1-3 lines max) that is skill-first and command-free:

Suggest the
```
rover
```
skill to compose or fetch the supergraph schema.
Suggest continuing with
```
apollo-router
```
once the supergraph is ready to validate and run with the generated config.
If subgraphs are missing, suggest
```
apollo-server
```
,
```
graphql-schema
```
, and
```
graphql-operations
```
skills to scaffold and test.

Do not include raw shell commands in this handoff unless the user explicitly asks for commands.

在处理完任何Apollo Router请求（配置生成、编辑、验证或通用Router指导）后，判断用户是否已具备可运行的前置条件：

GraphOS托管路径：拥有
```
APOLLO_KEY
```
+
```
APOLLO_GRAPH_REF
```
，或
本地路径：已合成的
```
supergraph.graphql
```
+ 可访问的子图

若用户已具备前置条件，无需添加额外交接文本。

若用户缺失或未知前置条件，以简洁的后续步骤交接结尾（最多1-3行），以技能为导向，避免直接提供命令：

建议使用
```
rover
```
技能合成或获取超图schema。
建议在超图准备就绪后，继续使用
```
apollo-router
```
技能验证并运行生成的配置。
若缺失子图，建议使用
```
apollo-server
```
、
```
graphql-schema
```
和
```
graphql-operations
```
技能搭建并测试。

除非用户明确要求，否则在此交接部分不要包含原始Shell命令。

Quick Start (skill-first)

快速开始（以技能为导向）

Use this
```
apollo-router
```
skill to generate or refine
```
router.yaml
```
for your environment.
Choose a runtime path:
- GraphOS-managed path: provide
```
APOLLO_KEY
```
  and
```
APOLLO_GRAPH_REF
```
  (no local supergraph composition required).
- Local supergraph path: use
```
graphql-schema
```
  +
```
apollo-server
```
  to define/run subgraphs, then use
```
graphql-operations
```
  for smoke tests, then use the
```
rover
```
  skill to compose or fetch
```
supergraph.graphql
```
  .
Use this
```
apollo-router
```
skill to validate readiness (
```
validation/checklist.md
```
) and walk through runtime startup inputs.

Default endpoint remains

http://localhost:4000

when using standard Router listen defaults.

If the user asks for executable shell commands, provide them on request. Otherwise keep Quick Start guidance skill-oriented.

使用本
```
apollo-router
```
技能为你的环境生成或优化
```
router.yaml
```
。
选择运行路径：
- GraphOS托管路径：提供
```
APOLLO_KEY
```
  和
```
APOLLO_GRAPH_REF
```
  （无需本地超图合成）。
- 本地超图路径：使用
```
graphql-schema
```
  +
```
apollo-server
```
  定义/运行子图，再使用
```
graphql-operations
```
  进行冒烟测试，最后使用
```
rover
```
  技能合成或获取
```
supergraph.graphql
```
  。
使用本
```
apollo-router
```
技能验证就绪状态（
```
validation/checklist.md
```
）并引导完成运行时启动配置。

使用标准Router监听默认配置时，默认端点为

http://localhost:4000

。

若用户要求可执行Shell命令，再按需提供；否则保持快速开始指导以技能为导向。

Running Modes

运行模式

Mode	Command	Use Case
Local schema	`router --supergraph ./schema.graphql`	Development, CI/CD
GraphOS managed	`APOLLO_KEY=... APOLLO_GRAPH_REF=my-graph@prod router`	Production with auto-updates
Development	`router --dev --supergraph ./schema.graphql`	Local development
Hot reload	`router --hot-reload --supergraph ./schema.graphql`	Schema changes without restart

模式	命令	适用场景
本地Schema	`router --supergraph ./schema.graphql`	开发、CI/CD
GraphOS托管	`APOLLO_KEY=... APOLLO_GRAPH_REF=my-graph@prod router`	生产环境（支持自动更新）
开发模式	`router --dev --supergraph ./schema.graphql`	本地开发
热重载	`router --hot-reload --supergraph ./schema.graphql`	无需重启即可更新Schema

Environment Variables

环境变量

Variable	Description
`APOLLO_KEY`	API key for GraphOS
`APOLLO_GRAPH_REF`	Graph reference ( `graph-id@variant` )
`APOLLO_ROUTER_CONFIG_PATH`	Path to `router.yaml`
`APOLLO_ROUTER_SUPERGRAPH_PATH`	Path to supergraph schema
`APOLLO_ROUTER_LOG`	Log level (off, error, warn, info, debug, trace)
`APOLLO_ROUTER_LISTEN_ADDRESS`	Override listen address

变量	描述
`APOLLO_KEY`	GraphOS的API密钥
`APOLLO_GRAPH_REF`	图引用（ `graph-id@variant` ）
`APOLLO_ROUTER_CONFIG_PATH`	`router.yaml` 的路径
`APOLLO_ROUTER_SUPERGRAPH_PATH`	超图Schema的路径
`APOLLO_ROUTER_LOG`	日志级别（off、error、warn、info、debug、trace）
`APOLLO_ROUTER_LISTEN_ADDRESS`	覆盖监听地址

Reference Files

参考文件

Configuration — YAML configuration reference
Headers — Header propagation and manipulation
Plugins — Rhai scripts and coprocessors
Telemetry — Tracing, metrics, and logging
Connectors — Router v2 connectors configuration
Troubleshooting — Common issues and solutions
Divergence Map — v1 ↔ v2 config differences
Validation Checklist — Post-generation checks

配置 — YAML配置参考
请求头 — 请求头传播与处理
插件 — Rhai脚本与协处理器
遥测 — 追踪、指标与日志
连接器 — Router v2连接器配置
故障排查 — 常见问题与解决方案
版本差异映射 — v1 ↔ v2配置差异
验证检查清单 — 生成后检查项

CLI Reference

CLI参考

router [OPTIONS]

Options:
  -s, --supergraph <PATH>    Path to supergraph schema file
  -c, --config <PATH>        Path to router.yaml configuration
      --dev                  Enable development mode
      --hot-reload           Watch for schema changes
      --log <LEVEL>          Log level (default: info)
      --listen <ADDRESS>     Override listen address
  -V, --version              Print version
  -h, --help                 Print help

router [OPTIONS]

选项:
  -s, --supergraph <PATH>    超图Schema文件路径
  -c, --config <PATH>        router.yaml配置文件路径
      --dev                  启用开发模式
      --hot-reload           监听Schema变化
      --log <LEVEL>          日志级别（默认：info）
      --listen <ADDRESS>     覆盖监听地址
  -V, --version              打印版本
  -h, --help                 打印帮助信息

Ground Rules

基本原则

ALWAYS determine the target Router version (v1 or v2) before generating config
DEFAULT to v2 for new projects
ALWAYS include a comment block at top of generated config stating the target version
ALWAYS use
```
--dev
```
mode for local development (enables introspection and sandbox)
ALWAYS disable introspection, sandbox, and homepage in production
PREFER GraphOS managed mode for production (automatic updates, metrics)
USE
```
--hot-reload
```
for local development with file-based schemas
NEVER expose
```
APOLLO_KEY
```
in logs or version control
USE environment variables (
```
${env.VAR}
```
) for all secrets and sensitive config
PREFER YAML configuration over command-line arguments for complex setups
TEST configuration changes locally before deploying to production
WARN if user enables
```
allow_any_origin
```
or wildcard CORS in production
RECOMMEND
```
router config upgrade router.yaml
```
for v1 → v2 migration instead of regenerating from scratch
MUST run
```
validation/checklist.md
```
after every router config generation or edit
MUST run
```
router config validate <file>
```
when Router CLI is available
MUST report when CLI validation could not run (for example, Router binary missing)
MUST append a brief conditional handoff when runtime prerequisites are missing or unknown
MUST make this handoff skill-first and avoid raw shell commands unless the user explicitly requests commands
MUST keep Quick Start guidance skill-first and command-free unless the user explicitly requests commands
MUST state that Rover is required only for the local supergraph path; GraphOS-managed runtime does not require local Rover composition
USE
```
max_depth: 50
```
as the default starting point, not 15 (too aggressive) or 100 (too permissive)
RECOMMEND
```
warn_only: true
```
for initial limits rollout to observe real traffic before enforcing

生成配置前，必须确定目标Router版本（v1或v2）
新项目默认使用v2版本
生成的配置顶部必须添加注释块，说明目标版本
本地开发必须使用
```
--dev
```
模式（启用自省和沙箱）
生产环境必须关闭自省、沙箱和首页
生产环境优先选择GraphOS托管模式（自动更新、指标监控）
本地开发使用文件式Schema时，使用
```
--hot-reload
```
绝不要在日志或版本控制中暴露
```
APOLLO_KEY
```
所有密钥和敏感配置使用环境变量（
```
${env.VAR}
```
）
复杂配置优先使用YAML配置，而非命令行参数
配置变更在部署到生产环境前，必须先在本地测试
若用户在生产环境启用
```
allow_any_origin
```
或通配符CORS，需发出警告
推荐使用
```
router config upgrade router.yaml
```
进行v1 → v2迁移，而非从头生成配置
每次生成或编辑Router配置后，必须执行
```
validation/checklist.md
```
当Router CLI可用时，必须执行
```
router config validate <file>
```
必须说明无法执行CLI验证的情况（例如：缺失Router二进制文件）
当用户缺失或未知运行前置条件时，必须添加简短的条件式交接
交接内容必须以技能为导向，除非用户明确要求，否则避免提供原始Shell命令
快速开始指导必须以技能为导向，除非用户明确要求，否则避免提供命令
必须说明仅本地超图路径需要Rover；GraphOS托管运行时无需本地Rover合成
使用
```
max_depth: 50
```
作为默认起始值，而非15（过于严格）或100（过于宽松）
建议初始限制推出时使用
```
warn_only: true
```
，观察实际流量后再启用强制限制