O NPM é adequado para as seguintes necessidades:

• Vários serviços web em uma VPS que precisam ser roteados por subdomínio;
• Você não quer escrever à mão a configuração do Nginx para cada aplicativo;
• Você quer solicitar, renovar e verificar certificados HTTPS pela interface web;
• Um home lab ou uma equipe pequena precisa de gerenciamento unificado de proxy reverso;
• Os aplicativos Docker são adicionados, migrados ou têm portas alteradas com frequência;
• Você precisa de Basic Auth, Access List ou suporte a WebSocket simples.

As situações a seguir não exigem necessariamente o NPM:

• Você tem apenas um site e duas ou três linhas de configuração do Caddy já bastam;
• Toda a configuração é gerenciada por Git, Ansible ou CI/CD e você não quer modificá-la em uma interface web;
• Você precisa de governança de tráfego complexa, descoberta dinâmica de serviços ou Kubernetes Ingress;
• Você espera que ele substitua diretamente o Cloudflare WAF, a autenticação de aplicativos ou um gateway de confiança zero;
• O que você gerencia não são serviços HTTP/HTTPS, mas muitos protocolos complexos de camada 4.

O núcleo do NPM continua sendo o Nginx. A interface web reduz a barreira de configuração, mas não resolve automaticamente os problemas de permissões, vulnerabilidades, backup do banco de dados e controle de acesso do próprio aplicativo.

Se você está acostumado com arquivos de configuração e só faz proxy de três a cinco serviços, o Guia completo de proxy reverso com Caddy em uma VPS costuma ser mais leve. Se você precisa que colegas que não são de operações possam adicionar domínios, ou os serviços mudam com frequência, o NPM vai economizar muito trabalho.

O NPM em si não é pesado; o que realmente consome recursos são os aplicativos que ele faz proxy.

Três portas são necessárias:

• 80/tcp: HTTP e validação HTTP-01 do Let's Encrypt;
• 443/tcp: tráfego HTTPS público;
• 81/tcp: backend de administração do NPM.

Este artigo abre as portas 80 e 443 para a internet pública, mas vincula a 81 apenas a 127.0.0.1. O backend de administração é acessado por um túnel SSH para evitar exposição direta à internet pública.

Antes de entrar em produção, verifique se as portas já estão em uso:

sudo ss -lntp | grep -E ':(80|81|443)\b' || true

Se o Nginx, Apache, Caddy ou outro proxy já ocupa as portas 80/443, primeiro decida quem assume o ponto de entrada; não inicie dois serviços disputando a mesma porta. Para uma solução de problemas detalhada, consulte O que fazer quando uma porta da VPS está ocupada.

Este artigo usa duas redes Docker:

• npm-internal: conecta apenas o NPM e o MariaDB, de modo que o banco de dados não fica exposto à internet pública;
• proxy: compartilhada pelo NPM e pelos aplicativos Docker com proxy, acessando os upstreams pelo nome do contêiner.

O caminho das requisições externas é aproximadamente:

用户浏览器
   ↓ 80/443
Nginx Proxy Manager
   ↓ Docker proxy 网络
应用容器:内部端口

Se o aplicativo não estiver no Docker, você também pode apontar o Proxy Host para o endereço interno da VPS ou para o IP privado de outro servidor.

Primeiro confirme se o Docker e o Compose estão disponíveis:

docker version
docker compose version

Se não estiverem instalados, você pode ler primeiro o Guia prático de implantação com Docker. Para servidores de produção, recomenda-se instalar a partir do repositório oficial do Docker, em vez de usar a longo prazo o Compose desatualizado da distribuição.

Crie o diretório e a rede compartilhada:

sudo mkdir -p /opt/nginx-proxy-manager/data
sudo mkdir -p /opt/nginx-proxy-manager/letsencrypt
sudo mkdir -p /opt/nginx-proxy-manager/mariadb
sudo chown -R "$USER":"$USER" /opt/nginx-proxy-manager

docker network create proxy

Se a rede proxy já existir, o Docker exibirá um conflito de nome e você não precisa criá-la novamente. Você pode confirmar com o seguinte comando:

docker network inspect proxy

Não use diretamente como senha os npm, password ou nomes de domínio dos exemplos. Gere dois conjuntos de valores aleatórios:

openssl rand -base64 36
openssl rand -base64 36

Salve-os em /opt/nginx-proxy-manager/.env:

NPM_DB_ROOT_PASSWORD=替换为第一组随机密码
NPM_DB_PASSWORD=替换为第二组随机密码

Restrinja as permissões do arquivo:

chmod 600 /opt/nginx-proxy-manager/.env

Se a senha contiver espaços, quebras de linha ou caracteres especiais de interpolação do Compose, a análise pode falhar. Usar openssl rand -hex 32 gera senhas hexadecimais puras que são mais fáceis de colocar em .env.

Crie /opt/nginx-proxy-manager/compose.yaml:

services:
  app:
    image: jc21/nginx-proxy-manager:2.15.1
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "127.0.0.1:81:81/tcp"
    environment:
      TZ: Asia/Shanghai
      DB_MYSQL_HOST: db
      DB_MYSQL_PORT: 3306
      DB_MYSQL_USER: npm
      DB_MYSQL_PASSWORD: ${NPM_DB_PASSWORD}
      DB_MYSQL_NAME: npm
    volumes:
      - /opt/nginx-proxy-manager/data:/data
      - /opt/nginx-proxy-manager/letsencrypt:/etc/letsencrypt
    networks:
      - npm-internal
      - proxy
    depends_on:
      db:
        condition: service_healthy

  db:
    image: linuxserver/mariadb:11.4.12
    container_name: nginx-proxy-manager-db
    restart: unless-stopped
    environment:
      TZ: Asia/Shanghai
      MYSQL_ROOT_PASSWORD: ${NPM_DB_ROOT_PASSWORD}
      MYSQL_DATABASE: npm
      MYSQL_USER: npm
      MYSQL_PASSWORD: ${NPM_DB_PASSWORD}
    volumes:
      - /opt/nginx-proxy-manager/mariadb:/config
    networks:
      - npm-internal
    healthcheck:
      test: ["CMD-SHELL", "mariadb-admin ping -h 127.0.0.1 -uroot -p\"$${MYSQL_ROOT_PASSWORD}\" --silent"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s

networks:
  npm-internal:
    internal: true
  proxy:
    external: true

Aqui as versões do NPM e do MariaDB são fixadas para evitar uma atualização acidental de versão principal durante um docker compose pull. O projeto oficial também oferece suporte a SQLite, que de fato é mais simples para testes pessoais; mas com vários proxies, certificados e operação a longo prazo, um banco de dados separado é mais fácil de fazer backup, inspecionar e restaurar.

Verifique a configuração final para garantir que as senhas sejam lidas corretamente:

cd /opt/nginx-proxy-manager
docker compose config --quiet

Não cole a saída completa de docker compose config em um ticket público; ela pode expandir a senha do banco de dados em .env.

Inicie os serviços:

cd /opt/nginx-proxy-manager
docker compose up -d
docker compose ps

A primeira inicialização gera o segredo JWT, inicializa o banco de dados e a estrutura de tabelas, e pode levar um ou dois minutos. Veja os logs:

docker compose logs --tail=150 app
docker compose logs --tail=100 db

Confirme a porta do backend local:

curl -I http://127.0.0.1:81

Se retornar falha logo após a inicialização, aguarde a verificação de integridade do banco de dados passar e verifique os logs novamente. Não exclua o diretório de dados e reinstale só porque a primeira conexão falhou.

Como a porta 81 escuta apenas no localhost, você precisa estabelecer um túnel SSH a partir do seu próprio computador:

ssh -L 8181:127.0.0.1:81 your_user@your_vps_ip

Mantenha a conexão do terminal aberta e depois acesse no navegador:

http://127.0.0.1:8181

A versão atual exibe por padrão um assistente de inicialização que permite criar o primeiro administrador. Use um e-mail real que possa receber notificações e uma senha aleatória separada.

O seguinte conjunto de credenciais, comum em artigos antigos, não é mais adequado como fluxo padrão para o tutorial atual:

[email protected]
changeme

Se você atualizar a partir de um diretório de dados antigo, a conta original será mantida; se você vir a interface da conta antiga em uma instalação nova, verifique se reutilizou um /data ou banco de dados anterior.

Suponha que você queira fazer proxy de app.example.com para um aplicativo:

1. Crie um registro A no seu provedor de DNS apontando para o IPv4 público da VPS;
2. Se você tiver IPv6, crie também um registro AAAA e confirme que as portas 80/443 da VPS também estão abertas no firewall IPv6;
3. Aguarde a resolução entrar em vigor;
4. Verifique o resultado da resolução localmente.

dig +short app.example.com A
dig +short app.example.com AAAA

Se o AAAA apontar para o servidor errado, o Let's Encrypt e alguns usuários podem falhar ao acessar via IPv6. Se você não usa IPv6 por enquanto, excluir o AAAA incorreto é mais seguro do que deixá-lo apontando sempre para o lugar errado.

Depois de entrar no NPM, selecione Hosts → Proxy Hosts → Add Proxy Host.

Exemplo de configuração básica:

Antes de salvar, teste o upstream dentro do contêiner do NPM:

docker exec nginx-proxy-manager getent hosts my-app
docker exec nginx-proxy-manager curl -I http://my-app:3000

Se não for possível resolver o nome do contêiner, os dois contêineres não estão conectados à mesma rede proxy.

O Compose do próprio aplicativo pode ser escrito assim:

services:
  my-app:
    image: your-app-image:固定版本
    restart: unless-stopped
    expose:
      - "3000"
    networks:
      - proxy

networks:
  proxy:
    external: true

expose apenas declara a porta interna do contêiner e não publica a 3000 diretamente na internet pública. Os usuários externos só podem acessar pelas portas 80/443 do NPM, reduzindo a superfície de ataque.

Contêineres que já estão em execução podem entrar temporariamente na rede:

docker network connect proxy my-app

Mas, depois que o contêiner for recriado, a conexão manual pode ser perdida. A configuração de longo prazo deve ser escrita no arquivo Compose do aplicativo.

Se o aplicativo roda diretamente no host da VPS e não no Docker, não preencha 127.0.0.1 no NPM. O 127.0.0.1 dentro do contêiner do NPM aponta para o próprio contêiner do NPM, não para o host.

Você pode usar uma das seguintes abordagens:

• Fazer o aplicativo escutar no endereço privado do host e depois preencher esse endereço;
• Adicionar um mapeamento host-gateway no Compose do Linux;
• Usar o IP privado de outro servidor na mesma LAN;
• Migrar o aplicativo também para a rede Docker compartilhada.

Exemplo de host-gateway:

services:
  app:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Depois disso, você pode tentar usar host.docker.internal como Forward Hostname. O firewall do host e o endereço de escuta do aplicativo ainda precisam permitir conexões a partir da bridge do Docker.

Na página SSL do Proxy Host:

1. Selecione Request a new SSL Certificate;
2. Ative Force SSL;
3. Para sites normais, você pode ativar HTTP/2 Support;
4. Preencha o e-mail e aceite os termos do Let's Encrypt;
5. Depois de salvar, verifique o status do certificado.

A validação HTTP-01 exige:

• Que os registros A/AAAA do domínio apontem corretamente para a VPS atual;
• Que a porta 80 seja acessível pela internet pública;
• Que o firewall na nuvem, o UFW e os grupos de segurança permitam 80/443;
• Que a porta 80 não esteja ocupada por outro proxy reverso;
• Que o Cloudflare ou outro proxy não envie as requisições para a origem errada.

Se a emissão do certificado falhar, não clique uma dúzia de vezes seguidas. O Let's Encrypt tem limites de frequência; corrija primeiro o DNS e as portas e solicite novamente.

Muitos painéis de administração, aplicativos de chat, terminais online e ferramentas de desenvolvimento precisam de WebSocket. A primeira coisa a fazer é ativar Websockets Support no Proxy Host.

Se ainda desconectar:

• Confirme o caminho WebSocket do aplicativo upstream;
• Procure 400, 403 ou 502 nas ferramentas de desenvolvedor do navegador;
• Verifique se o aplicativo exige um proxy confiável ou a URL externa correta;
• Confirme os limites de WebSocket e de timeout do Cloudflare;
• Verifique as requisições Upgrade nos logs do NPM e do aplicativo.

Não comece colando grandes blocos de configuração do Nginx de origem desconhecida em Advanced. O NPM já gera os cabeçalhos de proxy comuns, e configurações duplicadas podem causar conflitos.

A Access List do NPM pode aplicar dois tipos de restrições básicas:

• HTTP Basic Auth com nome de usuário e senha;
• Permitir ou negar acesso por IP ou sub-rede.

Ela é adequada para sites de demonstração temporários, ferramentas internas simples ou uma segunda barreira de acesso, mas não equivale a um sistema de identidade completo. Não dependa apenas do Basic Auth nos seguintes cenários:

• Backends que gerenciam contas na nuvem, senhas ou informações de pagamento;
• Colaboração entre várias pessoas que exige auditoria e login único;
• APIs públicas, Webhooks ou clientes móveis;
• Cenários que exigem MFA, políticas de dispositivos e permissões granulares.

Backends mais sensíveis podem ser colocados atrás de WireGuard, Tailscale, Headscale ou Cloudflare Access. Ao gerenciar o próprio NPM, um túnel SSH costuma ser mais direto do que expor a porta 81.

Tecnicamente, você pode fazer proxy reverso de npm.example.com para a porta de administração, mas isso expõe a superfície de login à internet pública. Se você realmente precisa de login web remoto, pelo menos faça tudo o seguinte:

• Use um subdomínio separado;
• Ative HTTPS;
• Configure uma Access List ou um gateway de identidade externo;
• Faça os administradores usarem senhas longas exclusivas;
• Não abra a porta 81 diretamente;
• Configure alertas de login e verifique os logs regularmente;
• Ao restringir as regiões ou IPs de origem permitidos, prepare primeiro um método de recuperação.

Se você é o único que gerencia uma única VPS, continue usando um túnel SSH; não há necessidade de adicionar um ponto de entrada público só para "parecer conveniente".

Ao integrar o Cloudflare, recomenda-se primeiro usar a nuvem cinza "somente DNS" para concluir a validação do NPM e do certificado, confirmar que o acesso direto à origem funciona e depois ativar o proxy de nuvem laranja.

Pontos comuns de atenção:

• Use Full (strict) no modo SSL/TLS, não Flexible;
• O NPM de origem ainda precisa de um certificado HTTPS válido;
• O Flexible causa facilmente loops de redirecionamento HTTP/HTTPS;
• Cloudflare 521/522 geralmente indica um problema de porta de origem, firewall ou conexão;
• O IP real do cliente exige configuração de proxy confiável; não confie cegamente em qualquer X-Forwarded-For;
• Uploads de arquivos grandes, conexões longas e streaming precisam ser verificados com os limites do plano e os termos de serviço do Cloudflare.

Para loops de redirecionamento, consulte Solução de loops de redirecionamento HTTPS; para 521/522, consulte Solução de problemas de origem Cloudflare 521/522.

Se o aplicativo suporta arquivos grandes, mas você recebe 413 Request Entity Too Large ao enviar pelo NPM, você pode configurar o seguinte em Advanced do Proxy Host correspondente conforme necessário:

client_max_body_size 2g;
proxy_request_buffering off;

Não configure dezenas de GB sem critério. Verifique também de forma sincronizada:

• O limite de upload do próprio aplicativo;
• Os limites de PHP, Node.js ou do framework de backend;
• O limite de upload do Cloudflare;
• O espaço em disco da VPS e o diretório temporário;
• Os timeouts das requisições e a rede do cliente.

Depois de modificar, valide com um arquivo de teste controlável; não use seu único arquivo grande para o primeiro teste.

Primeiro veja a saída do contêiner:

cd /opt/nginx-proxy-manager
docker compose logs --tail=200 app
docker compose logs --tail=100 db

Os logs persistentes e a configuração gerada do NPM ficam em /opt/nginx-proxy-manager/data. Durante a solução de problemas, você pode verificar:

sudo find /opt/nginx-proxy-manager/data -maxdepth 3 -type f | sort | tail -n 50

Não edite à mão sem cuidado os arquivos de configuração do Nginx gerados automaticamente. Na próxima vez que você salvar um Proxy Host na interface web, as alterações manuais podem ser sobrescritas. A personalização de longo prazo deve ir nos locais Advanced ou de configuração personalizada suportados pelo NPM, e ser validada antes de atualizar.

No mínimo, faça backup de:

• /opt/nginx-proxy-manager/data: usuários, configuração, segredo JWT e dados do aplicativo;
• /opt/nginx-proxy-manager/letsencrypt: certificados e informações da conta;
• /opt/nginx-proxy-manager/mariadb: arquivos do banco de dados;
• compose.yaml e .env;
• As versões atuais das imagens e as instruções de recuperação.

Copiar arquivos diretamente enquanto o banco de dados está em execução não garante necessariamente um backup consistente. Recomenda-se exportar primeiro o banco de dados:

cd /opt/nginx-proxy-manager
docker compose exec -T db mariadb-dump \
  -unpm \
  -p"$NPM_DB_PASSWORD" \
  npm > npm-$(date +%F).sql

O Shell acima exige carregar primeiro .env:

set -a
. /opt/nginx-proxy-manager/.env
set +a

O SQL exportado, o diretório de configuração e .env devem ser criptografados e copiados para outra máquina ou armazenamento de objetos. Manter os backups apenas no mesmo disco da VPS não resolve falha de disco ou suspensão da conta.

Antes de atualizar, verifique as imagens atuais e faça um backup:

cd /opt/nginx-proxy-manager
docker inspect nginx-proxy-manager --format '{{.Config.Image}}'
docker compose config > compose.before-upgrade.yaml

Leia as Release Notes da versão de destino, confirme as mudanças de banco de dados e arquitetura e depois modifique as tags de imagem em compose.yaml:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 app

Depois de atualizar, teste pelo menos:

• O login do administrador;
• Um upstream HTTP normal;
• Um aplicativo WebSocket;
• O status do certificado HTTPS;
• As Access Lists;
• Os logs do banco de dados e de renovação de certificados.

Não pule várias versões principais a partir de uma versão muito antiga sem backup. Reverter a imagem não é o mesmo que reverter o banco de dados; se o esquema do banco de dados já foi migrado, você também precisa restaurar os dados anteriores à atualização.

• As portas 80/443 são ocupadas por apenas um proxy de entrada;
• A porta 81 está vinculada apenas ao localhost, a uma VPN ou a uma rede de gerenciamento confiável;
• Os administradores usam senhas aleatórias exclusivas, não reutilizadas com as do banco de dados;
• O MariaDB não mapeia portas públicas;
• Os contêineres de aplicativos preferem expose e redes compartilhadas, e não publicam diretamente portas de administração;
• As permissões de .env são definidas como 600 e não são enviadas para repositórios públicos;
• Os Proxy Hosts só fazem proxy de serviços que você tem o direito de gerenciar;
• O Basic Auth não substitui o login próprio do aplicativo nem o MFA;
• O Cloudflare usa Full (strict), evitando Flexible;
• Verifique regularmente os logs de certificados, login, proxy e banco de dados;
• Fixe as versões antes de atualizar, faça backup do banco de dados e teste a recuperação;
• Feche os Proxy Hosts, certificados e registros DNS que não são mais usados;
• Não trate o NPM como WAF, scanner de vulnerabilidades ou sistema completo de confiança zero.

Na primeira implantação, adicione apenas um aplicativo de teste sem importância. Confirme que DNS, HTTP, HTTPS, WebSocket e logs estão todos normais antes de migrar os serviços de produção. Não mude uma dúzia de domínios para o novo proxy no mesmo dia, caso contrário, quando surgirem problemas, será difícil saber se é DNS, NPM, rede Docker ou configuração do aplicativo.

Para indivíduos e equipes pequenas, o maior valor do NPM não é "desempenho mais forte que o Nginx", mas sim o gerenciamento centralizado de domínios, certificados e configuração de proxy. A verdadeira chave da estabilidade continua sendo: manter apenas um ponto de entrada, ter uma rede upstream clara, não deixar o backend de administração exposto, fixar as versões e garantir que os backups possam ser restaurados.

• Documentação oficial de instalação do Nginx Proxy Manager
• Nginx Proxy Manager v2.15.1 Release
• Repositório do GitHub do Nginx Proxy Manager
• Documentação sobre limites de frequência do Let's Encrypt