Configura i domini personalizzati

Installazione e configurazione

Prima di qualsiasi passaggio, leggere Prima di iniziare e Nozioni di base sui terminali. Queste istruzioni presuppongono che tu abbia aperto l'intero supastack monorepo in VS Code; la sua radice package.json contrassegna la radice del repository. Nei comandi pnpm, un pacchetto dell'area di lavoro è un'app o una cartella di codice condiviso; nel prodotto, uno spazio di lavoro è il contenitore dei dati di un team e il limite di sicurezza. corepack pnpm --filter ... seleziona un pacchetto dal monorepo mentre i comandi vengono eseguiti dalla sua radice. Se hai aperto solo una cartella mobile o desktop sincronizzata, non contiene il backend Web, la configurazione di Docker o gli script root: esegui il backend da questo monorepo o da un server ospitato raggiungibile e utilizza gli script della cartella della piattaforma. Una variabile di ambiente è un'impostazione denominata memorizzata in un file .env locale o nel dashboard dell'hosting; riavvia l'app pertinente dopo averla modificata e mantieni i segreti del server fuori dai valori NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Aprire apps/web/.env.local e utilizzare CUSTOM_DOMAINS_PROVIDER=local per visualizzare in anteprima la schermata Domini senza modifiche DNS.

2. Per un nome host cliente reale, configura Cloudflare per SaaS con la tua zona, un token API limitato a quella zona e il target CNAME; immettere i valori solo server nell'host Web, non nel browser.

3. Eseguire Web con corepack pnpm --filter @supastack/web dev e aprire Impostazioni → Domini come proprietario/amministratore dell'area di lavoro. Previsto: l'adattatore locale attiva immediatamente un dominio di prova; l'adattatore Cloudflare attende i record DNS visualizzati.

Impostare CUSTOM_DOMAINS_PROVIDER=cloudflare con CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID e CUSTOM_DOMAIN_CNAME_TARGET. Il token API necessita dell'autorizzazione SSL e Certificati: Modifica sulla zona (i nomi host personalizzati API si trovano in /zones/{zone_id}/custom_hostnames). Il target CNAME è un nome host nella tua zona Cloudflare, ad esempio clienti.esempio.com, che si risolve nella tua applicazione distribuita.

Aggiungi un record DNS nella zona che punta il target CNAME alla tua origine (l'origine fallback in Cloudflare per i termini SaaS). Cloudflare rilascia a ciascun nome host personalizzato un record DCV TXT più un record TXT di proprietà opzionale; la schermata delle impostazioni mostra ai clienti esattamente quali record creare.

Per lo sviluppo locale utilizzare CUSTOM_DOMAINS_PROVIDER=local, che contrassegna ogni nome host immediatamente attivo con i clienti target.localhost. CUSTOM_DOMAINS_PROVIDER=off (impostazione predefinita) nasconde i controlli della sezione.

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

Comandi da copiare

Segui i commenti per vedere in quale cartella viene eseguito un comando. Se due terminali sono etichettati, apri due finestre di terminale e mantieni il primo comando in esecuzione mentre usi il secondo.

corepack pnpm --filter @supastack/web dev

Flusso di implementazione

I proprietari e gli amministratori dello spazio di lavoro gestiscono i domini in Impostazioni → Domini (cinque per spazio di lavoro). I clienti puntano un record CNAME per il proprio nome host sulla destinazione CNAME, aggiungono i record TXT mostrati per la proprietà e la convalida del certificato, quindi premono Aggiorna stato. Una volta che Cloudflare segnala il nome host attivo, diventa un'origine attendibile per l'autenticazione su tale distribuzione e il nome/logo dell'area di lavoro marchia l'app Chrome su quel nome host.

I domini Apex (root) non possono essere CNAME nella maggior parte dei provider DNS: i clienti devono utilizzare un sottodominio come portale.example.com o un provider con appiattimento CNAME. I cookie rimangono limitati a ciascun host, quindi il dominio del cliente rappresenta un accesso separato; il Single Sign-On tra domini personalizzati non rientra nell'ambito.

Verifica e risoluzione dei problemi

Se Cloudflare rimane in sospeso, confronta i record CNAME e TXT del cliente con i valori esatti mostrati sulla scheda del dominio e attendi il tempo di aggiornamento di DNS. Utilizza un sottodominio quando il provider DNS non può appiattire un dominio root CNAME. Se il menu è assente, verifica che la funzionalità sia abilitata e che l'utente che ha effettuato l'accesso sia il proprietario o l'amministratore dell'area di lavoro.

In attesa per un lungo periodo di solito significa che il codice CNAME del cliente è mancante o ancora in propagazione: ricontrolla i record DNS mostrati sulla scheda del dominio. Uno stato spostato o non riuscito significa che Cloudflare non può più risolvere il nome host nella zona; rimuoverlo e aggiungerlo nuovamente. I dati di convalida vengono archiviati come provider JSON, quindi le future forme di convalida Cloudflare non necessitano di modifiche allo schema.