← Cloudflare Workers / workers / configuration

Umístění

Standardně Workers a Pages Functions se spouští v datovém centru nejblíže místu přijetí požadavku. Pokud váš Worker odesílá požadavky na backendovou infrastrukturu, jako jsou databáze nebo API, může být výkonnější provozovat tento Worker blíže backendu než koncovému uživateli.

{
	"placement": {
		// Use one of the following options (mutually exclusive):
		"mode": "smart", // Cloudflare automatically places your Worker closest to the upstream with the most requests
		"region": "gcp:us-east4", // Explicit cloud region to run your Worker closest to - e.g. "gcp:us-east4" or "aws:us-east-1"
		"host": "db.example.com:5432", // A host to probe (TCP/layer 4) - e.g. a database host - and place your Worker closest to
		"hostname": "api.example.com", // A hostname to probe (HTTP/layer 7) - e.g. an API endpoint - and place your Worker closest to
	},
}

[placement]
mode = "smart"
region = "gcp:us-east4"
host = "db.example.com:5432"
hostname = "api.example.com"

Umístění dokáže snížit celkovou latenci požadavku na Worker tím, že minimalizuje latenci zpáteční cesty požadavků mezi vaším Workerem a backendovými službami. Díky tomu lze dosáhnout latence v jednotkách milisekund k databázím, API a dalším službám běžícím ve starší cloudové infrastruktuře.

Představte si uživatele v australském Sydney, který přistupuje k aplikaci běžící na Workers. Tato aplikace provádí několik zpátečních cest k databázi v německém Frankfurtu.

Latence z opakovaných cest tam a zpět mezi Sydney a Frankfurtem se sčítá. Umístěním Workeru blíže databázi Cloudflare zkracuje celkovou dobu trvání požadavku.

Smart Placement automaticky analyzuje vzorce provozu vašeho Workeru a umístí ho na optimální lokalitu. Smart Placement použijte, když:

• Váš Worker se připojuje k více backendovým službám
• Neznáte přesné umístění své infrastruktury
• Vaše backendové služby jsou distribuované nebo replikované

Smart Placement se zapíná pro každý Worker zvlášť. Po zapnutí analyzuje doba trvání požadavku Workeru pravidelně v různých lokalitách Cloudflare.

U každé kandidátské lokality Smart Placement zohledňuje výkon Workeru a síťovou latenci přidanou přeposláním požadavku. Pokud je kandidátská lokalita výrazně rychlejší, požadavek se přepošle tam. V opačném případě Worker běží ve výchozí lokalitě nejbližší požadavku.

Smart Placement bere v úvahu pouze lokality, kde Worker již dříve běžel. Nemůže Worker umístit do lokality, která běžně nepřijímá provoz.

• Smart Placement ovlivňuje pouze spouštění obslužné rutiny události fetch. Nemá to vliv na Metody RPC nebo pojmenované entrypointy.
• Workers bez handleru události fetch Smart Placement ignoruje.
• Statické prostředky se vždy poskytují z lokality nejblíže příchozímu požadavku. Pokud váš kód načítá assety pomocí static assets binding, assety se poskytují z místa, kde váš Worker běží.

Smart Placement je dostupný ve všech plánech Workers.

Přidejte následující do konfiguračního souboru Wrangler:

{
	"placement": {
		"mode": "smart",
	},
}

[placement]
mode = "smart"

Smart Placement může po nasazení analyzovat váš Worker až 15 minut.

1. Přejděte na Workers & Pages.

   Přejděte na Workers & Pages ↗

2. Vyberte svůj Worker.

3. Přejděte na Nastavení > Obecné.

4. V části Umístění, vyberte Smart.

Aby mohl Smart Placement rozhodnout o umístění, potřebuje stálý provoz na Worker z více lokalit. Proces analýzy může trvat až 15 minut.

Stav umístění svého Workeru zjistíte prostřednictvím Workers API:

curl -X GET https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/services/$WORKER_NAME \
-H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
-H "Content-Type: application/json" | jq .

Možné stavy umístění:

Jakmile povolíte Smart Placement, začnou se sbírat údaje o době trvání požadavků. Doba trvání požadavku se měří v datovém centru nejbližším koncovému uživateli. Ve výchozím nastavení se 1 % požadavků nesměruje pomocí Smart Placement, aby sloužily jako výchozí základ pro srovnání.

Zobrazit u vašeho Workeru analytika doby trvání požadavků k měření dopadu Smart Placement.

Cloudflare přidává cf-placement hlavičku ke všem požadavkům, když je umístění povoleno. Pomocí této hlavičky zjistíte, zda byl požadavek směrován pomocí Smart Placement a kde Worker požadavek zpracoval.

Hodnota hlavičky obsahuje typ umístění a kód letiště označující umístění datacentra:

• remote-LHR : požadavek byl směrován pomocí Smart Placement do datacentra poblíž Londýna.
• local-EWR : požadavek nebyl směrován pomocí Smart Placement. Worker běžel ve výchozí lokalitě poblíž Newarku.

Nápovědy pro umístění vám umožňují explicitně určit, kde váš Worker běží. Použijte nápovědy pro umístění, pokud:

• Znáte přesné umístění své backendové infrastruktury
• Váš Worker se připojuje k jedné databázi, API nebo službě
• Vaše infrastruktura je single-homed (není replikovaná ani anycastovaná)

Mezi příklady patří primární databáze, virtuální stroj nebo klastr Kubernetes v konkrétní oblasti. Snížení obousměrné latence z 20 až 30 milisekund na dotaz na 1 až 3 milisekundy zlepšuje dobu odezvy.

Pokud vaše infrastruktura běží v AWS, GCP nebo Azure, nastavte placement.region vlastnost pomocí formátu {provider}:{region}:

{
	"placement": {
		"region": "aws:us-east-1", // Explicit cloud region to run your Worker closest to - e.g. "gcp:us-east4" or "aws:us-east-1"
	},
}

[placement]
region = "aws:us-east-1"

Cloudflare namapuje vámi zadaný cloudový region na datacentrum s nejnižší latencí k tomuto regionu. Cloudflare automaticky upravuje umístění s ohledem na údržbu sítě nebo změny, takže nemusíte zadávat záložní (failover) regiony.

Pokud vaše infrastruktura neběží u žádného z hlavních poskytovatelů cloudu, můžete zadat koncový bod, který Cloudflare otestuje. Cloudflare podle něj odhadne polohu vašeho externího hostitele a umístí Workers do nejbližšího regionu.

Nastavte placement.host k identifikaci služby vrstvy 4. Cloudflare měří latenci pomocí kontrol TCP CONNECT a vybírá nejvhodnější datacentrum.

{
	"placement": {
		"host": "my_database_host.com:5432", // A host to probe (TCP/layer 4) - e.g. a database host - and place your Worker closest to
	},
}

[placement]
host = "my_database_host.com:5432"

Nastavte placement.hostname k identifikaci služby vrstvy 7. Cloudflare měří latenci pomocí kontrol HTTP HEAD a vybírá nejvhodnější datacentrum.

{
	"placement": {
		"hostname": "my_api_server.com", // A hostname to probe (HTTP/layer 7) - e.g. an API endpoint - and place your Worker closest to
	},
}

[placement]
hostname = "my_api_server.com"

Sondy se odesílají z veřejných rozsahů IP adres, nikoli z rozsahů IP adres Cloudflare. Cloudflare v pravidelných intervalech znovu ověřuje umístění služby. Tyto sondy lokalizují prostředky s jediným připojením a u broadcastových, anycastových, multicastových nebo replikovaných prostředků nefungují správně.

Nápovědy pro umístění podporují identifikátory oblastí Amazon Web Services (AWS), Google Cloud Platform (GCP) a Microsoft Azure:

Úplný seznam kódů regionů najdete v Regiony AWS ↗, Regiony GCP ↗, nebo Oblasti Azure ↗.

Umístění Workers se chová podobně bez ohledu na to, zda používáte Smart Placement, nebo Placement Hints. Následující chování platí pro obě možnosti.

Následující omezení platí jak pro Smart Placement, tak pro Placement Hints:

• Umístění ovlivňuje pouze spouštění obslužné rutiny události fetch. Nemá to vliv na Metody RPC nebo pojmenované entrypointy.
  • Workers bez handleru události fetch jsou při umísťování ignorovány.
  • Statické prostředky se vždy poskytují z lokality nejblíže příchozímu požadavku. Pokud váš kód načítá assety pomocí static assets binding, assety se poskytují z místa, kde váš Worker běží.

Cloudflare přidává cf-placement hlavičku ke všem požadavkům, pokud je aktivní umístění (placement). Pomocí této hlavičky zjistíte, zda byl požadavek směrován s využitím umístění a kde ho Worker zpracoval.

Hodnota hlavičky obsahuje typ umístění a kód letiště označující umístění datacentra:

• remote-LHR : požadavek byl směrován pomocí Smart Placement do datacentra poblíž Londýna.
• local-EWR : požadavek nebyl směrován pomocí Smart Placement. Worker běžel ve výchozí lokalitě poblíž Newarku.

Pokud na Workers vytváříte full-stack aplikace, rozdělte edge logiku (autentizace, routing) a back-end logiku (databázové dotazy, volání API) do samostatných Workers. Použijte Service Bindings pro jejich propojení pomocí typově bezpečného RPC.

Povolte umístění pro backendový Worker, aby se spouštěl blízko vaší databáze, zatímco edge Worker bude řešit ověřování blízko uživatele.

Tento příklad ukazuje dva Workery:

• auth-worker, runs at the edge (no placement), handles authentication
• app-worker, placed near your database, handles data queries

{
	"name": "auth-worker",
	"main": "src/index.ts",
	"services": [{ "binding": "APP", "service": "app-worker" }],
}

name = "auth-worker"
main = "src/index.ts"

[[services]]
binding = "APP"
service = "app-worker"

import { AppWorker } from "../app-worker/src/index";

interface Env {
	APP: Service<AppWorker>;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const authHeader = request.headers.get("Authorization");
		if (!authHeader?.startsWith("Bearer ")) {
			return new Response("Unauthorized", { status: 401 });
		}

		const userId = await validateToken(authHeader.slice(7));
		if (!userId) {
			return new Response("Invalid token", { status: 403 });
		}

		// Call the placed back-end Worker via RPC
		const data = await env.APP.getUser(userId);
		return Response.json(data);
	},
};

async function validateToken(token: string): Promise<string | null> {
	return token === "valid" ? "user-123" : null;
}

{
	"name": "app-worker",
	"main": "src/index.ts",
	"placement": {
		// Use one of the following options (mutually exclusive):
		// "mode": "smart", // Cloudflare automatically places your Worker closest to the upstream with the most requests
		"region": "aws:us-east-1", // Explicit cloud region to run your Worker closest to - e.g. "gcp:us-east4" or "aws:us-east-1"
		// "host": "db.example.com:5432", // A host to probe (TCP/layer 4) - e.g. a database host - and place your Worker closest to
		// "hostname": "api.example.com", // A hostname to probe (HTTP/layer 7) - e.g. an API endpoint - and place your Worker closest to
	},
}

name = "app-worker"
main = "src/index.ts"

[placement]
region = "aws:us-east-1"

import { WorkerEntrypoint } from "cloudflare:workers";

export default class AppWorker extends WorkerEntrypoint {
	async fetch() {
		return new Response(null, { status: 404 });
	}

	// Each method runs near your database - multiple queries stay fast
	async getUser(userId: string) {
		const user = await this.env.DB.prepare("SELECT * FROM users WHERE id = ?")
			.bind(userId)
			.first();
		return user;
	}

	async getUserListings(userId: string) {
		// Multiple round-trips to the DB are low-latency when placed nearby
		const user = await this.env.DB.prepare("SELECT * FROM users WHERE id = ?")
			.bind(userId)
			.first();
		const listings = await this.env.DB.prepare(
			"SELECT * FROM listings WHERE owner_id = ?",
		)
			.bind(userId)
			.all();
		const reviews = await this.env.DB.prepare(
			"SELECT * FROM reviews WHERE listing_id IN (SELECT id FROM listings WHERE owner_id = ?)",
		)
			.bind(userId)
			.all();

		return { user, listings: listings.results, reviews: reviews.results };
	}
}

auth-worker se spouští na okraji sítě, aby rychle odmítl neautorizované požadavky. Ověřené požadavky se předávají přes RPC do app-worker, který běží v blízkosti vaší databáze pro rychlé dotazy.

Durable Objects poskytují automatické umístění bez nutnosti konfigurace. Dotazy na vestavěnou databáze SQLite jsou fakticky s nulovou latencí ↗ protože výpočet běží ve stejném procesu jako data.

Proveďte co nejvíce práce přímo uvnitř Durable Object a vraťte souhrnný výsledek, místo abyste z Workeru posílali několik samostatných požadavků:

import { DurableObject } from "cloudflare:workers";

type Session = { id: string; user_id: string; created_at: number };
type PromptHistory = {
	id: string;
	session_id: string;
	role: string;
	content: string;
};

export class AgentHistory extends DurableObject {
	async getSessionContext(sessionId: string) {
		// All queries execute with zero network latency — compute and data are colocated
		const session = this.ctx.storage.sql
			.exec<Session>("SELECT * FROM sessions WHERE id = ?", sessionId)
			.one();
		const prompts = this.ctx.storage.sql
			.exec<PromptHistory>(
				"SELECT * FROM prompt_history WHERE session_id = ? ORDER BY created_at",
				sessionId,
			)
			.toArray();

		return { session, prompts };
	}
}