Nginx

O que permite fazer?

• Publicar um domínio para um VPS: o nginx do host compartilhado termina o HTTPS e encaminha o tráfego para o nginx que roda dentro do VPS.
• Ler e reescrever o server block de um domínio dentro do VPS, com teste nginx -t e reversão automática se algo falhar.
• Listar os domínios que chegam ao VPS, com o seu proxy_pass, o redirecionamento de porta que usam e o deploy ao qual estão vinculados.
• Ler os logs de acesso e de erro de cada domínio (as últimas 500 linhas).
• Excluir um domínio: são removidos o server block do host, o do VPS e, se for da zona da ArduMaker, o registro DNS.

Quando convém usar?

• Publicar uma aplicação própria (Node, Python, Go…) que escuta em uma porta local do VPS.
• Escrever o server block quando nenhum deploy de Git nem nenhuma app da ArduMaker o escreveu, ou seja, quando o domínio responde 502 ou o site padrão.
• Ajustar o proxy de um site: pastas estáticas, WebSockets, rotas especiais.
• Diagnosticar um 502, um redirecionamento quebrado ou um domínio que não carrega.

Como funciona na ArduMaker?

Um domínio passa por dois nginx. O do host compartilhado termina o TLS na porta 443 e faz proxy_pass para uma porta do host (host_port) que é um redirecionamento para a porta 443 do VPS. Dentro do VPS, o nginx escuta na 443 em HTTP simples (sem ssl) e distribui por server_name para cada serviço.

Ativar um domínio (lado do host)

1. Valida-se que o domínio seja um FQDN estrito (letras, números, hífens e pontos, pelo menos dois rótulos). Se não for, responde dominio_invalido antes de tocar em qualquer coisa.
2. Um domínio que já é de outra empresa é rejeitado (dominio_ocupado).
3. Sem host_port, o destino é o nginx do VPS: se faltar o redirecionamento para a 443, ele é criado fechado à internet. Com host_port, tem de ser a porta do host de um redirecionamento DESTE VPS.
4. Se o nome não for um subdomínio de um único nível da zona da ArduMaker, verifica-se que o DNS chega ao host e, com create_cert, emite-se o certificado (ver SSL).
5. Escreve-se o server block do host. Com use_ssl (padrão) a porta 80 redireciona para HTTPS com um 301 e a 443 serve HTTPS com HTTP/2. Executa-se nginx -t e recarrega-se; se o teste falhar, o que acabou de ser escrito é apagado.
6. Se o host já tem um server block com esse nome que aponta para outro VPS, ele não é tocado e a operação falha com ruta_ocupada.

Escrever o server block dentro do VPS

1. As edições do nginx de um mesmo VPS são feitas uma de cada vez: dois deploys, ou uma app e uma edição manual, ficam na fila.
2. Se já existe /etc/nginx/sites-available/<dominio>.conf, guarda-se uma cópia .backup.
3. Escreve-se o conteúdo completo (substitui o arquivo, não mescla) e cria-se o link em /etc/nginx/sites-enabled/.
4. Executa-se nginx -t. Se falhar, apagam-se arquivo e link, restaura-se a cópia e recria-se o link anterior: a resposta é Nginx configuration test failed - changes reverted.
5. Reinicia-se o nginx (systemctl restart nginx). Se não arrancar, faz-se a mesma reversão e responde-se Nginx reload failed - changes reverted.
6. Se tudo correu bem, apaga-se a cópia .backup.

O conteúdo não tem outra validação além de nginx -t: é o mesmo poder que o editor de configuração do painel.

O que muda realmente?

No host compartilhado

• Um server block por domínio, que não se vê a partir do VPS.
• Se não existia, um redirecionamento de porta para a 443 do VPS. Não é aberto no firewall e fica fechado aos demais VPS do host.

Dentro do VPS

• /etc/nginx/sites-available/<dominio>.conf e o seu link /etc/nginx/sites-enabled/<dominio>.conf.
• Os logs /var/log/nginx/<dominio>_access.log e /var/log/nginx/<dominio>_error.log, se o server block os declarar (os modelos da ArduMaker declaram).
• Ao excluir o domínio removem-se o arquivo e o link, e o domínio deixa de aparecer nos deploys que o tinham vinculado.

Cada operação fica no registro de atividade do VPS em nome de quem a fez (ou de quem autorizou o agente).

Portas e proxy

O que o proxy do host acrescenta

• Cabeçalhos Host, X-Real-IP (o IP do cliente, sempre sobrescrito), X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host e X-Forwarded-Port.
• Suporte a WebSocket (Upgrade e Connection).
• client_max_body_size 100M e tempos de conexão, envio e leitura de 360 segundos.

O nginx do VPS usa o IP do cliente de X-Real-IP apenas quando a conexão chega por loopback, que é como chega o proxy do host. Uma app atrás dele vê o IP real em X-Real-IP.

Exemplo de server block

Um server block mínimo para uma app que escuta na porta 3000 do VPS:

server {
    listen 443;
    listen [::]:443;
    server_name app.ejemplo.com;

    access_log /var/log/nginx/app.ejemplo.com_access.log;
    error_log /var/log/nginx/app.ejemplo.com_error.log;

    absolute_redirect off;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

• Sem ssl nem certificados: o TLS termina no host e os certificados não são copiados para o VPS.
• absolute_redirect off; faz com que os redirecionamentos do próprio nginx (por exemplo /blog → /blog/) saiam relativos. Sem isso saem como http://dominio:443/blog/ e o navegador não chega.
• Os logs com o nome <dominio>_access.log e <dominio>_error.log são os que ver_logs_nginx_vps lê.

Conflitos e concorrência

• dominio_ocupado (409): o domínio é de outra empresa (cai em uma zona que outra empresa registrou, outra o publicou com Apps ou um deploy de outra o tem vinculado).
• ruta_ocupada: o host já tem um server block com esse nome que aponta para outro VPS. Não é tocado.
• host_port_no_es_del_vps (400): o host_port enviado não é um redirecionamento deste VPS. A resposta traz valid_host_ports e vps_nginx_host_port. host_port não é a porta onde o serviço escuta dentro do VPS.
• Duas edições simultâneas do nginx de um mesmo VPS não se sobrepõem: são executadas uma depois da outra.
• Um domínio que já é usado por uma app ou pelo n8n aparece como usado em listar_dominios_vps (campos used_by, linked_to_repo e puerto_in_vps).

Esquema

Resultado esperado

• activar_dominio_vps devolve nginx (success, domain, host_port, exit_code), certificate e target (host_port, vps_port, via, next_step).
• via: "vps_nginx": o domínio chega ao nginx do VPS e precisa do seu server block. via: "direct": vai direto a essa porta do VPS, que tem de responder HTTP simples.
• listar_dominios_vps mostra cada domínio com server_name, proxy_pass, puerto, puerto_in_vps e linked_to_repo.

Para verificar de fora:

curl -sI https://app.ejemplo.com/
# una carpeta debe redirigir de forma relativa: Location: /blog/
curl -sI https://app.ejemplo.com/blog

Erros e resolução

Se o host ou o VPS não respondem, a resposta é um erro de estado (424), que pode ser repetido. activar_dominio_vps e editar_nginx_dominio_vps são seguros de repetir: o primeiro pergunta antes de criar cada peça e o segundo substitui o arquivo completo. eliminar_dominio_vps pede cuidado: apaga o registro DNS da zona da ArduMaker e os dois server blocks.

Relação com MCP

Sim, há acesso MCP. As ferramentas estão nos perfis /mcp e /mcp/vps e agem com as permissões da pessoa que autorizou o agente; um agente só de leitura vê apenas as de leitura.

Sequência típica: crear_dominio_vps (só para a zona da ArduMaker) → verificar_dominio_vps → activar_dominio_vps sem host_port → editar_nginx_dominio_vps se nenhum deploy escrever o server block. Referência de cada ferramenta em /mcp/docs e exemplos em /mcp/dominios.

Funcionalidades relacionadas

• Certificados SSL
• Domínios e DNS
• Firewall e portas
• Deploy do GitHub
• Servidores VPS
• Monitoramento