Custom Domains einrichten

Einrichtung und Konfiguration

Lesen Sie vor jedem Schritt Bevor Sie beginnen und Terminal-Grundlagen. Bei diesen Anweisungen wird davon ausgegangen, dass Sie das vollständige Supastack-Monorepo in VS Code geöffnet haben. Sein Stamm package.json markiert den Repository-Stamm. In pnpm-Befehlen ist ein Arbeitsbereichspaket eine App oder ein Ordner mit gemeinsam genutztem Code. Im Produkt ist ein Arbeitsbereich der Datencontainer und die Sicherheitsgrenze eines Teams. corepack pnpm --filter ... wählt ein Paket aus dem Monorepo aus, während Befehle von seinem Stammverzeichnis aus ausgeführt werden. Wenn Sie nur einen synchronisierten Mobil- oder Desktop-Ordner geöffnet haben, enthält dieser weder das Web-Backend, Docker-Setup noch Root-Skripte: Führen Sie das Backend von diesem Monorepo oder einem erreichbaren gehosteten Server aus und verwenden Sie die eigenen Skripte des Plattformordners. Eine Umgebungsvariable ist eine benannte Einstellung, die in einer lokalen .env-Datei oder Ihrem Hosting-Dashboard gespeichert ist; Starten Sie die entsprechende App neu, nachdem Sie sie geändert haben, und halten Sie Servergeheimnisse von den Werten NEXT_PUBLIC_ und EXPO_PUBLIC_ fern.

1. Öffnen Sie apps/web/.env.local und verwenden Sie CUSTOM_DOMAINS_PROVIDER=local, um eine Vorschau des Domänenbildschirms ohne DNS-Änderungen anzuzeigen.

2. Konfigurieren Sie für einen echten Kunden-Hostnamen Cloudflare für SaaS mit Ihrer eigenen Zone, einem auf diese Zone beschränkten API-Token und dem CNAME-Ziel. Geben Sie die Nur-Server-Werte auf dem Webhost ein, nicht im Browser.

3. Führen Sie Web mit corepack pnpm --filter @supastack/web dev aus und öffnen Sie Einstellungen → Domänen als Arbeitsbereichsbesitzer/-administrator. Erwartet: Der lokale Adapter aktiviert sofort eine Testdomäne; Der Cloudflare-Adapter wartet auf die angezeigten DNS-Datensätze.

Setzen Sie CUSTOM_DOMAINS_PROVIDER=cloudflare und konfigurieren Sie CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID sowie CUSTOM_DOMAIN_CNAME_TARGET. Das API-Token benötigt für die Zone die Berechtigung SSL and Certificates:Edit (die Custom Hostnames API liegt unter /zones/{zone_id}/custom_hostnames). Das CNAME-Ziel ist ein Hostname in Ihrer Cloudflare-Zone — zum Beispiel customers.example.com — der auf Ihre bereitgestellte App verweist.

Legen Sie in der Zone einen DNS-Eintrag an, der das CNAME-Ziel auf Ihren Ursprung verweist (den Fallback-Ursprung in der Cloudflare-for-SaaS-Terminologie). Cloudflare stellt für jeden benutzerdefinierten Hostnamen einen DCV-TXT-Eintrag und optional einen TXT-Eintrag zur Eigentumsprüfung bereit. Die Einstellungen zeigen Kunden genau, welche Einträge anzulegen sind.

Verwenden Sie für die lokale Entwicklung CUSTOM_DOMAINS_PROVIDER=local; damit wird jeder Hostname sofort mit dem Ziel customers.localhost aktiviert. CUSTOM_DOMAINS_PROVIDER=off (Standard) blendet die Steuerelemente des Abschnitts aus.

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

Befehle zum Kopieren

Befolgen Sie die Kommentare, um zu sehen, in welchem Ordner ein Befehl ausgeführt wird. Wenn zwei Terminals gekennzeichnet sind, öffnen Sie zwei Terminalfenster und lassen Sie den ersten Befehl laufen, während Sie den zweiten verwenden.

corepack pnpm --filter @supastack/web dev

Implementierungsablauf

Workspace-Owner und Admins verwalten Domains unter Einstellungen → Domains (höchstens fünf pro Workspace). Kunden richten für ihren Hostnamen einen CNAME-Eintrag auf das CNAME-Ziel ein, ergänzen die angezeigten TXT-Einträge zur Eigentums- und Zertifikatsprüfung und wählen dann Status aktualisieren. Sobald Cloudflare den Hostnamen als aktiv meldet, wird er für Authentifizierung in dieser Bereitstellung als vertrauenswürdiger Ursprung verwendet; Workspace-Name und Logo branden dann die App-Oberfläche auf diesem Hostnamen.

Apex-Domains (Stammdomains) lassen sich bei den meisten DNS-Anbietern nicht als CNAME einrichten. Kunden sollten eine Subdomain wie portal.example.com oder einen Anbieter mit CNAME-Flattening verwenden. Cookies bleiben auf den jeweiligen Host beschränkt; eine Kundendomain erfordert daher eine separate Anmeldung. Single Sign-on über benutzerdefinierte Domains hinweg ist nicht enthalten.

Überprüfung und Fehlerbehebung

Bleibt Cloudflare im Status pending, vergleichen Sie die CNAME- und TXT-Einträge des Kunden mit den genauen Werten auf der Domain-Karte und warten Sie die DNS-Aktualisierung ab. Verwenden Sie eine Subdomain, wenn der DNS-Anbieter einen CNAME für die Stammdomain nicht abbilden kann. Fehlt das Menü, prüfen Sie die Aktivierung und ob der angemeldete Nutzer Workspace-Eigentümer oder -Administrator ist.

Ein lange ausstehender Status bedeutet meist, dass der CNAME des Kunden fehlt oder noch propagiert wird — prüfen Sie die auf der Domainkarte angezeigten DNS-Einträge erneut. Ein verschobener oder fehlgeschlagener Status bedeutet, dass Cloudflare den Hostnamen der Zone nicht mehr zuordnen kann; entfernen Sie ihn und fügen Sie ihn erneut hinzu. Validierungsdaten werden als Provider-JSON gespeichert, sodass sich künftige Cloudflare-Validierungsformate ohne Schemaänderung abbilden lassen.