Configuração de Proxy em Contêineres Docker: Guia Completo com Exemplos de Código

Contêineres Docker frequentemente requerem acesso a recursos externos através de proxies — para scraping, testes de diferentes regiões ou para contornar restrições. Uma configuração incorreta do proxy leva a erros de conexão, vazamentos de IP real e falhas no funcionamento de aplicativos. Neste artigo, vamos explorar todas as maneiras de configurar proxies no Docker: desde variáveis de ambiente simples até cenários avançados com docker-compose e redes personalizadas.

Por que usar proxies em contêineres Docker

Contêineres Docker são usados em vários cenários onde proxies se tornam uma necessidade. Vamos considerar as principais tarefas que os proxies resolvem em aplicativos containerizados.

Scraping e coleta de dados: Se você está executando scrapers em contêineres Docker para coletar dados de marketplaces (Wildberries, Ozon), redes sociais ou motores de busca, proxies protegem contra bloqueios por IP. Os contêineres permitem escalar o scraping — iniciar de 10 a 50 instâncias simultaneamente, cada uma com seu próprio proxy.

Testes de diferentes regiões: Ao desenvolver aplicativos web ou APIs móveis, muitas vezes é necessário verificar como o serviço funciona de diferentes países. Contêineres Docker com proxies de diferentes geolocalizações permitem automatizar esses testes em um pipeline CI/CD.

Automação e bots: Contêineres com Selenium, Puppeteer ou Playwright para automação de navegadores requerem proxies para trabalhar com várias contas. Cada contêiner recebe seu próprio proxy e um ambiente isolado.

Contornando restrições corporativas: Em algumas infraestruturas, contêineres Docker devem passar por um proxy corporativo para acessar a internet. Sem a configuração correta, os contêineres não conseguirão baixar pacotes ou acessar APIs externas.

Configuração básica através de variáveis de ambiente

A maneira mais simples de configurar um proxy em um contêiner Docker é passar variáveis de ambiente ao iniciar. Este método funciona para a maioria dos aplicativos que respeitam as variáveis padrão HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

Executando o contêiner com proxy através do docker run:

docker run -d \
  -e HTTP_PROXY="http://username:password@proxy.example.com:8080" \
  -e HTTPS_PROXY="http://username:password@proxy.example.com:8080" \
  -e NO_PROXY="localhost,127.0.0.1,.local" \
  your-image:latest

Explicação dos parâmetros:

• HTTP_PROXY — proxy para requisições HTTP
• HTTPS_PROXY — proxy para requisições HTTPS (use http://, não https://)
• NO_PROXY — lista de endereços que não devem passar pelo proxy

Exemplo com proxy SOCKS5:

docker run -d \
  -e HTTP_PROXY="socks5://username:password@proxy.example.com:1080" \
  -e HTTPS_PROXY="socks5://username:password@proxy.example.com:1080" \
  your-image:latest

Configurando proxy para o daemon do Docker (afeta todos os contêineres):

Se você precisa que todos os contêineres usem proxy por padrão, configure o daemon do Docker. Crie um arquivo /etc/systemd/system/docker.service.d/http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=http://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.local"

Após as alterações, reinicie o Docker:

sudo systemctl daemon-reload
sudo systemctl restart docker

Configuração de proxy no Dockerfile

Quando você constrói uma imagem Docker que precisa baixar pacotes através de um proxy (por exemplo, apt-get, pip, npm), é necessário configurar o proxy na etapa de construção. O Docker suporta argumentos de tempo de construção para isso.

Exemplo de Dockerfile com suporte a proxy:

FROM python:3.11-slim

# Argumentos para proxy (passados durante a construção)
ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

# Configurando variáveis de ambiente para a construção
ENV HTTP_PROXY=${HTTP_PROXY}
ENV HTTPS_PROXY=${HTTPS_PROXY}
ENV NO_PROXY=${NO_PROXY}

# Instalando dependências através do proxy
RUN apt-get update && apt-get install -y curl

# Instalando pacotes Python
COPY requirements.txt .
RUN pip install --proxy ${HTTP_PROXY} -r requirements.txt

# Copiando o aplicativo
COPY . /app
WORKDIR /app

# Removendo variáveis de proxy para runtime (opcional)
ENV HTTP_PROXY=
ENV HTTPS_PROXY=

CMD ["python", "app.py"]

Construindo a imagem passando o proxy:

docker build \
  --build-arg HTTP_PROXY=http://proxy.example.com:8080 \
  --build-arg HTTPS_PROXY=http://proxy.example.com:8080 \
  --build-arg NO_PROXY=localhost,127.0.0.1 \
  -t my-app:latest .

Para aplicativos Node.js (npm através de proxy):

FROM node:18-alpine

ARG HTTP_PROXY
ARG HTTPS_PROXY

# Configurando npm para trabalhar através do proxy
RUN npm config set proxy ${HTTP_PROXY}
RUN npm config set https-proxy ${HTTPS_PROXY}

COPY package*.json ./
RUN npm install

# Limpando configurações de proxy para npm
RUN npm config delete proxy
RUN npm config delete https-proxy

COPY . .
CMD ["node", "server.js"]

Configuração de proxy no docker-compose.yml

O Docker Compose simplifica o gerenciamento de proxies para aplicativos de múltiplos contêineres. Você pode configurar proxies globalmente ou para serviços específicos.

Configuração básica com proxy para um serviço:

version: '3.8'

services:
  parser:
    image: python:3.11-slim
    environment:
      - HTTP_PROXY=http://username:password@proxy.example.com:8080
      - HTTPS_PROXY=http://username:password@proxy.example.com:8080
      - NO_PROXY=localhost,127.0.0.1,db
    volumes:
      - ./app:/app
    working_dir: /app
    command: python parser.py
    
  db:
    image: postgres:15
    # O banco de dados não usa proxy
    environment:
      - POSTGRES_PASSWORD=secret

Usando arquivo .env para armazenamento seguro de credenciais:

Crie um arquivo .env no diretório com docker-compose.yml:

PROXY_URL=http://username:password@proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Referencie as variáveis no docker-compose.yml:

version: '3.8'

services:
  parser:
    image: python:3.11-slim
    environment:
      - HTTP_PROXY=${PROXY_URL}
      - HTTPS_PROXY=${PROXY_URL}
      - NO_PROXY=${NO_PROXY}
    volumes:
      - ./app:/app
    working_dir: /app
    command: python parser.py

Configuração de proxy para construção da imagem no docker-compose:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - HTTP_PROXY=${PROXY_URL}
        - HTTPS_PROXY=${PROXY_URL}
        - NO_PROXY=${NO_PROXY}
    environment:
      - HTTP_PROXY=${PROXY_URL}
      - HTTPS_PROXY=${PROXY_URL}
    ports:
      - "3000:3000"

Escalonamento com diferentes proxies para cada instância:

Se você precisa executar vários scrapers, cada um com seu próprio proxy, use serviços separados:

version: '3.8'

services:
  parser-1:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy1.example.com:8080
    volumes:
      - ./data:/data
    
  parser-2:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy2.example.com:8080
    volumes:
      - ./data:/data
    
  parser-3:
    image: my-parser:latest
    environment:
      - PROXY_URL=http://user:pass@proxy3.example.com:8080
    volumes:
      - ./data:/data

Configuração de proxy no nível da aplicação

Alguns aplicativos não suportam as variáveis de ambiente padrão HTTP_PROXY. Nesses casos, é necessário configurar o proxy no código do aplicativo ou em arquivos de configuração.

Python (biblioteca requests):

import os
import requests

# Obtendo o proxy da variável de ambiente
proxy_url = os.getenv('PROXY_URL', 'http://proxy.example.com:8080')

proxies = {
    'http': proxy_url,
    'https': proxy_url
}

# Usando o proxy nas requisições
response = requests.get('https://api.example.com/data', proxies=proxies)
print(response.json())

# Para proxy SOCKS5, instale pip install requests[socks]
# proxies = {
#     'http': 'socks5://user:pass@proxy.example.com:1080',
#     'https': 'socks5://user:pass@proxy.example.com:1080'
# }

Python (aiohttp para requisições assíncronas):

import os
import aiohttp
import asyncio

async def fetch_with_proxy():
    proxy_url = os.getenv('PROXY_URL')
    
    async with aiohttp.ClientSession() as session:
        async with session.get(
            'https://api.example.com/data',
            proxy=proxy_url
        ) as response:
            data = await response.json()
            print(data)

asyncio.run(fetch_with_proxy())

Node.js (biblioteca axios):

const axios = require('axios');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyUrl = process.env.PROXY_URL || 'http://proxy.example.com:8080';
const agent = new HttpsProxyAgent(proxyUrl);

axios.get('https://api.example.com/data', {
  httpsAgent: agent
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Erro:', error.message);
});

Node.js (módulo https embutido):

const https = require('https');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyUrl = process.env.PROXY_URL;
const agent = new HttpsProxyAgent(proxyUrl);

const options = {
  hostname: 'api.example.com',
  port: 443,
  path: '/data',
  method: 'GET',
  agent: agent
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => data += chunk);
  res.on('end', () => console.log(JSON.parse(data)));
});

req.on('error', (error) => console.error(error));
req.end();

Selenium com proxy em contêiner Docker:

from selenium import webdriver
from selenium.webdriver.common.proxy import Proxy, ProxyType
import os

proxy_url = os.getenv('PROXY_URL', 'proxy.example.com:8080')

# Configurando o proxy para o Chrome
chrome_options = webdriver.ChromeOptions()
chrome_options.add_argument(f'--proxy-server={proxy_url}')

# Para autenticação, use uma extensão ou túnel SSH
driver = webdriver.Chrome(options=chrome_options)
driver.get('https://example.com')
print(driver.title)
driver.quit()

Puppeteer com proxy:

const puppeteer = require('puppeteer');

(async () => {
  const proxyUrl = process.env.PROXY_URL || 'proxy.example.com:8080';
  
  const browser = await puppeteer.launch({
    args: [`--proxy-server=${proxyUrl}`],
    headless: true
  });
  
  const page = await browser.newPage();
  
  // Autenticação para o proxy
  await page.authenticate({
    username: 'your-username',
    password: 'your-password'
  });
  
  await page.goto('https://example.com');
  console.log(await page.title());
  
  await browser.close();
})();

Qual tipo de proxy escolher para Docker

A escolha do tipo de proxy depende da tarefa que seu aplicativo está resolvendo no contêiner Docker. Vamos discutir os principais cenários e recomendações.

Recomendações para escolha para tarefas específicas:

Scraping de marketplaces e catálogos de produtos: Se você está fazendo scraping de Wildberries, Ozon ou outros marketplaces através de contêineres Docker, use proxies residenciais. Essas plataformas bloqueiam ativamente IPs de datacenter. Configure a rotação de proxies a cada 5-10 minutos para simular diferentes usuários.

Testes de API e desenvolvimento: Para testar suas próprias APIs ou integrações com serviços externos, proxies de datacenter são adequados. Eles oferecem alta velocidade e estabilidade de conexão, o que é importante para testes automatizados em CI/CD.

Automação com Selenium/Puppeteer: Ao executar automação de navegador em contêineres para trabalhar com sites seguros (redes sociais, bancos, aplicativos web complexos), escolha proxies residenciais. Eles reduzem a probabilidade de captchas e bloqueios.

Testes geograficamente distribuídos: Se você precisa verificar a disponibilidade do serviço de diferentes países, use proxies residenciais com seleção de geolocalização específica. Execute vários contêineres Docker, cada um com um proxy de seu país.

Solução de problemas comuns

Ao trabalhar com proxies em contêineres Docker, surgem problemas típicos. Vamos discutir os mais comuns e como resolvê-los.

Problema 1: O contêiner não consegue se conectar ao proxy

Sintomas: Erros "Connection refused", "Proxy connection failed", timeouts ao iniciar o contêiner.

Soluções:

• Verifique a acessibilidade do proxy a partir do host: curl -x http://proxy:port https://example.com
• Certifique-se de que o servidor proxy está acessível a partir da rede Docker. Se o proxy estiver em localhost do host, use host.docker.internal (Mac/Windows) ou o IP do host na rede bridge
• Verifique as regras do firewall — contêineres Docker podem estar bloqueados para conexões de saída
• Para proxies com autenticação, verifique a correção do username e password, escape caracteres especiais na URL

Exemplo de acesso ao proxy no host:

# Mac/Windows
docker run -e HTTP_PROXY=http://host.docker.internal:8080 my-image

# Linux (descubra o IP do host na rede bridge)
ip addr show docker0  # Normalmente 172.17.0.1
docker run -e HTTP_PROXY=http://172.17.0.1:8080 my-image

Problema 2: DNS não resolve através do proxy

Sintomas: Erros "Could not resolve host", requisições DNS não passam pelo proxy.

Soluções:

• Use um proxy SOCKS5 em vez de HTTP — SOCKS5 proxy também requisições DNS
• Configure DNS no Docker: adicione --dns 8.8.8.8 ao iniciar o contêiner
• Para aplicativos que não suportam DNS através do proxy, use proxychains dentro do contêiner

# Dockerfile com proxychains
FROM python:3.11-slim

RUN apt-get update && apt-get install -y proxychains4

# Configuração do proxychains
RUN echo "strict_chain\nproxy_dns\n[ProxyList]\nsocks5 proxy.example.com 1080" > /etc/proxychains4.conf

# Executando o aplicativo através do proxychains
CMD ["proxychains4", "python", "app.py"]

Problema 3: Vazamento do IP real do contêiner

Sintomas: O serviço alvo vê o IP do host ou do contêiner em vez do IP do proxy.

Soluções:

• Verifique se o aplicativo realmente está usando o proxy — faça uma requisição para https://api.ipify.org
• Certifique-se de que todos os clientes HTTP no código estão configurados para usar o proxy
• Para conexões WebRTC e WebSocket, o proxy pode não funcionar — desative WebRTC nos navegadores
• Verifique os cabeçalhos das requisições — algumas bibliotecas adicionam X-Forwarded-For com o IP real

Teste de vazamento de IP no contêiner:

# Sem proxy
docker run --rm curlimages/curl:latest curl https://api.ipify.org

# Com proxy
docker run --rm \
  -e HTTPS_PROXY=http://proxy.example.com:8080 \
  curlimages/curl:latest curl https://api.ipify.org

Problema 4: Funcionamento lento através do proxy

Sintomas: Altas latências, timeouts, carregamento lento de dados.

Soluções:

• Verifique a velocidade do proxy diretamente a partir do host — pode haver um problema no próprio proxy
• Aumente os timeouts no aplicativo para trabalhar com proxies lentos
• Use conexões keep-alive para reutilizar conexões TCP
• Para proxies residenciais, uma velocidade lenta é normal, otimize a quantidade de requisições
• Configure um pool de conexões nos clientes HTTP para requisições paralelas

Problema 5: O proxy funciona para HTTP, mas não para HTTPS

Sintomas: Requisições HTTP passam, HTTPS retornam erros SSL/TLS.

Soluções:

• Certifique-se de que a variável HTTPS_PROXY está definida (não apenas HTTP_PROXY)
• Use http:// na URL do proxy para HTTPS_PROXY, não https://
• Verifique se o proxy suporta o método CONNECT para tunelamento HTTPS
• Para proxies com certificados autoassinados, desative a verificação SSL (apenas para testes!)

Segurança e gerenciamento de credenciais

Armazenar credenciais de proxy em contêineres Docker requer atenção especial à segurança. Um gerenciamento inadequado de senhas pode levar ao vazamento delas em logs, imagens ou repositórios.

Use Docker Secrets para produção:

O Docker Swarm suporta um mecanismo de secrets para armazenamento seguro de senhas. Crie um secret:

echo "http://username:password@proxy.example.com:8080" | docker secret create proxy_url -

Use no docker-compose para Swarm:

version: '3.8'

services:
  app:
    image: my-app:latest
    secrets:
      - proxy_url
    environment:
      - PROXY_URL_FILE=/run/secrets/proxy_url
    command: sh -c 'export HTTP_PROXY=$(cat $$PROXY_URL_FILE) && python app.py'

secrets:
  proxy_url:
    external: true

Variáveis de ambiente através de arquivos (.env):

Para desenvolvimento, use arquivos .env, mas NUNCA os comite no Git. Adicione ao .gitignore:

# .gitignore
.env
.env.local
*.env

Crie .env.example sem credenciais reais:

# .env.example
PROXY_URL=http://username:password@proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1

Evite hardcoding de credenciais em imagens:

# ❌ RUIM - a senha permanecerá na imagem
FROM python:3.11
ENV HTTP_PROXY=http://user:secretpass@proxy.com:8080
COPY . /app

# ✅ BOM - passe através de argumentos de construção ou variáveis de runtime
FROM python:3.11
ARG HTTP_PROXY
# Usado apenas durante a construção, não é salvo na imagem final

Use builds de múltiplas etapas para limpar credenciais:

# Etapa de construção com proxy
FROM python:3.11 AS builder
ARG HTTP_PROXY
ENV HTTP_PROXY=${HTTP_PROXY}
COPY requirements.txt .
RUN pip install -r requirements.txt

# Etapa final sem variáveis de proxy
FROM python:3.11-slim
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY . /app
WORKDIR /app
CMD ["python", "app.py"]

Rotação de credenciais de proxy:

Se o seu provedor de proxy suporta API para geração de credenciais temporárias, use-as em vez de senhas estáticas. Crie um script init no contêiner:

#!/bin/bash
# entrypoint.sh

# Obtendo credenciais temporárias da API
PROXY_CREDS=$(curl -s https://api.proxyservice.com/generate-temp-auth)
export HTTP_PROXY="http://${PROXY_CREDS}@proxy.example.com:8080"

# Executando o aplicativo
exec python app.py

Registro sem vazamento de senhas:

Configure o registro para que variáveis com proxy não apareçam na saída:

import os
import re

def safe_log_env():
    """Registro de variáveis de ambiente sem senhas"""
    for key, value in os.environ.items():
        if 'PROXY' in key:
            # Mascarando a senha na URL
            safe_value = re.sub(r'://([^:]+):([^@]+)@', r'://\1:****@', value)
            print(f"{key}={safe_value}")
        else:
            print(f"{key}={value}")

safe_log_env()

Conclusão

Configurar proxies em contêineres Docker é uma habilidade importante para desenvolvedores que trabalham com scraping, automação e sistemas distribuídos. Você aprendeu como configurar proxies através de variáveis de ambiente, Dockerfile e docker-compose, como integrar proxies no código de aplicativos em Python e Node.js, e como resolver problemas típicos de conexão e segurança.

Pontos-chave para um trabalho bem-sucedido com proxies no Docker: use variáveis de ambiente para flexibilidade, armazene credenciais de forma segura através de secrets ou arquivos .env, escolha o tipo de proxy dependendo da tarefa, e sempre teste a ausência de vazamentos de IP real antes de implantar em produção.

Para a maioria das tarefas de scraping e automação em contêineres Docker, recomendamos o uso de proxies residenciais — eles oferecem alta anonimidade e risco mínimo de bloqueios ao trabalhar com sites seguros e APIs. Se você precisar da máxima velocidade para testes de API ou tarefas internas, considere proxies de datacenter.