Einführung
Eine Support-API benötigt einen Katalog, der einem anderen Worker gehört. Sie verbinden die öffentliche API mit einem bereitgestellten internen Katalog, reproduzieren und beheben ein fehlendes Binding und stellen beide Services bereit. Dabei bleibt der Katalog ohne öffentlichen Endpunkt.
Verwenden Sie Ihr eigenes Cloudflare-Lernkonto sowie das Wissen über Autorisierung, Konfiguration und Bereitstellung aus den vorherigen Labs. Diese unabhängige VM startet in /home/labex/project/service-binding mit Node.js 22.22.0, dem projektlokalen Wrangler 4.131.1 und einer synthetischen Katalog-Fixture. Es wird keine vorherige VM und keine vorhandene Ressource wiederverwendet. Für diese Übung benötigen Sie weder eine gekaufte Domain noch eine Datenbank oder ein kostenpflichtiges Upgrade. Die wenigen Anfragen werden der normalen Kontonutzung zugerechnet.
Lassen Sie ein Terminal geöffnet. Sie verwenden zwei lokale Prozesse, erstellen zwei eindeutig benannte temporäre Cloud-Worker, überprüfen ihre Verbindung, löschen den aufrufenden Worker und dessen Abhängigkeit und melden sich anschließend ab, bevor Sie die VM beenden.
Fehlendes Service-Binding reproduzieren
In diesem Schritt erstellen Sie eine öffentliche API, deren Katalogabhängigkeit absichtlich nicht konfiguriert ist. Ein separater bereitgestellter Worker verwaltet zwei synthetische Katalogeinträge. Zunächst laufen beide Prozesse nur in dieser VM.
cd /home/labex/project/service-binding
node --version
npx wrangler --version
cat catalog/index.js
Erwarten Sie Node v22.22.0 und Wrangler 4.131.1. Die Einrichtung hat die projektlokalen Abhängigkeiten installiert. Verwenden Sie auf einem anderen Rechner npm ci mit der Lock-Datei dieses Projekts. Die Fixture liefert eine öffentliche Servicebezeichnung, zwei Einträge und einen optionalen synthetischen Abfragewert probe, mit dem Sie eine Anfrage verfolgen können. Sie speichert keine Daten.
Erzeugen Sie einen einmaligen temporären Basisnamen und halten Sie die Identitäten beider Ressourcen in der normalen Konfiguration fest. Lassen Sie dieses Terminal geöffnet, damit WORKER_NAME verfügbar bleibt. Der Wert main des Katalogs ist relativ zu dessen eigenem Konfigurationsverzeichnis.
WORKER_NAME="labex-binding-$(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,
"services": []
}
CONFIG
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
Der Katalog deaktiviert sowohl workers.dev als auch Vorschau-URLs und besitzt keine Routen. Bei der lokalen Entwicklung wird trotzdem ein Loopback-Port für Tests geöffnet. Dadurch entsteht kein öffentlicher Cloud-Endpunkt. Die leere Liste services der öffentlichen API ist der Fehler, den Sie diagnostizieren werden.
Schreiben Sie den Handler der öffentlichen API. /health bleibt unabhängig. /catalog prüft vor dem internen Aufruf, ob das Binding vorhanden ist. catalog.internal ist eine vollständig qualifizierte Platzhalter-URL und kein DNS-Name, den Sie registrieren müssen: env.CATALOG wählt das Ziel aus. Wir erstellen eine neue GET-Anfrage, die nur den vorgesehenen Abfragewert enthält, statt beliebige Client-Header weiterzuleiten.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname === '/health' && request.method === 'GET') {
return Response.json({status: 'ok'});
}
if (url.pathname !== '/catalog') return Response.json({error: 'not_found'}, {status: 404});
if (request.method !== 'GET') {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET'}});
}
if (!env.CATALOG) return Response.json({error: 'catalog_binding_missing'}, {status: 503});
// This hostname completes the Request URL. The binding selects the target Worker.
const target = new URL('https://catalog.internal/catalog');
target.searchParams.set('probe', url.searchParams.get('probe') || '');
try {
return await env.CATALOG.fetch(new Request(target, {method: 'GET'}));
} catch {
return Response.json({error: 'catalog_unavailable'}, {status: 502});
}
}
};
JS
Starten Sie den bereitgestellten Katalog und die API als separate Hintergrundprozesse mit unterschiedlichen HTTP- und Inspector-Ports. Die Protokolle machen den Start sichtbar; & gibt die Shell-Eingabeaufforderung zurück.
npx wrangler dev --config catalog/wrangler.jsonc --ip 127.0.0.1 --port 8081 --inspector-port 9230 > catalog.log 2>&1 &
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat catalog.log
cat api.log
Warten Sie in beiden Protokollen auf die Bereitschaft. Wiederholen Sie bei Bedarf cat und prüfen Sie anschließend die Antworten:
curl -i http://127.0.0.1:8081/catalog
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/catalog
Der Katalog liefert 200 und seine beiden Einträge. Die Health-Prüfung liefert 200 mit {"status":"ok"}. Die Katalogroute der API liefert 503 mit {"error":"catalog_binding_missing"}. Die Abhängigkeit läuft, aber der aufrufende Worker besitzt keine konfigurierte Berechtigung, um sie zu erreichen. Führen Sie die Überprüfung durch, solange dieser Zustand mit fehlendem Binding besteht.
Die interne Verbindung deklarieren und testen
In diesem Schritt beheben Sie die Konfiguration, ohne den API-Code zu ändern. Prüfen Sie die tatsächlichen Hintergrundprozesse und beenden Sie nur den API-Prozess. Im Beispiel ist dies Job 2.
jobs
kill %2
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
binding ist der Name der Eigenschaft, die als env.CATALOG verfügbar ist. service ist der exakte Name des Ziel-Workers aus dessen Konfiguration. Eine Abweichung in einem dieser beiden Teile verursacht ein anderes Problem: Eine fehlende Eigenschaft löst den ausdrücklichen Fehler 503 aus, während ein nicht verfügbares Ziel den Fehler 502 oder einen Start- beziehungsweise Bereitstellungsfehler auslösen kann. Ersetzen Sie den Binding-Aufruf nicht durch eine öffentliche Fetch-URL.
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat api.log
Warten Sie, bis die API bereit ist, und prüfen Sie die Binding-Tabelle. Wrangler findet den laufenden Katalog anhand seines Namens und meldet den Verbindungsstatus. Wenn die Verbindung getrennt ist, überprüfen Sie den Katalogprozess und beide konfigurierten Namen und versuchen Sie es erneut.
curl -i "http://127.0.0.1:8080/catalog?probe=local-check"
curl -i -X POST http://127.0.0.1:8080/catalog
curl -i http://127.0.0.1:8080/missing
Die erste Antwort lautet 200 und enthält die exakte Servicebezeichnung des Katalogs, beide Einträge sowie probe: local-check. Die Methodenprüfung liefert 405, und die unbekannte Route liefert 404. Führen Sie die Überprüfung mit laufenden Servern durch. Dadurch wird ein neuer Probe-Wert durch die öffentliche API gesendet und der vollständige Vertrag geprüft.
Bindings gehören zu Konfigurationsumgebungen. Wenn Sie später --env preview verwenden, deklarieren Sie das vollständige Array services unter env.preview und verweisen Sie auf das vorgesehene bereitgestellte Ziel. Service-Bindings werden nicht von der obersten Ebene übernommen. Dieses Lab verwendet eine unbenannte Umgebung und übergibt niemals --env. Siehe Wrangler environments und die HTTP service binding interface.
Den internen Service und die öffentliche API bereitstellen
In diesem Schritt stellen Sie dieselbe Verbindung in Ihrem eigenen Lernkonto bereit. Beenden Sie beide tatsächlich laufenden lokalen Prozesse, die jobs anzeigt. Im Beispiel sind dies die Jobs 1 und 2.
jobs
kill %1 %2
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Öffnen Sie den angezeigten Geräte-Link in Ihrem angemeldeten Browser, geben Sie den aktuellen Code ein, prüfen Sie Wranglers Berechtigungen und den Hintergrundzugriff und wählen Sie wie zuvor beschrieben nur Ihr Lernkonto aus. Warten Sie, bis der Befehl im Terminal abgeschlossen ist.
npx wrangler whoami --json
Bestätigen Sie loggedIn: true sowie den tatsächlichen Kontonamen und die Konto-ID, auch wenn nur ein Konto aufgelistet ist. Ersetzen Sie YOUR_ACCOUNT_ID in den beiden folgenden Befehlen durch genau diese ID. Behalten Sie die ursprünglich erzeugten Namen und das Binding bei.
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
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,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
Stellen Sie zuerst das Ziel bereit, damit die deklarierte Abhängigkeit des öffentlichen Workers bereits vorhanden ist. Dies sind zwei unabhängige Bereitstellungen und keine atomare Veröffentlichung.
npx wrangler deploy --config catalog/wrangler.jsonc
npx wrangler deploy --config wrangler.jsonc
Der Katalog sollte keine öffentliche Route besitzen. Die API gibt ihre workers.dev-URL und ihr CATALOG-Binding aus. Kopieren Sie genau diese API-URL in die folgende Variable und verwenden Sie die vorhandene workers.dev-Subdomain des Kontos erneut. Bei einem Konto, das erstmals verwendet wird, können Sie dem von Wrangler angebotenen Subdomain-Dialog folgen, ohne eine vorhandene Subdomain zu ändern.
API_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$API_URL/health"
curl -i "$API_URL/catalog?probe=remote-check"
Erwarten Sie eine Health-Antwort mit 200 sowie das Katalogergebnis mit probe: remote-check. Die erste Bereitstellung oder die Verteilung des Hostnamens kann einen kurzen erneuten Versuch erfordern. Ein dauerhaftes 503 oder 502 erfordert die Prüfung der Binding-Konfiguration und der Bereitstellung des Ziels.
Öffnen Sie dasselbe Lernkonto im Dashboard, gehen Sie zu Compute → Workers & Pages und suchen Sie nach den beiden exakten Namen. Öffnen Sie beim öffentlichen API-Worker die Registerkarte Bindings. Das Diagramm zeigt das Binding CATALOG. Vergleichen Sie in der darunterliegenden Tabelle Name (CATALOG) und Value (Ihr passender -catalog-Worker). Der Binding-Name wird im Handler zu env.CATALOG, während sein Wert die bereitgestellte Abhängigkeit bezeichnet.
Folgen Sie dem Link zum Katalog-Worker in dieser Tabelle und wählen Sie anschließend dessen Registerkarte Domains. Bestätigen Sie, dass die obere Breadcrumb-Navigation nun mit -catalog endet. Unter Worker URL sollten sowohl die Schalter Production als auch Preview deaktiviert sein. Unter Custom Domains and Routes sollten keine Einträge vorhanden sein, wie unten dargestellt.
Dies sind Beispielnamen. Verwenden Sie Ihr erzeugtes Suffix und die Subdomain Ihres Kontos. Ein deaktivierter Schalter bedeutet, dass die angezeigte Adresse kein aktivierter öffentlicher Einstiegspunkt ist. Die oben funktionierende API-Anfrage erreicht diesen Worker über sein Service-Binding. Führen Sie diese Prüfung nur lesend durch: Aktivieren Sie keinen öffentlichen Endpunkt, fügen Sie keine Route hinzu und duplizieren Sie das Binding nicht, damit der interne Aufruf funktioniert. Verwenden Sie die Überprüfung. Sie prüft unabhängig die Kontoinhaberschaft, das bereitgestellte Service-Binding, die Endpunkteinstellungen und die entfernte Antwort mit einem neuen Probe-Wert. Das Deaktivieren dieser Endpunkte verhindert nicht, dass autorisierte Kontobetreiber den Service mit einem Binding versehen oder ändern. Es handelt sich nicht um ein Benutzeranmeldesystem.
Den aufrufenden Worker vor seiner Abhängigkeit löschen
In diesem Schritt entfernen Sie die beiden temporären Cloud-Worker, solange Sie noch autorisiert sind. Die Konfigurationsdateien sind Ihr Ressourcenverzeichnis. Bestätigen Sie vor dem Löschen die erzeugten Namen und die Konto-ID.
cat wrangler.jsonc
cat catalog/wrangler.jsonc
Löschen Sie zuerst den öffentlichen aufrufenden Worker und anschließend den internen Katalog. So bleibt kein bereitgestellter aufrufender Worker zurück, der auf einen entfernten Service verweist. Prüfen Sie bei jeder Eingabeaufforderung den exakten Lab-Namen und drücken Sie die einzelne Taste y.
npx wrangler delete --config wrangler.jsonc
npx wrangler delete --config catalog/wrangler.jsonc
Wrangler 4.131.1 kann nach dem Löschen des Scripts einen Authentifizierungsfehler für das veraltete Workers-Sites-KV melden. Erweitern Sie deshalb nicht die Berechtigungen und betrachten Sie diese Meldung nicht als Beweis für die Löschung. Aktualisieren Sie Workers & Pages und führen Sie die Überprüfung durch: Eine erfolgreiche autorisierte Bestandsaufnahme muss zeigen, dass beide exakten Namen nicht vorhanden sind. Netzwerk- oder Authentifizierungsfehler sind nicht schlüssig. Lassen Sie andere Worker, das Konto und die vorhandene Subdomain unverändert.
Die Lab-VM abmelden
In diesem Schritt entfernen Sie die Autorisierung der VM, nachdem Sie die Löschung beider Cloud-Worker überprüft haben.
npx wrangler logout
npx wrangler whoami --json
Erwarten Sie ausdrücklich "loggedIn": false. Der nicht authentifizierte Statusbefehl kann mit einem Fehlercode beendet werden. Das strukturierte Ergebnis ist der wichtige Nachweis. Führen Sie die Überprüfung durch und beenden Sie anschließend die VM. Die Anmeldung im Dashboard-Browser ist davon unabhängig und kann für ein anderes Lab bestehen bleiben. Das Beenden der VM ersetzt weder die Löschung in der Cloud noch die Abmeldung.
Zusammenfassung
Sie haben eine laufende Abhängigkeit diagnostiziert, die in den Bindings des aufrufenden Workers fehlte, ihren exakten Servicenamen deklariert und Anfragen über env.CATALOG.fetch() gesendet. Lokale und bereitgestellte Probes lieferten die Identität und die Daten des Katalogs zurück. Sie haben die bereitgestellte Verbindung geprüft und die öffentlichen Endpunkte des internen Services deaktiviert gelassen. Anschließend haben Sie den aufrufenden Worker vor seiner Abhängigkeit gelöscht und die VM abgemeldet.
Service-Bindings machen interne Worker-Verbindungen explizit. Benannte Umgebungen benötigen eigene Deklarationen, und lokale Konnektivität beweist allein weder die Eigentümerschaft in der Cloud noch die Konfiguration der Endpunkte.
