Ligar a um servidor remoto

Todos os clientes são um renderizador sobre um cc_server que detém os dados. A aplicação de ambiente de trabalho pode executar um dentro de si própria; a aplicação web em app.usectrl.dev não pode, porque um separador do navegador não consegue alojar um servidor. De qualquer forma, este guia aponta um cliente a um servidor a correr noutro sítio — uma máquina pequena, uma VM na nuvem, um servidor de build.

Pré-requisitos

Um cc_server a correr. Se não tiver um, consulte Executar um servidor headless.
Ou os três valores de emparelhamento que o servidor emitiu — o URL do servidor (ws://…/rpc ou wss://…/rpc), um ID do dispositivo e uma chave de emparelhamento — ou um código de convite de utilização única de um administrador do espaço de trabalho. Resgatar um convite aprovisiona o seu utilizador, regista a sua pertença e emite a credencial deste cliente por si, para que nunca tenha de tratar de um ID do dispositivo nem de uma chave.

Certifique-se de que o servidor está acessível

Um servidor local não precisa de nada: ws://localhost:9030/rpc funciona tanto na aplicação de ambiente de trabalho como no navegador, porque os navegadores tratam o loopback como uma origem fiável.

Um servidor noutra máquina é diferente. O app.usectrl.dev é servido por HTTPS, por isso o navegador só abre um socket wss:// com um certificado em que já confie — e o cc_server recusa, à partida, associar um endereço que não seja de loopback sem TLS. Dê-lhe uma destas opções:

um certificado diretamente, com --tls-cert e --tls-key
um proxy inverso que termina o TLS à frente, com o servidor iniciado com --insecure (texto simples por trás do proxy, apenas numa rede fidedigna)
um túnel ou VPN que forneça o certificado — Tailscale, cloudflared ou semelhante. Definições → Servidor → Ligação e status tem a ativação do túnel integrado em Partilhar este servidor.

Há duas definições do lado do servidor que é fácil esquecer. Atrás de um proxy, NAT ou túnel, defina --public-url com o endereço a que os clientes devem realmente ligar-se — por predefinição é o endereço de escuta local, por isso, sem ela, os clientes tentam o anfitrião errado. E, se alojar a sua própria cópia da build web, acrescente a origem dela a --allowed-origins, cuja predefinição é apenas https://app.usectrl.dev; o loopback e os clientes nativos são sempre permitidos.

Ligar a aplicação de ambiente de trabalho

Numa instalação nova:

Inicie o Control Center. O ecrã da primeira execução pergunta Como o Control Center deve ser executado?
Em vez de Executar nesta aplicação, preencha os campos de ligação: o URL do servidor e, além disso, um código de convite ou um ID do dispositivo e uma chave de emparelhamento.
Clique em Ligar. O Control Center liga-se ao servidor e abre na caixa de entrada do espaço de trabalho.

Num ambiente de trabalho que já executa o seu próprio servidor:

Abra Definições → Servidor → Ligação e status.
Clique em Adicionar servidor. Introduza o URL do servidor (wss://host:9030/rpc) e um código de convite ou um ID do dispositivo e uma chave de emparelhamento. O botão de sufixo do campo URL deteta instâncias do cc_server na sua LAN ou tailnet.
Clique em Ligar e depois em Alternar na linha do novo servidor.

A alternância é imediata: a aplicação reconstrói-se à volta da nova sessão no mesmo sítio, sem reiniciar. Se a ligação falhar, fica no servidor atual e vê o erro. A linha do servidor em que está não tem a ação Alternar; o servidor local é a primeira linha, com a etiqueta Executar nesta aplicação.

Depois de alternar, a aplicação de ambiente de trabalho não detém nenhuma base de dados. Todos os ecrãs leem e escrevem através do servidor remoto, por um WebSocket.

Ligar o cliente web

A build web é sempre remota.

Abra app.usectrl.dev ou a sua própria cópia da build web.
Introduza o URL do servidor e, além disso, um código de convite ou um ID do dispositivo e uma chave de emparelhamento.
O cliente liga-se ao servidor e apresenta a mesma interface que a aplicação de ambiente de trabalho.

Se houver um link direto de emparelhamento no URL, os campos são preenchidos previamente. A chave de emparelhamento viaja no fragmento do URL, que os navegadores nunca enviam ao servidor que aloja a página, por isso o anfitrião estático nunca a vê.

O que o navegador não faz

O cliente web lê e escreve no mesmo servidor que a aplicação de ambiente de trabalho, mas há algumas áreas que precisam de uma janela nativa ou dos próprios dispositivos da máquina:

sem notificações temporárias do sistema operativo, sons de notificação ou faixa de banners ambiente (o centro de notificações da aplicação continua a funcionar)
sem deteção de servidores na LAN ou tailnet na caixa de diálogo Adicionar servidor
sem leitor de artigos na aplicação — os artigos do feed de notícias abrem num novo separador
sem voltar a executar um resumo de reunião e sem cancelar um que esteja a ser processado

Dois comportam-se de forma diferente em vez de faltarem. A gravação de reuniões funciona no navegador, capturando o seu microfone mais uma partilha de ecrã que inclui uma faixa de áudio. Abrir no IDE também funciona, mas pede ao servidor que inicie o editor no ecrã do servidor, pelo que o botão se esconde perante um anfitrião headless sem editores instalados.

Resolução de problemas

A ligação expira: o servidor tem de estar acessível a partir do cliente. Verifique o endereço de escuta (--bind any), que a porta está aberta e que --public-url indica o endereço a que o cliente consegue realmente ligar-se. Na internet aberta, o TLS é obrigatório — uma associação em texto simples a um endereço que não seja de loopback é recusada no arranque, a menos que o servidor tenha sido iniciado com --insecure atrás de um proxy.
O navegador recusa ligar-se, mas um cliente nativo funciona: a origem do navegador não consta da lista --allowed-origins do servidor. A predefinição permite apenas https://app.usectrl.dev (mais o loopback).
Chave de emparelhamento recusada: volte a executar cc_server pair no servidor para rodar a chave desse dispositivo e introduza a nova. Um dispositivo revogado descobre que a sua credencial desapareceu e falha de forma segura; a revogação derruba uma sessão ativa em segundos.
Espaço de trabalho errado: o espaço de trabalho faz parte do URL (/workspaces/:workspaceId/…) e viaja em todas as chamadas, por isso mudar de espaço de trabalho num cliente altera apenas a sua própria vista. Só consegue aceder a espaços de trabalho de que seja membro — tudo o resto é recusado com “Not a member of this workspace”. Consulte Espaços de trabalho e isolamento.

Guias relacionados

Executar um servidor headless
Emparelhar um dispositivo: o caminho do relay para o telemóvel