← Cloudflare Workers / workers / static-assets / routing / advanced

Afinita verze

Během postupné nasazení, každý požadavek má náhodnou šanci na směrování k jedné či druhé verzi podle zadaných procentuálních podílů. To znamená, že stejnému uživateli může být při každém požadavku poskytnut obsah z jiné verze, což může způsobit nesoulad verzí vydává.

Afinita verze to řeší tak, že deterministicky přiřazuje uživatele k verzi na základě stabilního identifikátoru, takže po celou dobu postupného nasazování konzistentně přistupují ke stejné verzi napříč načteními stránky a dílčími požadavky.

Nastavte Cloudflare-Workers-Version-Key hlavičku v příchozím požadavku na váš Worker:

curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: foo'

Pro dané nasazení, všechny požadavky s klíčem verze nastaveným na foo zpracuje vždy stejná verze vašeho Workeru. Platforma klíč zahashuje a výsledek pak spolu s nastavenými procenty použije k deterministickému přiřazení verze, přičemž vy sami nevybíráte, na kterou verzi se daný klíč namapuje.

Jak postupujete v postupném nasazení (například z 10 % na 20 % a poté na 50 %), uživatelé, jejichž klíče už byly přiřazeny k nové verzi, na ní zůstanou. Uživatelé na staré verzi budou postupně přecházet na novou verzi s rostoucím procentem, ale zpět se nevrátí, pokud neprovedete rollback.

Můžete nastavit Cloudflare-Workers-Version-Key hlavičku jak při externím požadavku z internetu na váš Worker, tak při dílčím požadavku z jednoho Workeru na jiný Worker pomocí service binding.

Afinita verze je obzvláště důležitá, když váš Worker obsluhuje statická aktiva s názvy souborů obsahujícími hash obsahu (například index-a1b2c3d4.js), což je výchozí chování většiny moderních sestavovacích nástrojů a frameworků.

Během postupného nasazování budou mít různé verze vaší aplikace odlišné názvy souborů s assety:

• HTML verze A odkazuje na assets/index-a1b2c3d4.js
• HTML verze B odkazuje na assets/index-m3n4o5p6.js

Bez version affinity může uživatel obdržet HTML z verze A, ale když jeho prohlížeč požádá o index-a1b2c3d4.js, může být tento požadavek směrován na verzi B, která tento soubor nemá, což vede k chybě 404 a nefunkční stránce.

Konfigurace version affinity pomocí libovolné z metod uvedených v Zvolte klíč verze tomu zcela zabraňuje tím, že zajišťuje, aby všechny požadavky od stejného uživatele byly směrovány na stejnou verzi.

Správný klíč verze závisí na tom, jaké stabilní identifikátory má vaše aplikace k dispozici. Hlavičku můžete nastavit pomocí Transform Rule ve vaší zóně, který extrahuje hodnoty z požadavku bez úpravy kódu vaší aplikace.

Pokud má vaše aplikace identifikátor uživatele v cookie nebo hlavičce, jde o nejlepší možnost. Každý uživatel je deterministicky přiřazen k určité verzi a zůstává u ní napříč relacemi, zařízeními i obnoveními stránky.

http.cookie contains "user_id"

Pokud vaše aplikace nastavuje cookie relace, použijte identifikátor relace. Tím zajistíte konzistentní směrování po celou dobu trvání relace. Pokud relace vyprší a vytvoří se nová, uživatel může být přiřazen k jiné verzi.

http.cookie contains "session_id"

Pokud vaše aplikace nemá v požadavku žádný stabilní identifikátor, máte dvě možnosti:

Možnost 1: Použijte IP adresu klienta. Toto je nejjednodušší přístup a nevyžaduje žádné změny v aplikaci. Uživatelé za stejnou NAT nebo VPN budou seskupeni dohromady a mobilní uživatelé, kteří přepínají sítě, mohou změnit verzi, ale u většiny aplikací to výrazně omezuje časté přepínání mezi verzemi ve srovnání s náhodným směrováním jednotlivých požadavků.

true

Možnost 2: Nastavte ve svém Workeru dlouhodobou cookie. Při prvním požadavku (kterému bude přiřazena náhodná hodnota) váš Worker vygeneruje stabilní identifikátor a uloží jej jako cookie. Všechny další požadavky pak tuto cookie používají jako klíč verze. To poskytuje nejlepší konzistenci pro anonymní uživatele za cenu mírného navýšení kódu aplikace.

export default {
	async fetch(request, env) {
		const response = await handleRequest(request, env);

		// Set a long-lived cookie to use as a version affinity key.
		const COOKIE_NAME = "version-key"; // can be any name
		const cookieHeader = request.headers.get("Cookie") ?? "";
		const hasAffinityCookie = new RegExp(`(?:^|;\\s*)${COOKIE_NAME}=`).test(
			cookieHeader,
		);

		if (!hasAffinityCookie) {
			const id = crypto.randomUUID();
			response.headers.append(
				"Set-Cookie",
				`${COOKIE_NAME}=${id}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=31536000`,
			);
		}

		return response;
	},
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const response = await handleRequest(request, env);

    // Set a long-lived cookie to use as a version affinity key.
    const COOKIE_NAME = "version-key"; // can be any name
    const cookieHeader = request.headers.get("Cookie") ?? "";
    const hasAffinityCookie = new RegExp(`(?:^|;\\s*)${COOKIE_NAME}=`).test(cookieHeader);

    if (!hasAffinityCookie) {
      const id = crypto.randomUUID();
      response.headers.append(
        "Set-Cookie",
        `${COOKIE_NAME}=${id}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=31536000`,
      );
    }

    return response;
  },
};

Poté vytvořte Transform Rule, které bude tento cookie používat jako verzovací klíč:

http.cookie contains "version-key"

Funkčnost version affinity můžete ověřit odesláním více požadavků se stejným klíčem verze a kontrolou, že je zpracovává stejná verze:

# Both requests should return responses from the same version
curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: test-user-123'
curl -s https://example.com -H 'Cloudflare-Workers-Version-Key: test-user-123'

Použijte vazba metadat verze abyste během testování zahrnuli ID verze do odpovědi vašeho Workeru.

Během postupného nasazování sledujte v analytice svého Workeru zvýšený počet odpovědí 404, zejména u souborů assetů (.js, .css, .png). Použijte Analytics Engine nebo Logpush ke sledování těchto metrik a včasnému zachycení problémů s nesouladem verzí. Pokud si všimnete problémů, můžete vrátit zpět na předchozí verzi.

• Gradual Deployments - Jak funguje procentuální rozdělení provozu
• Přepisy verzí - Odešlete požadavek na konkrétní verzi podle ID (pro smoke testing a ladění, nikoli pro směrování koncových uživatelů)
• Vazba metadat verze : přístup k ID verze a tagu přímo z Workeru