转发流量 · Cloudflare One 文档

Forward（转发） 操作会在 Gateway 允许的 HTTP 流量上调用 Worker。使用它实现请求和响应转换、应用程序特定控制或后台任务，而无需运行单独的 HTTP 代理。

编写你自己的 Worker，或改编 Worker 模板。gateway-workers skill ↗ 为处理此集成的编码代理提供指导。

工作原理

Gateway 在 HTTP 请求策略之后、请求体策略和检查之前评估 Forward 策略。它按优先级顺序调用第一条匹配的 Forward 策略所选择的 Worker。

带有 Block 操作的 HTTP 请求策略会阻止调用 Worker。不匹配任何 Forward 策略的流量会继续，而不调用 Worker。

Gateway 在将原始请求体交给 Worker 之前对其进行检查。来自请求体策略或检查的 Block 决定可以中断已在运行的 Worker。

调用 Worker 并不确认请求体检查已成功。

flowchart LR
    accTitle: Gateway Forward 请求和响应流程
    accDescr: Gateway 评估 HTTP 请求策略，然后评估 Forward 策略，并在请求体策略和检查之前调用第一条匹配的 Worker。它在将原始请求体交给 Worker 之前对其进行检查。来自请求体策略或检查的 Block 决定可以中断 Worker。Gateway 在将最终响应返回给用户之前对其进行检查。
    A["原始请求"] --> B["Gateway HTTP 请求策略"]
    B -->|已允许，Forward 匹配| C["调用 Worker"]
    B -->|已拦截| X["拦截响应"]
    B -->|原始请求体，Forward 匹配| I["Gateway 请求体策略和检查"]
    I -->|已检查的请求体流| C
    I -->|已拦截| X
    I -.->|请求体 Block 中断 Worker| C
    C -->|next：最多一次| D["原始目标"]
    D --> C
    C -->|最终或合成响应| E["Gateway 响应检查"]
    E --> F["用户"]

Gateway 调用名为 GatewayMiddleware 的入口点的 handle(request, context, next) 方法：

request 是原始 HTTP Request，包括其正文流。
context 包含 Gateway 元数据。它描述原始请求，当你的 Worker 修改请求时不会更改。
next(request) 通过 Gateway 将请求发送到其原始目标，并返回上游 Response。Worker 调用 next() 时，Gateway 建立上游连接。

Worker 可以在调用 next() 之前修改方法、标头、cookie 或正文。它可以修改上游响应，或不调用 next() 而返回合成响应。每次调用最多调用一次 next()。你不能用它更改目标 URL 或主机、重试上游请求，或向多个目标发送请求。

Gateway 检查交给 Worker 之前的原始请求体 和 Worker 之后的最终响应（包括合成响应）。Gateway 不会在将修改后的请求字节发送到上游之前第二次检查它们。

例如，Worker 不能使用脱敏来绕过请求侧数据丢失防护（DLP）检查。Worker 添加到已允许请求的数据不会再接受一次请求侧 DLP 扫描。

普通的 Workers fetch() 是独立的子请求。使用 next() 以 Gateway 的路由和出站配置继续用户的请求。不要假定 fetch() 调用会使用用户的 Gateway 策略或出站 IP。

前提条件

拥有已设置 Workers 的 Cloudflare 账户。如果此前未使用过 Workers，请遵循 Workers 快速入门指南。Workers 和 Gateway 使用同一账户。
设置 Gateway HTTP 过滤，并将测试设备的流量路由经过 Gateway。
为 HTTPS 流量启用 TLS 解密并安装受信任的根证书。
使用与 Gateway 策略同一 Cloudflare 账户中已部署的 Worker。为该账户配置 Workers 子域。Worker 不需要公共路由。

设置 Forward

创建 Worker 项目。
npx wrangler init gateway-worker
yarn wrangler init gateway-worker
pnpm wrangler init gateway-worker
使用以下配置。禁用 workers_dev 和 preview_urls 可避免此 Worker 通过这些公共 URL 暴露。
{ "$schema": "./node_modules/wrangler/config-schema.json", "name": "gateway-worker", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-11-14", "workers_dev": false, "preview_urls": false }
name = "gateway-worker" main = "src/index.ts" # Set this to today's date compatibility_date = "2026-11-14" workers_dev = false preview_urls = false
将 src/index.ts 替换为所需的具名 Worker 入口点。

Gateway 通过 Workers RPC 调用 GatewayMiddleware.handle()。请将导出的类名准确保持为 GatewayMiddleware。

在此 Worker 项目中将 @cloudflare/zt-types ↗ 2026.10.1 或更高版本安装为开发依赖项。它提供 Gateway 上下文和延续类型：
npm i -D @cloudflare/zt-types
yarn add -D @cloudflare/zt-types
pnpm add -D @cloudflare/zt-types
bun add -d @cloudflare/zt-types
在 TypeScript 示例中保留仅类型导入。它们会在 TypeScript 编译时被移除。从 cloudflare:workers 导入运行时 WorkerEntrypoint 类。JavaScript 版本省略类型导入和注解，不需要此软件包。

此示例将请求原样传递，并添加响应标头，以便你验证 Worker 已运行。上下文参考描述你可以在其他脚本中使用的字段。
src/index.jsjs
import { WorkerEntrypoint } from "cloudflare:workers"; export class GatewayMiddleware extends WorkerEntrypoint { async handle(request, context, next) { const response = await next(request); const headers = new Headers(response.headers); headers.set("x-gateway-worker", "gateway-worker"); return new Response(response.body, { status: response.status, statusText: response.statusText, headers, }); } }
src/index.tsts
import { WorkerEntrypoint } from "cloudflare:workers"; import type { GatewayMiddlewareContext, GatewayMiddlewareNext, } from "@cloudflare/zt-types"; export class GatewayMiddleware extends WorkerEntrypoint { async handle( request: Request, context: GatewayMiddlewareContext, next: GatewayMiddlewareNext, ): Promise<Response> { const response = await next(request); const headers = new Headers(response.headers); headers.set("x-gateway-worker", "gateway-worker"); return new Response(response.body, { status: response.status, statusText: response.statusText, headers, }); } }
将 Worker 部署到包含你的 Gateway 策略的账户。
npx wrangler deploy
yarn wrangler deploy
pnpm wrangler deploy
在 Cloudflare One 中，转到 Traffic controls（流量控制） > Firewall policies（防火墙策略） > HTTP。
前往 Firewall policies ↗
选择 Add a policy（添加策略），为策略命名，并将其范围限定到一个测试主机以及测试用户或设备组。使用 Host、URL 和 HTTP Method 等请求元数据选择器。你还可以添加身份和设备状况条件。
将操作选择为 Forward，选择已部署的 Worker，然后选择 Create policy（创建策略）。Gateway 调用其 GatewayMiddleware 入口点，而不是默认的 fetch() 处理程序。
从测试设备请求所选主机，并检查 x-gateway-worker: gateway-worker 响应标头。匹配的过滤 Block 策略仍优先于 Forward。如果标头不存在，请参阅问题排查。

使用 API 配置

使用 Create a Zero Trust Gateway rule 端点，设置 action: "forward"，并在 rule_settings.forward.worker_id 中提供 Worker 的 ID。Worker ID 是 32 个字符的小写十六进制标识符。请使用其 ID，而不是其名称或 workers.dev URL。

Create a Zero Trust Gateway rulebash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/gateway/rules" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "Forward example.com to a Worker",
		"enabled": true,
		"precedence": 1000,
		"action": "forward",
		"filters": [
				"http"
		],
		"traffic": "http.request.host == \"example.com\"",
		"rule_settings": {
				"forward": {
						"worker_id": "<WORKER_ID>"
				}
		}
	}'

有关已部署 Worker 的标识符，请参阅 List Workers。

已知限制

Gateway 仅在保存 Forward 策略时解析所选 Worker。删除 Worker 不会移除或禁用该策略。匹配的请求随后会以 HTTP 500 失败，并且不会到达源站。在删除 Worker 之前，请更新所有使用它的 Forward 策略以选择另一个 Worker，或删除这些策略。

如果通过 Workers VPC 从 Cloudflare 计算平台发送的 HTTP 流量匹配 Forward 策略，Gateway 会丢弃该流量。Gateway 不会调用所选 Worker。请将此流量排除在你的 Forward 策略之外。

WebSocket 流量直接连接到原始上游服务并绕过所选 Worker。 Worker 不会收到 WebSocket 升级请求或消息，因此其逻辑不适用于这些连接。

代理 HTTP CONNECT 隧道直接连接到原始上游服务并绕过所选 Worker。

方面	行为
策略匹配	Forward 使用请求元数据、身份和设备状况条件。请求体检查结果、DLP 匹配和响应选择器无法选择 Worker。
解密	HTTPS 流量必须被解密。Gateway 不会为匹配 Do Not Inspect 的流量调用 Worker。
协议	支持常规 HTTP 请求。Gateway 不会为 CONNECT 隧道、WebSocket 连接、协议升级或 HTTP trailer 调用 Worker。
目标	`next()` 保留原始目标 URL 和主机。
延续	调用 `next()` 零次或一次。不支持重复或并发调用。
响应	返回 `200` 到 `599` 的最终状态。对于 HEAD 请求或状态 `204`、`205` 和 `304`，不返回正文。
流式传输	请求和响应正文通过 Gateway 流式传输，带有背压和取消。避免缓冲整个正文。
失败	调用错误、Worker 错误或 Gateway 与 Worker 之间的通信失败会 fail closed。Gateway 不会绕过 Worker 并转发原始请求。
限制	现有 Gateway 限制和 Workers 限制适用。Workers 用量遵循常规 Workers 定价。

对可以在返回响应后运行的后台任务使用 this.ctx.waitUntil()。这些任务仍受 Workers 执行限制约束，并且不是持久作业队列。对于需要重试或更长时间的工作，请使用 Queues 或 Workflows。

问题排查

如果 Worker 未运行，请确认设备使用 Gateway HTTP 过滤、HTTPS 已解密，并且请求被过滤策略允许。检查是否有 Do Not Inspect 策略或更早的 Forward 策略匹配该请求。

如果启用 Forward 后请求失败，请确认 Worker 导出 GatewayMiddleware、其 handle() 方法返回 Response，并且最多调用一次 next()。检查异常、不支持的状态码，以及必须没有正文的响应上的正文。使用 Workers Logs 检查调用错误。在修正失败脚本时禁用测试 Forward 策略。

有关身份和设备状况错误，请参阅处理身份和状况错误。

如果在 Worker 被删除后匹配请求返回 HTTP 500，请更新 Forward 策略以选择现有 Worker，或删除该策略。保存仍引用已删除 Worker 的策略会以 API 错误 2294 失败。

直通示例成功后，可以从 Worker 模板开始。