Feito com Chinaski

Conflitos de portas

Colisões de portas entre instâncias Chinaski (ou entre o Chinaski e outro software) aparecem como um serviço que não inicia, uma UI de admin que nunca responde, ou um proxy que reporta o backend inacessível. Esta página explica quais portas o Chinaski usa por padrão, onde a porta realmente é escolhida, e como diagnosticar e corrigir os conflitos usuais.

Qual porta é qual

O Chinaski tem algumas "portas" diferentes em jogo, e elas pertencem a camadas distintas:

  • O daemon do CMS escuta no endereço definido em /etc/chinaski<N>/env (LISTEN_URL), que é o único lugar onde é definido em runtime para um deploy systemd. Com o instalador padrão, a porta da instância é derivada automaticamente: nomes numéricos recebem 3000 + N (instância 2 → 3002), nomes não numéricos recebem 3001; passe --port para sobrescrever.
  • Instalações quick / bundles offline (sem reverse proxy, hypnotoad direto) escutam em 8080 por padrão, em todas as interfaces até você estreitar isso.
  • Caddy ou nginx detêm 80/443 e fazem reverse proxy para a porta loopback por instância.
  • O servidor MCP não se liga a nenhuma porta: ele conecta-se para fora à URL do CMS; apenas sua referência CHINASKI_API_URL menciona uma porta.

Sintomas e causas comuns

A unit do serviço oscila ou falha logo após o início. Algo mais já ocupa a porta. Depois de cinco inícios falhados dentro de um minuto a unit para de tentar e entra em estado de falha; systemctl status chinaski@<N> mais o journal contam a história. Verifique quem tem a porta com ss -tlnp | grep :300<N> (o diagnóstico próprio do checklist de produção). Corrija movendo uma das partes: defina um LISTEN_URL diferente no arquivo de env da instância, ou pare/redirecione o listener conflitante antes de reiniciar.

O admin ou o site público responde erros do tipo 502 após uma mudança de porta. O proxy não corresponde mais ao backend. O exemplo de Caddy gerado nomeia isso explicitamente: seu endereço upstream deve ser igual ao bind address no arquivo de env da instância. Mude um lado e não o outro (por exemplo, você edita /etc/chinaski1/env para uma porta nova mas não o Caddyfile) e o proxy continua discando a porta antiga. Correção: edite tanto o arquivo de env quanto o upstream do proxy, então reinicie o CMS e recarregue o proxy. Verifique com ss -tlnp | grep :300<N> que o daemon agora está vinculado, e com journalctl -u chinaski@<N> que ele se manteve de pé.

Duas instâncias colidem após uma reinstalação manual. Se a segunda instância foi instalada sem deixar o instalador escolher uma porta (por exemplo, um nome não numérico ou um --port reusado), ela compartilha a porta da primeira. Cada instância precisa de sua própria porta; o exemplo de Caddyfile explicita a alocação esperada (instância 1 → 3001, instância 2 → 3002 …), então cada instância nova deve cair na próxima porta livre da série 3000.

O site escuta mas ninguém de fora consegue alcançá-lo. Não é um conflito de todo: instalações de produção vinculam o CMS ao loopback de propósito (http://127.0.0.1:3001), com o reverse proxy aceitando o tráfego do mundo inteiro. Alargue o bind para 0.0.0.0 e ele "voltará a funcionar", enquanto também permite a qualquer cliente forjar headers encaminhados e derrotar o rate limiting por IP e os bloqueios de login. A correção correta para acesso remoto é fazer proxy por Caddy/nginx, não alargar o bind.

Mudando portas de forma limpa

  1. Decida a porta nova por instância e atualize LISTEN_URL em /etc/chinaski<N>/env.
  2. Atualize o upstream do proxy correspondente (127.0.0.1:<porta>) no lado Caddy/nginx.
  3. Reinicie a unit do CMS e recarregue ou reinicie o proxy.
  4. Se a porta nova precisar de acesso de firewall para um caso fora do escopo de proxy, espelhe a regra de firewall na mesma porta; a orientação do próprio instalador roteia o tráfego de todos os vhosts de idioma para aquela única porta.

Lembre-se de que as units de produção rodam o daemon como o usuário dedicado chinaski com um sandbox endurecido, então escolha portas altas (como a convenção da série 3000 acima) para o backend do CMS em vez de portas de nível de sistema.

Uma receita de diagnóstico rápido

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?

Se a porta esperada está presa ao processo certo mas o proxy ainda dá erro, compare a linha upstream do proxy contra o LISTEN_URL do arquivo de env: uma divergência aí é a causa única mais comum de "backend rodando mas site fora do ar".

Leia este site em