Einführung
Ein Hilfezentrum kann sein Design und sein Begrüßungsbanner aus KV lesen. Dadurch kann eine Redaktion diese Einstellungen ändern, ohne neuen Code bereitzustellen. Nach einer Aktualisierung sehen Leser an verschiedenen Standorten möglicherweise kurzzeitig unterschiedliche Versionen. Die Anwendung muss während dieses Übergangs nutzbar bleiben, anstatt davon auszugehen, dass jeder Lesevorgang die neuesten Einstellungen liefert.
Sie erstellen einen versionierten Konfigurationsleser mit sicheren Standardwerten, testen eine absichtlich simulierte Folge alter und neuer Werte und führen anschließend eine echte Aktualisierung in der Cloud durch. Eine Version ist ein zusammen mit den Einstellungen gespeichertes Kennzeichen. Sie hilft Ihnen dabei, den empfangenen Wert zu identifizieren. Sie macht KV jedoch nicht zu einer Datenbank mit starker Konsistenz und garantiert nicht, dass aufeinanderfolgende Anfragen steigende Versionsnummern sehen.
Schließen Sie zuerst die vorherigen KV-Labs ab. Diese unabhängige VM enthält Node.js 22.22.0 und Wrangler 4.131.1 als projektspezifische Version in /home/labex/project/delayed-config. Verwenden Sie Ihr eigenes Lernkonto mit denselben Berechtigungen zum Lesen des Kontos sowie zum Schreiben in Worker und KV. Die Übung erstellt einen kurzlebigen Worker und einen kurzlebigen Namespace und stellt ausschließlich synthetische Anzeigeeinstellungen bereit. Für den kleinen Datensatz sind weder ein kostenpflichtiges Upgrade noch eine gekaufte Domain erforderlich. Diese Einstellungen steuern weder die Autorisierung noch Zahlungen oder andere Entscheidungen, die eine sofortige autoritative Aktualisierung erfordern.
Einen unabhängigen Konfigurationsspeicher verbinden
In diesem Schritt verbinden Sie einen neuen Namespace für die Anzeigekonfiguration. Die CONFIG-Bindung hält die Ressourcenreferenz in der standardmäßigen Wrangler-Konfiguration. Verwenden Sie neue Lab-Ressourcen, damit absichtlich ungültige Einstellungen keine andere Anwendung beeinflussen können.
Wechseln Sie in das vorbereitete Projekt:
cd /home/labex/project/delayed-config
Erzeugen Sie einmalig einen eindeutigen Namen. openssl rand -hex 6 gibt ein zufälliges Suffix aus; $(...) fügt es in den Namen ein. Die Shell-Variable stellt diesen Namen für die folgenden Befehle in diesem Terminal bereit.
WORKER_NAME="labex-config-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorisieren Sie diese VM. Neben dem Lesen Ihrer Kontoidentität ermöglicht Workers Scripts Write die Bereitstellung und Löschung. Workers KV Write ermöglicht die Verwaltung des Namespace und der Schlüssel für dieses Lab.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Öffnen Sie den angezeigten Geräte-Link im Browser, geben Sie den aktuellen Code ein, prüfen Sie die angeforderten Berechtigungen und das Lernkonto und autorisieren Sie Wrangler. Auf der Zustimmungsseite kann außerdem ein Zugriff im Hintergrund angezeigt werden. Wechseln Sie zurück zum Terminal und warten Sie, bis die Anmeldung abgeschlossen ist.
Prüfen Sie dieselben Berechtigungen zum Schreiben in Worker und KV, die zuvor in diesem Kurs eingeführt wurden, und bestätigen Sie das Lernkonto.
npx wrangler whoami --json
Bestätigen Sie loggedIn: true sowie den name des Lernkontos, auch wenn nur ein Konto aufgelistet wird. Kopieren Sie die id dieses Kontos. Tragen Sie sie in der folgenden Konfiguration anstelle von YOUR_ACCOUNT_ID ein, bevor Sie den Befehl ausführen. Das cat-Here-Dokument schreibt alles zwischen den beiden JSON-Zeilen in eine Datei; > ersetzt die Datei. Durch das nicht maskierte Trennzeichen kann die Shell $WORKER_NAME einsetzen.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
Erstellen Sie in diesem Konto einen Namespace. Sein Titel enthält denselben eindeutigen Namen wie der Worker, damit Sie beide später wiedererkennen. --update-config=false lässt die Änderung an der Bindung sichtbar für Sie, statt die Datei automatisch zu ändern.
npx wrangler kv namespace create "$WORKER_NAME-config" --update-config=false
Die Ausgabe enthält die ID des neuen Namespace. Kopieren Sie sie und ersetzen Sie anschließend YOUR_ACCOUNT_ID und YOUR_NAMESPACE_ID in dieser vollständigen Konfiguration. Der Name der CONFIG-Bindung wird für Ihren Code gewählt; die ID identifiziert die tatsächliche Cloudflare-Ressource.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "CONFIG", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Suchen Sie den Namespace-Titel dieses Labs und vergleichen Sie seine ID mit der ID in der Datei. Andere Namespaces können vorhanden sein; lassen Sie diese unverändert. Diese Konfiguration legt fest, welches Konto und welche Ressource die späteren Befehle verwenden sollen. Eine Bindung ist eine Referenz auf einen Namespace und keine Kopie seiner Daten.
Versionierte Einstellungen mit sicheren Standardwerten lesen
In diesem Schritt sorgen Sie dafür, dass beide gültigen Versionen nutzbare Antworten liefern. Fehlende oder beschädigte Anzeigeeinstellungen fallen auf ein einfaches helles Design und kein Banner zurück. Dadurch verhindert eine optionale Darstellungseinstellung, dass das Hilfezentrum nicht mehr funktioniert.
Schreiben Sie den Handler. Das unveränderliche Objekt defaults enthält keinen anfragespezifischen Zustand und wird nie geändert. Jede Anfrage liest ihr eigenes KV-Ergebnis.
cat > src/index.js <<'JS'
const defaults = { version: 0, theme: "light", banner: "", source: "default" };
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname === "/health") return Response.json({ status: "ok" });
const key = url.searchParams.get("key") ?? "config:current";
if (url.pathname !== "/settings" || !/^config:[a-z0-9-]{1,20}$/.test(key)) {
return new Response("Not found", { status: 404 });
}
let value;
try {
value = await env.CONFIG.get(key, { type: "text", cacheTtl: 60 });
} catch {
return Response.json({ error: "Settings temporarily unavailable" }, { status: 503 });
}
if (value === null) return Response.json(defaults);
let settings;
try {
settings = JSON.parse(value);
} catch {
return Response.json(defaults);
}
if (!settings || !Number.isSafeInteger(settings.version) || settings.version < 1 ||
!["light", "dark"].includes(settings.theme) ||
typeof settings.banner !== "string" || settings.banner.length > 80) {
return Response.json(defaults);
}
return Response.json({
version: settings.version, theme: settings.theme,
banner: settings.banner, source: "stored"
});
}
};
JS
Die Anfrage an KV verwendet cacheTtl: 60, also eine Dauer für den Lesecache in Sekunden. Dadurch läuft der gespeicherte Schlüssel nicht ab. Ebenso wird dadurch nicht angewiesen, dass jeder Standort den neuesten Wert abruft. Sowohl vorhandene Werte als auch Ergebnisse für fehlende Schlüssel können zwischengespeichert werden. Halten Sie Schreibvorgänge selten und entwickeln Sie die Anwendung so, dass sie eine ältere gültige Konfiguration toleriert.
Der Handler prüft die Version, das unterstützte Design und die Bannerlänge, bevor er die Werte verwendet. Die Route /health antwortet, ohne optionale Einstellungen zu lesen. Bei einem Speicherfehler liefert /settings weiterhin ausdrücklich 503; die Anwendung meldet also nicht fälschlicherweise, dass sie Standardwerte erfolgreich aus dem Speicher geladen hat.
Erstellen Sie zwei kleine Versionsdateien. Wenn jeder vorgesehene Wert in einer normalen Datei steht, können Sie ihn vor dem Schreiben leicht prüfen:
cat > config-v1.json <<'JSON'
{"version":1,"theme":"light","banner":"Welcome"}
JSON
cat > config-v2.json <<'JSON'
{"version":2,"theme":"dark","banner":"New help center"}
JSON
Schreiben Sie diese Dateien in zwei getrennte lokale Fixture-Schlüssel sowie einen fehlerhaften Wert. Diese Schlüssel machen die möglichen Eingaben reproduzierbar; sie simulieren nicht die Netzwerkverzögerung von Cloudflare.
npx wrangler kv key put config:v1 --path config-v1.json --binding CONFIG --local
npx wrangler kv key put config:v2 --path config-v2.json --binding CONFIG --local
npx wrangler kv key put config:broken broken-json --binding CONFIG --local
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Warten Sie auf die Meldung, dass der Server bereit ist. Vergleichen Sie anschließend die beiden ausdrücklich ausgewählten Schlüssel:
curl -i 'http://127.0.0.1:8080/settings?key=config:v1'
curl -i 'http://127.0.0.1:8080/settings?key=config:v2'
Beide liefern HTTP 200 mit source: "stored". Version 1 verwendet das helle Design mit Welcome; Version 2 verwendet das dunkle Design mit New help center. Keine der beiden Versionen hängt vom Ergebnis einer vorherigen Anfrage ab.
curl -i 'http://127.0.0.1:8080/settings?key=config:missing'
curl -i 'http://127.0.0.1:8080/settings?key=config:broken'
Beide sollten {"version":0,"theme":"light","banner":"","source":"default"} zurückgeben. Die Version 0 ist das Standardkennzeichen der Anwendung; sie ist keine gespeicherte KV-Revision.
curl -i http://127.0.0.1:8080/health
Erwarten Sie {"status":"ok"}. Lassen Sie den lokalen Server bis zur Bereinigung laufen.
Eine kontrollierte Folge älterer Lesevorgänge testen
In diesem Schritt testen Sie den Handler mit einer vorhersehbaren Folge: alt, neu, wieder alt, neu, fehlend und ungültig. Dies ist ein Test-Fixture, also eine absichtlich bereitgestellte Eingabe, die eine ansonsten unvorhersehbare Situation reproduzierbar macht. Es ist kein Beleg dafür, dass eine echte Cloudflare-Anfrage veraltet war.
Erstellen Sie mit der Standardbibliothek für Assertions einen kleinen Node.js-Test. Er importiert den von Ihnen geschriebenen Handler und stellt dieselbe CONFIG.get()-Schnittstelle mit kontrollierten Rückgabewerten bereit:
cat > test-config.mjs <<'JS'
import assert from "node:assert/strict";
import worker from "./src/index.js";
const older = JSON.stringify({ version: 1, theme: "light", banner: "Welcome" });
const newer = JSON.stringify({ version: 2, theme: "dark", banner: "New help center" });
// A controlled fixture: these values simulate different reads, not a cloud outage.
const values = [older, newer, older, newer, null, "broken-json"];
const expectedVersions = [1, 2, 1, 2, 0, 0];
for (let i = 0; i < values.length; i += 1) {
const env = { CONFIG: { get: async () => values[i] } };
const response = await worker.fetch(new Request("https://example.test/settings"), env);
assert.equal(response.status, 200);
const body = await response.json();
assert.equal(body.version, expectedVersions[i]);
assert.ok(["light", "dark"].includes(body.theme));
assert.equal(typeof body.banner, "string");
}
console.log("Controlled old/new/missing/invalid reads stayed usable.");
JS
node test-config.mjs
Erwarten Sie Controlled old/new/missing/invalid reads stayed usable. Bei einer fehlgeschlagenen Assertion wird der Befehl mit einem Fehler beendet. Der wiederholte ältere Wert ist beabsichtigt: Fügen Sie keine globale Variable für die „neueste Version“ hinzu, um ihn zu verbergen. Worker können in unterschiedlichen Instanzen laufen. Eine solche Variable kann daher keine kontoweit neueste Version festlegen.
Eine Konfigurationsaktualisierung sollte während des Übergangs ältere gültige Leser nutzbar halten. Dieser Ansatz eignet sich für ein Banner oder ein Design. Dadurch wird KV jedoch nicht dafür geeignet, den Zugriff einer Person sofort zu widerrufen. Der echte Cloud-Test folgt als Nächstes. Dabei kann bereits die erste Anfrage den neuen Wert anzeigen; auch das ist ein gültiges Ergebnis.
Die erste Cloud-Version bereitstellen und festlegen
In diesem Schritt legen Sie eine echte entfernte Ausgangsbasis fest, bevor Sie sie ändern. Nur die aktuelle Konfiguration und das Fixture für den fehlerhaften Fallback gehören in den Cloud-Namespace dieses Labs.
npx wrangler kv key put config:current --path config-v1.json --binding CONFIG --remote
npx wrangler kv key put config:broken broken-json --binding CONFIG --remote
npx wrangler deploy
Bestätigen Sie den eindeutigen Worker-Namen und die CONFIG-Bindung und kopieren Sie anschließend die tatsächliche öffentliche URL:
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/settings"
Erwarten Sie Version 1, das Design light, das Banner Welcome und source: "stored". Berücksichtigen Sie bei Bedarf, dass der Hostname erst verfügbar werden und KV den Wert sichtbar machen muss. Ein Netzwerkfehler ist keine Konfigurationsantwort. Führen Sie die unabhängige Prüfung dieses Schritts durch, bevor Sie Version 1 ersetzen. Sie überprüft das ausgewählte Konto, den gespeicherten Wert, die bereitgestellte Bindung, die Standardwerte und die Health-Antwort.
Eine echte Aktualisierung beobachten, ohne einen veralteten Lesevorgang zu verlangen
In diesem Schritt aktualisieren Sie die gespeicherte Konfiguration, ohne den Worker-Code zu ändern. Prüfen Sie zunächst den vorgesehenen neuen Wert und schreiben Sie ihn anschließend in denselben entfernten Schlüssel:
cat config-v2.json
npx wrangler kv key put config:current --path config-v2.json --binding CONFIG --remote
npx wrangler kv key get config:current --binding CONFIG --remote --text
Der Management-Lesevorgang sollte Version 2 enthalten. Prüfen Sie nun, was die Anwendung sieht:
curl -i "$WORKER_URL/settings"
Möglicherweise sehen Sie sofort Version 2 oder während der Konvergenz weiterhin eine ältere gültige Version. Verlangen Sie keine veraltete Antwort, um die letztendliche Konsistenz zu „beweisen“, und schreiben Sie den Schlüssel nicht wiederholt schnell neu, um eine solche Antwort zu provozieren. Wiederholen Sie die HTTP-Anfrage bei Bedarf in Abständen von 15 Sekunden bis zu fünf Minuten. Dies ist ein begrenztes Beobachtungsfenster der Übung und keine Zusage, dass jeder globale Standort innerhalb von fünf Minuten konvergiert.
Fahren Sie fort, sobald der Endpunkt {"version":2,"theme":"dark","banner":"New help center","source":"stored"} zurückgibt. Wenn innerhalb dieses Beobachtungsfensters keine Konvergenz eintritt, prüfen Sie Konto und Bindung und melden Sie ein nicht eindeutiges Ergebnis. Für die unabhängige Prüfung müssen die tatsächlich gespeicherte Version und die tatsächliche Antwort übereinstimmen; eine lokale Datei oder ein Test-Fixture reicht dafür nicht aus.
curl -i "$WORKER_URL/settings?key=config:broken"
curl -i "$WORKER_URL/health"
Die beschädigte Anzeigekonfiguration verwendet weiterhin einen kontrollierten Standardwert, und der Health-Endpunkt bleibt ok. Wählen Sie im Dashboard dasselbe Konto aus und öffnen Sie den Namespace dieses Labs unter Storage & databases → Workers KV. Vergleichen Sie config:current mit Version 2 in Ihrer Datei. Diese schreibgeschützte Ansicht zeigt den verwalteten Wert; sie kann nicht beweisen, was derzeit an jedem entfernten Standort zwischengespeichert ist.
Der kontrollierte Test behandelte die Toleranz gegenüber älteren Werten. Die echte Aktualisierung behandelte dagegen die Bereitstellung und die beobachtete Konvergenz an Ihrem Testendpunkt. Halten Sie diese Schlussfolgerungen getrennt. Weitere Informationen zum Konsistenzmodell finden Sie unter Funktionsweise von KV.
Wähle KV Pairs und dann View neben config:current. Verwende Refresh, wenn die Liste die Aktualisierung noch nicht zeigt. Das Beispiel zeigt Version 2, das Design dark und das Banner New help center; der erzeugte Name deines Namespaces wird anders sein. Ändere den Wert bei dieser Prüfung nicht.
Die kurzlebigen Cloud-Ressourcen löschen
In diesem Schritt entfernen Sie beide Ressourcen, solange Wrangler noch autorisiert ist. Ein Namespace kann den zugehörigen Worker überdauern. Das alleinige Löschen der Anwendung entfernt daher nicht ihre Daten.
Stoppen Sie den lokalen Entwicklungsprozess, den Sie in diesem Terminal gestartet haben:
kill "$DEV_PID"
Prüfen Sie Ihre gespeicherten Ressourcenreferenzen, bevor Sie etwas löschen:
cat wrangler.jsonc
Bestätigen Sie den Worker-Namen labex-config-... und die Namespace-ID von CONFIG. Löschen Sie den Worker, der durch diese Konfiguration ausgewählt wird:
npx wrangler delete
Wenn Sie dazu aufgefordert werden, prüfen Sie, ob der angezeigte Name zu diesem Lab gehört, und bestätigen Sie mit y. Löschen Sie anschließend nur den Namespace, auf den CONFIG verweist:
npx wrangler kv namespace delete --binding CONFIG
Prüfen Sie den Namespace in jeder Bestätigungsabfrage, bevor Sie zustimmen. Lassen Sie wrangler.jsonc unverändert, damit die unabhängige Prüfung erkennen kann, welche Ressourcen nicht mehr vorhanden sein sollten.
npx wrangler kv namespace list
Der Namespace dieses Labs sollte nicht mehr vorhanden sein; nicht zugehörige Namespaces sollten bleiben. Aktualisieren Sie die Listen im Dashboard, um zu bestätigen, dass der Worker und der Namespace dieses Labs verschwunden sind. Eine fehlgeschlagene Anfrage oder eine abgelaufene Anmeldung beweist keine Löschung. Führen Sie die Prüfung dieses Schritts vor dem Abmelden durch, damit sie den autorisierten Bestand untersuchen kann.
Die Autorisierung der VM beenden
In diesem Schritt trennen Sie Wrangler, nachdem die Bereinigungsprüfung erfolgreich war. Durch das Abmelden wird die in dieser VM gespeicherte Wrangler-Autorisierung beendet. Cloud-Ressourcen werden dadurch nicht gelöscht, und Ihre normale Dashboard-Browsersitzung wird nicht abgemeldet.
npx wrangler logout
npx wrangler whoami --json
Bestätigen Sie, dass das strukturierte Ergebnis "loggedIn": false meldet. Dieser nicht authentifizierte Befehl kann mit einem Status ungleich null beendet werden; das ist hier zu erwarten. Wenn nur ein Verbindungsfehler und kein ausdrücklicher Authentifizierungsstatus erscheint, wiederholen Sie den Befehl, sobald die Verbindung funktioniert.
Die verbleibenden lokalen Dateien und der lokale KV-Zustand gehören zu dieser kurzlebigen VM. Sie sind von den Cloud-Ressourcen getrennt, die Sie bereits gelöscht haben. Sie können das Lab nun beenden.
Zusammenfassung
Sie haben einen Konfigurationsleser erstellt, der ältere und neuere gültige Einstellungen akzeptiert, bei fehlenden oder ungültigen Werten sichere Standardwerte verwendet und seinen Health-Endpunkt unabhängig von optionalen KV-Daten hält. Sie haben eine kontrollierte Folge älterer Lesevorgänge getestet, anschließend einen echten entfernten Schlüssel geändert und beobachtet, wie die Antwort der bereitgestellten Anwendung konvergiert.
Sie haben gelernt, dass Versionskennzeichen die zurückgegebenen Daten beschreiben, während Lesecache-Dauer, Ablauf und starke Konsistenz unterschiedliche Themen sind. Abschließend haben Sie die kurzlebigen Ressourcen gelöscht und sich abgemeldet. Die Kursaufgabe kombiniert die korrekte Namespace-Bindung mit der sicheren Verarbeitung von Hinweisen.
