Como encaminhar contentores Docker por uma VPN
Com Gluetun, as portas publicadas desaparecem ao usar network_mode: service. Veja o motivo, o erro do Docker e o compose correto para expor portas.
Como as portas desaparecem quando encaminha contentores Docker através de uma VPN
Para encaminhar contentores Docker através de uma VPN, atribui o túnel a um contentor e liga os restantes ao respetivo namespace de rede com network_mode: "service:gluetun". É essa ligação que causa mais confusão. O contentor ligado deixa de ter uma rede própria. Por isso, as portas publicadas e o nome do serviço Docker também desaparecem. Publique as portas no contentor da VPN. Os outros contentores chegam à aplicação através do nome do contentor da VPN.
Se deixar um bloco ports: no contentor ligado, o Docker recusa-se a criá-lo:
Error response from daemon: conflicting options: port publishing and the container type network modeA ferramenta usada aqui é o Gluetun, um contentor que liga a um fornecedor comercial de VPN (rede privada virtual) através de WireGuard ou OpenVPN e inclui a sua própria firewall. A versão v3.41.3 é a atual em outubro de 2026. Os exemplos usam Mullvad com WireGuard, por isso precisa de uma conta e de uma chave do fornecedor. Se preferir terminar o túnel em hardware seu, executar o seu próprio servidor WireGuard numa VPS cria a outra extremidade, e wg-easy em Docker disponibiliza essa configuração numa interface web.
O que network_mode: "service:gluetun" faz na prática
Normalmente, cada contentor Docker recebe o seu próprio namespace de rede: as suas próprias interfaces, tabela de encaminhamento, regras de firewall e sockets em escuta. O modo service: ignora esse passo e inicia o contentor dentro do namespace do gluetun. Um namespace significa um endereço IP, e isso altera seis aspectos.
- A aplicação não tem um endereço próprio. Usa o endereço do gluetun.
- A aplicação não está ligada a nenhuma rede Docker. Por isso, o seu nome de serviço nunca é registado nem resolvido. Os outros contentores têm de usar
gluetun. - Os contentores dentro do namespace comunicam entre si através de
localhost. - Dois contentores no mesmo namespace não podem escutar na mesma porta. A documentação do Gluetun é explícita: não existe solução alternativa.
- As capabilities pertencem a um contentor, não a um namespace. O Gluetun tem
NET_ADMINe/dev/net/tunporque cria a interface do túnel. O contentor ligado não as herda. - O Compose rejeita qualquer ficheiro em que um serviço defina simultaneamente
network_modeenetworks. Ligue o gluetun às suas redes, e a aplicação acompanha-o.
Reiniciar o gluetun desliga tudo o que está ligado a ele. Este comportamento está documentado e é a razão pela qual o gluetun reinicia o processo VPN dentro do contentor, em vez de terminar quando a ligação falha. Depois de reiniciar ou recriar o gluetun manualmente, reinicie os contentores ligados a ele.
O ficheiro Compose funcional
services:
gluetun:
image: qmcgaw/gluetun:v3
container_name: gluetun
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- VPN_SERVICE_PROVIDER=mullvad
- VPN_TYPE=wireguard
- SERVER_CITIES=Amsterdam
- TZ=Europe/Amsterdam
env_file:
- ./gluetun.env
volumes:
- ./gluetun:/gluetun
ports:
- 127.0.0.1:8080:8080/tcp
restart: unless-stopped
qbittorrent:
image: lscr.io/linuxserver/qbittorrent:latest
container_name: qbittorrent
network_mode: "service:gluetun"
environment:
- PUID=1000
- PGID=1000
- TZ=Europe/Amsterdam
- WEBUI_PORT=8080
volumes:
- ./qbittorrent:/config
- ./downloads:/downloads
depends_on:
gluetun:
condition: service_healthy
restart: unless-stoppedA tag :v3 é a versão estável mais recente da série v3. A tag :latest aponta para o último commit do branch master, que corresponde à versão de desenvolvimento. Por isso, fixe :v3 numa máquina que não pretende depurar a meio da semana.
WEBUI_PORT=8080 tem de corresponder à porta publicada, porque o qBittorrent escuta dentro do namespace do gluetun e a regra de publicação encaminha o tráfego do host para a porta 8080 nesse namespace. Se alterar um número sem alterar o outro, a porta não responde. 127.0.0.1:8080:8080 mantém a interface Web acessível apenas no endereço de loopback do host. Um 8080:8080 isolado publica em todas as interfaces e cria a sua própria regra de firewall. É assim que as portas publicadas pelo Docker ultrapassam diretamente o ufw.
Inicie os serviços e depois verifique-os nesta ordem:
docker compose up -d
docker compose ps
docker compose logs gluetun | tail -30docker compose ps deve mostrar o gluetun como healthy e o qbittorrent como running. Em seguida, confirme o endereço de saída a partir do namespace. Esta verificação determina o resultado de todas as outras:
docker run --rm --network=container:gluetun alpine:3.22 sh -c "apk add wget && wget -qO- https://ipinfo.io"O campo ip nesse JSON deve conter o endereço do seu fornecedor de VPN. Se contiver o endereço do próprio servidor, a aplicação não está no túnel e nada do que é descrito abaixo irá funcionar.
Mantenha as chaves fora do ficheiro Compose
gluetun.env contém as credenciais e fica fora do git:
WIREGUARD_PRIVATE_KEY=wOEI9rqqbDwnN8/Bpp22sVz48T71vJ4fYmFWujulwUU=
WIREGUARD_ADDRESSES=10.64.222.21/32Ambos os valores vêm de um ficheiro de configuração do WireGuard que gera na área da sua conta do provedor. Defina o ficheiro com o modo 600. Seja claro sobre o que isto oferece: a chave fica fora do seu repositório, mas docker inspect gluetun continua a mostrar todas as variáveis de ambiente a qualquer pessoa que consiga aceder ao socket do Docker. Ficheiros de ambiente e segredos no Docker Compose aborda opções mais robustas.
Como um container fora do túnel comunica com um container dentro dele
As duas direções funcionam, e cada uma usa um nome diferente. Os dois containers precisam de uma rede Docker partilhada. Neste caso, é a rede do gluetun, porque o container associado não tem uma rede própria. Como as redes do Docker Compose são ligadas explica os valores predefinidos.
De fora para dentro, use o nome do gluetun e a porta em que a aplicação escuta. Um container de reverse proxy acede à interface web do qBittorrent em gluetun:8080. Não é necessária nenhuma entrada ports:, porque o tráfego entre containers permanece na rede Docker e nunca passa por uma porta do host.
De dentro para fora, use o nome do serviço do outro container, por exemplo postgres:5432. Desde a versão v3.41, o Gluetun resolve os nomes de outros containers a partir do seu próprio namespace. Se um nome não for resolvido, fixe essa versão ou uma mais recente.
A firewall do Gluetun determina quem pode abrir uma ligação para ele. O tráfego proveniente da própria rede Docker do gluetun é permitido. Um cliente noutra sub-rede, um portátil na sua LAN ou um container numa rede bridge separada precisa de uma rota de retorno permitida pela firewall e pelo encaminhamento do gluetun:
FIREWALL_OUTBOUND_SUBNETS=192.168.1.0/24O significado documentado é exato: sub-redes separadas por vírgulas às quais o Gluetun e os containers que partilham a sua pilha de rede podem aceder.
As ligações recebidas da Internet são um problema separado. Os peers de um cliente torrent chegam pelo lado da VPN, pelo que publicar a porta 6881 no host não tem qualquer efeito para eles. É necessária uma porta encaminhada pelo fornecedor, e essa porta deve ser indicada em FIREWALL_VPN_INPUT_PORTS, que permite portas do lado do servidor VPN. O Mullvad, usado neste exemplo, não suporta encaminhamento de portas. Portanto, é necessário um fornecedor que o suporte. Esta é a parte que a maioria das pilhas multimédia criadas com Docker Compose deixa sem funcionar.
O kill switch: o que acontece quando o túnel cai
Este padrão justifica a sua complexidade quando ocorre uma falha. O contentor ligado partilha as interfaces e a tabela de encaminhamento do Gluetun. A firewall do Gluetun bloqueia o tráfego normal para a Internet fora do túnel, mas permite o endpoint do servidor VPN, o tráfego local do Docker e as exceções configuradas. É essa firewall que impede o fallback para a interface normal quando o túnel cai. Não existe uma janela em que os pacotes escapem pela interface normal enquanto um cliente volta a ligar-se.
O Gluetun monitoriza a própria ligação. A cada minuto, envia um echo ICMP (um ping) para os endereços em HEALTH_ICMP_TARGET_IPS, que por predefinição são 1.1.1.1,8.8.8.8. Se o ICMP não for permitido, essa verificação curta usa uma consulta DNS UDP em texto simples. A cada cinco minutos, estabelece uma ligação TCP e TLS (transport layer security) completa para HEALTH_TARGET_ADDRESSES, com cloudflare.com:443,github.com:443 como valor predefinido. Quando essas verificações falham, reinicia a VPN dentro do contentor e regista o evento:
WARN [vpn] restarting VPN because it failed to pass the healthcheck: periodic check: dialing: dial tcp4: lookup cloudflare.com: i/o timeoutLeia os logs do contentor ligado tendo essa sequência em conta. Linhas como connection refused, operation not permitted e i/o timeout dentro da aplicação são consequências de um túnel inativo, não as causas. A documentação do Gluetun afirma isto claramente, porque muitas pessoas reportam a consequência e passam horas a investigar o problema errado.
HEALTH_RESTART_VPN=on é o valor predefinido e deve permanecer ativado. Desative-o apenas enquanto investiga uma falha específica, porque, quando está desativado, um túnel inativo continua inativo.
Ordenação: impedir que a stack arranque antes de o túnel estar ativo
A imagem inclui um healthcheck do Docker:
HEALTHCHECK --interval=5s --timeout=5s --start-period=10s --retries=3 CMD /gluetun-entrypoint healthcheckEsse comando executa uma segunda cópia de curta duração do gluetun, que consulta o servidor de estado da instância em execução em http://127.0.0.1:9999/. Um túnel funcional responde 200 OK. Um túnel com problemas responde 500 Internal server error com uma mensagem de erro, e o Docker marca o container como não saudável depois de 3 verificações consecutivas sem sucesso.
condition: service_healthy é o mecanismo que aguarda por essa condição. O depends_on: [gluetun] simples aguarda apenas que o container arranque. Isso acontece vários segundos antes de o handshake terminar, pelo que a aplicação arranca sem rede funcional e frequentemente desiste da primeira tentativa de ligação. Healthchecks no Docker Compose explica a sintaxe e os campos de temporização.
Há uma limitação importante. O Compose avalia essa condição quando inicia a stack. Não para nem reinicia a aplicação mais tarde se o gluetun ficar não saudável. A recuperação automática interna do gluetun trata esse caso. Por isso, reinicia o processo VPN em vez do container.
Verifique se há vazamento de DNS antes de confiar na configuração
O DNS (domain name system) é o vazamento que persiste mesmo em um túnel correto. O Gluetun executa seu próprio resolvedor dentro do namespace e encaminha consultas via DoT (DNS over TLS) para a Cloudflare por padrão: DNS_UPSTREAM_RESOLVER_TYPE=dot e DNS_UPSTREAM_RESOLVERS=cloudflare. Mantenha ambos como estão e suas consultas serão criptografadas e trafegarão pelo túnel.
A configuração que causa falhas ao apontar para um resolvedor local é a DNS_UPSTREAM_PLAIN_ADDRESSES. Usuários recorrem a ela quando um nome não é resolvido e desejam que o roteador ou o resolvedor do provedor responda. A documentação do Gluetun alerta que consultas enviadas a um resolvedor na sua bridge Docker ou na LAN vazam para fora do túnel VPN. Um resolvedor público em texto simples ainda recebe consultas através do túnel, mas o provedor de VPN pode ler e modificar essas consultas. A versão desse mesmo erro no WireGuard é abordada em DNS que para de resolver sobre um túnel WireGuard.
Para testar, defina SHADOWSOCKS=on e SHADOWSOCKS_PASSWORD no gluetun, publique 8388:8388/tcp e 8388:8388/udp, conecte-se com um cliente Shadowsocks configurado para tunelar DNS via UDP e carregue um teste de vazamento de DNS. O resultado deve indicar seu provedor ou a Cloudflare, nunca seu roteador doméstico. A própria documentação do Gluetun avisa que alguns testes de vazamento relatam resultados estranhos, pois o resolvedor dentro do namespace é um intermediário de cache local, e não o servidor que responde finalmente. Considere um país incorreto ou o resolvedor do seu próprio ISP como o sinal real de vazamento.
Adicionar o Tailscale ao lado do sidecar da VPN e determinar qual prevalece
O Tailscale é uma rede sobreposta baseada em WireGuard para aceder às suas próprias máquinas. Muitas pessoas executam-no ao lado de uma VPN de um provedor para manter um caminho de administração para a stack. Partilhar um namespace também significa partilhar as regras de firewall. Por isso, as configurações de firewall e de encaminhamento precisam de ser compatíveis. A documentação do Tailscale define o comportamento padrão: ele funciona como uma rede sobreposta, encaminha tráfego apenas entre dispositivos que executam o Tailscale e não interfere no tráfego público da Internet.
A resposta depende, portanto, de uma configuração.
- Tailscale no seu próprio container, com a configuração padrão: nunca vê o tráfego de saída da aplicação. O Gluetun transporta todo esse tráfego. Um processo no container do Tailscale acede à aplicação em
gluetun:8080através de uma rede Docker partilhada. Para disponibilizar essa ligação a clientes da tailnet, é necessário encaminhamento ou um proxy. - Tailscale ligado ao namespace do gluetun com
network_mode: "service:gluetun": no modo padrão de rede userspace,TS_USERSPACEestá ativado. O tailscaled não cria nenhuma interface e funciona como proxy SOCKS5 ou HTTP, portanto não pode alterar o encaminhamento. O Gluetun continua a transportar o tráfego normal de saída, exceto quando uma aplicação utiliza explicitamente esse proxy. - O mesmo cenário, com
TS_USERSPACE=false: o Tailscale precisa do seu próprio dispositivo/dev/net/tune das respetivas capabilities, porque esses recursos não são fornecidos pelo namespace. O tailscaled cria um dispositivo de túnel e, no Linux, normalmente instala rotas /32 IPv4 individuais para os peers, em vez de uma única rota para100.64.0.0/10. Definir apenasTS_USERSPACE=falsenão ativa a rota agregada. As rotas de sub-rede de outros nós só são instaladas se passar--accept-routesatravés deTS_EXTRA_ARGS.TS_ROUTESfunciona no sentido oposto: anuncia ao resto da sua tailnet as sub-redes que este container consegue alcançar. É o equivalente atailscale set --advertise-routes=e não adiciona rotas neste container. O tráfego público continua a sair através do gluetun. - Rede no kernel no namespace do gluetun, com um exit node selecionado,
sudo tailscale set --exit-node=<exit-node-ip>: o Tailscale instala rotas padrão nesse namespace, mas a firewall do Gluetun pode bloquear esse caminho. Selecionar um exit node num container separado não altera as rotas da aplicação, e o modo userspace transporta apenas o tráfego enviado explicitamente através do proxy. Não combine rotas padrão concorrentes no namespace do gluetun. Deve existir uma rota padrão e um único responsável por ela.
Se o objetivo são essas rotas anunciadas e pretende que toda a rede privada atrás da máquina fique acessível, em vez de apenas a própria máquina, executar um router de sub-rede do Tailscale numa VPS aborda a aprovação da rota, o encaminhamento de IP e a flag do lado do cliente que TS_ROUTES, por si só, não configura.
Se o Tailscale existe para fornecer um URL de administração, e não uma rota, tailscale serve e tailscale funnel colocam HTTPS à frente de um serviço HTTP local. Apenas o funnel o expõe à Internet pública. A documentação do Tailscale Serve suporta apenas http://127.0.0.1 como destino de proxy HTTP. Uma rede Docker partilhada não torna http://gluetun:8080 um destino suportado. Partilhe o namespace de rede do gluetun com network_mode: "service:gluetun" e defina como destino http://127.0.0.1:8080.
Há um efeito secundário visível quando o Tailscale é executado dentro do túnel. Os peers veem o endereço do provedor da VPN, por isso é esperado que o Tailscale recorra a relays com mais frequência. tailscale status mostra relay "..." ao lado de um peer, em vez de direct, quando isso acontece. A ligação funciona, mas fica mais lenta. Se a única necessidade real era a rede sobreposta, a diferença entre WireGuard simples e Tailscale é um ponto de partida melhor.
O que falha e a mensagem que verá
O Docker recusa-se a criar o container da aplicação. Error response from daemon: conflicting options: port publishing and the container type network mode significa que um ports: ainda está presente no serviço anexado. Mova-o para o gluetun.
O Compose recusa o ficheiro inteiro. Um serviço não pode definir simultaneamente network_mode e networks. Coloque as redes no gluetun.
Outro container não consegue resolver a aplicação. curl: (6) Could not resolve host: qbittorrent é o comportamento correto, porque o container anexado não se juntou a nenhuma rede e não registou nenhum nome. Utilize gluetun e a porta.
O segundo container anexado não arranca. Dois processos no mesmo namespace não podem usar a mesma porta, e o que perde reporta que o endereço já está em uso. Altere a porta interna da aplicação ou execute um segundo gluetun.
A aplicação fica sem rede após ter mexido no gluetun. Reiniciar ou recriar o gluetun interrompe a conectividade de tudo o que está ligado a ele. Reinicie esses containers.
Páginas pequenas carregam e as grandes bloqueiam. Isso é MTU (maximum transmission unit). O túnel adiciona overhead e algo no caminho descarta os pacotes grandes sem enviar um erro de volta. Verifique WIREGUARD_MTU, cujo padrão na v3.41.3 é 1320, e reduza-o se o caminho exigir pacotes menores. A imagem de desenvolvimento utiliza a descoberta de MTU do caminho quando esta definição não está configurada.
O gluetun nunca fica saudável. A verificação de arranque nomeia os primeiros suspeitos: WARN [vpn] restarting VPN because it failed to pass the healthcheck: startup check: dialing: dial tcp4: lookup cloudflare.com: i/o timeout. Verifique se a chave expirou, depois se a lista de servidores está desatualizada e, por fim, se a firewall do seu host bloqueia tráfego UDP de saída.
FAQ
Por que as portas publicadas do meu container deixaram de funcionar atrás do Gluetun?
Porque network_mode: "service:gluetun" coloca o container no namespace de rede do gluetun, e um namespace tem um endereço IP e um conjunto de portas de escuta. A aplicação continua a escutar, mas a regra de publicação tem de ficar no container que possui o namespace. Mova a lista ports: para o serviço gluetun. Se a deixou no serviço associado, o Docker nem sequer a cria: Error response from daemon: conflicting options: port publishing and the container type network mode.
Como acedo a um container dentro do túnel VPN a partir de um container fora dele?
Use o nome do serviço do gluetun e a porta em que a aplicação escuta, por exemplo gluetun:8080. O container associado não tem uma rede Docker própria, pelo que o seu próprio nome nunca é resolvido. Não é necessário publicar portas para tráfego entre containers. No sentido inverso, um container dentro do namespace acede a um container externo através do nome do serviço, como postgres:5432, no Gluetun v3.41 e posteriores. Um cliente noutra sub-rede, como um portátil na sua LAN, precisa de uma rota de retorno permitida pela firewall e pelo encaminhamento do gluetun; adicione essa sub-rede a FIREWALL_OUTBOUND_SUBNETS.
O Gluetun funciona como kill switch quando a VPN cai?
Sim, com a firewall ativada. O container associado partilha as interfaces e as rotas do Gluetun, e a firewall bloqueia o tráfego normal para a Internet fora do túnel, permitindo o endpoint do servidor VPN, o tráfego Docker local e as exceções configuradas. O Gluetun reinicia então a VPN internamente e regista WARN [vpn] restarting VPN because it failed to pass the healthcheck, em vez de terminar, porque todos os containers associados perdem a rede quando o próprio gluetun reinicia.
Tailscale e Gluetun na mesma stack: qual deles transporta o tráfego de saída?
O Gluetun transporta o tráfego normal de saída, exceto se o encaminhar explicitamente através do Tailscale. Por predefinição, o Tailscale encaminha apenas o tráfego entre dispositivos da sua tailnet e não altera o tráfego público. No modo userspace predefinido da imagem do container, não cria qualquer interface, pelo que não pode afetar o encaminhamento. Com TS_USERSPACE=false, o Linux normalmente obtém rotas /32 IPv4 individuais para os peers, em vez de uma rota agregada 100.64.0.0/10, além de rotas para as sub-redes de outros nós apenas se adicionar --accept-routes através de TS_EXTRA_ARGS. TS_ROUTES anuncia as sub-redes deste container à sua tailnet e não adiciona rotas locais. Selecionar um exit node com sudo tailscale set --exit-node=<exit-node-ip> instala rotas predefinidas apenas no namespace que utiliza a rede kernel do Tailscale; um container separado não altera as rotas da aplicação, e o modo userspace só transporta o tráfego enviado através do seu proxy. Escolha um produto para gerir a rota predefinida, em vez de combinar os dois.