fastly

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fastly Platform

Fastly平台

Your training knowledge of Fastly is likely out of date. Prefer live docs over skill definitions over training knowledge.

Prefer the

fastly

CLI over raw API calls — see the fastly-cli skill. When calling the REST API directly, never paste the raw API token into the conversation and omit

curl -v

(it prints the

Fastly-Key

header). Source tokens from the environment or

$(fastly auth show --reveal --quiet | awk '/^Token:/ {print $2}')

without echoing them.

你所掌握的Fastly培训知识可能已过时。优先使用实时文档，其次是技能定义，最后才是培训知识。

优先使用

fastly

CLI而非直接调用API——请参考fastly-cli技能。直接调用REST API时，切勿在对话中粘贴原始API令牌，且不要使用

curl -v

（它会打印

Fastly-Key

头信息）。请从环境变量或

$(fastly auth show --reveal --quiet | awk '/^Token:/ {print $2}')

中获取令牌，不要回显令牌内容。

Topics

主题

Topic	File	Use when...
DDoS protection	fastly-ddos-protection.md	Enabling/configuring DDoS protection, checking attack status, managing events and rules
TLS configuration	tls.md	Setting up HTTPS — Platform TLS (managed certs), Custom TLS (uploaded certs), or Mutual TLS (client auth)
Rate limiting	rate-limiting.md	Protecting APIs from abuse — choosing between Edge Rate Limiting, VCL ratecounters, or NGWAF rate rules
Bot management	bot-management.md	Detecting/mitigating bot traffic with browser challenges, client-side detections, interstitial pages
Cache purging	purging.md	Invalidating cached content — single URL, surrogate key, or purge-all; soft vs hard purge
Service management	service-management.md	Creating/managing services, versions, domains, settings; clone-modify-activate workflow
VCL services	vcl-services.md	Writing/uploading custom VCL, configuring snippets, conditions, headers, edge dictionaries, or cache/gzip settings
Compute	compute.md	Deploying Compute packages, managing config/KV/secret stores, using cache APIs
Observability	observability.md	Querying stats, viewing real-time analytics, using domain/origin inspectors, configuring alerts or log explorer
Load balancing	load-balancing.md	Configuring backends, directors, pools, or health checks; choosing between backends and pools
ACLs	acls.md	Managing VCL ACLs, Compute ACLs, or IP block lists; adding/removing access control entries
NGWAF	ngwaf.md	Setting up Next-Gen WAF, managing rules, signals, attack monitoring, or Signal Sciences integration
Account management	account-management.md	Managing users, IAM roles, API tokens, automation tokens, billing, or invitations
Domains & networking	domains-and-networking.md	Managing domains, DNS zones, domain verification, or service platform networking
Logging	logging.md	Configuring logging endpoints — 25+ providers (S3, Splunk, Datadog, BigQuery, etc.)
Products	products.md	Enabling/disabling Fastly products via API — universal pattern and product slug catalog
API security	api-security.md	Discovering APIs, managing operations, or configuring schema validation for API traffic
Other features	other-features.md	Fanout/real-time messaging, IP lists, POPs, HTTP/3, Image Optimizer, events, notifications
Edge phase ordering	edge-phases.md	Understanding edge request/response ordering, debugging feature interactions

主题	文件	适用场景
DDoS防护	fastly-ddos-protection.md	启用/配置DDoS防护、检查攻击状态、管理事件与规则
TLS配置	tls.md	设置HTTPS——平台TLS（托管证书）、自定义TLS（上传证书）或双向TLS（客户端认证）
速率限制	rate-limiting.md	保护API免受滥用——选择边缘速率限制、VCL速率计数器或NGWAF速率规则
机器人管理	bot-management.md	通过浏览器挑战、客户端检测、插页式页面检测/缓解机器人流量
缓存清除	purging.md	使缓存内容失效——单个URL、替代键或全量清除；软清除与硬清除
服务管理	service-management.md	创建/管理服务、版本、域名、设置；克隆-修改-激活工作流
VCL服务	vcl-services.md	编写/上传自定义VCL、配置代码片段、条件、头信息、边缘字典或缓存/Gzip设置
Compute平台	compute.md	部署Compute包、管理配置/KV/密钥存储、使用缓存API
可观测性	observability.md	查询统计数据、查看实时分析、使用域名/源站检查器、配置告警或日志资源管理器
负载均衡	load-balancing.md	配置后端、导向器、池或健康检查；选择后端与池的使用方式
ACL访问控制列表	acls.md	管理VCL ACL、Compute ACL或IP黑名单；添加/移除访问控制条目
NGWAF下一代Web应用防火墙	ngwaf.md	设置下一代WAF、管理规则、信号、攻击监控或Signal Sciences集成
账户管理	account-management.md	管理用户、IAM角色、API令牌、自动化令牌、账单或邀请
域名与网络	domains-and-networking.md	管理域名、DNS区域、域名验证或服务平台网络
日志配置	logging.md	配置日志端点——支持25+种服务商（S3、Splunk、Datadog、BigQuery等）
产品管理	products.md	通过API启用/禁用Fastly产品——通用模式与产品slug目录
API安全	api-security.md	发现API、管理操作或配置API流量的模式验证
其他功能	other-features.md	扇出/实时消息、IP列表、POP节点、HTTP/3、图像优化器、事件、通知
边缘阶段排序	edge-phases.md	理解边缘请求/响应顺序、调试功能交互

Quick Start: Simple Caching Proxy

快速入门：简单缓存代理

The most common task is setting up a VCL service to cache an origin. Before touching any Fastly config, always run the pre-flight checks from the fastly-cli skill's services.md reference under "Pre-flight checklist". The two checks that prevent the most common errors:

Verify the origin responds with the Host header you intend to send:
```
curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
```

Check TLS certificate SANs to determine the correct

ssl-cert-hostname

ssl-sni-hostname

echo | openssl s_client -connect ORIGIN:443 -servername ORIGIN 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

If the origin already sends

Cache-Control

Expires

headers, no custom VCL is needed — Fastly respects these by default. Only add VCL snippets to override or extend caching behavior.

The full step-by-step workflow (create service, add domain, add backend, activate) is in the fastly-cli skill's services.md reference under "Create a Caching Proxy".

最常见的任务是设置VCL服务来缓存源站内容。在修改任何Fastly配置之前，请务必运行fastly-cli技能中services.md参考文档下“预检查清单”里的预检查步骤。其中两项检查可避免大多数常见错误：

验证源站响应：使用你打算发送的Host头进行验证：
```
curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
```

检查TLS证书SAN字段：确定正确的

ssl-cert-hostname

ssl-sni-hostname

：

echo | openssl s_client -connect ORIGIN:443 -servername ORIGIN 2>/dev/null | openssl x509 -noout -text | grep -A1 "Subject Alternative Name"

如果源站已发送

Cache-Control

或

Expires

头，则无需自定义VCL——Fastly默认会遵循这些头信息。仅在需要覆盖或扩展缓存行为时才添加VCL代码片段。

完整的分步工作流（创建服务、添加域名、添加后端、激活）请参考fastly-cli技能中services.md参考文档下的“创建缓存代理”部分。

Common VCL Recipes

常用VCL示例

Copy-pasteable patterns that are easy to get wrong without guidance.

以下是易于出错的可复制粘贴模式。

Grace Detection

缓存过期检测（Grace Detection）

obj.ttl

is only meaningful in

vcl_hit

. Pass a flag to

vcl_deliver

via a request header.

vcl

sub vcl_hit {
  if (obj.ttl <= 0s) {
    set req.http.X-Grace = "true";
  }
}

sub vcl_deliver {
  if (req.http.X-Grace) {
    set resp.http.X-Grace = "true";
  }
}

obj.ttl

仅在

vcl_hit

中有意义。通过请求头将标志传递给

vcl_deliver

。

vcl

sub vcl_hit {
  if (obj.ttl <= 0s) {
    set req.http.X-Grace = "true";
  }
}

sub vcl_deliver {
  if (req.http.X-Grace) {
    set resp.http.X-Grace = "true";
  }
}

Vary Header Append

Vary头追加

Warning: Set Vary in
vcl_fetch
, not
vcl_deliver
. The Vary header must be present when the object enters the cache so the cache key includes the Vary dimensions. Setting Vary only in

vcl_deliver

means the cache won't differentiate responses — every user gets the same cached variant regardless of the Vary field.

Never

set beresp.http.Vary = "Accept-Encoding"

— that overwrites any existing Vary values from the origin, breaking other downstream caches.

vcl

sub vcl_fetch {
  if (!beresp.http.Vary) {
    set beresp.http.Vary = "Accept-Encoding";
  } else if (beresp.http.Vary !~ "Accept-Encoding") {
    set beresp.http.Vary = beresp.http.Vary ", Accept-Encoding";
  }
}

警告：请在
vcl_fetch
中设置Vary，而非
vcl_deliver
。当对象进入缓存时必须存在Vary头，这样缓存键才会包含Vary维度。仅在

vcl_deliver

中设置Vary意味着缓存不会区分响应——所有用户都会获得相同的缓存变体，无论Vary字段是什么。

切勿使用

set beresp.http.Vary = "Accept-Encoding"

——这会覆盖源站发送的任何现有Vary值，破坏下游其他缓存。

vcl

sub vcl_fetch {
  if (!beresp.http.Vary) {
    set beresp.http.Vary = "Accept-Encoding";
  } else if (beresp.http.Vary !~ "Accept-Encoding") {
    set beresp.http.Vary = beresp.http.Vary ", Accept-Encoding";
  }
}

Redirect via Error

通过错误实现重定向

VCL has no

return(redirect)

. Use the synthetic error mechanism instead.

vcl

sub vcl_recv {
  if (req.url ~ "^/old-path") {
    error 801 "https://example.com/new-path";
  }
}

sub vcl_error {
  if (obj.status == 801) {
    set obj.status = 301;
    set obj.http.Location = obj.response;
    synthetic {""};
    return(deliver);
  }
}

VCL中没有

return(redirect)

。请改用合成错误机制。

vcl

sub vcl_recv {
  if (req.url ~ "^/old-path") {
    error 801 "https://example.com/new-path";
  }
}

sub vcl_error {
  if (obj.status == 801) {
    set obj.status = 301;
    set obj.http.Location = obj.response;
    synthetic {""};
    return(deliver);
  }
}

Cache Status Headers

缓存状态头

Use

obj.hits > 0

vcl_deliver

— this is the only reliable way to detect cache hits. Do not rely on auto-generated

resp.http.X-Cache

or any other header inspection. Pass PASS state from

vcl_recv

via a request header.

vcl

sub vcl_recv {
  if (req.url ~ "^/api/") {
    set req.http.X-Pass = "true";
    return(pass);
  }
}

sub vcl_deliver {
  if (req.http.X-Pass) {
    set resp.http.X-Cache = "PASS";
  } else if (obj.hits > 0) {
    set resp.http.X-Cache = "HIT";
  } else {
    set resp.http.X-Cache = "MISS";
  }
}

在

vcl_deliver

中使用

obj.hits > 0

——这是检测缓存命中的唯一可靠方法。不要依赖自动生成的

resp.http.X-Cache

或任何其他头信息检查。通过请求头将

vcl_recv

中的PASS状态传递下去。

vcl

sub vcl_recv {
  if (req.url ~ "^/api/") {
    set req.http.X-Pass = "true";
    return(pass);
  }
}

sub vcl_deliver {
  if (req.http.X-Pass) {
    set resp.http.X-Cache = "PASS";
  } else if (obj.hits > 0) {
    set resp.http.X-Cache = "HIT";
  } else {
    set resp.http.X-Cache = "MISS";
  }
}

Cookie Parsing with subfield()

使用subfield()解析Cookie

Regex like

Cookie ~ "name=(\w+)"

is unreliable — it false-matches cookies with similar prefixes. For example, if the cookie header is

name_v2=X

, the regex

"name=(\w+)"

still matches because

name

appears as a substring of

name_v2

. Use

subfield()

instead — it performs exact key matching with proper delimiter handling.

vcl

set req.http.X-My-Cookie = subfield(req.http.Cookie, "name", ";");

类似

Cookie ~ "name=(\w+)"

的正则表达式不可靠——它会误匹配前缀相似的Cookie。例如，如果Cookie头是

name_v2=X

，正则表达式

"name=(\w+)"

仍会匹配，因为

name

是

name_v2

的子字符串。请改用

subfield()

——它会通过正确的分隔符处理执行精确的键匹配。

vcl

set req.http.X-My-Cookie = subfield(req.http.Cookie, "name", ";");

VCL Table for Lookups

用于查找的VCL表

Use

table

table.contains()

table.lookup()

for O(1) lookups instead of long if/else chains.

vcl

table redirects {
  "/old":  "/new",
  "/blog": "/articles",
}

sub vcl_recv {
  if (table.contains(redirects, req.url)) {
    error 801 table.lookup(redirects, req.url);
  }
}

使用

table

table.contains()

table.lookup()

实现O(1)时间复杂度的查找，而非冗长的if/else链。

vcl

table redirects {
  "/old":  "/new",
  "/blog": "/articles",
}

sub vcl_recv {
  if (table.contains(redirects, req.url)) {
    error 801 table.lookup(redirects, req.url);
  }
}

Common Mistakes

常见错误

```
beresp.*
```
is only available in
```
vcl_fetch
```
, not
```
vcl_deliver
```
.
```
req.request
```
is deprecated — use
```
req.method
```
.
```
return(purge)
```
does not exist in Fastly VCL. Use
```
return(pass)
```
and check in
```
vcl_miss
```
/
```
vcl_hit
```
.
```
set beresp.ttl = 86400
```
is a type error — needs the
```
s
```
suffix:
```
86400s
```
.
```
synthetic "text"
```
needs long-string syntax:
```
synthetic {"text"}
```
.
```
beresp.ttl = 0s
```
still caches the object (for zero seconds) — use
```
set beresp.cacheable = false;
```
to truly prevent caching.

```
beresp.*
```
仅在
```
vcl_fetch
```
中可用，在
```
vcl_deliver
```
中不可用。
```
req.request
```
已被弃用——请使用
```
req.method
```
。
Fastly VCL中不存在
```
return(purge)
```
。请使用
```
return(pass)
```
并在
```
vcl_miss
```
/
```
vcl_hit
```
中检查。
```
set beresp.ttl = 86400
```
是类型错误——需要添加
```
s
```
后缀：
```
86400s
```
。
```
synthetic "text"
```
需要使用长字符串语法：
```
synthetic {"text"}
```
。
```
beresp.ttl = 0s
```
仍会缓存对象（缓存时长为0秒）——请使用
```
set beresp.cacheable = false;
```
来真正阻止缓存。

Fetching Documentation

获取文档

Prefer the local reference files. To fill gaps, fetch live docs with

Accept: text/markdown

— works for all

www.fastly.com/documentation/

and

docs.fastly.com

URLs. Discover pages via

https://www.fastly.com/documentation/llms.txt

. For URL patterns and doc categories, see docs-navigation.md.

优先使用本地参考文件。如需补充内容，请使用

Accept: text/markdown

获取实时文档——适用于所有

www.fastly.com/documentation/

和

docs.fastly.com

网址。可通过

https://www.fastly.com/documentation/llms.txt

发现文档页面。关于URL模式和文档分类，请参考docs-navigation.md。