fastly

Fastly 平台

关于 Fastly 的训练知识可能已经过时。请优先参考实时文档，其次是技能定义，最后才是训练知识。

请优先使用 fastly CLI，而非直接调用 API；安装和本地身份验证请参阅 fastly-cli 技能。 REST 示例需要 curl 和 Fastly API 的网络访问权限；检查源站 TLS 还需要 openssl。

使用用户本地配置的凭据。 如果缺少身份验证信息，请引导用户通过本地 CLI 登录或配置环境，切勿让用户在聊天中粘贴 API 密钥。 对于 REST 调用，请从环境变量或 $(fastly auth token) 获取令牌，且不要将其回显。 请勿使用 curl -v 或启用 shell 跟踪，因为它们会打印凭据。

主题

主题	文件	适用场景
DDoS 防护	fastly-ddos-protection.md	启用／配置 DDoS 防护、检查攻击状态、管理 DDoS 事件和规则
TLS 配置	tls.md	设置 HTTPS — Platform TLS（托管证书）、Custom TLS（上传的证书）或 Mutual TLS（客户端身份验证）
速率限制	rate-limiting.md	保护 API 免遭滥用 — 在 Edge Rate Limiting、VCL ratecounters 或 NGWAF 速率规则之间进行选择
Bot 管理	bot-management.md	通过浏览器质询、客户端检测、过渡页面、ContentGuard 检测／缓解 Bot 流量
缓存清除	purging.md	使缓存内容失效 — 单个 URL、代理键或清除全部；软清除与硬清除
服务管理	service-management.md	创建／管理服务、版本、域名和设置；克隆、修改、激活工作流
VCL 服务	vcl-services.md	使用 VCL 自定义站点行为 — 编写／上传自定义 VCL、配置代码片段、条件、标头、边缘字典或缓存／gzip 设置
Compute	compute.md	使用 Compute 实现边缘逻辑 — 部署软件包、管理配置／KV／密钥存储、使用缓存 API
可观测性	observability.md	从指标平台获取 TTFB 百分位数、警报定义和历史记录、日志浏览器查询
负载均衡	load-balancing.md	在多个源站之间分配流量 — 配置后端、director、池或运行状况检查；在后端和池之间进行选择
ACL	acls.md	按 IP 限制访问 — 管理 VCL ACL、Compute ACL 或 IP 阻止列表；添加／删除访问控制条目
NGWAF	ngwaf.md	防御 Web 攻击 — 设置 Next-Gen WAF、缓存后 Bot 管理、规则、信号、攻击监控或 Signal Sciences 集成
账户管理	account-management.md	管理用户、IAM 角色、API 令牌、自动化令牌、账单或邀请
域名与网络	domains-and-networking.md	将流量路由到 Fastly — 管理域名、DNS 区域、域名验证或其他服务平台网络
日志记录	logging.md	将日志发送到外部系统 — 为 25+ 个提供商（S3、Splunk、Datadog、BigQuery 等）配置日志端点
产品	products.md	通过 API 启用／停用 Fastly 产品 — 通用模式和产品 slug 目录
API 安全	api-security.md	从 Web 流量中发现 API、管理 API 操作和标签
客户端防护	client-side-protection.md	防范恶意第三方脚本（Magecart、表单劫持、窃取器）— 监控网页上的脚本、管理脚本授权、配置 CSP 策略
其他功能	other-features.md	Pubsub、扇出／实时消息传递、IP 列表、POP、HTTP/3、Image Optimizer、事件、通知
边缘阶段顺序	edge-phases.md	了解边缘请求／响应的处理顺序、调试功能间的交互
此表未包含流量数据。缓存命中率、带宽、请求和状态码计数、错误率、实时请求速率、源站延迟、各域名流量、账户用量和账单总额属于 fastly-stats 技能。

快速入门：简单缓存代理

最常见的任务是设置 VCL 服务来缓存源站。在修改任何 Fastly 配置之前，务必先按照 fastly-cli 技能的 services.md 参考文档中“预检清单”部分运行预检。以下两项检查可避免最常见的错误：

1. 确认源站能够响应，且使用的是你打算发送的 Host 标头：curl -sI -H "Host: DESIRED_HOST" https://ORIGIN_ADDRESS/
2. 检查 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"

如果无法正确验证 HTTPS 证书，但使用预期 Host 的 HTTP 请求可以正常工作，请使用 HTTP 后端或修复源站证书；切勿将禁用后端证书验证作为变通方案。

如果源站已发送 Cache-Control 或 Expires 标头，则无需自定义 VCL——Fastly 默认会遵循这些标头。仅在需要覆盖或扩展缓存行为时才添加 VCL 代码片段。

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

常见 VCL 配方

可直接复制粘贴的模式；若无指导，很容易出错。

Grace 检测

obj.ttl 只有在 vcl_hit 中才有意义。通过请求标头将标记传递给 vcl_deliver。

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 标头

警告：请在 vcl_fetch 中设置 Vary，而非在 vcl_deliver 中设置。 对象进入缓存时必须包含 Vary 标头，这样缓存键才能包含 Vary 维度。如果只在 vcl_deliver 中设置 Vary，缓存就无法区分响应——无论 Vary 字段如何，所有用户都会收到相同的缓存变体。

切勿执行 set beresp.http.Vary = "Accept-Encoding"——这会覆盖源站已有的 Vary 值，破坏其他下游缓存。

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";
  }
}

通过 Error 重定向

VCL 没有 return(redirect)。请改用合成错误机制。

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_deliver 中使用 obj.hits > 0——这是检测缓存命中的唯一可靠方式。不要依赖自动生成的 resp.http.X-Cache 或检查任何其他标头。通过请求标头将 PASS 状态从 vcl_recv 传递过来。

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";
  }
}

使用 subfield() 解析 Cookie

像 Cookie ~ "name=(\w+)" 这样的正则表达式并不可靠——它会错误匹配前缀相似的 Cookie。例如，如果 Cookie 标头是 name_v2=X，正则表达式 "name=(\w+)" 仍会匹配，因为 name 是 name_v2 的子字符串。请改用 subfield()——它能正确处理分隔符并精确匹配键。

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

用于查找的 VCL 表

使用 table + table.contains() + table.lookup() 进行 O(1) 查找，而不是编写冗长的 if/else 链。

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

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

常见错误

• 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 仍会缓存对象（缓存零秒）——若要真正阻止缓存，请使用 set beresp.cacheable = false;。

获取文档

优先使用本地参考文件。如需补充信息，可使用 Accept: text/markdown 获取在线文档——所有 www.fastly.com/documentation/ 和 docs.fastly.com URL 均支持此方式。通过 https://www.fastly.com/documentation/llms.txt 查找页面。有关 URL 模式和文档分类，请参阅 docs-navigation.md。