Centrifugo en un VPS: servidor de tiempo real autoalojado

Centrifugo se sitúa entre tu aplicación y sus usuarios. Tu backend — Laravel, Django, Express, Rails u otro — no mantiene ninguna conexión abierta: firma un token para cada usuario y publica mensajes con una simple llamada HTTP. Centrifugo mantiene las conexiones WebSocket de los navegadores y las apps móviles, y entrega cada mensaje a los suscriptores del canal correspondiente.

Esta separación tiene una ventaja concreta: tu aplicación sigue sin estado y es fácil de desplegar, y la parte de tiempo real cabe en un único binario Go que consume unas decenas de MB de RAM en reposo.

Un VPS Ubuntu 24.04 con 1 GB de RAM y 10 GB de disco, Docker y el plugin Compose instalados, y un subdominio que apunte al VPS, por ejemplo rt.example.com. El HTTPS no es opcional: un sitio servido por HTTPS solo puede abrir conexiones wss://, y tu clave de API nunca debe circular en claro.

Una conexión WebSocket empieza con una petición HTTP que pide cambiar de protocolo. nginx debe transmitir esa petición y no cortar una conexión que permanece en silencio unos minutos. En el bloque server de tu subdominio, con un certificado Let's Encrypt:

location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;
}

Tras nginx -t y una recarga, https://rt.example.com muestra la pantalla de inicio de sesión de la consola.

Publicar es enviar un objeto JSON a un canal. Sirve cualquier lenguaje capaz de hacer una petición HTTP:

curl -X POST https://rt.example.com/api/publish \
  -H "X-API-Key: $ENCRYPTION_KEY" \
  -d '{"channel": "commandes", "data": {"id": 1042, "statut": "payee"}}'

La respuesta {"result":{}} confirma que el mensaje se aceptó. Sin la cabecera X-API-Key, o con una clave incorrecta, Centrifugo responde 401.

Un navegador solo se conecta con un JWT firmado por tu backend con ENCRYPTION_KEY_HEX64. El claim sub lleva el identificador del usuario, exp la fecha de caducidad y channels la lista de canales a los que queda suscrito de oficio. Ejemplo en Python:

import time, jwt  # pip install pyjwt

def centrifugo_token(user_id: str) -> str:
    claims = {"sub": user_id, "exp": int(time.time()) + 3600, "channels": ["commandes"]}
    return jwt.encode(claims, ENCRYPTION_KEY_HEX64, algorithm="HS256")

Expón esta función detrás de una ruta autenticada de tu aplicación: solo un usuario con sesión iniciada en tu app debe poder obtener un token.

Los ajustes de esta instalación están cerrados a propósito. Un navegador no puede suscribirse por su cuenta a un canal ni publicar en él: solo recibe los canales listados en el claim channels de su token. Tu backend decide, cada vez que emite un token, quién escucha qué — un cliente solo ve sus propios pedidos, un agente de soporte solo la cola de su equipo.

Para un chat, la publicación pasa también por tu backend: el navegador envía el mensaje a tu aplicación, que lo valida, lo guarda en la base de datos y lo publica por la API. Este rodeo cuesta unos milisegundos y te deja el control de la moderación y del historial.

Por último, da a los tokens una duración corta, una hora por ejemplo. En lugar de pasar un token fijo, deja que el SDK pida uno nuevo a tu aplicación cuando caduque:

const client = new Centrifuge('wss://rt.example.com/connection/websocket', {
  getToken: async () => {
    const res = await fetch('/realtime/token', { credentials: 'include' });
    return (await res.json()).token;
  },
});

La ruta /realtime/token es de tu aplicación; comprueba la sesión del usuario antes de firmar nada.

En el lado cliente, el SDK oficial centrifuge (npm) abre la conexión y entrega los mensajes:

import { Centrifuge } from 'centrifuge';

const client = new Centrifuge('wss://rt.example.com/connection/websocket', {
  token: tokenFromYourBackend,
});
client.on('publication', (ctx) => console.log(ctx.channel, ctx.data));
client.connect();

Si la conexión falla, mira primero los registros (docker compose logs centrifugo). El mensaje «request Origin is not authorized» indica que falta el origen de tu sitio en CENTRIFUGO_CLIENT_ALLOWED_ORIGINS; «invalid token» apunta a un token mal firmado o caducado.

Abre https://rt.example.com e introduce ADMIN_PASSWORD: la consola no pide usuario. Muestra la versión del nodo, el número de clientes y usuarios conectados, y permite enviar comandos de la API — publicar un mensaje de prueba, listar los canales activos — sin escribir código. Es la forma más rápida de comprobar que un mensaje sale antes de buscar el fallo en el navegador.

Esta guía usa el motor en memoria: un solo nodo, sin dependencias. Sirve para la mayoría de las aplicaciones, y un VPS modesto ya sostiene un gran número de conexiones simultáneas, de ahí el límite de archivos abiertos ampliado en el docker-compose.yml. El día en que un nodo no baste, Centrifugo puede repartir la carga entre varios nodos unidos por Redis. Para actualizar, cambia la etiqueta de la imagen tras leer las notas de versión y ejecuta docker compose pull && docker compose up -d; las conexiones se restablecen solas, porque los SDK cliente se reconectan automáticamente.