Conflits de ports

Les collisions de ports entre instances Chinaski (ou entre Chinaski et d'autres logiciels) se manifestent par un service qui ne démarre pas, une UI d'admin qui ne répond jamais, ou un proxy qui rapporte le backend injoignable. Cette page explique quels ports Chinaski utilise par défaut, où le port est réellement choisi, et comment diagnostiquer et corriger les conflits habituels.

Quel port est quoi

Chinaski a plusieurs « ports » en jeu, et ils appartiennent à des couches différentes :

• Le daemon du CMS écoute sur l'adresse de /etc/chinaski<N>/env (LISTEN_URL), qui est le seul endroit où c'est fixé à l'exécution pour un déploiement systemd. Avec l'installeur standard, le port d'instance est dérivé automatiquement : les noms numériques reçoivent 3000 + N (instance 2 → 3002), les noms non numériques reçoivent 3001 ; passez --port pour outrepasser.
• Les installations rapides / paquets hors ligne (sans reverse proxy, hypnotoad en direct) écoutent sur 8080 par défaut, sur toutes les interfaces tant que vous ne le restreignez pas.
• Caddy ou nginx possèdent 80/443 et font du reverse proxy vers le port loopback de chaque instance.
• Le serveur MCP ne lie aucun port du tout : il se connecte vers l'URL du CMS ; seul son CHINASKI_API_URL référence un port.

Symptômes et causes courants

L'unité de service oscille ou échoue peu après le démarrage. Quelque chose d'autre tient déjà le port. Après cinq démarrages ratés en une minute, l'unité cesse de réessayer et passe en état failed : systemctl status chinaski@<N> plus le journal racontent l'histoire. Vérifiez qui a le port avec ss -tlnp | grep :300<N> (le diagnostic de la checklist de production elle-même). Corrigez en déplaçant l'une des parties : fixez un autre LISTEN_URL dans le fichier env de l'instance, ou arrêtez/réaffectez l'écouteur en conflit avant de redémarrer.

L'admin ou le site public répond des erreurs de type 502 après un changement de port. Le proxy ne correspond plus au backend. L'exemple Caddy généré le nomme explicitement : son adresse d'amont doit égaler l'adresse d'écoute dans le fichier env de l'instance. Changez un côté et pas l'autre (par exemple vous modifiez /etc/chinaski1/env vers un nouveau port mais pas le Caddyfile), et le proxy continue d'appeler l'ancien port. Correctif : éditez à la fois le fichier env et l'amont du proxy, puis redémarrez le CMS et rechargez le proxy. Vérifiez avec ss -tlnp | grep :300<N> que le daemon est désormais lié, et avec journalctl -u chinaski@<N> qu'il est resté debout.

Deux instances entrent en collision après une réinstallation manuelle. Si la seconde instance a été installée sans laisser l'installeur choisir un port (par exemple un nom non numérique ou un --port réutilisé), elle partage le port de la première. Chaque instance a besoin de son propre port ; l'exemple de Caddyfile épelle l'allocation attendue (instance 1 → 3001, instance 2 → 3002 …) si bien que chaque nouvelle instance doit atterrir sur le prochain port libre de la série 3000.

Le site écoute mais personne de l'extérieur ne peut l'atteindre. Pas un conflit du tout : les installations de production lient le CMS au loopback exprès (http://127.0.0.1:3001), le reverse proxy acceptant le trafic du monde. Élargissez l'écoute à 0.0.0.0 et ça « se mettra à fonctionner », tout en laissant n'importe quel client usurper les en-têtes transmis et contourner la limitation de débit par IP et les verrouillages de connexion. Le correctif correct pour l'accès distant est de proxifier via Caddy/nginx, pas d'élargir l'écoute.

Changer de ports proprement

1. Décidez du nouveau port par instance et mettez à jour LISTEN_URL dans /etc/chinaski<N>/env.
2. Mettez à jour l'amont du proxy correspondant (127.0.0.1:<port>) côté Caddy/nginx.
3. Redémarrez l'unité du CMS et rechargez ou redémarrez le proxy.
4. Si le nouveau port a besoin d'un accès firewall pour un cas limite sans proxy, reflétez la règle de firewall vers ce même port : le guidage de l'installeur lui-même route le trafic de chaque vhost de langue vers ce port unique.

Rappelez-vous que les unités de production exécutent le daemon sous l'utilisateur dédié chinaski avec un bac à sable durci, donc choisissez des ports hauts (comme la convention de série 3000 ci-dessus) pour le backend du CMS plutôt que des ports de niveau système.

Une recette de diagnostic rapide

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 le port attendu est tenu par le bon processus mais que le proxy donne encore une erreur, comparez la ligne d'amont du proxy au LISTEN_URL du fichier env : un décalage là est la cause la plus courante de « backend qui tourne mais site en panne ».