Connettiti a un server remoto
Ogni client è un renderer sopra un cc_server che possiede i dati. Il desktop può
eseguirne uno al proprio interno; l’app web su app.usectrl.dev
non può, perché una scheda del browser non può ospitare un server. In entrambi i
casi, questa guida punta un client su un server in esecuzione altrove: una
macchinetta, una VM nel cloud, un server di build.
Prerequisiti
Sezione intitolata “Prerequisiti”- Un
cc_serverin esecuzione. Se non ne hai uno, vedi Esegui un server headless. - O i tre valori di abbinamento generati dal server — l’URL del server (
ws://…/rpcowss://…/rpc), un ID dispositivo e una chiave di abbinamento — oppure un codice di invito monouso da un amministratore dello spazio di lavoro, oppure un link di invito o di abbinamento che li contiene. Riscattare un invito esegue il provisioning del tuo utente, registra la tua appartenenza e genera per te la credenziale di questo client, quindi non devi mai gestire un ID dispositivo o una chiave. Ottieni questi valori tramite un canale attendibile e verifica l’impronta del server rispetto a un QR attendibile o a un pin noto alla prima connessione.
Assicurati che il server sia raggiungibile
Sezione intitolata “Assicurati che il server sia raggiungibile”Un server locale non richiede nulla: ws://localhost:9030/rpc funziona sia dal
desktop sia dal browser, perché i browser considerano il loopback un’origine
affidabile.
Un server su un’altra macchina è diverso. app.usectrl.dev è servito in HTTPS,
quindi il browser apre un socket wss:// solo con un certificato di cui si fida
già — e cc_server rifiuta comunque di fare il bind di un indirizzo non di
loopback senza TLS. Dagli una di queste opzioni:
- un certificato diretto, con
--tls-certe--tls-key - un reverse proxy che termina il TLS davanti al server, avviato con
--insecure(testo in chiaro tra proxy e server sul listener esterno, solo su una rete affidabile; questo non disabilita la sessione client cifrata obbligatoria) - un tunnel o una VPN che fornisce il certificato — Tailscale, cloudflared o simili. In Impostazioni → Server → Connessione e stato l’opt-in del tunnel integrato si trova sotto Condividi questo server.
Due impostazioni lato server sono facili da dimenticare. Dietro un proxy, un NAT
o un tunnel, imposta --public-url sull’indirizzo che i client devono
effettivamente contattare — il valore predefinito è il bind locale, quindi senza
di esso i client provano l’host sbagliato. E se ospiti una tua copia della build
web, aggiungi la sua origine a --allowed-origins, che per impostazione
predefinita contiene solo https://app.usectrl.dev; il loopback e i client
nativi sono sempre consentiti.
Connetti l’app desktop
Sezione intitolata “Connetti l’app desktop”Su un’installazione nuova:
- Avvia Control Center. La schermata di primo avvio mostra Benvenuto in Control Center.
- Fai clic su Connetti a un server e inserisci l’URL del server e, in alternativa, un codice di invito oppure, in Usa una chiave di abbinamento, un ID dispositivo e una chiave di abbinamento.
- Fai clic su Connetti. Control Center contatta il server e atterra sulla posta in arrivo dello spazio di lavoro.
Se hai un link di invito o di abbinamento, fai invece clic su Incolla un link di abbinamento e incollalo. La finestra di dialogo mostra a quale server porta il link. Controllalo, poi fai clic su Connetti: incollare da solo non avvia mai la connessione. Se una connessione non riesce, la finestra di dialogo resta aperta con l’errore e tutto ciò che hai inserito.
Su un desktop che esegue già un proprio server:
- Apri Impostazioni → Server → Connessione e stato.
- Fai clic su Aggiungi server. Inserisci l’URL del server (
wss://host:9030/rpc) e, in alternativa, un codice di invito oppure, in Usa una chiave di abbinamento, un ID dispositivo e una chiave di abbinamento. Il pulsante di suffisso del campo URL rileva le istanze dicc_serversulla tua LAN o sul tuo tailnet. - Fai clic su Connetti, poi su Passa nella riga del nuovo server.
Il passaggio è dal vivo: l’app si ricostruisce attorno alla nuova sessione sul posto, senza riavvio. Se la connessione non riesce, resti sul server corrente e vedi l’errore. La riga del server su cui ti trovi non ha l’azione Passa; il server locale è la prima riga, etichettata Esegui in questa app.
Dopo il passaggio, il desktop non possiede alcun database. Ogni schermata legge e scrive attraverso il server remoto su una sessione WebSocket firmata e cifrata end-to-end; la stessa protezione vale su loopback e tramite il relay.
Connetti il client web
Sezione intitolata “Connetti il client web”La build web è sempre remota.
- Apri app.usectrl.dev o la tua copia della build web.
- Fai clic su Connetti a un server e inserisci l’URL del server e, in alternativa, un codice di invito oppure, in Usa una chiave di abbinamento, un ID dispositivo e una chiave di abbinamento. Incolla un link di abbinamento accetta invece un link di invito o di abbinamento.
- Fai clic su Connetti. Il client contatta il server e mostra la stessa interfaccia del desktop.
Se nell’URL è presente un deep link di abbinamento, la finestra di dialogo di connessione si apre con i campi già compilati, così puoi controllare il server prima di fare clic su Connetti. La chiave di abbinamento viaggia nel frammento dell’URL, che i browser non inviano mai al server che ospita la pagina. Tratta il link come un segreto e fidati della pagina che serve il client web: il frammento non protegge da codice di pagina malevolo.
Cosa non fa il browser
Sezione intitolata “Cosa non fa il browser”Il client web legge e scrive sullo stesso server del desktop, ma alcune superfici richiedono una finestra nativa o i dispositivi della macchina stessa:
- niente toast di notifica del sistema operativo, suoni di notifica o barra dei banner ambientali (il centro notifiche in-app funziona comunque)
- nessuna ricerca dei server su LAN o tailnet nella finestra Aggiungi server
- nessun lettore di articoli in-app: gli articoli delle notizie si aprono in una nuova scheda
- niente nuovo avvio di un riassunto di riunione e niente annullamento di uno in elaborazione
Due funzioni si comportano diversamente anziché mancare del tutto. La registrazione delle riunioni funziona nel browser e cattura il microfono più una condivisione dello schermo che include una traccia audio. Anche Apri in IDE funziona, ma chiede al server di avviare l’editor sul display del server, quindi il pulsante si nasconde su un host headless senza editor installati.
Risoluzione dei problemi
Sezione intitolata “Risoluzione dei problemi”- La connessione va in timeout: il server deve essere raggiungibile dal client. Controlla il bind (
--bind any), che la porta sia aperta e che--public-urlindichi l’indirizzo che il client può effettivamente contattare. Su internet aperto il TLS è obbligatorio: un bind non di loopback in chiaro viene rifiutato all’avvio, a meno che il server non sia stato avviato con--insecuredietro un proxy. - Il browser rifiuta di connettersi ma un client nativo funziona: l’origine del browser non è nell’elenco
--allowed-originsdel server. Il valore predefinito consente solohttps://app.usectrl.dev(più il loopback). - L’identità del server è cambiata: il client rifiuta un’impronta diversa dal pin salvato. Verifica l’identità del server fuori banda e riassocia tramite un canale attendibile; non ignorare l’avviso e non passare a un client più vecchio o in chiaro.
- Chiave di abbinamento rifiutata: riesegui
cc_server pairsul server per ruotare la chiave di quel dispositivo, poi inserisci quella nuova. Un dispositivo revocato non trova più la sua credenziale e fallisce in modo restrittivo; la revoca interrompe una sessione attiva entro pochi secondi. - Spazio di lavoro sbagliato: lo spazio di lavoro fa parte dell’URL (
/workspaces/:workspaceId/…) e viaggia con ogni chiamata, quindi cambiare spazio di lavoro in un client modifica solo la tua vista. Puoi raggiungere solo gli spazi di lavoro di cui sei membro: qualsiasi altro viene rifiutato con “Not a member of this workspace”. Vedi Spazi di lavoro e isolamento.
Guide correlate
Sezione intitolata “Guide correlate”- Esegui un server headless
- Associa un dispositivo: il percorso tramite relay per il telefono