跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

动态调度 Worker

最后更新 查看 MarkdownAgent 设置

创建动态调度 Worker,将传入请求路由到你的调度命名空间中的用户 Worker。 动态调度 Worker 是一种专门的路由 Worker,将传入请求定向到调度命名空间中的相应用户 Worker。与使用 Workers Routes 不同,调度 Worker 允许你通过代码以编程方式控制请求路由。

图 1:Workers for Platforms:主流程

为什么使用动态调度 Worker?

  • 规模:将请求路由到数百万个主机名对应的不同 Worker,而无需为每个主机名定义 Workers Routes 配置
  • 自定义路由逻辑:编写代码以精确确定请求应如何路由。例如:
  • 添加平台功能:在路由层构建其他功能:
    • 在请求到达用户 Worker 之前运行身份验证检查
    • 从传入请求中移除或添加标头或元数据
    • 附加有用的上下文,例如用户 ID 或账户信息
    • 根据需要转换请求或响应

配置调度命名空间绑定

要允许动态调度 Worker 动态地将请求路由到命名空间中的 Worker,你需要配置调度命名空间绑定(binding)。此绑定使动态调度 Worker 能够使用 env.dispatcher.get() 调用该命名空间中的任何用户 Worker。

{
	"dispatch_namespaces": [
		{
			"binding": "DISPATCHER",
			"namespace": "my-dispatch-namespace"
		}
	]
}
[[dispatch_namespaces]]
binding = "DISPATCHER"
namespace = "my-dispatch-namespace"

绑定配置完成后,你的动态调度 Worker 可以将请求路由到命名空间中的任何 Worker。以下是你可以在调度器中实现的常见路由模式。

按请求传递数据与能力

当你的调度 Worker 调用用户 Worker 时,可以随该调用发送额外值。例如,调度 Worker 可以先对请求进行身份验证,再将得到的用户 ID、权限或账户信息发送给用户 Worker。

当上下文应来自你的平台代码、而不是直接来自传入请求时,这种方式很有用。要发送此上下文,请将这些值添加到 env.DISPATCHER.get() 第二个参数中的 props。

在调度 Worker 中,从调度命名空间检索用户 Worker 时传入用户 ID 和权限:

dispatcher/src/index.jsjs
export default {
	async fetch(request, env) {
		const userId = "user-123";
		const permissions = ["read", "write"];

		const userWorker = env.DISPATCHER.get("user-worker", {
			props: { userId, permissions },
		});

		return userWorker.fetch(request);
	},
};
dispatcher/src/index.tsts
export default {
	async fetch(request, env): Promise<Response> {
		const userId = "user-123";
		const permissions = ["read", "write"];

		const userWorker = env.DISPATCHER.get("user-worker", {
			props: { userId, permissions },
		});

		return userWorker.fetch(request);
	},
} satisfies ExportedHandler<Cloudflare.Env>;

在用户 Worker 中,通过 ctx.props 接收这些值。在 WorkerEntrypoint 中,通过 this.ctx.props 访问它们:

user-worker/src/index.jsjs
import { WorkerEntrypoint } from "cloudflare:workers";

export default class UserWorker extends WorkerEntrypoint {
	async fetch(_request) {
		const { userId, permissions } = this.ctx.props;
		return Response.json({ userId, permissions });
	}
}
user-worker/src/index.tsts
import { WorkerEntrypoint } from "cloudflare:workers";

interface UserWorkerProps {
	userId: string;
	permissions: string[];
}

export default class UserWorker extends WorkerEntrypoint<
	Cloudflare.Env,
	UserWorkerProps
> {
	async fetch(_request: Request): Promise<Response> {
		const { userId, permissions } = this.ctx.props;
		return Response.json({ userId, permissions });
	}
}

这些数据值对用户代码可见。调度 Worker 可以为每次调用选择不同的 props,而无需更改或重新部署用户 Worker。

授予对特定平台函数的访问权限

你可能不希望用户 Worker 直接访问调度 Worker 中的全部上下文。例如,身份验证数据由你的平台管理,应向用户代码隐藏。

在这种情况下,请传递能力(capability),而不是直接传递数据。能力会暴露用户 Worker 可以调用的特定方法,底层数据、凭据和资源仍保留在调度 Worker 中。Workers 会将该能力作为 RPC stub 传递,并将方法调用转发回你的调度 Worker。

要创建能力,请从调度 Worker 导出一个 WorkerEntrypoint 类。ctx.exports 对象让调度 Worker 可以为该导出类创建 RPC stub,然后再将其传递给用户 Worker。

以下示例展示了这种模式。调度 Worker 使用站点 ID 和访问者 ID 创建 Connector 能力。它通过 props 将该能力传递给用户 Worker,而不会把这些 ID 作为单独的数据值传递。用户 Worker 随后可以调用 Connector 暴露的方法。

在调度 Worker 中定义 Connector 方法,用站点和访问者 ID 配置 connector,再将其传递给用户 Worker:

dispatcher/src/index.jsjs
import { WorkerEntrypoint } from "cloudflare:workers";

export class Connector extends WorkerEntrypoint {
	async invoke() {
		return `${this.ctx.props.siteId}:${this.ctx.props.visitorId}`;
	}
}

export default {
	async fetch(request, env, ctx) {
		const siteId = "site-123";
		const visitorId = "visitor-456";
		const connector = ctx.exports.Connector({
			// These props configure the Connector stub.
			// The user Worker cannot read them directly.
			props: { siteId, visitorId },
		});

		const userWorker = env.DISPATCHER.get("user-worker", {
			// The user Worker receives these values through ctx.props.
			props: {
				CONNECTOR: connector,
			},
		});

		return userWorker.fetch(request);
	},
};
dispatcher/src/index.tsts
import { WorkerEntrypoint } from "cloudflare:workers";

interface ConnectorProps {
	siteId: string;
	visitorId: string;
}

export class Connector extends WorkerEntrypoint<
	Cloudflare.Env,
	ConnectorProps
> {
	async invoke(): Promise<string> {
		return `${this.ctx.props.siteId}:${this.ctx.props.visitorId}`;
	}
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const siteId = "site-123";
		const visitorId = "visitor-456";
		const connector = ctx.exports.Connector({
			// These props configure the Connector stub.
			// The user Worker cannot read them directly.
			props: { siteId, visitorId },
		});

		const userWorker = env.DISPATCHER.get("user-worker", {
			// The user Worker receives these values through ctx.props.
			props: {
				CONNECTOR: connector,
			},
		});

		return userWorker.fetch(request);
	},
} satisfies ExportedHandler<Cloudflare.Env>;

在用户 Worker 中,通过 this.ctx.props 接收该能力并调用其暴露的方法:

user-worker/src/index.jsjs
import { WorkerEntrypoint } from "cloudflare:workers";

export default class UserWorker extends WorkerEntrypoint {
	async fetch(_request) {
		return Response.json({
			connector: await this.ctx.props.CONNECTOR.invoke(),
		});
	}
}
user-worker/src/index.tsts
import { WorkerEntrypoint } from "cloudflare:workers";

interface Connector {
	invoke(): Promise<string>;
}

interface UserWorkerProps {
	CONNECTOR: Connector;
}

export default class UserWorker extends WorkerEntrypoint<
	Cloudflare.Env,
	UserWorkerProps
> {
	async fetch(_request: Request): Promise<Response> {
		return Response.json({
			connector: await this.ctx.props.CONNECTOR.invoke(),
		});
	}
}

将数据传递给出站 Worker

要从调度 Worker 向出站 Worker 发送数据,请先在调度命名空间绑定中声明参数名称:

{
	"dispatch_namespaces": [
		{
			"binding": "DISPATCHER",
			"namespace": "my-dispatch-namespace",
			"outbound": {
				"service": "outbound-worker",
				"parameters": ["requestContext"]
			}
		}
	]
}
[[dispatch_namespaces]]
binding = "DISPATCHER"
namespace = "my-dispatch-namespace"

  [dispatch_namespaces.outbound]
  service = "outbound-worker"
  parameters = [ "requestContext" ]

在调度 Worker 中,通过 env.DISPATCHER.get() 第三个参数的 outbound 选项,传递同名的值:

dispatcher/src/index.jsjs
export default {
	async fetch(request, env) {
		const userId = "user-123";

		const userWorker = env.DISPATCHER.get(
			"user-worker",
			{
				props: { userId },
			},
			{
				outbound: {
					requestContext: {
						userId,
						requestId: crypto.randomUUID(),
					},
				},
			},
		);

		return userWorker.fetch(request);
	},
};
dispatcher/src/index.tsts
export default {
	async fetch(request, env): Promise<Response> {
		const userId = "user-123";

		const userWorker = env.DISPATCHER.get(
			"user-worker",
			{
				props: { userId },
			},
			{
				outbound: {
					requestContext: {
						userId,
						requestId: crypto.randomUUID(),
					},
				},
			},
		);

		return userWorker.fetch(request);
	},
} satisfies ExportedHandler<Cloudflare.Env>;

在出站 Worker 中,将该值作为环境绑定访问:

outbound-worker/src/index.jsjs
export default {
	async fetch(request, env) {
		console.log(env.requestContext.userId, env.requestContext.requestId);
		return fetch(request);
	},
};
outbound-worker/src/index.tsts
interface Env {
	requestContext: {
		userId: string;
		requestId: string;
	};
}

export default {
	async fetch(request, env): Promise<Response> {
		console.log(env.requestContext.userId, env.requestContext.requestId);
		return fetch(request);
	},
} satisfies ExportedHandler<Env>;

出站 Worker 参数支持 JSON 值。它们独立于第二个参数中的 props,后者会传递给用户 Worker。

路由示例

图 2:Workers for Platforms:主流程

基于 KV 的路由

将路由映射存储在 Workers KV 中。这样你可以修改路由逻辑,而无需更改或重新部署动态调度 Worker。

export default {
	async fetch(request, env) {
		try {
			const url = new URL(request.url);

			// Use hostname, path, or any combination as the routing key
			const routingKey = url.hostname;

			// Lookup user Worker name from KV store
			const userWorkerName = await env.USER_ROUTING.get(routingKey);

			if (!userWorkerName) {
				return new Response("Route not configured", { status: 404 });
			}

			// Optional: Cache the KV lookup result
			const userWorker = env.DISPATCHER.get(userWorkerName);
			return await userWorker.fetch(request);
		} catch (e) {
			if (e.message.startsWith("Worker not found")) {
				return new Response("", { status: 404 });
			}
			return new Response(e.message, { status: 500 });
		}
	},
};

基于子域名的路由

将子域名路由到相应的 Worker。例如,my-customer.example.com 将路由到调度命名空间中名为 my-customer 的 Worker。

export default {
	async fetch(request, env) {
		try {
			// Extract user Worker name from subdomain
			// Example: customer1.example.com -> customer1
			const url = new URL(request.url);
			const userWorkerName = url.hostname.split(".")[0];

			// Get user Worker from dispatch namespace
			const userWorker = env.DISPATCHER.get(userWorkerName);
			return await userWorker.fetch(request);
		} catch (e) {
			if (e.message.startsWith("Worker not found")) {
				// User Worker doesn't exist in dispatch namespace
				return new Response("", { status: 404 });
			}
			// Could be any other exception from fetch() or from the dispatched Worker
			return new Response(e.message, { status: 500 });
		}
	},
};

基于路径的路由

将 URL 路径路由到相应的 Worker。例如,example.com/customer-1 将路由到调度命名空间中名为 customer-1 的 Worker。

export default {
	async fetch(request, env) {
		try {
			const url = new URL(request.url);
			const pathParts = url.pathname.split("/").filter(Boolean);

			if (pathParts.length === 0) {
				return new Response("Invalid path", { status: 400 });
			}

			// example.com/customer-1 -> routes to 'customer-1' worker
			const userWorkerName = pathParts[0];

			const userWorker = env.DISPATCHER.get(userWorkerName);
			return await userWorker.fetch(request);
		} catch (e) {
			if (e.message.startsWith("Worker not found")) {
				return new Response("", { status: 404 });
			}
			return new Response(e.message, { status: 500 });
		}
	},
};

这篇文档对您有帮助吗?