Conectar a un servidor remoto

Todo cliente es un renderizador sobre un cc_server que es el propietario de los datos. La aplicación de escritorio puede ejecutar uno dentro de sí misma; la aplicación web de app.usectrl.dev no puede, porque una pestaña del navegador no puede alojar un servidor. En cualquier caso, esta guía apunta un cliente a un servidor que se ejecuta en otro lugar: una máquina pequeña, una VM en la nube o un servidor de compilación.

Requisitos previos

Un cc_server en ejecución. Si no tienes uno, consulta Ejecutar un servidor headless.
Los tres valores de emparejamiento que generó el servidor —la URL del servidor (ws://…/rpc o wss://…/rpc), un id de dispositivo y una clave de emparejamiento— o un código de invitación de un solo uso de un administrador del espacio de trabajo. Canjear una invitación aprovisiona tu usuario, registra tu pertenencia y genera por ti la credencial de este cliente, así que nunca tienes que gestionar un id de dispositivo ni una clave.

Asegúrate de que se puede acceder al servidor

Un servidor local no necesita nada: ws://localhost:9030/rpc funciona tanto desde la aplicación de escritorio como desde el navegador, porque los navegadores consideran loopback un origen de confianza.

Un servidor en otra máquina es distinto. app.usectrl.dev se sirve por HTTPS, así que el navegador solo abrirá un socket wss:// con un certificado en el que ya confíe; además, cc_server se niega a enlazar una dirección que no sea loopback sin TLS. Dale una de estas opciones:

un certificado directamente, con --tls-cert y --tls-key
un proxy inverso que termine el TLS delante, con el servidor iniciado con --insecure (texto sin cifrar detrás del proxy, solo en una red de confianza)
un túnel o VPN que proporcione el certificado: Tailscale, cloudflared o similar. Ajustes → Servidor → Conexión y estado tiene la opción integrada de túnel en Compartir este servidor.

Hay dos ajustes del lado del servidor que es fácil pasar por alto. Detrás de un proxy, NAT o túnel, configura --public-url con la dirección a la que los clientes deben marcar realmente; de forma predeterminada usa el enlace local, así que sin ella los clientes intentan el host equivocado. Y si alojas tu propia copia de la compilación web, añade su origen a --allowed-origins, que de forma predeterminada solo incluye https://app.usectrl.dev; loopback y los clientes nativos siempre están permitidos.

Conectar la aplicación de escritorio

En una instalación nueva:

Inicia Control Center. La pantalla del primer inicio pregunta ¿Cómo debe ejecutarse Control Center?
En lugar de Ejecutar en esta aplicación, rellena los campos de conexión: la URL del servidor y, o bien un código de invitación, o bien un id de dispositivo y una clave de emparejamiento.
Haz clic en Conectar. Control Center marca el servidor y aterriza en la bandeja de entrada del espacio de trabajo.

En un escritorio que ya ejecuta su propio servidor:

Abre Ajustes → Servidor → Conexión y estado.
Haz clic en Añadir servidor. Introduce la URL del servidor (wss://host:9030/rpc) y, o bien un código de invitación, o bien un id de dispositivo y una clave de emparejamiento. El botón del sufijo del campo de URL detecta instancias de cc_server en tu LAN o tailnet.
Haz clic en Conectar y luego en Cambiar en la fila del nuevo servidor.

El cambio es en vivo: la aplicación se reconstruye sobre la nueva sesión en el mismo sitio, sin reiniciar. Si la conexión falla, permaneces en el servidor actual y ves el error. La fila del servidor en el que estás no tiene acción Cambiar; el servidor local es la primera fila, etiquetada Ejecutar en esta aplicación.

Una vez cambiado, el escritorio no posee ninguna base de datos. Cada pantalla lee y escribe a través del servidor remoto mediante un WebSocket.

Conectar el cliente web

La compilación web siempre es remota.

Abre app.usectrl.dev o tu propia copia de la compilación web.
Introduce la URL del servidor y, o bien un código de invitación, o bien un id de dispositivo y una clave de emparejamiento.
El cliente marca el servidor y renderiza la misma interfaz que el escritorio.

Si en la URL hay un enlace profundo de emparejamiento, los campos vienen rellenos de antemano. La clave de emparejamiento viaja en el fragmento de la URL, que los navegadores nunca envían al servidor que aloja la página, así que el host estático nunca la ve.

Lo que el navegador no hace

El cliente web lee y escribe en el mismo servidor que el escritorio, pero algunas superficies necesitan una ventana nativa o los propios dispositivos de la máquina:

no hay toasts de notificación del sistema operativo, sonidos de notificación ni carril de banners ambiental (el centro de notificaciones de la aplicación sigue funcionando)
no hay descubrimiento de servidores en la LAN o la tailnet en el cuadro de diálogo Añadir servidor
no hay lector de artículos integrado: los artículos del feed se abren en una pestaña nueva
no se puede volver a ejecutar el resumen de una reunión ni cancelar uno que se está procesando

Dos se comportan de forma distinta en lugar de faltar. La grabación de reuniones funciona en el navegador: captura tu micrófono y un uso compartido de pantalla que incluya una pista de audio. Abrir en el IDE también funciona, pero pide al servidor que lance el editor en la pantalla del servidor, así que el botón se oculta frente a un host headless sin editores instalados.

Solución de problemas

La conexión agota el tiempo de espera: se debe poder acceder al servidor desde el cliente. Comprueba el enlace (--bind any), que el puerto esté abierto y que --public-url indique la dirección a la que el cliente puede marcar realmente. Por internet abierto, el TLS es obligatorio: un enlace que no sea loopback y sin cifrar se rechaza al arrancar, a menos que el servidor se haya iniciado con --insecure detrás de un proxy.
El navegador se niega a conectar pero un cliente nativo funciona: el origen del navegador no está en la lista --allowed-origins del servidor. De forma predeterminada solo se permite https://app.usectrl.dev (además de loopback).
Clave de emparejamiento rechazada: vuelve a ejecutar cc_server pair en el servidor para rotar la clave de ese dispositivo y luego introduce la nueva. Un dispositivo revocado se encuentra con que su credencial ha desaparecido y falla de forma cerrada; la revocación corta una sesión activa en cuestión de segundos.
Espacio de trabajo equivocado: el espacio de trabajo forma parte de la URL (/workspaces/:workspaceId/…) y viaja con cada llamada, así que cambiar de espacio de trabajo en un cliente solo cambia tu propia vista. Solo puedes acceder a los espacios de trabajo de los que eres miembro; cualquier otro se rechaza con «Not a member of this workspace». Consulta Espacios de trabajo y aislamiento.

Guías relacionadas

Ejecutar un servidor headless
Emparejar un dispositivo: la ruta del relé para el teléfono