Einführung
Wenn eine Dokumentationswebsite Seiten verschiebt, sollten alte Links weiterhin an die richtige Stelle führen. Ein Redirect ist eine HTTP-Antwort, die den Browser auffordert, eine andere URL abzurufen. In diesem Lab speichert KV einen kleinen Katalog, der alte Pfade auf neue Dokumentationspfade abbildet.
Sie untersuchen und validieren zunächst einen bereitgestellten JSON-Datensatz, bevor Sie ihn importieren. Anschließend lesen Sie den Katalog in mehreren Seiten aus. Pagination bedeutet, eine begrenzte Ergebnismenge anzufordern und mithilfe einer Fortsetzungsmarke die nächste Ergebnismenge abzurufen. Zum Schluss ändern Sie ein Ziel und archivieren zwei Einträge, während Sie einen nicht zugehörigen Datensatz im selben Namespace erhalten. Das ist hilfreich, wenn Sie eine Sammlung von Einstellungen verwalten, statt einzelne Schlüssel nacheinander zu bearbeiten.
Bearbeiten Sie zuerst die vorherigen geführten KV-Labs. Diese frische VM enthält Node.js 22.22.0 und Wrangler 4.131.1 als lokale Projektabhängigkeit unter /home/labex/project/redirect-catalog. Das Setup stellt fünf synthetische Redirects bereit, importiert sie aber nicht und erstellt keine Cloud-Ressourcen. Verwenden Sie Ihr eigenes Lernkonto mit denselben Berechtigungen zum Lesen des Kontos sowie zum Schreiben in Worker und KV. Ein temporärer Worker und ein Namespace reichen aus; für diesen kleinen Datensatz benötigen Sie kein kostenpflichtiges Upgrade und keine gekaufte Domain. Der öffentliche Katalog enthält nur Beispielpfade.
Einen Redirect-Namespace verbinden
In diesem Schritt verbinden Sie einen unabhängigen Namespace für einen kleinen Redirect-Katalog. Das Binding ROUTES identifiziert diesen Namespace sowohl für Befehlszeilenoperationen als auch für den Worker. Jedes Lab verwendet eigene Ressourcen, sodass der Katalog keinen vorherigen Namespace verändert.
Wechseln Sie in das vorbereitete Projekt:
cd /home/labex/project/redirect-catalog
Erzeugen Sie einmalig einen eindeutigen Namen. openssl rand -hex 6 gibt ein zufälliges Suffix aus; $(...) fügt dieses in den Namen ein. Die Shell-Variable hält den Namen für die folgenden Befehle in diesem Terminal verfügbar.
WORKER_NAME="labex-routes-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorisieren Sie diese VM. Zusätzlich zum Lesen Ihrer Kontoidentität erlaubt Workers Scripts Write die Bereitstellung und Löschung. Workers KV Write erlaubt 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 zusätzlich ein Zugriff im Hintergrund angezeigt werden. Kehren Sie zum Terminal zurück und warten Sie, bis die Anmeldung abgeschlossen ist.
Prüfen Sie dieselben Schreibberechtigungen für Worker und KV, die in „Create a Feature Flag Store“ eingeführt wurden. Bestätigen Sie das Lernkonto, bevor Sie die Autorisierung erteilen.
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. Der nicht quotierte Trenner erlaubt es der Shell, $WORKER_NAME einzusetzen.
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 verwendet denselben eindeutigen Namen wie der Worker, damit Sie beide später erkennen können. --update-config=false lässt Sie das Binding selbst eintragen, statt die Datei automatisch ändern zu lassen.
npx wrangler kv namespace create "$WORKER_NAME-routes" --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 des Bindings ROUTES wird von Ihrem Code verwendet; 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": "ROUTES", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Suchen Sie den Namespace dieses Labs und vergleichen Sie seine ID mit der Datei. Andere Namespaces können vorhanden sein; lassen Sie sie unverändert. Diese Konfiguration legt fest, welches Konto und welche Ressource die folgenden Befehle verwenden. Ein Binding ist ein Verweis auf einen Namespace, keine Kopie seiner Daten.
Einen kleinen Katalog validieren und importieren
In diesem Schritt prüfen Sie einen Datensatz, bevor ein einzelner Befehl alle Einträge schreibt. Eine Bulk-Operation spart wiederholte Arbeit, wiederholt aber auch jeden Fehler in den bereitgestellten Daten. Lesen Sie zuerst die vorbereitete Datei:
cat redirects.json
Jedes Objekt besitzt einen key wie route:/old-start und einen value wie /docs/start. Das Präfix route: gruppiert die Katalogeinträge; es ist Bestandteil des Schlüssels und kein Verzeichnis. Das Ziel ist ein Pfad auf derselben Website und keine beliebige externe URL.
Schreiben Sie ein gewöhnliches Node.js-Validierungsskript. Es liest einen Dateinamen ein, prüft Array und Felder, lehnt doppelte Schlüssel ab und gibt erst dann eine Anzahl aus, wenn alle Einträge erfolgreich geprüft wurden. Das Set merkt sich bereits gefundene Schlüssel. Die regulären Ausdrücke beschränken diesen Lehrdatensatz auf einfache alte Pfade und Dokumentationsziele. Sie sind Regeln dieser Anwendung und keine von KV auferlegten Einschränkungen.
cat > validate-redirects.mjs <<'JS'
import { readFile } from "node:fs/promises";
const filename = process.argv[2] ?? "redirects.json";
const entries = JSON.parse(await readFile(filename, "utf8"));
if (!Array.isArray(entries) || entries.length === 0 || entries.length > 20) {
throw new Error("Use a non-empty teaching dataset of at most 20 entries.");
}
const seen = new Set();
for (const entry of entries) {
if (!entry || typeof entry.key !== "string" || !/^route:\/old-[a-z-]+$/.test(entry.key)) {
throw new Error("Every key must name an old route, such as route:/old-start.");
}
if (typeof entry.value !== "string" || !/^\/docs\/[a-z-]+$/.test(entry.value)) {
throw new Error("Every destination must be a /docs/ path on this site.");
}
if (Object.keys(entry).some(key => !["key", "value"].includes(key))) {
throw new Error("This dataset accepts only key and value fields.");
}
if (seen.has(entry.key)) throw new Error(`Duplicate key: ${entry.key}`);
seen.add(entry.key);
}
console.log(`Validated ${entries.length} unique redirect entries.`);
JS
node validate-redirects.mjs redirects.json
Erwarten Sie Validated 5 unique redirect entries.. Wenn die Validierung fehlschlägt, korrigieren Sie die Datei vor dem Import. Das Ablehnen doppelter Schlüssel ist wichtig, weil das erneute Schreiben desselben Schlüssels seinen Wert ersetzt.
Erstellen Sie zunächst lokal ein nicht zur Route gehörendes Testobjekt und importieren Sie anschließend den Katalog. Damit können Sie später prüfen, ob bei der Katalogverwaltung andere Daten erhalten bleiben.
npx wrangler kv key put system:owner labex-redirect-demo --binding ROUTES --local
npx wrangler kv bulk put redirects.json --binding ROUTES --local
npx wrangler kv key list --binding ROUTES --local
Erwarten Sie fünf route:-Einträge sowie system:owner. bulk put schreibt die Einträge aus der Datei. Es ersetzt nicht den gesamten Namespace und entfernt keine Schlüssel, die in der Datei fehlen. Außerdem garantiert es keine atomare Änderung, die überall gleichzeitig sichtbar ist.
Importieren Sie nun denselben geprüften Datensatz in den Cloud-Namespace dieses Labs:
npx wrangler kv key put system:owner labex-redirect-demo --binding ROUTES --remote
npx wrangler kv bulk put redirects.json --binding ROUTES --remote
npx wrangler kv key list --binding ROUTES --remote
Bestätigen Sie die sechs Schlüssel. Die expliziten Zieloptionen halten lokale Übungen und Cloud-Schreibvorgänge getrennt. Führen Sie die Prüfung dieses Schritts aus, bevor Sie Einträge ändern.
Jede Seite lesen und Redirects bereitstellen
In diesem Schritt erstellen Sie einen Worker, der alle Routenschlüssel auflistet und deren Redirects bereitstellt. Ein einzelner KV-Aufruf von list() liefert möglicherweise nur einen Teil einer Sammlung. Der cursor ist eine von KV bereitgestellte Fortsetzungsmarke. Übergeben Sie ihn unverändert, um den nächsten Teil anzufordern.
Schreiben Sie diesen Handler. Das absichtlich kleine limit: 2 macht die Pagination bei nur fünf Datensätzen sichtbar. In produktivem Code wird normalerweise eine größere Seitengröße verwendet. Dieses Lab begrenzt die Daten auf zwanzig Einträge, damit die Schleife klein bleibt.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
try {
if (url.pathname === "/catalog") {
const names = [];
let cursor;
let complete = false;
let pages = 0;
do {
const page = await env.ROUTES.list({ prefix: "route:", limit: 2, cursor });
names.push(...page.keys.map(key => key.name));
pages += 1;
complete = page.list_complete;
cursor = complete ? undefined : page.cursor;
if ((!complete && !cursor) || pages > 20) {
return Response.json({ error: "Catalog could not be completed" }, { status: 503 });
}
} while (!complete);
return Response.json({ keys: names, pages });
}
if (url.pathname.startsWith("/docs/")) {
return new Response(`Example destination: ${url.pathname}`);
}
const target = await env.ROUTES.get(`route:${url.pathname}`);
if (target === null) return new Response("Not found", { status: 404 });
if (!/^\/docs\/[a-z-]+$/.test(target)) {
return Response.json({ error: "Invalid redirect destination" }, { status: 500 });
}
return Response.redirect(new URL(target, url.origin).href, 302);
} catch {
return Response.json({ error: "Redirect storage unavailable" }, { status: 503 });
}
}
};
JS
Die do...while-Schleife fordert mindestens eine Seite an und läuft weiter, bis list_complete den Wert true hat. Sie verwendet bei jeder Anfrage weiterhin prefix: "route:", sodass das Owner-Testobjekt nicht in den Katalog gelangt. names.push(...) hängt die Schlüsselnamen jeder Seite an das Ergebnis an.
Ein leeres Array keys bedeutet nicht zwangsläufig, dass die Auflistung abgeschlossen ist: Gelöschte oder abgelaufene Einträge können dazu führen, dass eine Seite keine Schlüssel zurückgibt, obwohl weitere Seiten vorhanden sind. Deshalb verwendet die Schleife list_complete und nicht die Länge des Arrays. Die Begrenzung der Seitenzahl und die Prüfung auf einen fehlenden Cursor erzeugen einen kontrollierten Fehler, falls dieses kleine Beispiel die Auflistung nicht abschließen kann. Siehe KV listing and pagination.
Für andere Pfade liest der Worker den passenden Routenschlüssel. Fehlende Routen geben 404 zurück. Ein unterstütztes Ziel erzeugt eine 302-Antwort mit einem Location-Header. Die Laufzeit prüft die Ziele erneut, damit ein fehlerhaft bearbeiteter KV-Wert Besucher nicht auf eine andere Website umleiten kann. Die /docs/-Antworten sind einfache Platzhalter, die den Zielpfad anzeigen, keine vollständige Dokumentationswebsite.
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, und untersuchen Sie anschließend den vollständigen Katalog:
curl -i http://127.0.0.1:8080/catalog
Erwarten Sie fünf sortierte Routenschlüssel und mindestens drei Seiten. Zusätzliche leere Seiten sind möglich. Entscheidend ist, dass die vollständige Menge der Schlüssel enthalten ist und kein Eintrag system:owner erscheint.
curl -i http://127.0.0.1:8080/old-start
Erwarten Sie HTTP 302 sowie Location: http://127.0.0.1:8080/docs/start. Standardmäßig zeigt curl die Redirect-Antwort an, ohne ihr zu folgen. Lassen Sie den lokalen Datensatz für den späteren Vergleich unverändert.
Ausgewählte Routen aktualisieren und andere Daten erhalten
In diesem Schritt ändern Sie den Cloud-Katalog, ohne seinen Namespace zu ersetzen. Die neue Startseite ist /docs/getting-started; zwei temporäre Seiten sollen nicht mehr weiterleiten.
npx wrangler kv key put route:/old-start /docs/getting-started --binding ROUTES --remote
Das Schreiben eines ausgewählten Schlüssels lässt die anderen Routen unverändert. Für mehrere Löschungen akzeptiert Wrangler ein JSON-Array mit den exakten Schlüsselnamen. Lesen Sie diese kleine Liste der zu archivierenden Schlüssel, bevor Sie die Löschung ausführen:
cat > retired-keys.json <<'JSON'
["route:/old-contact", "route:/old-event"]
JSON
cat retired-keys.json
npx wrangler kv bulk delete retired-keys.json --binding ROUTES --remote
Wenn Sie dazu aufgefordert werden, bestätigen Sie, dass sich das Binding und der aufgelistete Vorgang auf den temporären Namespace dieses Labs beziehen. Die Liste enthält nur zwei Routenschlüssel und nicht system:owner.
npx wrangler kv key list --binding ROUTES --remote
npx wrangler kv key get system:owner --binding ROUTES --remote --text
Erwarten Sie drei verbleibende Routen und den unveränderten Wert labex-redirect-demo. Führen Sie den ursprünglichen Bulk-Import jetzt nicht erneut aus: Seine alten Werte würden die Aktualisierung rückgängig machen und die archivierten Schlüssel wiederherstellen.
Stellen Sie den Worker bereit, bestätigen Sie das Binding ROUTES und kopieren Sie seine tatsächliche öffentliche Adresse:
npx wrangler deploy
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/catalog"
Prüfen Sie zuerst, dass /catalog HTTP 200 und die erwarteten JSON-Schlüssel zurückgibt. Erscheint eine Cloudflare-Fehlerseite, warten Sie kurz und wiederholen Sie die Leseanfragen. Eine entfernte Route ist nur dann korrekt, wenn sie HTTP 404 mit dem Anwendungstext Not found zurückgibt; der Statuscode allein reicht nicht.
Der Katalog sollte nur route:/old-pricing, route:/old-start und route:/old-support enthalten. Testen Sie die geänderten und archivierten Pfade:
curl -i "$WORKER_URL/old-start"
curl -i "$WORKER_URL/old-contact"
curl -i "$WORKER_URL/old-event"
Erwarten Sie, dass der Startpfad auf /docs/getting-started weiterleitet. Beide archivierten Pfade sollten 404 zurückgeben. Wenn neue Cloud-Daten noch nicht sichtbar sind, warten Sie auf die KV-Replikation und wiederholen Sie die schreibgeschützten Prüfungen. Eine fehlgeschlagene Verbindung ist kein Beleg für ein erfolgreiches Archivieren.
curl -i http://127.0.0.1:8080/catalog
Die lokale Entwicklung listet weiterhin die ursprünglichen fünf Routen auf. Dieser Unterschied bestätigt, dass die Verwaltungsbefehle den Cloud-Speicher als Ziel verwendet haben. Wählen Sie im Dashboard dasselbe Konto aus, öffnen Sie Storage & databases → Workers KV und untersuchen Sie den Namespace dieses Labs. Vergleichen Sie die drei Routeneinträge und das erhaltene Owner-Testobjekt mit der Befehlsausgabe. Dieser Kontrollpunkt ist schreibgeschützt. Der erzeugte Namespace-Name und seine ID gelten nur für diesen Durchlauf.
Wählen Sie KV Pairs, um die unten gezeigten Datensätze zu sehen. Verwenden Sie Refresh, wenn Sie den Namespace vor Abschluss der Wartungsbefehle geöffnet haben.
Temporäre Cloud-Ressourcen löschen
In diesem Schritt entfernen Sie beide Ressourcen, solange Wrangler noch autorisiert ist. Ein Namespace kann den Worker überleben. Daher entfernt das Löschen der Anwendung allein nicht deren Daten.
Stoppen Sie den lokalen Entwicklungsprozess, den Sie in diesem Terminal gestartet haben:
kill "$DEV_PID"
Überprüfen Sie Ihre gespeicherten Ressourcenverweise, bevor Sie etwas löschen:
cat wrangler.jsonc
Bestätigen Sie den Worker-Namen labex-routes-... und die Namespace-ID des Bindings ROUTES. 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 ROUTES verweist:
npx wrangler kv namespace delete --binding ROUTES
Prüfen Sie den Namespace in jeder Bestätigungsaufforderung, bevor Sie den Vorgang annehmen. Lassen Sie wrangler.jsonc unverändert, damit die unabhängige Prüfung feststellen kann, welche Ressourcen nicht mehr vorhanden sein sollen.
npx wrangler kv namespace list
Der Namespace dieses Labs sollte nicht mehr vorhanden sein; nicht zugehörige Namespaces sollten erhalten bleiben. Aktualisieren Sie die Listen im Dashboard und bestätigen Sie, 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 aus, bevor Sie sich abmelden, damit sie ein autorisiertes Inventar untersuchen kann.
Die Autorisierung der VM beenden
In diesem Schritt trennen Sie Wrangler, nachdem die Aufräumprüfung erfolgreich war. Durch das Abmelden wird die gespeicherte Wrangler-Autorisierung dieser VM 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 enden; das ist hier erwartbar. 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 temporären VM. Sie sind von den Cloud-Ressourcen getrennt, die Sie bereits gelöscht haben. Sie können das Lab nun abschließen.
Zusammenfassung
Sie haben einen kleinen Redirect-Datensatz vor einem Bulk-Schreibvorgang validiert, lokale und Cloud-Ziele ausdrücklich getrennt und jede Seite einer KV-Auflistung mit Präfix durchlaufen. Sie haben eine Route geändert und zwei exakte Schlüssel archiviert, während Sie einen nicht zugehörigen Owner-Datensatz erhalten haben. Die bereitgestellten Antworten bestätigten das neue Ziel und die fehlenden archivierten Routen, während der lokale Katalog seine ursprünglichen Daten behielt.
Zum Schluss haben Sie den temporären Worker und den Namespace gelöscht und sich abgemeldet. Als Nächstes bearbeiten Sie Konfigurationslesevorgänge, die vorübergehend eine frühere Version zurückgeben können.
