Einführung
Ein Help Center benötigt schnelle öffentliche Seiten, einen JSON-Health-Endpunkt und ein Dokument, das nur für Mitarbeitende bestimmt ist. Eine statische Datei kann versehentlich Vorrang vor dem Code erhalten, der eine Anfrage verarbeiten soll. Sie beobachten dieses Verhalten lokal, konfigurieren das Routing mit Vorrang für den Worker und stellen anschließend eine ausdrückliche Richtlinie bereit, die die öffentliche Website nutzbar hält und gleichzeitig ein synthetisches Mitarbeiter-Fixture schützt.
Dieses eigenständige Lab beginnt in /home/labex/project/help-center mit Node.js 22.22.0, dem projektspezifisch installierten Wrangler 4.131.1 sowie bereitgestellten HTML-, CSS- und JavaScript-Fixtures. Verwenden Sie Ihr eigenes Cloudflare-Lernkonto sowie die zuvor vermittelten Kenntnisse zu Autorisierung, Bereitstellung und Secret-Dateien. Eine vorherige VM, Cloud-Ressource, gekaufte Domain, Datenbank oder kostenpflichtige Erweiterung ist nicht erforderlich. Anfragen werden auf die normale Kontonutzung angerechnet.
Alle Inhalte und Zugangsdaten sind synthetisch. Lassen Sie ein Terminal geöffnet. Die unsichere Ausgangskonfiguration bleibt lokal; nur der reparierte Worker wird bereitgestellt. Löschen Sie vor dem Ende der VM die Bereitstellung, entfernen Sie die lokale Test-Zugangsdaten und melden Sie sich ab.
Asset-First-Routing lokal beobachten
In diesem Schritt untersuchen Sie eine bereitgestellte Help-Center-Oberfläche und beobachten, wie passende Dateien standardmäßig Vorrang vor einem Worker erhalten. Die Fixtures enthalten absichtlich eine widersprüchliche Datei /api/health und ein gefälschtes Mitarbeiterhandbuch. Alle Inhalte sind synthetisch, und diese erste Konfiguration bleibt lokal.
cd /home/labex/project/help-center
node --version
npx wrangler --version
ls -R public
Erwarten Sie Node v22.22.0 und Wrangler 4.131.1. Bei der Einrichtung wurden projektspezifische Tools installiert. Verwenden Sie bei einer Reproduktion an einem anderen Ort npm ci mit der Lockdatei des Projekts. Das Verzeichnis public enthält HTML, CSS, JavaScript für den Browser sowie die beiden Routing-Fixtures. Legen Sie dort keine Zugangsdaten oder echten internen Dokumente ab.
WORKER_NAME="labex-help-$(openssl rand -hex 6)"
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"assets": {
"directory": "./public",
"binding": "ASSETS",
"html_handling": "none",
"not_found_handling": "none",
"run_worker_first": false
}
}
CONFIG
directory legt fest, welche Dateien hochgeladen werden. binding stellt sie dem Handler als env.ASSETS zur Verfügung. html_handling: none behält explizite Dateipfade bei, während not_found_handling: none einen automatischen SPA-Fallback verhindert. Der Handler ordnet / ausdrücklich /index.html zu, weil die automatische HTML-Verarbeitung deaktiviert ist. Für den Health-Endpunkt soll er JSON zurückgeben und andere Pfade an den Asset-Speicher delegieren.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname === '/api/health') {
return Response.json({status: 'ok', service: 'help-center'});
}
const assetUrl = new URL(request.url);
if (assetUrl.pathname === '/') assetUrl.pathname = '/index.html';
return env.ASSETS.fetch(new Request(assetUrl, request));
}
};
JS
npx wrangler dev --ip 0.0.0.0 --port 8080 > dev.log 2>&1 &
cat dev.log
Warten Sie, bis das Protokoll die Bereitschaft meldet, bevor Sie fortfahren. Führen Sie bei Bedarf erneut cat aus.
curl -i http://127.0.0.1:8080/
curl -i http://127.0.0.1:8080/styles.css
curl -i http://127.0.0.1:8080/api/health
curl -i http://127.0.0.1:8080/staff/handbook.html
Die Startseite und das CSS liefern 200. Der Health-Endpunkt liefert den statischen Text STATIC_HEALTH_PLACEHOLDER statt des JSON aus dem Handler, weil das passende Asset Vorrang hat. Auch das synthetische Handbuch ist direkt lesbar. Dies zeigt die Routing-Priorität, ist aber keine sichere Bereitstellung. Stellen Sie diese Ausgangskonfiguration nicht bereit. Führen Sie vor der Änderung zunächst die Überprüfung durch.
Wenn Ihr Lab eine Web-8080-Vorschau bereitstellt, öffnen Sie sie jetzt. Die Help-Center-Oberfläche wird geladen, aber in der Statuszeile steht, dass der API-Status nicht verfügbar ist, weil der Browser JSON erwartet hat. Verwenden Sie die Antworten der CLI als maßgebliche Routing-Prüfung; die Vorschau dient als visuelle Kontrolle.
Das folgende Beispiel zeigt das Ausgangsproblem: Die Seite und das Stylesheet werden geladen, aber API status unavailable bedeutet, dass der Browser nicht das erwartete Health-JSON erhalten hat. Eine funktionierende Seitenoberfläche allein bestätigt nicht, dass das API-Routing funktioniert.
Den Worker vor den Assets ausführen und Mitarbeiterinhalte schützen
In diesem Schritt führen Sie den Handler vor jedem statischen Treffer aus. Beenden Sie den tatsächlichen Dev-Prozess, den jobs anzeigt. Das Beispiel geht von Job 1 aus.
jobs
kill %1
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"assets": {
"directory": "./public",
"binding": "ASSETS",
"html_handling": "none",
"not_found_handling": "none",
"run_worker_first": true
}
}
CONFIG
Mit run_worker_first: true gelangt jede Anfrage in den Handler, auch wenn ansonsten direkt ein passendes Asset gefunden würde. Es gibt auch selektive Routenmuster, aber diese kleine Anwendung verwendet eine einzige ausdrücklich festgelegte Routing-Richtlinie. Siehe Konfiguration statischer Assets.
Erzeugen Sie mithilfe des zuvor vermittelten Workflows für Secret-Dateien eine kurzlebige Zugangsdaten für Mitarbeitende. umask schränkt die Berechtigungen neuer Dateien ein. Dieses Bearer-Token ist ausschließlich für das Lab bestimmt und niemals ein API-Token für ein Konto. Halten Sie es aus öffentlichen Dateien, JavaScript im Browser, URLs und Protokollen heraus.
umask 077
STAFF_TOKEN=$(openssl rand -hex 24)
printf 'STAFF_TOKEN=%s\n' "$STAFF_TOKEN" > .dev.vars
cat .gitignore
Bestätigen Sie, dass .dev.vars* und .env* ignoriert werden. Ersetzen Sie den Handler durch die folgende vollständige Richtlinie. Sie dekodiert den Pfad einmal, liefert den Health-Endpunkt als JSON aus, erlaubt nur die aufgeführten öffentlichen Dateien, prüft vor dem Abruf dieses Assets die Zugangsdaten für Mitarbeitende und weist unbekannte Pfade zurück. Die an ASSETS gesendete Anfrage enthält keinen Authorization-Header des Clients. Geschützte Antworten verwenden private, no-store.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
let path;
try { path = decodeURIComponent(url.pathname); }
catch { return Response.json({error: 'not_found'}, {status: 404}); }
if (path === '/api/health') {
if (request.method !== 'GET') {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET'}});
}
return Response.json({status: 'ok', service: 'help-center'});
}
const publicPaths = ['/', '/index.html', '/styles.css', '/app.js'];
if (path === '/staff/handbook.html') {
if (!env.STAFF_TOKEN) return Response.json({error: 'staff_unconfigured'}, {status: 503});
if (request.headers.get('Authorization') !== `Bearer ${env.STAFF_TOKEN}`) {
return Response.json({error: 'unauthorized'}, {status: 401});
}
} else if (!publicPaths.includes(path)) {
return Response.json({error: 'not_found'}, {status: 404});
}
if (!['GET', 'HEAD'].includes(request.method)) {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET, HEAD'}});
}
url.pathname = path === '/' ? '/index.html' : path;
// Only known paths reach the asset store, after any required authorization.
const response = await env.ASSETS.fetch(new Request(url, {method: request.method}));
if (path === '/staff/handbook.html') {
const headers = new Headers(response.headers);
headers.set('Cache-Control', 'private, no-store');
return new Response(response.body, {status: response.status, headers});
}
return response;
}
};
JS
npx wrangler dev --ip 0.0.0.0 --port 8080 > dev.log 2>&1 &
cat dev.log
Vergleichen Sie nach der Bereitschaft die Antworten für öffentliche, geschützte und unbekannte Pfade:
curl -i http://127.0.0.1:8080/api/health
curl -i http://127.0.0.1:8080/staff/handbook.html
curl -i http://127.0.0.1:8080/staff/handbook.html -H "Authorization: Bearer wrong-token"
curl -i http://127.0.0.1:8080/staff/handbook.html -H "Authorization: Bearer $STAFF_TOKEN"
curl -i --path-as-is http://127.0.0.1:8080/%73taff/handbook.html
curl -i http://127.0.0.1:8080/missing-page -H "Sec-Fetch-Mode: navigate"
Der Health-Endpunkt liefert jetzt 200 mit {"status":"ok","service":"help-center"}, obwohl die widersprüchliche Datei weiterhin existiert. Fehlende oder falsche Zugangsdaten liefern JSON mit 401; mit dem passenden Token wird das synthetische Handbuch als HTML zurückgegeben. Auch der codierte Mitarbeiterpfad liefert 401, und die unbekannte Navigation liefert JSON mit 404. Das Entfernen des Fixtures würde das Routing-Problem verdecken; behalten Sie es bei.
Aktualisieren Sie die optionale Web-8080-Vorschau. Der Status sollte jetzt API status: ok anzeigen. Der Handbuch-Endpunkt liefert ohne Zugangsdaten JSON mit 401. Einige eingebettete Browser blockieren die Navigation zu dieser Antwort und zeigen weiterhin die vorherige Seite an. Verwenden Sie das oben gezeigte curl-Ergebnis, um die Antwort zu untersuchen. Dieses Browserverhalten ist kein Beleg für erfolgreichen Zugriff. Verwenden Sie für den autorisierten Zugriff curl mit dem synthetischen Header; fügen Sie das Secret nicht in die Adressleiste ein. Führen Sie die Überprüfung bei laufendem Server durch. Sie prüft außerdem HEAD, codierte Pfade, alternative Schreibweisen und öffentliche Asset-Typen.
Vergleichen Sie die Statuszeile mit der vorherigen Vorschau. API status: ok zeigt jetzt, dass die Seite die Health-Antwort lesen kann. Diese visuelle Prüfung deckt die öffentliche Health-Route ab; verwenden Sie die oben gezeigten curl-Antworten, um das geschützte Handbuch zu beurteilen.
Assets und den geschützten Handler bereitstellen
In diesem Schritt stellen Sie nur die reparierte Konfiguration in Ihrem Lernkonto bereit. Beenden Sie den aktuellen lokalen Prozess und verwenden Sie dabei die tatsächliche Nummer aus jobs.
jobs
kill %1
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Öffnen Sie den angezeigten Geräte-Link beziehungsweise geben Sie den Code in Ihrem angemeldeten Browser ein, prüfen Sie die vorhandenen Wrangler-Berechtigungen und den Background Access und wählen Sie Ihr Lernkonto aus. Warten Sie, bis der Vorgang im Terminal abgeschlossen ist.
npx wrangler whoami --json
Bestätigen Sie den tatsächlichen Kontonamen und die ID. Ersetzen Sie anschließend YOUR_ACCOUNT_ID unten durch diese ID. Behalten Sie den ursprünglichen Ressourcennamen und die reparierten Asset-Einstellungen bei.
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"preview_urls": false,
"assets": {
"directory": "./public",
"binding": "ASSETS",
"html_handling": "none",
"not_found_handling": "none",
"run_worker_first": true
}
}
CONFIG
npx wrangler deploy
Wrangler lädt das Verzeichnis public hoch und stellt seinen Handler bereit. Kopieren Sie die exakt ausgegebene workers.dev-URL unten. Verwenden Sie die vorhandene Subdomain des Lernkontos erneut. Erstanwender können dem Wrangler-Dialog für verfügbare Subdomains folgen.
APP_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$APP_URL/staff/handbook.html"
Vor dem Hochladen des Secrets liefert diese Route 503 mit staff_unconfigured: Der Handler wird zuerst ausgeführt und verweigert den Zugriff standardmäßig. .dev.vars ist eine lokale Konfiguration und wurde bei der Bereitstellung nicht hochgeladen. Wenn die erste Antwort wegen der Verteilung des Hostnamens verzögert ist, wiederholen Sie die Anfrage kurz, bevor Sie einen anhaltenden Fehler untersuchen.
npx wrangler secret bulk .dev.vars
npx wrangler secret list
Bestätigen Sie, dass STAFF_TOKEN als secret_text aufgeführt wird, ohne seinen Wert anzuzeigen. Die Verteilung des Secrets kann kurze Zeit benötigen, bis sie jeden Bereitstellungsort erreicht. Wenn die nächsten Anfragen weiterhin staff_unconfigured liefern, warten Sie 10 Sekunden und wiederholen Sie die Anfragen bis zu zwei Minuten lang. Fordern Sie stabile Antworten mit 401 ohne Zugangsdaten und 200 mit Zugangsdaten, bevor Sie die Überprüfung verwenden. Ein anhaltender Unterschied muss untersucht werden. Akzeptieren Sie 503 nicht als Endergebnis und ändern Sie die Autorisierungsrichtlinie nicht, nur damit eine Prüfung erfolgreich ist.
curl -i "$APP_URL/"
curl -i "$APP_URL/api/health"
curl -i "$APP_URL/staff/handbook.html"
curl -i "$APP_URL/staff/handbook.html" -H "Authorization: Bearer $STAFF_TOKEN"
curl -i "$APP_URL/missing-page" -H "Sec-Fetch-Mode: navigate"
Erwarten Sie öffentliches HTML, Health-JSON, 401 ohne Zugangsdaten, HTML des Handbuchs mit Zugangsdaten sowie 404 für die unbekannte Seite. Öffnen Sie im selben Dashboard-Konto Compute → Workers & Pages, suchen Sie den genauen Worker und bestätigen Sie seine öffentliche URL. Verwenden Sie die Überprüfung für den tatsächlichen Besitz, die bereitgestellten Bindings, die Asset-Inhalte und das Autorisierungsverhalten. Sie können die öffentliche Startseite auch in Ihrem eigenen Browser öffnen. Senden Sie das Mitarbeiter-Token jedoch nicht über eine URL. Die synthetische Token-Prüfung ist eine Routing-Lektion, kein vollständiges Identitätssystem für Mitarbeitende.
Vergleichen Sie auf der Registerkarte Overview des Workers den Namen in der Breadcrumb-Navigation und die verknüpfte workers.dev-Adresse mit der Ausgabe Ihrer Bereitstellung. Der Name und die Subdomain in diesem Screenshot sind Beispiele; Ihr generierter Name und die Subdomain Ihres Kontos werden abweichen. Dies ist die öffentliche Adresse der Bereitstellung, während Web 8080 Ihren lokalen Entwicklungsserver anzeigt. Das Öffnen dieses vorhandenen Workers erfordert nicht das Erstellen einer weiteren Anwendung.
Die Help-Center-Bereitstellung löschen
In diesem Schritt entfernen Sie den Lab-Worker sowie seine zugehörigen Assets und die Secret-Bindung, während Sie noch autorisiert sind. Bestätigen Sie den eindeutigen Namen und das Konto:
cat wrangler.jsonc
npx wrangler delete
Prüfen Sie an der Eingabeaufforderung den genauen Namen des Labs und drücken Sie anschließend die einzelne Taste y. Wrangler 4.131.1 meldet nach dem Löschen möglicherweise den dokumentierten Authentifizierungsfehler für das veraltete Workers-Sites-KV. Erweitern Sie die Berechtigungen nicht und verwenden Sie diese Meldung nicht als Beleg für die Löschung. Aktualisieren Sie Workers & Pages und verwenden Sie die Überprüfung: Eine erfolgreiche autorisierte Bestandsaufnahme muss zeigen, dass dieser Name nicht vorhanden ist. Lassen Sie nicht betroffene Ressourcen, das Konto und dessen workers.dev-Subdomain unverändert.
Lokale Zugangsdaten entfernen und Verbindung trennen
In diesem Schritt entfernen Sie nach der bestätigten Bereinigung der Cloud die lokale synthetische Zugangsdaten und trennen anschließend diese VM.
rm .dev.vars
unset STAFF_TOKEN
npx wrangler logout
npx wrangler whoami --json
Erwarten Sie ausdrücklich "loggedIn": false. Ein Status ungleich null beim nicht authentifizierten Beenden ist zu erwarten, wenn dieses strukturierte Ergebnis vorhanden ist. Verwenden Sie die Überprüfung und beenden Sie die VM. Eine Browser-Anmeldung kann weiterhin bestehen. Weder das Beenden der VM noch das Abmelden löscht Cloud-Ressourcen für Sie.
Zusammenfassung
Sie haben das Asset-First-Routing beobachtet und anschließend die Verarbeitung mit Vorrang für den Worker verwendet, damit API-Antworten und Autorisierung vor passenden Dateien ausgeführt werden. Die bereitgestellte Help-Center-Oberfläche behielt öffentliches HTML, CSS und JavaScript für den Browser bei, während die ausdrückliche Pfadbehandlung nicht authentifizierte Mitarbeiteranfragen und unbekannte Routen blockierte. Sie haben codierte Pfade und browserähnliche Navigation getestet, die reparierte Website mit einem separat hochgeladenen Secret bereitgestellt und anschließend Löschung und Abmeldung überprüft.
Wählen Sie die Reihenfolge des Routings bewusst, wenn statische Dateien und Anwendungsrichtlinien denselben Hostnamen verwenden. Eine lokale Antwort allein bestätigt weder die bereitgestellte Konfiguration noch die Identität des Kontos.
