← Cloudflare Workers / workers / platform

Převezměte nasazení (dočasné účty)

Dočasné náhledové účty umožňují nasazovat a testovat Workers než se ověříte u Cloudflare. Poté můžete účet nárokovat a zachovat jeho nasazení a podporované prostředky.

Cloudflare Drop ↗ demonstruje tento životní cyklus náhledu a převzetí pro statické weby. Platformy mohou pomocí REST API nabídnout podobný postup pro generované aplikace.

Kontext návrhu najdete v Dočasné účty Cloudflare pro AI agenty ↗.

Integraci zvolte podle toho, kdo řídí zřizování účtů:

Pro produkci a kontinuální integraci a nasazování (CI/CD) používejte trvalý účet Cloudflare. Ověřte se pomocí wrangler login nebo Token Cloudflare API.

Použijte Wrangler, když AI agent nebo nástroj spouští příkazy pro nasazení. Wrangler se stará o proof-of-work výzvu, přihlašovací údaje a claim URL.

Wrangler 4.102.0 nebo novější vypíše pokyny pro opětovné spuštění neautentizovaných nasazení s --temporary.

REST API použijte v případě, že nasazení řídí backend vaší platformy. Backend založí účet ještě před ověřením uživatele a následně nasadí podporované prostředky.

Všechna volání pro provisioning a nasazení provádějte ze svého backendu. Odpověď provisioningu obsahuje citlivé přihlašovací údaje a claim URL.

Následující diagram ukazuje, jak platforma uchovává dočasné přihlašovací údaje na backendu, zatímco uživatel prohlíží a přebírá nasazení:

flowchart LR
    accTitle: Platform preview and claim architecture
    accDescr: A user accepts Cloudflare's policies and requests a preview in the platform UI. The trusted platform backend creates a temporary account, keeps account.apiToken private, deploys the Worker, and returns only the preview and claim URLs to the UI. The claim URL is a bearer credential shown only to the intended user. The user claims the account in the Cloudflare dashboard. Future platform deployments require a separate OAuth flow.

    USER((User))

    subgraph PLATFORM["Platform"]
        direction TB
        UI["Platform UI<br/>No temporary API token"]
        BACKEND["Trusted platform backend<br/>Stores account.apiToken"]
        UI -->|"2. Request preview"| BACKEND
        BACKEND -->|"10. Preview URL and bearer claim URL only"| UI
    end

    subgraph CLOUDFLARE["Cloudflare"]
        direction TB
        API["Cloudflare API"]
        DASHBOARD["Cloudflare dashboard<br/>Claims the account"]
    end

    USER -->|"1. Accept policies and generate application"| UI
    BACKEND -->|"3. Request challenge"| API
    API -->|"4. Challenge parameters"| BACKEND
    BACKEND -->|"5. Solve challenge locally"| BACKEND
    BACKEND -->|"6. Create temporary account with solution"| API
    API -->|"7. Account ID, API token, and claim URL"| BACKEND
    BACKEND -->|"8. Deploy Worker and request subdomain"| API
    API -->|"9. workers.dev subdomain"| BACKEND
    UI -->|"11. Show live preview and intended-user-only claim link"| USER
    USER -->|"12. Sign in and complete claim"| DASHBOARD
    DASHBOARD -.->|"Optional after claim"| OAUTH["Separate OAuth flow<br/>for future platform deployments"]

Před vytvořením dočasného účtu si vyžádejte výzvu proof-of-work:

curl "https://api.cloudflare.com/client/v4/provisioning/previews/challenge" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{}'

Odpověď obsahuje token výzvy, seed a parametry obtížnosti:

{
	"success": true,
	"result": {
		"challengeToken": "<CHALLENGE_TOKEN>",
		"seed": "<BASE64URL_32_BYTE_SEED>",
		"k": 8000,
		"g": 2000
	},
	"errors": [],
	"messages": []
}

Vyřešte výzvu výpočtem sekvenčního řetězce kontrolních bodů SHA-256:

Před vyřešením challenge vyžadujte k a g aby byla kladná celá čísla. Výzvu odmítněte, pokud seed nelze dekódovat na 32 bajtů nebo pokud k * g přesahuje 64,000,000.

Následující příklad v Node.js aplikuje tyto meze a vrací objekt požadovaný pro create request:

import { createHash } from "node:crypto";

function sha256(value) {
	return createHash("sha256").update(value).digest();
}

export function solvePreviewChallenge({ challengeToken, seed, k, g }) {
	const seedBytes = Buffer.from(seed, "base64url");
	if (seedBytes.length !== 32) {
		throw new Error("seed must decode to 32 bytes");
	}
	if (!Number.isInteger(k) || k <= 0) {
		throw new Error("k must be a positive integer");
	}
	if (!Number.isInteger(g) || g <= 0) {
		throw new Error("g must be a positive integer");
	}
	if (k * g > 64_000_000) {
		throw new Error("k * g must not exceed 64,000,000");
	}

	const checkpoints = [];
	let hash = sha256(seedBytes);

	checkpoints.push(hash);

	for (let segment = 0; segment < k; segment++) {
		for (let iteration = 0; iteration < g; iteration++) {
			hash = sha256(hash);
		}

		checkpoints.push(hash);
	}

	return {
		challengeToken,
		solution: {
			checkpoints: Buffer.concat(checkpoints).toString("base64"),
		},
	};
}

import { createHash } from "node:crypto";

type PreviewChallenge = {
	challengeToken: string;
	seed: string;
	k: number;
	g: number;
};

function sha256(value: Uint8Array): Buffer {
	return createHash("sha256").update(value).digest();
}

export function solvePreviewChallenge({
	challengeToken,
	seed,
	k,
	g,
}: PreviewChallenge) {
	const seedBytes = Buffer.from(seed, "base64url");
	if (seedBytes.length !== 32) {
		throw new Error("seed must decode to 32 bytes");
	}
	if (!Number.isInteger(k) || k <= 0) {
		throw new Error("k must be a positive integer");
	}
	if (!Number.isInteger(g) || g <= 0) {
		throw new Error("g must be a positive integer");
	}
	if (k * g > 64_000_000) {
		throw new Error("k * g must not exceed 64,000,000");
	}

	const checkpoints: Buffer[] = [];
	let hash = sha256(seedBytes);

	checkpoints.push(hash);

	for (let segment = 0; segment < k; segment++) {
		for (let iteration = 0; iteration < g; iteration++) {
			hash = sha256(hash);
		}

		checkpoints.push(hash);
	}

	return {
		challengeToken,
		solution: {
			checkpoints: Buffer.concat(checkpoints).toString("base64"),
		},
	};
}

Vyžadovat, aby uživatel přijal Cloudflare Smluvní podmínky ↗ a Zásady ochrany osobních údajů ↗ před vytvořením účtu. Nastavte acceptTermsOfService na "yes" až poté, co uživatel obojí odsouhlasí.

Poté odešlete řešení proof-of-work s požadovanými poli zásad:

curl "https://api.cloudflare.com/client/v4/provisioning/previews" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "termsOfService": "https://www.cloudflare.com/terms/",
    "privacyPolicy": "https://www.cloudflare.com/privacypolicy/",
    "acceptTermsOfService": "yes",
    "challengeToken": "<CHALLENGE_TOKEN>",
    "solution": {
      "checkpoints": "<BASE64_CHECKPOINTS>"
    }
  }'

Odpověď obsahuje dočasné přihlašovací údaje a URL adresu pro převzetí:

{
	"success": true,
	"result": {
		"account": {
			"id": "<TEMPORARY_ACCOUNT_ID>",
			"name": "<TEMPORARY_ACCOUNT_NAME>",
			"type": "standard",
			"apiToken": "<TEMPORARY_ACCOUNT_API_TOKEN>",
			"tokenId": "<TEMPORARY_TOKEN_ID>",
			"expiresAt": "<ACCOUNT_EXPIRES_AT>"
		},
		"claim": {
			"token": "<CLAIM_TOKEN>",
			"url": "https://dash.cloudflare.com/claim-preview?claimToken=<CLAIM_TOKEN>",
			"expiresAt": "<CLAIM_EXPIRES_AT>"
		}
	},
	"errors": [],
	"messages": []
}

Než odpověď použijete, ověřte, že success je true. Ověřte, že account.id, account.apiToken, account.expiresAt, claim.url, a claim.expiresAt jsou přítomné.

Použijte account.id a account.apiToken s podporovanými koncovými body Cloudflare API. Dočasné hodnoty používejte pouze u podporovaných operací se zdroji.

Tokeny dočasných účtů neudělují všechna oprávnění API, která mají trvalé účty. Nepodporované operace vrátí chybu autorizace.

Následující příklady nahrají a nasadí Worker s Workers Script Upload API, poté načtěte účtu workers.dev subdoména.

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/scripts/$SCRIPT_NAME" \
  -X PUT \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  -F 'metadata={"main_module":"worker.mjs","compatibility_date":"<YYYY-MM-DD>"};type=application/json' \
  -F '[email protected];type=application/javascript+module'

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/workers/subdomain" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

import Cloudflare from "cloudflare";

export async function deployWorker(
	accountId: string,
	apiToken: string,
	scriptName: string,
	compatibilityDate: string,
	scriptContent: string,
) {
	const client = new Cloudflare({ apiToken });
	const workerModule = new File([scriptContent], "worker.mjs", {
		type: "application/javascript+module",
	});

	await client.workers.scripts.update(scriptName, {
		account_id: accountId,
		metadata: {
			main_module: "worker.mjs",
			compatibility_date: compatibilityDate,
		},
		files: [workerModule],
	});

	const { subdomain } = await client.workers.subdomains.get({
		account_id: accountId,
	});

	return `https://${scriptName}.${subdomain}.workers.dev`;
}

Zadejte URL adresu nasazení a claim.url zamýšlenému uživateli.

Zamýšlený uživatel musí převzetí dokončit do 60 minut. Pouhé otevření URL adresy pro převzetí před uplynutím lhůty nestačí.

Otevřou danou URL adresu, přihlásí se do Cloudflare nebo si vytvoří účet a poté dokončí kroky v dashboardu.

Pokud uživatel nedokončí převzetí účtu, Cloudflare účet i jeho prostředky odstraní.

Ve Wrangleru znovu spusťte wrangler deploy --temporary pokud vyprší platnost dočasných přihlašovacích údajů nebo claim URL. Wrangler vytvoří nový účet a vypíše nové claim URL.

U integrací REST si vyžádejte novou výzvu (challenge) a účet, pokud account.expiresAt nebo claim.expiresAt uplyne před claimem.

Po převzetí zůstávají Worker a podporované prostředky v účtu, který jej převzal.

Chcete-li pokračovat pomocí Wrangler, spusťte wrangler login, poté nasaďte bez --temporary. Převzetí neuděluje platformě trvalý přístup k účtu.

Pro pozdější nasazení připojte nárokovaný účet prostřednictvím běžného ověřeného postupu, například pomocí OAuth klient Cloudflare.

Následující tabulka shrnuje podporované funkce a limity. Dočasné přihlašovací údaje neumožňují všechny operace u těchto prostředků.

• account.apiToken autorizuje podporované operace nad prostředky. Nikdy jej nevystavujte v odpovědích prohlížeče ani v kódu na straně klienta.
• Považujte claim.url jako přístupový token typu bearer. Kdokoli, kdo zná danou URL, si může nárokovat vlastnictví dočasného účtu.
• Obě hodnoty ukládejte pouze v úložišti na backendu nebo v úložišti relace na straně serveru vázaném na daného uživatele. Doručte claim.url pouze danému uživateli.
• Obě hodnoty vylučte z protokolů, analytiky a telemetrie podpory. Uložené kopie odstraňte, jakmile již nejsou potřeba, nejpozději však do vrácené doby expirace.

• Cloudflare před vytvořením účtu vyžaduje kontrolu proof-of-work. Wrangler tuto kontrolu zpracovává automaticky, zatímco integrace přes REST musí odeslat řešení.
• Cloudflare omezuje rychlost vytváření dočasných účtů (rate limiting). Před opakováním počkejte, nebo se ověřte pomocí trvalého účtu.
• --temporary podporuje pouze neautentizované použití. Existující přihlašovací údaje OAuth, API token nebo globální API klíč způsobí chybu.
• --temporary není globální příznak. Obsahují jej pouze příkazy, které podporují dočasné přihlašovací údaje.
• Zřizování dočasných účtů je dostupné pouze prostřednictvím výchozího veřejného API endpointu. Přes FedRAMP High API endpoint dostupné není.
• Cloudflare může odmítnout požadavky, které neprojdou dalšími kontrolami proti zneužití.