Bezpečný deploy na Cloudflare

Krok 1: Otevřete formulář tokenu ve správném účtu

V dashboardu se přepněte do účtu projektu a otevřete Manage Account → Account API Tokens → Create Token → Custom token. Účtový token patří účtu a do jiného účtu se nikdy nedostane. Funguje i uživatelský token (My Profile → API Tokens), jen ho musíte na jeden účet omezit sami (krok 3).

Krok 2: Pojmenujte token a přidejte jen oprávnění, která projekt používá

Název: např. my-app deploy. Pak pro každý potřebný řádek klikněte na Add more. Podívejte se na bindingy ve svém wrangler.jsonc: d1_databases znamená D1, r2_buckets R2, kv_namespaces KV.

Workers Scripts pokrývá deploy, secrets, Durable Objects i logy. Pokud deploy později spadne na chybějící oprávnění (Queues, Containers, Images), přidejte jen to jedno.

Krok 3: Omezte token na jeden účet

Jen ve formuláři uživatelského tokenu: v sekci Account Resources nechte Include a místo All accounts vyberte účet projektu. Je to nejdůležitější pole celého formuláře. Formulář účtového tokenu ho nemá, protože token je k účtu vázaný.

Krok 4: Povolte token jen z vaší IP adresy

V sekci Client IP Address Filtering nechte Allow a zadejte svou veřejnou adresu. Uniklý token je pak jinde k ničemu. Adresy zjistíte takto:

# your public IPv4 address
curl -4 -s https://ifconfig.me; echo

# your public IPv6 address (no output = you have none, skip it)
curl -6 -s --max-time 5 https://ifconfig.me; echo

Pokud máte i IPv6, přidejte ji přes Add more (adresu nebo její rozsah /64). Jinak se Wrangler může připojit přes IPv6 a dostane chybu 403. Seznam jde upravit i později, třeba když vám poskytovatel adresu změní.

Krok 5: Nastavte platnost, vytvořte token a zkopírujte ho

TTL je nepovinné; rozumná výchozí volba je rok, pak token přegenerujete. Klikněte na Continue to summary → Create Token a hodnotu zkopírujte. Neposílejte ji chatem ani e-mailem, v další kapitole ji vložíte rovnou do projektu. Zkopírujte si i Account ID: na Account home klikněte na tři tečky vedle názvu účtu a zvolte Copy account ID. Account ID není tajné.

Krok 1: Zapište Account ID do wrangler.jsonc

Přidejte "account_id" hned pod "name". Od teď každý deploy i wrangler příkaz tohoto projektu míří jen do tohoto účtu. Pokud má projekt víc konfigurací Wrangleru (např. samostatný statický Worker), přidejte ho do každé.

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Locked to one account: a deploy or any wrangler command cannot land in another account.
  // The API token lives in .env.deploy (see package.json scripts "deploy" and "wr").
  "account_id": "<ACCOUNT_ID>",
  // ... the rest of your config stays as it is
}

Krok 2: Vložte token do .env.deploy

Vytvořte soubor v kořeni projektu a vložte do něj token. Next.js, OpenNext i Vite načítají jen .env, .env.local, .env.<mode> a .env.<mode>.local, wrangler dev jen .dev.vars nebo .env. Soubor .env.deploy sám od sebe nečte nic.

# Only for deploys and the wrangler CLI. Next.js, OpenNext and Vite never read this file.
CLOUDFLARE_API_TOKEN="<API_TOKEN>"

# only you can read the file
chmod 600 .env.deploy

# must print a .gitignore rule; if it prints nothing, add one
git check-ignore -v .env.deploy || echo '.env*' >> .gitignore

# Docker only: keep all env files out of the image
echo '.env*' >> .dockerignore

Krok 3: Odstraňte proměnné Cloudflare ze všech ostatních env souborů

Smažte řádky CLOUDFLARE_API_TOKEN a CLOUDFLARE_ACCOUNT_ID z .env, .env.local, .env.production, .dev.vars a podobných. První příkaz níže nesmí nic vypsat.

# Which env files still contain Cloudflare variables? (prints names, never values)
grep -l 'CLOUDFLARE_' .env .env.* .dev.vars 2>/dev/null | grep -v '^.env.deploy$'

# Show the variable names in .env without their values
sed 's/=.*/=<redacted>/' .env

Proč i Account ID, když není tajné? U příkazů pro Workery vyhrává account_id ve wrangler.jsonc (ověřeno na Wrangleru 4.98 i 4.149), ale příkazy wrangler pages … dávají přednost proměnné a wrangler dev ji předá vašemu kódu jako binding. Jedno místo pro účet obojímu předejde.

Krok 4: Nechte token načítat npm skripty

Každý skript spustí vlastní bash, načte do něj .env.deploy a provede jeden příkaz. Token ve vašem terminálu nezůstane. V package.json nahraďte odpovídající skripty:

Krok 5: Místo npx wrangler používejte npm run -s wr --

Vše za -- dostane Wrangler. Nahraďte npx wrangler i v README, dokumentaci a skriptech, ať nikdo nespustí příkaz bez tokenu.

# instead of:  npx wrangler <command>
npm run -s wr -- whoami
npm run -s wr -- tail
npm run -s wr -- d1 execute <DB_NAME> --remote --command "SELECT 1"
npm run -s wr -- r2 object get <BUCKET>/<KEY> --remote

Proč ne vlastní --env-file Wrangleru? Funguje jen za názvem příkazu (wrangler whoami --env-file=…), před ním Wrangler vypíše jen nápovědu. Obal je jednodušší a stejný pro všechny příkazy.

Krok 1: Wrangler vidí token a správný účet

npm run -s wr -- whoami
# → "You are logged in with an Account API Token" (or "User API Token")
#   and the account you expect

Vidíte jiný účet nebo chybu? Zkontrolujte hodnotu tokenu v .env.deploy a že příkaz spouštíte v kořeni projektu. U uživatelského tokenu se vypíše i Unable to retrieve email… User Details Read: je to jen informace, žádné oprávnění přidávat není třeba.

Krok 2: Bez obalu Wrangler přihlášený není

npx wrangler whoami
# → "You are not authenticated. Please run `wrangler login`."
#   That is correct: without the wrapper there is no token. Do NOT run wrangler login.

Pokud hlásí přihlášení, je aktivní stará relace OAuth (spusťte npx wrangler logout) nebo je token pořád v .env či ve vašem shellu (otevřete nový terminál a vraťte se ke kroku 3 kapitoly 04).

Krok 3: Výstup buildu neobsahuje token

Sestavte projekt lokálně (nic se nenasadí) a prohledejte výstup. Kontroly vypisují jen názvy, nikdy samotný token.

Krok 1: Přidejte skript, který drží staré chunky

Uložte ho jako scripts/keep-old-chunks.sh. merge zkopíruje archivované chunky do čerstvého buildu (nový soubor nikdy nepřepíše), save přidá nasazené chunky do archivu. Archiv leží mimo projekt, v ~/next-deployments-old-assets/<složka projektu>, takže ho čistý checkout ani rm -rf .open-next nesmaže.

#!/usr/bin/env bash
# Keeps the JS/CSS chunks of earlier builds available after a deploy.
#   merge  before the deploy: copy archived chunks into the fresh build (new files are never overwritten)
#   save   after a successful deploy: add the deployed chunks to the archive
# Archive: $OLD_ASSETS_DIR, default ~/next-deployments-old-assets/<project folder name>
# Chunk folder: $CHUNKS_DIR, default .open-next/assets/_next/static (OpenNext); static export: out/_next/static
set -euo pipefail

BUILD="${CHUNKS_DIR:-.open-next/assets/_next/static}"
ARCHIVE="${OLD_ASSETS_DIR:-$HOME/next-deployments-old-assets/$(basename "$PWD")}/$BUILD"

# Copy files from $1 to $2 that do not exist in $2 yet; the count goes to COPIED.
# Paths keep the leading "./" (build folders may start with "-").
COPIED=0
copy_missing() {
  local src=$1 dst=$2 f
  COPIED=0
  while IFS= read -r -d '' f; do
    if [ ! -e "$dst/$f" ]; then
      mkdir -p -- "$(dirname -- "$dst/$f")"
      cp -p -- "$src/$f" "$dst/$f"
      COPIED=$((COPIED + 1))
    fi
  done < <(cd "$src" && find . -type f -print0)
}

# Delete Windows "Zone.Identifier" files (created when files are copied through Windows Explorer into WSL).
remove_zone_ids() {
  local dir n
  for dir in "$@"; do
    [ -d "$dir" ] || continue
    n=$(find "$dir" -type f -name '*:Zone.Identifier' -print -delete | wc -l)
    [ "$n" -gt 0 ] && echo "keep-old-chunks: deleted $n Zone.Identifier files in $dir"
  done
  return 0
}

[ -d "$BUILD" ] || { echo "keep-old-chunks: $BUILD not found, run the build first" >&2; exit 1; }
remove_zone_ids "$ARCHIVE" "$BUILD"

case "${1:-}" in
  merge)
    if [ -d "$ARCHIVE" ]; then
      copy_missing "$ARCHIVE" "$BUILD"
      echo "keep-old-chunks: added $COPIED old files from $ARCHIVE"
    else
      echo "keep-old-chunks: no archive yet ($ARCHIVE), it starts with this deploy"
    fi
    ;;
  save)
    mkdir -p "$ARCHIVE"
    copy_missing "$BUILD" "$ARCHIVE"
    echo "keep-old-chunks: archived $COPIED new files to $ARCHIVE"
    ;;
  *)
    echo "usage: $0 merge|save" >&2
    exit 2
    ;;
esac

chmod +x scripts/keep-old-chunks.sh

Jiné umístění? Nastavte OLD_ASSETS_DIR. Skript z archivu i buildu maže soubory Zone.Identifier z Windows, které vznikají při kopírování přes Průzkumník do WSL.

Krok 2: Zavolejte ho kolem deploye

merge před deployem, save až po úspěšném, aby se do archivu nedostaly soubory, které nikdy nebyly nasazené. Skript deploy pro OpenNext z kapitoly 04 to už dělá. Statický export Next.js jen nastaví CHUNKS_DIR:

# Static Next.js export (output: "export") deployed as Workers Static Assets
"deploy": "next build && CHUNKS_DIR=out/_next/static scripts/keep-old-chunks.sh merge && bash -c 'set -a; . ./.env.deploy; set +a; wrangler deploy' && CHUNKS_DIR=out/_next/static scripts/keep-old-chunks.sh save"

Archiv naroste o pár set kilobajtů na deploy. Kdyby byl někdy velký, smažte v něm nejstarší složky buildů (po pár týdnech je už nikdo nepotřebuje).

Krok 1: Zjistěte, jestli stejný token nepoužívají jiné projekty

Token zkopírovaný z projektu do projektu je běžný. Jeho smazání by rozbilo ostatní, takže každý z nich potřebuje nejdřív vlastní token.

# Do other projects use the same token? Prints file names only, never the token.
# Anything outside this project = that project must get its own token before you delete this one.
T=$(grep '^CLOUDFLARE_API_TOKEN=' .env | cut -d= -f2- | tr -d '"')
[ -n "$T" ] && grep -lsF -- "$T" ~/projects/*/.env* ~/projects/*/.dev.vars; unset T

Krok 2: Najděte starý token v dashboardu

Účtový token je v Manage Account → Account API Tokens, uživatelský v My Profile → API Tokens. Volání níže vypíše ID tokenu a nastaví mu Last used na teď, takže ho v seznamu poznáte. Čerstvého data se nelekněte.

# Which token is it? Prints only its ID, never the token.
# The call also sets "Last used" of that token in the dashboard to now: that is how you spot it in the list.
T=$(grep '^CLOUDFLARE_API_TOKEN=' .env | cut -d= -f2- | tr -d '"')

# account token (Manage Account → Account API Tokens)
curl -s -H "Authorization: Bearer $T" "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/tokens/verify" | grep -o '"id":"[^"]*"'

# user token (My Profile → API Tokens)
curl -s -H "Authorization: Bearer $T" "https://api.cloudflare.com/client/v4/user/tokens/verify" | grep -o '"id":"[^"]*"'
unset T

Krok 3: Vytvořte nový token

Podle kapitoly 03, jeden na projekt.

Krok 4: Upravte projekt

account_id, .env.deploy s novým tokenem, vyčištěný .env, skripty (kapitola 04).

Krok 5: Ověřte účet a build

Kapitola 05.

Krok 6: Nasaďte

npm run deploy. Worker, který teď běží, už žádný token neobsahuje.

Krok 7: Smažte starý token

V dashboardu token, který jste našli v kroku 2. U Next.js teprve teď, u prostého Workeru klidně už po kroku 5.

Krok 8: Zrušte přístup přes OAuth

Pokud jste někdy použili wrangler login:

npx wrangler logout
# then in the dashboard: My Profile → Access Management → Connected Applications → revoke Wrangler