fastly-cli

触发条件和范围

重要：许多子命令的路径不直观（例如，fastly domain create 会因 403 失败，正确路径是 fastly service domain create；日志配置位于 fastly service logging；警报位于 fastly service alert；速率限制位于 fastly service rate-limit）。

涵盖：服务、后端、域名、VCL 片段、缓存清除、Compute/WASM 部署、日志流式传输（S3/Datadog/Splunk/Kafka/25+ 个提供商）、NGWAF/WAF、TLS/mTLS、KV/配置/密钥存储、统计数据、警报、速率限制、ACL 和身份验证令牌。

Fastly CLI 概览

先决条件

需要安装 fastly CLI；执行 API 操作还需要能够访问 Fastly 的网络连接。 安装说明请参阅 https://www.fastly.com/documentation/reference/cli/。 JSON 示例还需要 jq；源站检查会用到 curl 和 openssl。 构建 Compute 应用需要项目所用的语言工具链及依赖项。

使用用户本地 CLI 或环境中已配置的凭据。 如果缺少身份验证，请让用户在本地完成 fastly auth login --sso，或在聊天之外配置 FASTLY_API_TOKEN。 切勿在聊天中索要 API 密钥、打印令牌，或在已通过身份验证的命令中启用 shell 跟踪。

参考资料

主题	文件	适用场景...
身份验证	auth.md	登录、已存储的令牌、服务身份验证、CI/CD 身份验证配置
Compute	compute.md	构建/部署边缘应用、本地开发服务器
服务	services.md	服务 CRUD、后端、域名、ACL、字典、VCL、缓存清除、速率限制
日志	logging.md	将日志流式传输到 S3、GCS、Datadog、Splunk、Kafka 和 25+ 个提供商
NGWAF	ngwaf.md	Next-Gen WAF 工作区、IP/国家/地区列表、规则、信号、阈值、警报
通知	notifications.md	Slack/PagerDuty/webhook 集成、审计日志事件映射
统计数据	stats.md	fastly stats 子命令分别接受哪些标志，以及两组标志有哪些差异
存储	stores.md	KV Stores、Config Stores、Secret Stores、资源链接
TLS	tls.md	平台 TLS、Let's Encrypt 订阅、自定义证书、双向 TLS

关于端点选择、单位和时间窗口约定，以及查询示例，请使用 fastly-stats 技能。

命令结构

fastly <command> <subcommand> [flags]

顶级命令

类别	命令
计算	compute - 构建并部署边缘应用
服务	service - 管理 CDN 服务、日志记录、后端、VCL、ACL、清除缓存
安全	ngwaf - Web 应用防火墙
TLS	tls-subscription、tls-custom、tls-platform、tls-config - 证书管理
存储	kv-store、config-store、secret-store - 边缘数据存储
身份验证	auth - 登录、已存储令牌、活动令牌输出、撤销；auth-token（已弃用）
信息	stats、ip-list、pops、whoami - 信息查询
通知	integration - 通知目标；audit-log event-mapping - 事件触发器
其他	dashboard、domain、dns、apisecurity、products、object-storage、tools

全局标志

适用于大多数命令：

# Service targeting
--service-id SERVICE_ID    # Target service by ID
--service-name NAME        # Target service by name
-s SERVICE_ID              # Short form

# Version targeting (version-scoped commands like `fastly service domain/backend/...`)
# NOTE: `fastly domain create` does NOT accept --version (it uses a different API)
--version VERSION          # Specific version number
--version active           # Currently active version
--version latest           # Most recent version
--version staged           # Currently staged version

# Authentication
--token TOKEN              # API token or stored token name (use 'default' for default)

# Output (--json is per-command, not global)
--verbose                  # Detailed output
--quiet                    # Minimal output

# Automation
--accept-defaults          # Accept default values
--auto-yes                 # Skip confirmations
--non-interactive          # No prompts

关键模式

• 按 ID 指定目标（-s SERVICE_ID）或按名称指定目标（--service-name NAME）
• 版本指定：--version active、--version latest、--version staged 或 --version N
• 使用 --autoclone 自动克隆已锁定的版本
• 使用 --json 生成脚本化输出；在 CI/CD 中使用 --non-interactive --accept-defaults
• JSON 字段名称因命令而异；编写 jq 选择器前请检查输出。
• ActiveVersion 的结构因情况而异；优先使用 --version active，或使用 jq -r '.ActiveVersion.Number // .ActiveVersion' 解析
• CLI 版本通过 fastly version 查询（而非 fastly --version）
• POP/Shield 查询使用 fastly pops；它没有 list 子命令，也不支持 --json；使用 SHIELD 列的值（而非 POP 的 CODE）作为 --shield 的参数
• 身份验证：使用 fastly auth login --sso 登录，或设置 FASTLY_API_TOKEN 环境变量
• 对于需要活动 API 令牌的命令，使用 $(fastly auth token)；使用 $(fastly auth token --token TOKEN_NAME) 选择特定的已存储令牌
• auth token 会拒绝向终端输出，但 Agent 捕获的 stdout 可能并非终端；切勿单独运行该命令或回显其结果
• 日志记录位于 service logging 下（例如，fastly service logging s3 create）
• 配置：使用 fastly config --location 查找平台特定的 CLI 配置文件；fastly.toml 是项目清单

常见标志示例

以下标志最容易引起混淆。请直接复制并粘贴这些模式。

自动克隆（现有服务版本）

# --autoclone automatically clones a locked version before making changes.
# Without it, you get "version is locked" errors and waste time cloning manually.
fastly service backend create --service-id $SID --version active --autoclone \
  --name my-origin --address origin.example.com --port 443 --use-ssl

fastly service domain create --service-id $SID --version active --autoclone \
  --name cdn.example.com

在现有服务上创建、更新或删除后端、域名、代码片段、VCL、条件、标头或其他受版本限制的资源时，请传入 --autoclone。 对于全新服务，请使用未锁定的 --version 1 进行配置，不要使用 --autoclone；然后按下方的新服务工作流所示进行验证并激活一次。

布尔标志（--use-ssl；--use-ssl 不等同于 --use-ssl true）

# CORRECT - boolean flags are bare, no value
fastly service backend create --name origin --address example.com --port 443 --use-ssl

# WRONG - do not pass a value to boolean flags
fastly service backend create --name origin --address example.com --port 443 --use-ssl true

其他用法相同的布尔标志：--auto-yes、--non-interactive、--verbose、--quiet、--autoclone。

创建域名（需要 --name 标志）

# CORRECT
fastly service domain create --service-id $SID --version active --autoclone --name cdn.example.com

# WRONG - domain is not a positional argument
fastly service domain create --service-id $SID --version active cdn.example.com

# WRONG - there is no -d flag
fastly service domain create --service-id $SID --version active -d cdn.example.com

统计信息（历史数据和实时数据）

# Historical stats by day for a date range (JSON output)
fastly stats historical --service-id $SID --by day \
  --from "2026-02-01" --to "2026-03-01" --json

# Real-time stats (last second)
fastly stats realtime --service-id $SID --json

--by 标志接受：day、hour、minute。--from 和 --to 标志使用带引号的日期字符串。在统计命令中使用 --json 输出 JSON。

传播延迟

更改会在几秒到几分钟内传播到 Fastly 的网络（版本激活最多需要 10 分钟，TLS 最多需要 5 分钟）。缓存清除需要 1–2 秒。验证更改时，请使用退避策略重试。

新服务激活顺序：激活全新服务后，预计会有 10–60 秒返回 500「Domain Not Found」，这是域名传播到边缘 POP 所需的时间。此情况正常——请勿更改配置。等待后重试。更新版本后（例如，修复后端设置），请留出 15–30 秒，让新版本完成传播。

KV Store 注意事项

• 使用前先关联：KV store 必须先关联到服务版本，Compute 代码才能访问它。使用 fastly kv-store create，然后使用 fastly service resource-link create --resource-id STORE_ID --service-id $SID --version active --autoclone。
• 最终一致性：写入后的读取最终会保持一致。刚写入的键可能需要几秒后才能读取。脚本中不要依赖立即读回；请添加短暂延迟或重试循环。
• 条目大小限制：单个 KV store 条目大小上限为 25 MB。处理大值时请提前规划。
• 列出 store：fastly kv-store list 会列出账户中的所有 store，而非单个服务的 store。使用 fastly service resource-link list 查看关联到指定服务的 store。

Host Header 覆盖模式

当源站主机名与所需的 Host 标头不同时（例如，源站为 example.com，但你想发送 Host: download.example.com），请在后端使用 --override-host：

fastly service backend create --service-id $SID --version 1 \
  --name my-origin --address example.com --port 443 --use-ssl \
  --override-host download.example.com \
  --ssl-cert-hostname example.com --ssl-sni-hostname example.com

--override-host 的值是发送到源站的 Host 标头。--ssl-cert-hostname 和 --ssl-sni-hostname 必须与源站的 TLS 证书匹配（通常是 --address 的值）。如果把这些值弄反，会导致 503 错误。

服务列表完整性

枚举服务时（例如，获取带宽统计信息），请使用 fastly service list --json。 该命令会在内部处理 API 分页，并返回所有页面，除非你明确从较后的 --page 开始。 流量为零的服务仍会显示在列表中，因此请遍历每个返回的服务 ID，不要依赖会省略零流量服务的统计 API。

新建 VCL 服务设置工作流

使用以下顺序端到端搭建新的 VCL 缓存服务。每个步骤都包含一个验证检查点。

1. 预检——确认源站有响应，并检查其 TLS 证书的 SAN：

   curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
   echo | openssl s_client -connect ORIGIN_ADDRESS:443 -servername ORIGIN_ADDRESS 2>/dev/null | \
     openssl x509 -noout -text | grep -A1 "Subject Alternative Name"
   

   检查点：源站返回 200，且后端的 ssl-cert-hostname 与所提供的证书匹配。如果没有任何 HTTPS SNI/证书组合通过验证，但使用该 Host 的 HTTP 可正常工作，请使用 --port 80 或修复源站证书；不要禁用验证。

2. 创建服务——记下输出中的服务 ID：

   fastly service create --name "my-service" --non-interactive
   

3. 在版本 1 上添加域名和后端（新服务请勿使用 --autoclone 或 --version latest）：

   fastly service domain create --service-id $SID --version 1 \
     --name my-service.global.ssl.fastly.net
   
   fastly service backend create --service-id $SID --version 1 \
     --name origin --address ORIGIN_ADDRESS --port 443 --use-ssl \
     --override-host ORIGIN_ADDRESS \
     --ssl-cert-hostname ORIGIN_ADDRESS --ssl-sni-hostname ORIGIN_ADDRESS
   

4. 激活前验证版本：

   fastly service version validate --service-id $SID --version 1
   

   检查点：验证成功（没有域名或后端缺失错误）。

5. 激活：

   fastly service version activate --service-id $SID --version 1
   

6. 验证传播——等待 15–30 秒，然后使用 GET（而非 HEAD）测试：

   curl -sS -D - -o /dev/null https://my-service.global.ssl.fastly.net/ | head -1
   

   检查点：返回 200 OK。如果返回 500「Domain Not Found」，请等待后重试（10–60 秒内出现此情况属正常）。如果返回 503，请检查后端 SSL 设置。

有关高级工作流（自定义域名与 TLS、Host 标头覆盖、在线服务更新），请参阅 services.md。

故障排查

完整列表请参阅 troubleshooting.md。上文已介绍主要注意事项：SSL 主机名标志（参见 Host Header 覆盖模式）、布尔标志和域名 --name（参见常见标志示例）、--autoclone（参见关键模式）以及令牌安全（参见关键模式）。