Conflictos de puertos

Las colisiones de puertos entre instancias de Chinaski (o entre Chinaski y otro software) se manifiestan como un servicio que no arranca, un admin UI que nunca responde, o un proxy que reporta el backend inalcanzable. Esta página explica qué puertos usa Chinaski por defecto, dónde se elige realmente el puerto, y cómo diagnosticar y corregir los conflictos usuales.

Qué puerto es cuál

Chinaski tiene varios "puertos" distintos en juego, y pertenecen a capas diferentes:

• El daemon del CMS escucha en la dirección de /etc/chinaski<N>/env (LISTEN_URL), que es el único lugar donde se configura en runtime para un despliegue con systemd. Con el instalador estándar, el puerto de la instancia se deriva automáticamente: los nombres numéricos reciben 3000 + N (instancia 2 → 3002), los nombres no numéricos reciben 3001; pasa --port para anularlo.
• Instalaciones rápidas / bundles sin conexión (sin reverse proxy, hypnotoad directo) escuchan en 8080 por defecto, en todas las interfaces hasta que lo restrinjas.
• Caddy o nginx son dueños de 80/443 y hacen reverse proxy hacia el puerto loopback de cada instancia.
• El servidor MCP no binda ningún puerto: se conecta hacia fuera a la URL del CMS; solo su CHINASKI_API_URL referencia un puerto.

Síntomas y causas comunes

La unidad de servicio da vueltas o falla poco después de arrancar. Algo más ya tiene el puerto. Después de cinco arranques fallidos en un minuto la unidad deja de reintentar y entra en estado fallido: systemctl status chinaski@<N> más el journal cuentan la historia. Verifica quién tiene el puerto con ss -tlnp | grep :300<N> (el diagnóstico propio del checklist de producción). Corrígelo moviendo a alguna de las partes: define un LISTEN_URL distinto en el archivo env de la instancia, o detén/reutiliza el listener en conflicto antes de reiniciar.

El admin o el site público responde con errores tipo 502 tras un cambio de puerto. El proxy ya no coincide con el backend. El ejemplo generado de Caddy lo dice explícitamente: su dirección upstream debe ser igual a la dirección de bind en el archivo env de la instancia. Cambia un lado y no el otro (p. ej. editas /etc/chinaski1/env a un puerto nuevo pero no el Caddyfile) y el proxy sigue llamando al puerto viejo. Corrección: edita tanto el archivo env como el upstream del proxy, luego reinicia el CMS y recarga el proxy. Verifica con ss -tlnp | grep :300<N> que el daemon ahora está bindeado, y con journalctl -u chinaski@<N> que se mantuvo arriba.

Dos instancias colisionan tras una reinstalación manual. Si la segunda instancia se instaló sin dejar que el instalador eligiera un puerto (p. ej. un nombre no numérico o un --port reutilizado), comparte el puerto de la primera. Cada instancia necesita su propio puerto; el ejemplo de Caddyfile detalla la asignación esperada (instancia 1 → 3001, instancia 2 → 3002 …) así que cada instancia nueva debería caer en el siguiente puerto libre de la serie 3000.

El site escucha pero nadie de afuera puede alcanzarlo. No es un conflicto para nada: las instalaciones de producción bindean el CMS al loopback a propósito (http://127.0.0.1:3001), con el reverse proxy aceptando el tráfico del mundo. Amplía el bind a 0.0.0.0 y "empezará a funcionar", mientras también dejas que cualquier cliente falsifique headers de reenvío y venza el rate limiting por IP y los lockouts de login. La corrección correcta para acceso remoto es proxy a través de Caddy/nginx, no ampliar el bind.

Cambiar puertos de forma limpia

1. Decide el puerto nuevo por instancia y actualiza LISTEN_URL en /etc/chinaski<N>/env.
2. Actualiza el upstream del proxy correspondiente (127.0.0.1:<port>) del lado de Caddy/nginx.
3. Reinicia la unidad del CMS y recarga o reinicia el proxy.
4. Si el puerto nuevo necesita acceso de firewall para un caso borde sin proxy, replica la regla de firewall al mismo puerto: la guía del propio instalador enruta el tráfico de cada vhost de idioma a ese único puerto.

Recuerda que las unidades de producción corren el daemon como el usuario dedicado chinaski con un sandbox endurecido, así que elige puertos altos (como la convención de la serie 3000 de arriba) para el backend del CMS en lugar de puertos a nivel de sistema.

Una receta rápida de diagnóstico

systemctl status chinaski@<N>            # is the unit in a restart loop / failed?
journalctl -u chinaski@<N> --since today # what did the daemon say at startup?
ss -tlnp | grep -E ':(3000|3001|3002|8080)'   # who owns which port now?

Si el puerto esperado está en manos del proceso correcto pero el proxy todavía falla, compara la línea upstream del proxy contra el LISTEN_URL del archivo env: un desajuste ahí es la causa única más común de "backend corriendo pero site caído".