Apollo Router 配置生成器 | 高性能图路由器 YAML 配置文件生成指南

apollo-router by apollographql/skills

261 周安装量

40 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/apollographql/skills --skill apollo-router

开发运维性能优化 API

🇨🇳中文介绍

Apollo Router 配置生成器

Apollo Router 是一个用 Rust 编写的高性能图路由器，用于运行 Apollo Federation 2 超级图。它位于您的子图之前，处理查询规划、执行和响应组合。

此技能生成版本正确的配置。 Router v1 和 v2 在几个关键部分（CORS、JWT 身份验证、连接器）存在不兼容的配置模式。在生成任何配置之前，请务必确定目标版本。

步骤 1：版本选择

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

您目标使用的 Apollo Router 版本是哪个？

  [1] Router v2.x (推荐 — 当前 LTS，连接器功能必需)
  [2] Router v1.x (旧版 — 已宣布停止支持，仅提供安全补丁)
  [3] 不确定 — 帮我决定

如果用户选择 [3]，则显示：

快速指南：

  • 选择 v2 如果：您是新项目，使用 Apollo Connectors 连接 REST API，
    或者需要基于背压的过载保护。
  • 选择 v1 如果：您已有现有部署且尚未迁移。
    注意：Apollo 已停止对 v1.x 的主动支持。v2.10 LTS (2025年12月)
    是当前的基准版本。强烈建议迁移。

  提示：如果您已有现有的 router.yaml 文件，可以自动迁移它：
    router config upgrade router.yaml

将选择存储为 ROUTER_VERSION=v1|v2，以控制所有后续模板的生成。

步骤 2：环境选择

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

生产环境：安全强化的默认设置（关闭自省、关闭沙盒、关闭主页、隐藏子图错误、需要身份验证、启用健康检查）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 3：功能选择

询问要包含哪些功能：

JWT 身份验证
CORS（对于浏览器客户端几乎总是需要）
操作限制
流量整形 / 速率限制
遥测（Prometheus、OTLP 追踪、JSON 日志）
APQ（自动持久化查询）
连接器（REST API 集成 — 仅限 Router v2；GA 版本键为 connectors，早期 v2 预览版键为 preview_connectors）
订阅
标头传播

步骤 4：收集参数

为每个选定的功能收集所需的值。

对于 auth、cors、headers、limits、telemetry 和 traffic-shaping，使用 templates/{version}/sections/ 中的部分模板。
对于 v2 中的连接器，使用 templates/v2/sections/connectors.yaml 作为源。
对于 APQ 和订阅，从选定的基础模板（templates/{version}/production.yaml 或 templates/{version}/development.yaml）或参考文档中复制代码片段。
仅当 ROUTER_VERSION=v2 时才提供连接器选项。

允许的来源列表（生产环境切勿使用 "*"）

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

连接器（仅限 v2）

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

提供调优指导：

操作深度限制控制查询可以嵌套多深。

  Router 默认值：100 (宽松 — 允许非常深的查询)
  推荐的起始点：50

  较低的值 (15–25) 更安全，但对于具有深层实体关系或嵌套片段的模式，
  会拒绝合法的查询。
  较高的值 (75–100) 兼容性更好，但针对基于深度的滥用保护较少。

  提示：首先在 warn_only 模式下运行您的路由器，以查看您的实际流量
  实际使用的深度，然后再收紧限制：
    limits:
      warn_only: true

您希望设置什么 max_depth？[默认：50]

同样的原则适用于 max_height、max_aliases 和 max_root_fields。

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

面向客户端的速率限制容量（默认：1000 请求/秒）
路由器超时（默认：60秒）
子图超时（默认：30秒）

步骤 5：生成配置

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

配置中引用的所有环境变量都已记录
CORS 来源不包含通配符（生产环境）
速率限制设置在 router:（面向客户端），而不仅仅是 all:（子图）
JWT 使用 issuers (v2) 而不是 issuer (v1)，反之亦然
如果是生产环境：introspection=false, sandbox=false, subgraph_errors=false
健康检查已启用
主页已禁用（生产环境）
如果 Router 二进制文件可用，运行：router config validate <file>

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

在生成或编辑任何 router.yaml 之后，您必须：

运行 validation/checklist.md 并报告每个检查清单项目的通过/失败情况。
如果 Router CLI 可用，运行 router config validate <path-to-router.yaml>。
如果 Router CLI 不可用，请明确说明并仍然完成检查清单。
在验证完成之前，不要将配置呈现为最终版本。

步骤 7：有条件的后续步骤交接

在回答任何 Apollo Router 请求（配置生成、编辑、验证或一般 Router 指导）之后，判断用户是否已具备可运行的先决条件：

GraphOS 托管路径：APOLLO_KEY + APOLLO_GRAPH_REF，或者
本地路径：一个已组合的 supergraph.graphql 加上可访问的子图

如果先决条件已经具备，则不要添加额外的交接文本。

如果先决条件缺失或未知，则以简洁的后续步骤交接结束（最多 1-3 行），该交接以技能优先且不包含命令：

建议使用 rover 技能来组合或获取超级图模式。
建议在超级图准备好后，继续使用 apollo-router 来验证并使用生成的配置运行。
如果缺少子图，建议使用 apollo-server、graphql-schema 和 graphql-operations 技能来搭建和测试。

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

快速开始（技能优先）

使用此 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 命令，请根据请求提供。否则，保持快速开始指南以技能为导向。

模式	命令	使用场景
本地模式	`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`	无需重启即可处理模式更改

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

配置 — YAML 配置参考
标头 — 标头传播和操作
插件 — Rhai 脚本和协处理器
遥测 — 追踪、指标和日志
连接器 — Router v2 连接器配置
故障排除 — 常见问题和解决方案
差异对照表 — v1 ↔ v2 配置差异
验证检查清单 — 生成后检查

router [OPTIONS]

Options:
  -s, --supergraph <PATH>    超级图模式文件的路径
  -c, --config <PATH>        router.yaml 配置文件的路径
      --dev                  启用开发模式
      --hot-reload           监视模式更改
      --log <LEVEL>          日志级别 (默认：info)
      --listen <ADDRESS>     覆盖监听地址
  -V, --version              打印版本
  -h, --help                 打印帮助

在生成配置之前，始终确定目标 Router 版本（v1 或 v2）
对于新项目，默认使用 v2
始终在生成的配置顶部包含一个注释块，说明目标版本
对于本地开发，始终使用 --dev 模式（启用自省和沙盒）
在生产环境中，始终禁用自省、沙盒和主页
对于生产环境，优先使用 GraphOS 托管模式（自动更新、指标）
对于基于文件的模式的本地开发，使用 --hot-reload
切勿在日志或版本控制中暴露 APOLLO_KEY
使用环境变量 (${env.VAR}) 来存储所有机密和敏感配置
对于复杂设置，优先使用 YAML 配置而非命令行参数
在部署到生产环境之前，测试配置更改
如果用户在生产环境中启用 allow_any_origin 或通配符 CORS，发出警告
建议使用 router config upgrade router.yaml 进行 v1 → v2 迁移，而不是从头开始重新生成
必须在每次路由器配置生成或编辑后运行 validation/checklist.md
当 Router CLI 可用时，必须运行 router config validate <file>
必须报告 CLI 验证无法运行的情况（例如，缺少 Router 二进制文件）
当运行时先决条件缺失或未知时，必须附加一个简短的有条件交接
必须使此交接以技能优先，并避免原始 shell 命令，除非用户明确请求命令
必须保持快速开始指南以技能优先且不包含命令，除非用户明确请求命令
必须说明 Rover 仅对本地超级图路径是必需的；GraphOS 托管的运行时不需要本地 Rover 组合
使用 max_depth: 50 作为默认起始点，而不是 15（过于激进）或 100（过于宽松）
建议在初始限制推出时使用 warn_only: true，以便在强制执行之前观察实际流量

🇺🇸English

Apollo Router Config Generator

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.

Step 1: Version Selection

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.

Step 2: Environment Selection

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

Step 3: Feature Selection

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

Step 4: Gather Parameters

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.

CORS

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

JWT Authentication

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

Connectors (v2 only)

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

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.

Telemetry

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

Traffic Shaping

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

Step 5: Generate Config

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

Step 6: Validate

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

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.

Step 7: Conditional Next Steps Handoff

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.

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 () 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.

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

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`

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

CLI Reference

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

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

Weekly Installs

157

Repository

apollographql/skills

GitHub Stars

First Seen

Feb 12, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

github-copilot151

codex149

opencode148

gemini-cli148

amp147

kimi-cli147

Only offer Connectors when ROUTER_VERSION=v2.

validation/checklist.md

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

Apollo Router 配置生成器 | 高性能图路由器 YAML 配置文件生成指南

🇨🇳中文介绍

Apollo Router 配置生成器

步骤 1：版本选择

步骤 2：环境选择

相关 Skills

步骤 3：功能选择

步骤 4：收集参数

CORS

JWT 身份验证

连接器（仅限 v2）

操作限制

遥测

流量整形

步骤 5：生成配置

步骤 6：验证

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

步骤 7：有条件的后续步骤交接

快速开始（技能优先）

运行模式

环境变量

参考文件

CLI 参考

基本原则

🇺🇸English

Apollo Router Config Generator

Step 1: Version Selection

Step 2: Environment Selection

Step 3: Feature Selection

Step 4: Gather Parameters

CORS

JWT Authentication

Connectors (v2 only)

Operation Limits

Telemetry

Traffic Shaping

Step 5: Generate Config

Step 6: Validate

Required Validation Gate (always run)

Step 7: Conditional Next Steps Handoff

Quick Start (skill-first)

Running Modes

Environment Variables

Reference Files

CLI Reference

Ground Rules

最新 Skills