Nginx Proxy Manager (NPM)

O Nginx Proxy Manager é responsável pela publicação dos serviços, atuando como ponto de entrada único do ambiente.

Ele opera em alta disponibilidade usando VIP (192.168.1.20) com keepalived.

🎯 Objetivo

centralizar acesso aos serviços
simplificar publicação via subdomínios
aplicar SSL automaticamente
integrar autenticação (Authelia)
suportar alta disponibilidade (VIP)

📋 Resumo operacional

Topologia

Componente	Nó primário	Nó secundário	Endereço
Nginx Proxy Manager	RPi (`192.168.1.11`)	NAS (`192.168.1.10`)	VIP `192.168.1.20`
Keepalived	RPi	NAS	`status.json` na porta `9080`

Fonte da verdade

configuração do NPM no RPi
sincronização manual para NAS via /opt/scripts/npm-sync.sh

Dependências

Pi-hole com split DNS apontando domínios internos para 192.168.1.20
keepalived saudável nos dois nós
Authelia no RPi para hosts protegidos

Comandos de validação

curl http://192.168.1.20:9080/status.json
curl -k -I https://servico.scultetus.dev.br
curl http://192.168.1.11:9080/status.json
curl http://192.168.1.10:9080/status.json

Limitações

o VIP cobre endpoint, mas não sincroniza configuração automaticamente
failover pode manter proxy ativo e ainda falhar em serviços dependentes só do RPi

Última validação

20/04/2026

🧱 Arquitetura

Instâncias

Instância	Local	Observação
NPM principal	Raspberry Pi	executa enquanto o NAS está ligado
NPM secundário	NAS	garante continuidade

Alta disponibilidade

Componente	Função
keepalived	gerencia estado MASTER/BACKUP
VIP `192.168.1.20`	endpoint único do proxy
status.json	referência de estado HA

Execução

keepalived roda em container Docker
os dois hosts participam do cluster
apenas um nó responde pelo VIP por vez

🌐 Fluxo de acesso

Usuário → DNS (Pi-hole)
               ↓
         VIP 192.168.1.20
               ↓
        Nginx Proxy Manager
               ↓
        (opcional) Authelia
               ↓
            Serviço

🔁 Comportamento do VIP

Operação normal

um nó responde como MASTER
o outro permanece como BACKUP
o acesso externo e interno deve apontar sempre para o VIP

Em caso de falha

o VIP migra para o outro host
o NPM do nó ativo assume o tráfego
o serviço continua acessível, desde que a configuração esteja alinhada

Limitação importante

⚠️ O failover do VIP mantém a disponibilidade do endpoint, mas não substitui sincronização de configuração entre as instâncias do NPM.

🔄 Sincronização entre instâncias

O NPM não possui sincronização nativa entre múltiplas instâncias.

Como o ambiente utiliza VIP com keepalived, é essencial manter as configurações alinhadas entre os dois nós.

Estratégia adotada

A sincronização é realizada manualmente via script:

origem: RPi (instância principal / fonte da verdade)
destino: NAS (instância secundária)
mecanismo: tar via SSH

Estrutura sincronizada

/data/nginx/

Inclui:

proxy hosts
certificados
configurações do NPM

Script de sincronização

Local típico:

/opt/scripts/npm-sync.sh

Função:

para o NPM no destino
sincroniza arquivos
sobe novamente o serviço

Execução

A sincronização é feita sob demanda:

bash /opt/scripts/npm-sync.sh

Fluxo operacional

Alteração no NPM (RPi)
        ↓
Executar sync
        ↓
NAS atualizado
        ↓
Ambos os nós consistentes

⚠️ Pontos de atenção

alterações feitas diretamente no NAS podem ser sobrescritas
sempre considerar o RPi como origem
executar sync após mudanças relevantes
garantir que o NPM esteja parado durante o sync

📌 Estado atual do Authelia no ambiente

Authelia roda somente no RPi
o serviço foi migrado do NAS para o RPi porque o RPi permanece ligado 24/7
em incidentes de failover, validar se o backend do Authelia no RPi está acessível

🧪 Validação após sync

acessar interface do NPM nos dois nós
validar proxy hosts
testar acesso via domínio
validar certificados

📌 Observação importante

⚠️ O VIP garante disponibilidade de rede, mas a consistência depende da sincronização.

Sem sync, o failover pode resultar em comportamento diferente entre os nós.

🔐 Integração com Authelia

Objetivo

proteger serviços publicados externamente
exigir autenticação/2FA fora da rede local
preservar acesso interno quando aplicável

Padrão adotado

acesso interno → liberado ou menos restrito
acesso externo → protegido via Authelia

Exemplo de configuração

include /snippets/authelia-location.conf;
include /snippets/authelia-authrequest.conf;

location / {
    proxy_pass http://SERVICO_INTERNO;
}

Restrição por rede

allow 192.168.1.0/24;
allow 10.13.13.0/24;
deny all;

🔒 SSL

certificados gerenciados pelo próprio NPM
uso de Let’s Encrypt
validação via domínio público
o proxy é o ponto central para TLS dos serviços publicados

🧪 Troubleshooting

1. Testar o VIP

ping 192.168.1.20

2. Verificar estado HA

curl http://192.168.1.11:9080/status.json
curl http://192.168.1.10:9080/status.json

3. Testar backend diretamente

curl -I http://IP_DO_SERVICO

4. Testar o host publicado

curl -k -I https://servico.scultetus.dev.br

5. Validar certificado

openssl s_client -connect servico.scultetus.dev.br:443

6. Testar do ponto de vista do NPM

docker exec -it nginx-proxy-manager curl http://SERVICO_INTERNO

🔍 Diagnóstico rápido

Sintoma	Interpretação provável
DNS resolve, mas não conecta	problema no proxy
HTTP funciona, HTTPS não	problema de SSL/certificado
acesso pede autenticação inesperada	regra/autenticação do Authelia
funciona internamente, falha externamente	regra de acesso, proxy ou auth
VIP responde, mas host não abre	backend ou configuração do NPM

🧭 Fluxo mental de diagnóstico

DNS resolve?
  ↓ não → Pi-hole / DNS
  ↓ sim
VIP responde?
  ↓ não → keepalived / HA
  ↓ sim
Backend responde?
  ↓ não → serviço interno
  ↓ sim
Authelia / SSL / regra do proxy?

✅ Boas práticas

manter as configurações do NPM alinhadas entre os dois nós
testar acesso interno e externo após alterações
validar backend antes de culpar o proxy
tratar o VIP como endpoint único de publicação
documentar exceções de acesso local/VPN

📌 Observações importantes

o VIP 192.168.1.20 é o endpoint estável da camada de proxy
o DNS dos serviços publicados deve resolver para esse fluxo de acesso
o keepalived garante continuidade do IP virtual, não consistência automática das configs do NPM

📌 Referências rápidas

DNS → Pi-hole
Proxy → NPM
HA → keepalived + VIP 192.168.1.20
Auth → Authelia
Monitoramento → Uptime Kuma