Einführung
Ein Wartungsbanner sollte verschwinden, sobald das Zeitfenster für seine Ankündigung endet. Bleibt es sichtbar, könnten Besucher annehmen, dass eine alte Störung weiterhin besteht. Sie erstellen einen Worker, der einen Hinweis aus KV liest und entscheidet, ob er noch angezeigt werden soll.
Es gibt zwei voneinander unabhängige Fristen. Eine Anwendungsfrist teilt Ihrem Code mit, wann die Nachricht nicht mehr angezeigt werden soll. Ein KV-Ablauf teilt dem Speicherdienst mit, wann der Eintrag entfernt werden soll. Sie lassen absichtlich einen alten Referenzeintrag im Speicher, um zu zeigen, dass Ihre Anwendung abgelaufene Inhalte ausblenden kann, obwohl die Daten noch vorhanden sind. Anschließend beobachten Sie, wie ein zweiter Eintrag automatisch aus Cloud KV abläuft.
Schließen Sie zuerst Serve Account Preferences ab. Diese unabhängige VM enthält Node.js 22.22.0 und das projektlokale Wrangler 4.131.1 in /home/labex/project/temporary-notices. Verwenden Sie Ihr eigenes Lernkonto sowie dieselben Berechtigungen zum Lesen des Kontos und zum Schreiben in Worker und KV. Sie erstellen einen temporären Worker und Namespace, verwenden ausschließlich künstliche Nachrichten und führen vor dem Abmelden die Bereinigung durch. Für die kleine Übung benötigen Sie weder eine gekaufte Domain noch ein kostenpflichtiges Upgrade. Planen Sie zusätzlich zum Schreiben und Testen des Handlers etwa fünf Minuten für die zeitgesteuerte Beobachtung ein.
Einen Notice-Namespace verbinden
In diesem Schritt verbinden Sie einen neuen Namespace für temporäre Hinweise. Verwenden Sie einen separaten Namespace und einen eindeutigen Worker-Namen, damit Experimente mit dem Ablauf nicht die Daten einer anderen Anwendung entfernen können. Die Bindung NOTICES verbindet Ihren Handler mit dieser Ressource.
Wechseln Sie in das vorbereitete Projekt:
cd /home/labex/project/temporary-notices
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-notices-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorisieren Sie diese VM. Neben dem Lesen Ihrer Kontokennung ermöglichen Workers Scripts Write die Bereitstellung und Löschung sowie Workers KV Write die Verwaltung des Namespace und der Schlüssel für dieses Labor.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Öffnen Sie den angezeigten Gerätelink 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 Hintergrundzugriff 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 in Create a Feature Flag Store eingeführt wurden. Bestätigen Sie Ihr Lernkonto, bevor Sie die Autorisierung erteilen.
npx wrangler whoami --json
Bestätigen Sie loggedIn: true sowie name des Lernkontos, auch wenn nur ein Konto aufgeführt ist. Kopieren Sie die id dieses Kontos. Tragen Sie sie in der folgenden Konfiguration ein und ersetzen Sie YOUR_ACCOUNT_ID, 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 maskierte Begrenzer ermöglicht 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 das Paar später wiedererkennen. --update-config=false lässt die Änderung der Bindung sichtbar für Sie, anstatt die Datei automatisch zu ändern.
npx wrangler kv namespace create "$WORKER_NAME-notices" --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 Bindungsname NOTICES 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": "NOTICES", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Suchen Sie den Titel des Namespace für dieses Labor 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 späteren Befehle verwenden sollen. Eine Bindung ist ein Verweis auf einen Namespace, keine Kopie seiner Daten.
Einen alten Hinweis vor dem Löschen seiner Daten ausblenden
In diesem Schritt trennen Sie das Anzeigeverhalten von der Bereinigung des Speichers. Ein Zeitstempel ist eine Zahl, die einen Zeitpunkt darstellt. displayUntil verwendet hier Unix-Sekunden, gezählt ab dem Beginn des Jahres 1970 in UTC. Date.now() gibt Millisekunden zurück, daher teilt der Handler vor dem Vergleich durch 1000. Der Vergleich in derselben Einheit verhindert einen häufigen Fehler bei Fristen.
Schreiben Sie den Handler mit diesem maskierten Here-Dokument:
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
const key = url.searchParams.get("key") ?? "notice:maintenance";
if (url.pathname !== "/notice" || !/^notice:[a-z]{1,20}$/.test(key)) {
return new Response("Not found", { status: 404 });
}
let entry;
try {
entry = await env.NOTICES.getWithMetadata(key, "text");
} catch {
return Response.json({ error: "Notice storage unavailable" }, { status: 503 });
}
if (entry.value === null) {
return Response.json({ visible: false, reason: "missing" });
}
let notice;
try {
notice = JSON.parse(entry.value);
} catch {
return Response.json({ visible: false, reason: "invalid" });
}
if (!notice || typeof notice.message !== "string" || !notice.message.trim() ||
!Number.isSafeInteger(notice.displayUntil) || notice.displayUntil <= 0) {
return Response.json({ visible: false, reason: "invalid" });
}
if (Math.floor(Date.now() / 1000) >= notice.displayUntil) {
return Response.json({ visible: false, reason: "expired" });
}
return Response.json({
visible: true, message: notice.message,
kind: entry.metadata?.kind === "maintenance" ? "maintenance" : "general"
});
}
};
JS
Der Abfrageparameter key wählt einen künstlichen Hinweis aus. Ohne diesen Parameter verwendet der Handler notice:maintenance. Die Anwendung blendet fehlende, fehlerhafte und abgelaufene Hinweise mit einer erklärenden JSON-Antwort aus. Ein Lesefehler in KV gibt 503 zurück, statt so zu tun, als würde der Hinweis fehlen. Das Metadatenfeld kind kennzeichnet die Kategorie des Hinweises; fehlende oder unerwartete Metadaten führen zu general.
Der Vergleich der Frist verwendet >=: Der Hinweis wird genau zum Fristende ausgeblendet, nicht erst eine Sekunde später. Diese Prüfung läuft bei jeder Anfrage. Eine Webseite, die ein Banner bereits angezeigt hat, müsste es zusätzlich mit einem eigenen Timer aktualisieren oder entfernen; eine Worker-Antwort kann eine bereits gerenderte Seite nicht selbst ändern.
Speichern Sie lokal absichtlich einen alten Referenzhinweis. Die Frist 1 bezeichnet einen bekannten Zeitpunkt im Jahr 1970, daher ist dieser Eintrag aus Sicht der Anwendung bereits abgelaufen. Wir lassen einen KV-Ablauf absichtlich weg, damit der Eintrag zur Prüfung verfügbar bleibt.
npx wrangler kv key put notice:reference '{"message":"Old maintenance notice","displayUntil":1}' --binding NOTICES --local --metadata '{"kind":"maintenance"}'
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Der Hintergrundserver schreibt seine Ausgabe in local.log. Wiederholen Sie den Befehl zum Anzeigen des Logs, bis der Server seine Bereitschaft an Port 8080 meldet. Rufen Sie nun den alten Referenzeintrag ab:
curl -i 'http://127.0.0.1:8080/notice?key=notice:reference'
Erwarten Sie HTTP 200 und {"visible":false,"reason":"expired"}. Die Anführungszeichen verhindern, dass das Fragezeichen in der URL als Shell-Syntax für Dateinamen behandelt wird. Beweisen Sie, dass der Eintrag weiterhin vorhanden ist:
npx wrangler kv key get notice:reference --binding NOTICES --local --text
Die JSON-Daten sind weiterhin vorhanden. Ihr Code hat verhindert, dass der alte Hinweis angezeigt wird, nicht eine automatische Löschung. Auch ein fehlender Schlüssel sollte sicher behandelt werden:
curl -i 'http://127.0.0.1:8080/notice?key=notice:missing'
Erwarten Sie {"visible":false,"reason":"missing"}. Lassen Sie den lokalen Server bis zur Bereinigung laufen.
Einen Hinweis mit zwei Fristen veröffentlichen
In diesem Schritt veröffentlichen Sie zuerst den Worker und starten anschließend ein kurzes Zeitfenster für einen Hinweis in der Cloud. Wenn Sie den Endpunkt vor dem Start der Zeitmessung vorbereiten, haben Sie Zeit, das aktive Ergebnis zu prüfen.
Erstellen Sie denselben Referenzeintrag ohne Ablauf im entfernten Namespace:
npx wrangler kv key put notice:reference '{"message":"Old maintenance notice","displayUntil":1}' --binding NOTICES --remote --metadata '{"kind":"maintenance"}'
npx wrangler deploy
Bestätigen Sie den erzeugten Worker-Namen und die Bindung NOTICES. Speichern Sie anschließend die tatsächliche öffentliche URL aus der Ausgabe:
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/notice?key=notice:reference"
Erwarten Sie, dass der alte Referenzeintrag als expired ausgeblendet wird. Wenn der Hostname noch nicht bereit ist, warten Sie und versuchen Sie es erneut, bevor Sie mit dem zeitgesteuerten Teil beginnen. Rufen Sie den standardmäßigen Wartungsschlüssel noch nicht ab: Auch Lesezugriffe auf fehlende KV-Schlüssel können zwischengespeichert werden.
Lesen Sie die restlichen Anweisungen, bevor Sie die nächsten Befehle ausführen. date +%s gibt die aktuelle Unix-Zeit der VM zurück; $((...)) führt Shell-Arithmetik aus. Wir beenden die Anzeige des Hinweises nach drei Minuten und bitten KV eine Minute später, ihn zu entfernen.
DISPLAY_UNTIL=$(($(date +%s) + 180))
KV_EXPIRES=$((DISPLAY_UNTIL + 60))
Schreiben Sie die tatsächlichen Anwendungsdaten. Der nicht maskierte Begrenzer JSON fügt die numerische Frist in die Datei ein:
cat > notice.json <<JSON
{"message":"Maintenance starts soon","displayUntil":$DISPLAY_UNTIL}
JSON
--path liest den Wert aus dieser Datei. --expiration setzt einen absoluten KV-Ablauf in Unix-Sekunden; --metadata fügt neben dem Wert die Kategorie des Hinweises hinzu.
npx wrangler kv key put notice:maintenance --path notice.json --binding NOTICES --remote --expiration "$KV_EXPIRES" --metadata '{"kind":"maintenance"}'
KV unterstützt außerdem eine relative TTL (Time to Live), angegeben als Sekunden ab dem Schreibvorgang. Wrangler nennt diese Option --ttl; die Binding-API nennt sie expirationTtl. Sowohl der relative als auch der absolute Ablauf müssen mindestens 60 Sekunden in der Zukunft liegen. Hier verwenden wir einen absoluten Ablauf, damit Sie die beiden Fristen direkt vergleichen können. Siehe KV expiration options.
npx wrangler kv key list --binding NOTICES --remote
Suchen Sie notice:maintenance, seine expiration und die Metadaten kind. Der Referenzeintrag besitzt keinen KV-Ablauf. Lesen Sie nun die aktive Nachricht:
curl -i "$WORKER_URL/notice"
Erwarten Sie HTTP 200 und {"visible":true,"message":"Maintenance starts soon","kind":"maintenance"}. Führen Sie die Prüfung dieses Schritts jetzt durch, bevor das Anzeigezeitfenster endet. Sie prüft den tatsächlichen Cloud-Wert, die Metadaten, den KV-Ablauf, die Bindung und die aktive Antwort. Ein allein gespeicherter Zeitstempel beweist nicht, dass der Hinweis gespeichert wurde.
Wenn Sie das Zeitfenster verpassen, wiederholen Sie die beiden Zeitzuweisungen, schreiben Sie notice.json erneut und wiederholen Sie den Remote-Put mit neuen Fristen. Wiederholen Sie Schreibvorgänge nicht schnell hintereinander. Ein zuvor zwischengespeicherter Lesezugriff kann Zeit benötigen, bevor er den Ersatzwert anzeigt. Warten Sie daher und wiederholen Sie die aktive Prüfung. Fahren Sie erst fort, wenn sie erfolgreich ist.
Öffnen Sie nach erfolgreicher aktiver Prüfung im Dashboard desselben Lernkontos Storage & databases → Workers KV und wählen Sie den Namespace dieses Labs. Öffnen Sie KV Pairs und klicken Sie neben notice:maintenance auf View, um Nachricht und displayUntil zu prüfen. KV-Ablaufzeit und Metadaten finden Sie in der CLI-Schlüsselliste; diese Dashboard-Ansicht zeigt den gespeicherten Wert. Lesen Sie nur: Die Zeit läuft weiter. Ist der Schlüssel bereits abgelaufen, fahren Sie mit dem nächsten Schritt fort, statt ihn nur für diese Ansicht neu anzulegen. Name und Zeitstempel im Screenshot sind Beispiele und dürfen nicht übernommen werden.
Ausgeblendete Inhalte und den automatischen Ablauf beobachten
In diesem Schritt beobachten Sie die beiden Fristen, ohne den Wartungsschlüssel manuell zu löschen. Lassen Sie notice.json unverändert, damit Sie die ursprünglichen Daten mit dem Ergebnis vergleichen können.
Geben Sie beide geplanten Zeitpunkte und die aktuelle Zeit aus:
printf 'displayUntil=%s
KV expiration=%s
now=%s
' "$DISPLAY_UNTIL" "$KV_EXPIRES" "$(date +%s)"
Warten Sie, bis die aktuelle Zeit displayUntil erreicht. Diese Befehle berechnen nur die verbleibende Wartezeit. Wenn die Frist bereits abgelaufen ist, überspringt die Bedingung das Warten. sleep erwartet Sekunden; if verhindert, dass eine negative Verzögerung übergeben wird.
WAIT_SECONDS=$((DISPLAY_UNTIL - $(date +%s) + 1))
if [ "$WAIT_SECONDS" -gt 0 ]; then sleep "$WAIT_SECONDS"; fi
curl -i "$WORKER_URL/notice"
Die Nachricht darf nicht mehr sichtbar sein. Erwarten Sie vor dem KV-Ablauf {"visible":false,"reason":"expired"}. Wenn Sie erst zurückkehren, nachdem KV den Schlüssel bereits ablaufen ließ, kann reason auch missing sein; beide Antworten verhindern die Anzeige. Der erhaltene Referenzeintrag bleibt eine direkte Prüfung des Verhaltens der Anwendungsfrist:
curl -i "$WORKER_URL/notice?key=notice:reference"
npx wrangler kv key get notice:reference --binding NOTICES --remote --text
Der Endpunkt blendet den Referenzeintrag als expired aus, während der KV-Lesezugriff weiterhin seine alte JSON-Antwort liefert. Dies zeigt, warum eine Anwendungsfrist nützlich ist, wenn gespeicherte Daten weiterhin verfügbar bleiben.
Warten Sie nun bis zum KV-Ablauf:
WAIT_SECONDS=$((KV_EXPIRES - $(date +%s) + 1))
if [ "$WAIT_SECONDS" -gt 0 ]; then sleep "$WAIT_SECONDS"; fi
npx wrangler kv key list --binding NOTICES --remote
curl -i "$WORKER_URL/notice"
Die Auflistung sollte nur notice:reference enthalten; der Standardendpunkt sollte {"visible":false,"reason":"missing"} zurückgeben. Führen Sie für den Wartungsschlüssel keinen Löschbefehl aus: Bei dieser Beobachtung geht es um den automatischen Ablauf. Wenn der Eintrag weiterhin sichtbar ist, wiederholen Sie die schreibgeschützten Prüfungen in Abständen von 15 Sekunden, höchstens zwei Minuten lang. Das ist ein Beobachtungszeitfenster für die Übung und keine Garantie für einen exakt bestimmten Löschzeitpunkt. Wenn sich der Zustand nicht stabilisiert, melden Sie das Ergebnis als nicht eindeutig, statt Erfolg zu behaupten. Ein Autorisierungs- oder Netzwerkfehler beweist nicht, dass der Eintrag fehlt.
KV-Ablauf und Lesecache sind unterschiedliche Konzepte. Der Ablauf gilt auch dann, wenn eine längere Dauer für den Lesecache angefordert wurde. Änderungen an gespeicherten Konfigurationsdaten können sich jedoch verzögert verbreiten. Daher ist eine nach einem früheren Lesezugriff geschriebene neue Frist keine sofortige globale Garantie für die Zeitplanung. Dieses Labor prüft die Frist, die in dem Datensatz enthalten ist, den der Handler tatsächlich liest.
Die temporären Cloud-Ressourcen löschen
In diesem Schritt entfernen Sie beide Ressourcen, solange Wrangler noch autorisiert ist. Ein Namespace kann den Worker überdauern. Das Löschen der Anwendung allein bereinigt daher ihre Daten nicht.
Beenden Sie den lokalen Entwicklungsprozess, den Sie in diesem Terminal gestartet haben:
kill "$DEV_PID"
Prüfen Sie Ihre gespeicherten Ressourcenverweise, bevor Sie etwas löschen:
cat wrangler.jsonc
Bestätigen Sie den Worker-Namen labex-notices-... und die Namespace-ID von NOTICES. 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 Labor gehört, und bestätigen Sie mit y. Löschen Sie anschließend nur den Namespace, auf den NOTICES verweist. Dadurch wird auch der erhaltene Referenzeintrag entfernt:
npx wrangler kv namespace delete --binding NOTICES
Prüfen Sie den Namespace in jeder Bestätigungsabfrage, bevor Sie fortfahren. Lassen Sie wrangler.jsonc unverändert, damit die unabhängige Prüfung die Ressourcen identifizieren kann, die nicht mehr vorhanden sein sollen.
npx wrangler kv namespace list
Der Namespace dieses Labors sollte nicht mehr vorhanden sein; nicht zugehörige Namespaces sollten erhalten bleiben. Aktualisieren Sie die Listen im Dashboard, um zu bestätigen, dass der Worker und der Namespace dieses Labors 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 ein autorisiertes Inventar prüfen kann.
Die Autorisierung der VM beenden
In diesem Schritt trennen Sie Wrangler, nachdem die Bereinigungsprüfung erfolgreich war. Das Abmelden beendet die gespeicherte Wrangler-Autorisierung dieser VM; es löscht keine Cloud-Ressourcen und meldet Sie nicht von Ihrer normalen Dashboard-Browsersitzung ab.
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 zu erwarten. Wenn lediglich ein Verbindungsfehler auftritt und kein ausdrücklicher Authentifizierungsstatus angezeigt wird, versuchen Sie es erneut, 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 Labor nun beenden.
Zusammenfassung
Sie haben einen Hinweisleser erstellt, der bei jeder Anfrage eine Anzeigefrist prüft, fehlende und ungültige Daten sicher behandelt und eine Kategorie aus den KV-Metadaten liest. Ein erhaltener alter Eintrag hat gezeigt, dass Inhalte nicht zuerst gelöscht werden müssen, um sie auszublenden. Ein zweiter Eintrag hat den KV-Ablauf mit einem absoluten Zeitstempel und einer separaten Prüfung der automatischen Entfernung demonstriert.
Sie haben zwischen Anzeigefrist, Speicherablauf und Verhalten des Lesecaches unterschieden, anschließend die temporären Ressourcen gelöscht und sich abgemeldet. Als Nächstes importieren und pflegen Sie einen kleinen Weiterleitungskatalog in KV.
