Frontend bei Cloudflare betreiben

PLUS Ein Frontend, das die Headless-Schnittstelle liest, kann als Cloudflare Worker laufen: Cloudflare baut die Website bei jeder Änderung im Git-Repository und liefert sie weltweit aus. WP-ImmoMakler bleibt die Datenquelle und meldet nach jedem Import, dass die Website neu gebaut werden soll. Diese Seite beschreibt, was Sie dafür in WordPress und bei Cloudflare einstellen. Die Beispiele beziehen sich auf ein Astro-Frontend mit vorab erzeugten Seiten und serverseitigen Routen für Suche und Formulare, wie es der Astro-Starter von 49heroes umsetzt.

Was Cloudflare kostet

Im kostenlosen Workers-Tarif gelten diese Grenzen:

Kostenloser Tarif	Grenze
Serverseitig erzeugte Anfragen (Suche, Formulare, Merkliste, Suchauftrag-Seite, Webhook)	100.000 pro Tag
Rechenzeit pro Anfrage	10 ms
Vorab erzeugte Seiten, Bilder, Skripte	kostenlos und unbegrenzt
Builds aus Git	3.000 Minuten pro Monat, einer gleichzeitig

Detailseiten, Kategorieseiten und Inhaltsseiten werden beim Build erzeugt und zählen nicht als Anfragen. Die Wartezeit auf WordPress zählt nicht zur Rechenzeit, nur das Erzeugen der Seite. Die Rechenzeiten sehen Sie bei Cloudflare unter Observability des Workers. Der kostenpflichtige Tarif beginnt bei 5 US-Dollar im Monat; die aktuellen Bedingungen stehen in der Preisübersicht von Cloudflare.

Voraussetzungen

• WP-ImmoMakler ab Version 5.71.0 in einer PLUS-Edition
• Ihre WordPress-Website ist aus dem Internet erreichbar und hat ein gültiges Zertifikat. Ein Worker ruft keine privaten Adressen und keine Seiten mit selbst signiertem Zertifikat ab.
• Ein Cloudflare-Konto und das Git-Repository Ihres Frontends bei GitHub oder GitLab

In WordPress einrichten

Im Backend Ihrer Website (wp-admin) unter WP-ImmoMakler → Integrationen → Headless:

1. Schnittstelle einschalten

   Aktivieren Sie Headless-Schnittstelle aktivieren und speichern Sie. Prüfen Sie, ob die Schnittstelle antwortet:

   curl -s https://www.ihre-domain.de/wp-json/immomakler-headless/v1/site

   Die Antwort beginnt mit {"api_version":. Antwortet WordPress mit rest_no_route, ist die Schnittstelle noch ausgeschaltet oder ein Objekt-Cache hält die alten Einstellungen; leeren Sie dann den Cache.

2. Zugangsdaten notieren

   Notieren Sie unter Zugangsdaten den API-Key und unter Webhook-Secret und Status das Webhook-Secret. Beide hinterlegen Sie später bei Cloudflare.

3. Adresse Ihres Frontends eintragen

   Tragen Sie unter Adresse Ihres Frontends die Adresse des Workers ein, zum Beispiel https://ihr-projekt.ihr-konto.workers.dev, später Ihre eigene Domain. Die Links der Schnittstelle, der E-Mails zu Anfragen und der Suchaufträge zeigen dann auf das Frontend. Die Adresse erfahren Sie nach dem ersten Build bei Cloudflare; Sie können das Feld bis dahin leer lassen.

4. Vertrauenswürdige Proxy-Adressen eintragen

   Ein Worker sendet Formulare im Namen der Besucher und hat keine feste Adresse. Tragen Sie unter Vertrauenswürdige Proxy-Adressen die Adressbereiche ein, die Cloudflare unter cloudflare.com/ips veröffentlicht, einen pro Zeile in CIDR-Schreibweise, zum Beispiel 173.245.48.0/20 oder 2400:cb00::/32. Ohne diese Bereiche zählt die Begrenzung der Anfragen pro Stunde alle Besucher Ihres Frontends zusammen. Mehr dazu unter Formulare über die Headless-Schnittstelle.

Bei Cloudflare einrichten

1. Repository verbinden

   Öffnen Sie im Cloudflare-Dashboard Workers & Pages → Create → Import a repository und wählen Sie das Repository Ihres Frontends. Bei einem privaten Repository einer Organisation muss die GitHub-App von Cloudflare Zugriff darauf haben; das genehmigen Inhaber der Organisation bei GitHub unter Settings → GitHub Apps.

2. Build einstellen

   Vergeben Sie einen Projektnamen aus Kleinbuchstaben, Ziffern und Bindestrichen; er wird Teil der Adresse. Für den Astro-Starter lautet der Build-Befehl npm run build und der Deploy-Befehl npx wrangler deploy. Preview builds können Sie ausgeschaltet lassen, solange Sie nur im Hauptzweig arbeiten; jede Vorschau braucht eigene Variablen und Secrets.

3. Build-Variablen eintragen

   Die Variablen unter Advanced settings → Variables gelten nur für den Build. Werte, die beim Build in die Website geschrieben werden, gehören hierher; ändern Sie einen, braucht es einen neuen Build. Für den Astro-Starter:

   Name	Wert
   DEPLOY_TARGET	cloudflare
   IMMOMAKLER_API_URL	https://www.ihre-domain.de/wp-json/immomakler-headless/v1
   PUBLIC_SITE_URL	die Adresse des Workers, nach dem ersten Build

   Lassen Sie keine Zeile mit leerem Wert stehen, sonst reagiert der Button Deploy nicht. Den API-Key braucht der Build nur, wenn API-Key auch für lesende Anfragen verlangen eingeschaltet ist.

4. Ersten Build starten und Adresse übernehmen

   Klicken Sie auf Deploy. Nach dem Build zeigt die Übersicht des Workers seine Adresse, https://<Projektname>.<Konto>.workers.dev; die Subdomain Ihres Kontos steht auch in der Übersicht unter Workers & Pages. Tragen Sie die Adresse als PUBLIC_SITE_URL unter Settings → Build → Variables and secrets und in WordPress als Adresse Ihres Frontends ein, und starten Sie den Build neu (Retry build).

5. Secrets hinterlegen

   Unter Settings → Runtime variables and secrets legen Sie im Bereich Production die Werte an, die der Worker bei jeder Anfrage liest. Klicken Sie jeweils auf Add variable und wählen Sie als Type den Eintrag Secret:

   Name	Wert
   IMMOMAKLER_API_KEY	der API-Key aus dem Tab Headless
   IMMOMAKLER_WEBHOOK_SECRET	das Webhook-Secret aus demselben Tab
   BUILD_HOOK_URL	die Adresse des Deploy Hooks aus dem nächsten Abschnitt

   Secrets wirken ohne neuen Build. Eine Build-Variable ist zur Laufzeit nicht verfügbar: Ein API-Key, der nur dort steht, fehlt den Formularen.

   Precaución

   Legen Sie auch BUILD_HOOK_URL als Secret an, nicht als Variable. Einfache Variablen ersetzt Cloudflare bei jedem Deploy durch die aus der Wrangler-Konfiguration des Repositorys, so dass die Adresse nach dem nächsten Push fehlt. Den Hinweis, die Variable in die Wrangler-Konfiguration zu übernehmen, befolgen Sie nicht: Die Adresse stünde dann im Repository, und jeder mit Lesezugriff könnte Builds starten.

Nach jedem Import neu bauen

WP-ImmoMakler meldet Änderungen an das Frontend, und das Frontend startet bei Cloudflare einen Build:

1. Deploy Hook anlegen

   Legen Sie bei Cloudflare unter Settings → Builds → Deploy Hooks einen Hook für den Hauptzweig an und kopieren Sie seine Adresse. Wer diese Adresse kennt, kann Builds starten; behandeln Sie sie wie ein Passwort. Hinterlegen Sie sie als Secret BUILD_HOOK_URL. Ist die Adresse in fremde Hände geraten, löschen Sie den Hook, legen einen neuen an und ersetzen das Secret.

2. Webhook in WordPress einschalten

   Schalten Sie unter Webhook senden den Versand ein und tragen Sie unter Webhook-Adresse die Adresse ein, die Ihr Frontend für Benachrichtigungen bereitstellt, beim Astro-Starter https://<Adresse des Workers>/api/revalidate/, mit dem Schrägstrich am Ende. Die Wartezeit (Sekunden) fasst die Änderungen eines Imports zu einem einzigen Build zusammen.

3. Verbindung prüfen

   Klicken Sie auf Testnachricht senden. Die Einstellungen melden, ob die Nachricht zugestellt wurde; eine Testnachricht löst keinen Build aus. Um die ganze Kette zu prüfen, ändern und speichern Sie eine Immobilie: Nach der Wartezeit erscheint bei Cloudflare unter Deployments ein neuer Build.

Wie die Nachricht aufgebaut ist und wie Ihr Frontend die Signatur prüft, beschreibt Webhook, Links und Weiterleitung.

Consejo

In einem Worker steht das Node-Modul node:crypto nur mit dem Kompatibilitäts-Flag nodejs_compat zur Verfügung. Mit Web Crypto prüfen Sie die Signatur ohne dieses Flag, in Node und in Workers gleichermaßen:

const encoder = new TextEncoder();
const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
const digest = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(`${timestamp}.${rawBody}`)));
const expected = 'sha256=' + Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('');

let difference = expected.length ^ signatureHeader.length;
for (let i = 0; i < Math.min(expected.length, signatureHeader.length); i++) {
  difference |= expected.charCodeAt(i) ^ signatureHeader.charCodeAt(i);
}
const valid = difference === 0;

Eigene Domain

Hinterlegen Sie Ihre Domain bei Cloudflare unter Settings → Domains & Routes. Ändern Sie danach die Adresse an allen Stellen: PUBLIC_SITE_URL bei Cloudflare (mit neuem Build), Adresse Ihres Frontends und Webhook-Adresse in WordPress. Tragen Sie die Domain außerdem bei Ihrem Captcha-Anbieter als erlaubte Domain ein, und unter Erlaubte Ursprünge (Origins), wenn Besucher-Browser WordPress direkt aufrufen, etwa für die Adressvorschläge der Umkreissuche.

Häufige Fragen

Ist der Betrieb kostenlos?

Im kostenlosen Tarif bezahlen Sie nichts, solange die Website innerhalb der Grenzen aus Was Cloudflare kostet bleibt. Vorab erzeugte Seiten zählen nicht mit.

Kann ich die Website lokal bauen und per SFTP hochladen?

Nur zum Teil. Die vorab erzeugten Seiten sind einfache Dateien, die jeder Webspace ausliefert. Die Suche mit Filtern, die Formulare, die Merkliste, die Suchauftrag-Seite und die Benachrichtigung nach Importen brauchen aber einen Server, der Anfragen beantwortet. Dafür gibt es zwei Wege: einen Hosting-Tarif, der Node.js-Anwendungen ausführt, oder ein Frontend, das Suche und Formulare direkt aus dem Browser an die Schnittstelle schickt; die Formularrouten nehmen solche Anfragen von den erlaubten Ursprüngen an. Neue Immobilien erscheinen bei einem hochgeladenen Build erst nach dem nächsten Build und Upload.

Brauche ich Vorschau-Builds?

Nein. Vorschau-Builds erzeugen für jeden Zweig außer dem Hauptzweig eine eigene Vorschau. Jede Vorschau braucht eigene Variablen und Secrets und hat eine eigene Adresse, die in WordPress nicht als erlaubter Ursprung eingetragen ist.

Wo trage ich welche Variable ein?

Werte, die beim Build in die Website geschrieben werden (DEPLOY_TARGET, IMMOMAKLER_API_URL, PUBLIC_SITE_URL), gehören zu den Build-Variablen, beim Anlegen unter Advanced settings → Variables, später unter Settings → Build → Variables and secrets. Werte, die der Worker bei jeder Anfrage liest (IMMOMAKLER_API_KEY, IMMOMAKLER_WEBHOOK_SECRET, BUILD_HOOK_URL), legen Sie nach dem Anlegen als Secret unter Settings → Runtime variables and secrets an.

Woher kenne ich die Adresse des Workers?

Sie setzt sich aus dem Projektnamen und der workers.dev-Subdomain Ihres Kontos zusammen. Die Subdomain zeigt die Übersicht unter Workers & Pages, die vollständige Adresse die Übersicht des Workers nach dem ersten Build.

Fehlerbehebung

Was Sie sehen	Ursache	Lösung
Der Button Deploy reagiert nicht	eine Variable mit leerem Wert oder ein ungültiges Feld	leere Zeilen entfernen, nach rot markierten Feldern suchen
Der Build bricht ab mit GET /site failed with 404 Es wurde keine Route gefunden	die Schnittstelle ist in WordPress ausgeschaltet	Schnittstelle einschalten
Der Build bricht mit einem Zertifikats- oder Verbindungsfehler ab	WordPress ist nicht öffentlich erreichbar	eine öffentlich erreichbare WordPress-Website mit gültigem Zertifikat verwenden
Formulare schlagen fehl, der Spam-Token antwortet mit 502, WordPress meldet 403	IMMOMAKLER_API_KEY fehlt zur Laufzeit, steht nur bei den Build-Variablen oder weicht vom API-Key in WordPress ab	unter Runtime variables and secrets als Secret hinterlegen, den aktuellen API-Key kopieren
Log: “Headless webhook address redirects; followed it once”	der Webhook-Adresse fehlt der Schrägstrich am Ende, das Frontend leitet weiter; WP-ImmoMakler folgt der Weiterleitung auf derselben Domain	die im Log unter to genannte Adresse eintragen, zum Beispiel …/api/revalidate/
Log: “Headless webhook refused by the front end” mit Status 301, 302, 307 oder 308	die Webhook-Adresse leitet auf eine andere Domain oder mit einer Art von Weiterleitung weiter, der WP-ImmoMakler nicht folgt	die endgültige Adresse eintragen
Testnachricht oder Log: Status 503	IMMOMAKLER_WEBHOOK_SECRET fehlt	als Secret hinterlegen
Testnachricht: Status 401	das Secret weicht von dem in WordPress ab	Secret erneut kopieren
Importe bauen die Website nicht neu	BUILD_HOOK_URL fehlt oder Webhook senden ist aus	Deploy Hook und Webhook einrichten
Importe bauen die Website nur bis zum nächsten Push neu	BUILD_HOOK_URL wurde als Variable statt als Secret angelegt, der nächste Deploy hat sie entfernt	als Secret neu anlegen
Der Sprachumschalter oder E-Mails führen zu WordPress	Adresse Ihres Frontends ist leer	Adresse eintragen, neu bauen
Kanonische Links zeigen auf localhost	PUBLIC_SITE_URL fehlt	Build-Variable eintragen, neu bauen

Das könnte Sie auch interessieren

• Headless-Betrieb mit eigenem Frontend
• Webhook, Links und Weiterleitung
• Formulare über die Headless-Schnittstelle
• API-Referenz der Headless-Schnittstelle