Introdução: por que os gerenciadores de pacotes precisam de configurações próprias de proxy

Você provavelmente já passou por isso: as variáveis http_proxy e https_proxy estão exportadas no terminal, o curl baixa páginas numa boa, mas o npm install trava por um minuto e cai com erro ETIMEDOUT. Ou o apt update tenta silenciosamente acessar o espelho diretamente, como se nenhum proxy existisse. Ou o Docker na hora de buildar uma imagem não consegue puxar a camada base, mesmo que o docker pull funcione a partir do mesmo console. Isso não é bug nem misticismo. Simplesmente cada ferramenta tem sua própria forma de ler as configurações de rede, e as variáveis de ambiente cobrem isso apenas parcialmente.

Este guia é dedicado justamente aos arquivos de configuração próprios de cinco ferramentas das quais nenhum desenvolvedor escapa: npm (arquivo .npmrc), pip (pip.conf ou pip.ini), apt (diretório apt.conf.d), Docker (daemon.json e config.json) e git (git config). Deliberadamente não repetimos aqui o conteúdo sobre variáveis de ambiente no terminal e em CI. A tarefa aqui é outra: mostrar como definir o proxy de forma que ele seja aplicado sempre, independentemente de quem executou o comando e de onde.

No final, você terá cinco configurações funcionais que pode copiar para qualquer máquina, entenderá onde cada ferramenta busca suas configurações e terá um conjunto de comandos para verificar tudo. Além disso, saberá como reverter tudo rapidamente.

Para quem é este guia

  • Para desenvolvedores cujo notebook ou servidor de trabalho está atrás de um proxy corporativo ou doméstico.
  • Para testadores e especialistas em automação que precisam que os builds passem por um endereço de proxy dedicado.
  • Para administradores que configuram imagens padrão de estações de trabalho.
  • Para todos que usam um proxy alugado (inclusive móvel) para desenvolvimento e querem que apenas uma ferramenta específica o utilize, em vez do sistema inteiro.

O que é preciso saber de antemão

Bastam habilidades básicas de terminal: abrir o console, entrar em um diretório, editar um arquivo de texto. Vamos usar o editor nano no Linux e o Bloco de Notas no Windows, mas qualquer um serve. Entender o que é um endereço IP e uma porta também ajuda, embora vamos relembrar o básico na seção de conceitos.

Quanto tempo vai levar

Se você configurar as cinco ferramentas em sequência, reserve de 60 a 90 minutos. Cada ferramenta individual leva de 10 a 15 minutos, incluindo a verificação. A etapa mais longa é o Docker, porque lá existem dois níveis de configuração e é necessário reiniciar o serviço.

Preparação inicial

Antes de editar as configurações, vamos reunir tudo o que é necessário. Pular esta etapa é a principal razão pela qual depois a pessoa fica horas tentando adivinhar onde está o erro.

Dados necessários sobre o proxy

Você precisa de quatro parâmetros. Anote-os em um arquivo de texto para não ter que procurar nas mensagens:

  • Tipo de proxy: HTTP ou HTTPS (às vezes SOCKS5, mas a maioria dos gerenciadores de pacotes espera um proxy HTTP).
  • Endereço: nome de domínio ou IP, por exemplo proxy.corp.local ou 10.20.30.40.
  • Porta: geralmente 3128, 8080 ou 8888.
  • Login e senha, se o proxy exigir autenticação. Fique atento aos caracteres especiais na senha: eles precisarão de codificação, como explicamos abaixo.

Requisitos de sistema e versões

As instruções foram testadas nas versões atuais de 2026 e servem para:

  • Ubuntu 22.04 e 24.04, Debian 12 e 13 (para apt).
  • Node.js 20 e 22 com npm 10 e 11.
  • Python 3.10 ou superior com pip 24 ou superior.
  • Docker Engine 25 ou superior (a chave proxies no daemon.json surgiu na versão 23; em versões mais antigas use o systemd drop-in, mostraremos as duas formas).
  • Git 2.40 ou superior.

Se você usa Windows, todos os comandos para npm, pip e git funcionam no PowerShell sem alterações, mudam apenas os caminhos dos arquivos. Para o Docker Desktop, as configurações de proxy são feitas pela interface gráfica, e também vamos abordar isso.

Permissões de acesso

Para npm, pip e git bastam permissões de usuário comum: suas configurações ficam no diretório pessoal. Para apt e Docker será necessário sudo, porque os arquivos ficam em /etc e alteram o comportamento de serviços do sistema.

Backups

Antes de começar, copie as configurações existentes. Um comando para cada arquivo, e você sempre poderá voltar ao estado original:

cp ~/.npmrc ~/.npmrc.bak 2>/dev/null; cp ~/.config/pip/pip.conf ~/pip.conf.bak 2>/dev/null; cp ~/.gitconfig ~/.gitconfig.bak 2>/dev/null; sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null; sudo cp -r /etc/apt/apt.conf.d /etc/apt/apt.conf.d.bak 2>/dev/null

O final 2>/dev/null serve para o comando não reclamar caso o arquivo ainda não exista. Isso é normal: muitos usuários não têm .npmrc nem pip.conf inicialmente.

Dica: crie uma pasta proxy-configs no diretório pessoal e mantenha ali as versões de referência das cinco configurações. Migrar para uma nova máquina vira uma simples cópia de cinco arquivos.

Conceitos básicos: por que as variáveis de ambiente não bastam

Vamos entender o que acontece por baixo dos panos, senão os próximos passos parecerão um conjunto de feitiços mágicos.

O que é proxy no contexto de um gerenciador de pacotes

Servidor proxy é um intermediário. Em vez de se conectar diretamente a registry.npmjs.org, seu npm se conecta ao proxy e pede que ele vá até registry.npmjs.org. Para recursos HTTPS, usa-se o método CONNECT: o proxy estabelece um túnel, e o tráfego criptografado passa por ele sem ser descriptografado. Para o gerenciador de pacotes, é importante saber o endereço do proxy, a porta e, se necessário, as credenciais.

Como as ferramentas descobrem o proxy

Existem três camadas de configuração, que formam uma cadeia de prioridades:

  1. Flags de linha de comando: por exemplo, pip install --proxy. Valem para uma única execução.
  2. Configuração própria da ferramenta: .npmrc, pip.conf e outros. Valem sempre para aquela ferramenta.
  3. Variáveis de ambiente: http_proxy, https_proxy, no_proxy. Valem para todos os programas da sessão atual que as leiam.

A palavra-chave é que as leiam. E é aí que os problemas começam.

Quatro razões pelas quais as variáveis de ambiente não são suficientes

Primeira razão: troca de usuário. Quando você digita sudo apt update, o comando é executado como root, e o sudo por padrão limpa o ambiente (opção env_reset). Suas variáveis http_proxy permanecem com o usuário comum. Além disso, o próprio apt baixa arquivos sob o usuário de serviço _apt, que não tem sua sessão.

Segunda razão: daemons e serviços. O Docker Engine é um serviço em background iniciado pelo systemd na inicialização do sistema. Ele nunca viu seu terminal. O comando docker pull apenas envia uma requisição ao daemon, e é o daemon que baixa a imagem. Por isso, as variáveis no seu console não afetam o docker pull de forma alguma.

Terceira razão: interpretações diferentes. Alguns programas leem só http_proxy em minúsculas, outros só HTTP_PROXY, outros ambos. Versões antigas do npm ignoravam no_proxy. Algumas ferramentas não entendem credenciais na variável. A configuração própria elimina o chute.

Quarta razão: granularidade. Uma variável de ambiente ou existe, ou não existe. Mas você pode precisar enviar pelo proxy apenas github.com, e não o GitLab interno. Ou acessar o PyPI público pelo proxy, e o índice interno diretamente. Só as configurações sabem fazer essas regras: o git suporta configuração de proxy por URL específica, o apt por host específico, o Docker por lista de exceções no nível do daemon.

Codificação de caracteres especiais na senha

Login e senha nas configurações são passados dentro de URLs no formato http://user:password@host:port. Os caracteres @, :, /, #, ?, % e espaço dentro da senha quebram a interpretação do endereço. Eles precisam ser substituídos por códigos percentuais: @ vira %40, : vira %3A, # vira %23, / vira %2F, % vira %25, espaço vira %20. Por exemplo, a senha p@ss:1 na configuração fica p%40ss%3A1. Guarde bem essa regra, ela vai salvar você nas cinco ferramentas.

Passo 1: Verificando o proxy e preparando a linha de referência

Objetivo da etapa: confirmar que o proxy realmente funciona e obter uma linha de conexão testada, que vamos inserir em todas as configurações.

  1. Abra o terminal. No Linux é Ctrl+Alt+T; no Windows, o PowerShell pelo menu Iniciar.
  2. Monte a linha de conexão no formato http://LOGIN:SENHA@ENDEREÇO:PORTA. Sem autenticação, apenas http://ENDEREÇO:PORTA. Exemplo: http://dev:s3cret@10.20.30.40:3128.
  3. Execute uma requisição de teste com curl, especificando o proxy explicitamente com a flag -x, para não depender das variáveis:
    curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/
  4. Aguarde a resposta. Ela deve começar com a linha HTTP/2 200 ou HTTP/1.1 200 OK. Se aparecer 407 Proxy Authentication Required, o login ou a senha estão errados. Se aparecer Could not resolve proxy, há erro de digitação no endereço. Se aparecer connection refused, a porta está errada ou o proxy está desligado.
  5. Repita o teste para os outros destinos: https://pypi.org/simple/, https://deb.debian.org/, https://registry-1.docker.io/v2/, https://github.com/. Para o Docker, uma resposta 401 é normal: significa que você chegou ao registro e ele está pedindo o token.
  6. Anote a linha final no seu arquivo de texto. Essa é a sua linha de referência do proxy.

Atenção: se a senha contiver caracteres especiais, codifique-os exatamente nesta etapa e teste a versão codificada com curl. Assim, em todas as configurações seguintes você vai inserir uma linha já comprovadamente funcional.

Dica: se o provedor lhe der não um único proxy, mas um pool de endereços ou um proxy móvel com rotação de IP, normalmente existe um ponto de entrada único: um host e uma porta, atrás dos quais os IPs mudam automaticamente. Coloque nas configurações justamente esse ponto de entrada, e não IPs específicos do pool, senão as configurações ficarão desatualizadas na primeira rotação.

Verificação: o curl com a flag -x retorna código 200 (ou 401 para o Docker Hub) nos cinco endereços. Se ao menos um não responder, não avance: configurações não consertam um proxy que não funciona.

Passo 2: Configurando o npm através do arquivo .npmrc

Objetivo da etapa: fazer npm install, npm view e npm publish funcionarem através do proxy em qualquer projeto e qualquer console, inclusive ambientes de desenvolvimento que executam o npm por conta própria.

Onde fica a configuração do npm

O npm lê as configurações de vários arquivos, em ordem crescente de prioridade: valores internos, arquivo global no diretório de instalação do npm, o usuário ~/.npmrc (no Windows, C:\Users\NOME\.npmrc) e o .npmrc do projeto na raiz do projeto, ao lado do package.json. Para proxy, quase sempre se usa o arquivo do usuário: ele se aplica a todos os projetos, mas não entra no repositório.

Configuração passo a passo

  1. Defina o proxy para tráfego HTTP comum:
    npm config set proxy http://dev:s3cret@10.20.30.40:3128
  2. Defina o proxy para tráfego HTTPS (o registro npm funciona por HTTPS, então esta é a configuração principal):
    npm config set https-proxy http://dev:s3cret@10.20.30.40:3128
    Atenção: o valor começa com http://, e não https://. Esse é o endereço do próprio proxy, e ele geralmente aceita conexões por HTTP comum, mesmo ao tunelar HTTPS.
  3. Se você tem um registro interno ou espelho que precisa ser acessado diretamente, adicione exceções separadas por vírgula:
    npm config set noproxy localhost,127.0.0.1,.corp.local
    O ponto antes do domínio significa todos os subdomínios.
  4. Abra o arquivo e confirme que as linhas foram gravadas:
    cat ~/.npmrc
    No Windows: type $env:USERPROFILE\.npmrc. Você deve ver três linhas no formato chave=valor.
  5. Se o proxy corporativo substituir certificados, adicione o certificado raiz da empresa:
    npm config set cafile /etc/ssl/certs/corp-root.pem
    Não desative a verificação de certificados com strict-ssl=false sem extrema necessidade: isso abre caminho para substituição de pacotes.

Caminho alternativo: criar o arquivo manualmente. O conteúdo de ~/.npmrc será assim:

proxy=http://dev:s3cret@10.20.30.40:3128 https-proxy=http://dev:s3cret@10.20.30.40:3128 noproxy=localhost,127.0.0.1,.corp.local

Cada par deve ficar em sua própria linha. Sem aspas e sem espaços em volta do sinal de igual.

E o yarn e o pnpm?

O Yarn Classic (1.x) lê o mesmo ~/.npmrc e ainda o seu próprio ~/.yarnrc com as chaves proxy e https-proxy. O Yarn Berry (2+) armazena as configurações em .yarnrc.yml: chaves httpProxy e httpsProxy. O pnpm é totalmente compatível com .npmrc, não é preciso fazer nada adicional. Vale lembrar que npm ci e IDEs corporativas executam o npm com o mesmo usuário, então o .npmrc do usuário cobre esses casos também.

Dica: o comando npm config list --json mostra a configuração final considerando todos os arquivos. Se você vir proxy=null, o arquivo não foi lido: confira se ele está no diretório pessoal exatamente do usuário com o qual você executa o npm.

Verificação: execute npm view lodash version. Em 1 a 3 segundos deve retornar uma linha com o número da versão. Para deixar mais claro, remova temporariamente as variáveis de ambiente (unset http_proxy https_proxy) e repita: o npm ainda deve funcionar, porque lê o .npmrc.

Possíveis problemas

  • ETIMEDOUT ou ECONNRESET: endereço ou porta do proxy errados, ou o proxy bloqueia CONNECT na porta 443. Verifique a linha de referência com curl.
  • 407 Proxy Authentication Required: erro no login ou senha, geralmente um caractere especial não codificado.
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY: o proxy substitui o certificado, é preciso cafile com o certificado raiz corporativo.

Passo 3: Configurando o pip através do pip.conf

Objetivo da etapa: fazer pip install e pip download funcionarem através do proxy, inclusive dentro de ambientes virtuais e ao executar a partir de scripts Python.

Onde encontrar o pip.conf

O pip usa três níveis de arquivos: global (para todo o sistema), do usuário e do ambiente virtual. Os caminhos dependem do sistema:

  • Linux, usuário: ~/.config/pip/pip.conf (a variante antiga ~/.pip/pip.conf também é lida).
  • Linux, global: /etc/pip.conf.
  • macOS, usuário: ~/Library/Application Support/pip/pip.conf, e se essa pasta não existir - ~/.config/pip/pip.conf.
  • Windows, usuário: %APPDATA%\pip\pip.ini, ou seja, C:\Users\NOME\AppData\Roaming\pip\pip.ini.
  • Dentro de um ambiente virtual: o arquivo pip.conf (ou pip.ini) direto na raiz do diretório da venv.

Para não ficar adivinhando, pergunte ao próprio pip: o comando pip config debug exibe todos os caminhos que ele verifica e marca os arquivos existentes.

Configuração passo a passo

  1. Confirme que o pip está atualizado: pip --version. Deve ser a versão 24 ou superior.
  2. Defina o proxy com um único comando, o pip criará o arquivo no lugar certo:
    pip config set global.proxy http://dev:s3cret@10.20.30.40:3128
    Aqui global significa a seção [global] do arquivo, e não o nível do sistema. O arquivo criado é o do usuário.
  3. Se o proxy substituir certificados, indique o certificado raiz:
    pip config set global.cert /etc/ssl/certs/corp-root.pem
  4. Veja o resultado:
    pip config list
    Saída esperada: global.proxy='http://dev:s3cret@10.20.30.40:3128'.
  5. Abra o arquivo e verifique o formato. Ele deve ficar assim:
    [global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
    Cada linha separada, a seção entre colchetes no topo.

Uma diferença importante do pip em relação ao npm: o pip não tem configuração separada para proxy HTTPS. Uma única chave proxy é usada para todas as conexões. E o pip não tem equivalente direto ao noproxy na configuração: ele só pega exceções da variável de ambiente no_proxy. Se você precisa acessar um índice interno diretamente, é mais simples indicar um index-url separado para ele e executar o pip com a flag --proxy vazia para esse caso, ou usar um pip.conf de projeto dentro da venv sem a linha proxy.

Dica: se você tem vários projetos e em um precisa de proxy e em outro não, coloque o pip.conf na raiz do ambiente virtual correspondente. As configurações da venv têm prioridade sobre as do usuário, e você terá comportamentos diferentes sem alternar arquivos globais.

Atenção: não adicione trusted-host = pypi.org para silenciar erros de certificado. Isso desativa a verificação de autenticidade e permite que qualquer intermediário injete um pacote falso. A solução correta é a chave cert com o certificado corporativo.

Verificação: execute pip download requests --no-deps -d /tmp/piptest. Em alguns segundos vai aparecer o arquivo requests-*.whl no diretório. Depois remova o diretório de teste. Se quiser confirmar que está funcionando justamente pela configuração, remova as variáveis de ambiente e repita.

Possíveis problemas

  • ProxyError ou Cannot connect to proxy: erro de digitação no endereço ou porta errada. Compare com a linha de referência.
  • Tunnel connection failed: 407: erro de autenticação. Verifique a codificação da senha.
  • SSLError CERTIFICATE_VERIFY_FAILED: é preciso a chave cert com o certificado raiz do proxy.
  • O arquivo foi gravado, mas o pip não o vê: você está executando o pip de outro interpretador (por exemplo, python3 -m pip de outro Python). Execute pip config debug com o mesmo comando que você usa para instalar pacotes.

Passo 4: Configurando o apt através do diretório apt.conf.d

Objetivo da etapa: fazer sudo apt update e sudo apt install baixarem pacotes através do proxy, e os acessos ao espelho interno irem direto.

Por que justamente o apt.conf.d

O apt lê as configurações de /etc/apt/apt.conf e de todos os arquivos do diretório /etc/apt/apt.conf.d/ em ordem alfabética. A boa prática é não tocar nos arquivos de outros, mas criar o seu com um prefixo numérico. O número define a ordem de leitura: o arquivo 80proxy será aplicado depois de 01autoremove e outros arquivos do sistema. É justamente aqui que as configurações sobreviverão a qualquer atualização do pacote apt.

Configuração passo a passo

  1. Crie um novo arquivo de configuração:
    sudo nano /etc/apt/apt.conf.d/80proxy
    Vai abrir um editor vazio.
  2. Escreva duas linhas para repositórios HTTP e HTTPS. Atenção às aspas e pontos e vírgulas - na sintaxe do apt eles são obrigatórios:
    Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128";
  3. Se houver um espelho interno que não precisa de proxy, adicione uma linha com exceção. A palavra DIRECT em maiúsculas significa conexão direta:
    Acquire::http::Proxy::mirror.corp.local "DIRECT";
  4. Salve o arquivo: no nano pressione Ctrl+O, depois Enter, depois Ctrl+X para sair.
  5. Restrinja as permissões do arquivo, afinal ele contém a senha:
    sudo chmod 600 /etc/apt/apt.conf.d/80proxy
    Só o root poderá ler o conteúdo.
  6. Verifique se o apt interpretou o arquivo sem erros de sintaxe:
    apt-config dump | grep -i proxy
    Você deve ver as linhas Acquire::http::Proxy e Acquire::https::Proxy com seus valores.

Aqui está um exemplo completo do arquivo para maior clareza:

Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::http::Proxy::mirror.corp.local "DIRECT"; Acquire::https::Proxy::mirror.corp.local "DIRECT";

Alternativa para uma única execução sem arquivo: sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update. A flag -o é útil para testar um valor antes de gravá-lo na configuração.

Dica: servidores proxy que fazem cache de pacotes deb costumam ter uma porta separada para o apt. Pergunte ao administrador: se houver, o apt update vai acelerar várias vezes graças ao cache local.

Verificação: execute sudo apt update. Na saída aparecerão linhas Hit ou Get com os endereços dos repositórios e não haverá linhas com Err. Note que não definimos variáveis de ambiente e o sudo as descartaria de qualquer forma, mas o apt ainda assim saiu para a rede. Esse é exatamente o efeito da configuração própria.

Possíveis problemas

  • Err: 407 Proxy Authentication Required: a autenticação não passou, verifique a codificação dos caracteres especiais.
  • Could not connect ou Connection timed out: o apt foi direto. Provavelmente há um erro de digitação no arquivo, e o apt-config dump não o mostra. Verifique a capitalização em Acquire e os dois pontos duplos.
  • E: Syntax error: falta um ponto e vírgula ou uma aspa final de linha.
  • O arquivo está no lugar, mas a exceção DIRECT não funciona: confirme que o nome do host na linha de exceção coincide letra por letra com o nome em sources.list, sem http:// e sem porta.

Passo 5: Configurando o Docker em dois níveis

Objetivo da etapa: fazer docker pull, docker build e docker compose pull baixarem imagens através do proxy, e os contêineres, quando necessário, receberem as configurações de proxy automaticamente.

Dois níveis que costumam ser confundidos

O Docker tem dois lugares independentes onde o proxy é necessário de formas diferentes:

  • Nível do daemon (serviço dockerd). É ele que baixa as imagens do registro. Configura-se em /etc/docker/daemon.json ou via systemd. Exige reiniciar o serviço.
  • Nível do cliente (arquivo ~/.docker/config.json). Ele não afeta o download de imagens. Mas ele transmite automaticamente as variáveis de proxy para dentro dos contêineres em execução e para o processo de build, para que apt ou pip dentro do contêiner também vejam o proxy.

Configurar só o cliente - o docker pull não funcionará. Configurar só o daemon - as imagens serão baixadas, mas o RUN apt-get update dentro do Dockerfile vai falhar. Precisa dos dois.

Parte A: daemon via daemon.json

  1. Verifique a versão: docker version. Se a versão do servidor for 23.0 ou superior, use o daemon.json. Se for mais antiga, vá para a parte B.
  2. Abra o arquivo de configuração do daemon:
    sudo nano /etc/docker/daemon.json
    Se o arquivo já existir e contiver outras chaves, adicione o bloco proxies dentro das mesmas chaves, separado por vírgula. Se o arquivo não existir, crie do zero.
  3. Escreva o bloco de configuração:
    { "proxies": { "http-proxy": "http://dev:s3cret@10.20.30.40:3128", "https-proxy": "http://dev:s3cret@10.20.30.40:3128", "no-proxy": "localhost,127.0.0.0/8,registry.corp.local" } }
    Atenção: as chaves são escritas com hífen e em minúsculas exatamente assim. Esse é o formato do daemon; no cliente as chaves serão outras.
  4. Salve o arquivo (Ctrl+O, Enter, Ctrl+X).
  5. Verifique se o JSON é válido, senão o daemon não vai iniciar:
    python3 -m json.tool /etc/docker/daemon.json
    Se o comando exibiu o conteúdo do arquivo com indentação, a sintaxe está correta. Se reclamar de Expecting value ou Extra data, procure uma vírgula a mais ou faltando.
  6. Reinicie o serviço:
    sudo systemctl restart docker
    A reinicialização leva de 5 a 15 segundos. Todos os contêineres em execução serão parados, então faça isso em um momento tranquilo.
  7. Confirme que o daemon subiu: sudo systemctl status docker. Deve aparecer active (running) em verde.

Atenção: uma vírgula a mais no daemon.json e o Docker não inicia de jeito nenhum, e junto com ele caem todos os contêineres da máquina. Sempre verifique o arquivo com json.tool antes de reiniciar e mantenha uma cópia de backup por perto.

Parte B: daemon via systemd (para versões antigas e como alternativa)

  1. Crie o diretório para configurações adicionais do serviço: sudo mkdir -p /etc/systemd/system/docker.service.d
  2. Crie o arquivo: sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
  3. Escreva:
    [Service] Environment="HTTP_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="HTTPS_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="NO_PROXY=localhost,127.0.0.0/8,registry.corp.local"
  4. Salve e aplique: sudo systemctl daemon-reload, depois sudo systemctl restart docker.

Sim, aqui são usadas variáveis de ambiente, mas não estão definidas no seu console, e sim na definição do serviço: o daemon as recebe do systemd na inicialização. Essa é a única forma para Docker anterior à versão 23. Se você tiver tanto o daemon.json quanto o arquivo systemd configurados, a prioridade é do daemon.json.

Parte C: cliente via ~/.docker/config.json

  1. Abra ou crie o arquivo nano ~/.docker/config.json. Se o arquivo já contiver o bloco auths com seus logins nos registros, não o apague, apenas adicione um novo bloco ao lado separado por vírgula.
  2. Escreva:
    { "proxies": { "default": { "httpProxy": "http://dev:s3cret@10.20.30.40:3128", "httpsProxy": "http://dev:s3cret@10.20.30.40:3128", "noProxy": "localhost,127.0.0.0/8,.corp.local" } } }
    Aqui as chaves são no estilo camelCase: httpProxy, httpsProxy, noProxy. Essa é a diferença em relação ao daemon.json, e não se pode confundir.
  3. Salve o arquivo. Não é necessário reiniciar nada, o cliente lê o arquivo a cada comando.

Agora, em docker run e docker build, as variáveis HTTP_PROXY, HTTPS_PROXY e NO_PROXY entrarão automaticamente no contêiner (em ambos os casos). Isso significa que apt-get e pip dentro do Dockerfile também passarão pelo proxy sem ARG e ENV manuais.

Docker Desktop no Windows e macOS

Abra as configurações pelo ícone na bandeja, seção Resources, subseção Proxies. Ative Manual proxy configuration, insira o endereço nos campos Web Server (HTTP) e Secure Web Server (HTTPS), e a lista de exceções em Bypass proxy settings for these hosts and domains. Clique em Apply and restart. O config.json do cliente no Windows fica em C:\Users\NOME\.docker\config.json e se configura da mesma forma descrita acima.

Dica: o comando docker info exibe uma seção com HTTP Proxy, HTTPS Proxy e No Proxy. É a forma mais rápida de saber se o daemon viu suas configurações, sem iniciar um download.

Verificação: execute docker pull hello-world. A imagem pesa alguns kilobytes e será baixada em poucos segundos; no final aparecerá Status: Downloaded newer image. Depois verifique a parte do cliente: docker run --rm alpine env | grep -i proxy. Na saída devem aparecer as linhas HTTP_PROXY e HTTPS_PROXY com o seu endereço.

Possíveis problemas

  • O Docker não inicia após editar o daemon.json: erro de sintaxe. Veja sudo journalctl -u docker -n 30, lá estará indicada a linha com o erro. Restaure a partir do backup.
  • docker pull fica travado e cai por timeout, embora docker info mostre o proxy: o daemon não foi reiniciado após a edição, ou o proxy não permite CONNECT para registry-1.docker.io. Verifique a linha de referência com curl.
  • Dentro do build o apt-get update falha, mas o docker pull funciona: o config.json do cliente não está configurado, ou o build está sendo feito por um builder remoto que lê outro arquivo.
  • O contêiner recebeu o proxy, mas não consegue acessar um contêiner vizinho: adicione os nomes dos serviços internos e a sub-rede do Docker ao noProxy.

Passo 6: Configurando o git através do git config

Objetivo da etapa: fazer git clone, fetch, pull e push por HTTPS passarem pelo proxy, podendo deixar conexão direta para o servidor interno e definir um proxy específico para um host em particular.

Onde o git armazena as configurações

Três níveis: do sistema (/etc/gitconfig), global do usuário (~/.gitconfig, no Windows C:\Users\NOME\.gitconfig) e local dentro do repositório (.git/config). O proxy geralmente é definido globalmente, e as exceções pontuais também globalmente, mas com vinculação a URL.

Configuração passo a passo

  1. Defina o proxy para todas as conexões HTTPS e HTTP com um único comando:
    git config --global http.proxy http://dev:s3cret@10.20.30.40:3128
    Diferente do npm, o git não tem um https.proxy separado para o protocolo HTTPS: a chave http.proxy se aplica a ambos. A configuração https.proxy aparece em tutoriais antigos, mas não é uma chave padrão do git e é ignorada.
  2. Se o servidor interno não precisar de proxy, defina um valor vazio justamente para a URL dele:
    git config --global http.https://git.corp.local.proxy ""
    Uma string vazia significa conexão direta. A parte entre http. e .proxy é o prefixo da URL à qual a regra se aplica.
  3. Se para um host específico for necessário outro proxy (por exemplo, um proxy móvel dedicado), indique-o da mesma forma vinculado à URL:
    git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128
  4. Se o proxy substituir certificados, adicione o certificado raiz:
    git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem
  5. Verifique o arquivo final:
    git config --global --list | grep -i proxy
    Você verá as linhas http.proxy=... e http.https://git.corp.local.proxy= com valor vazio.

O arquivo ~/.gitconfig após esses comandos ficará assim:

[http] proxy = http://dev:s3cret@10.20.30.40:3128 sslCAInfo = /etc/ssl/certs/corp-root.pem [http "https://git.corp.local"] proxy = [http "https://github.com"] proxy = http://dev:s3cret@10.20.30.41:3128

Essa granularidade é inatingível via variáveis de ambiente: o no_proxy só sabe excluir hosts, mas não atribuir proxies diferentes a servidores diferentes.

E os endereços SSH?

A configuração http.proxy não afeta endereços no formato git@github.com:user/repo.git, porque esse é o protocolo SSH, não HTTP. Se o seu proxy permitir tunelamento para a porta 22 via CONNECT, é possível configurar o cliente SSH no arquivo ~/.ssh/config com a diretiva ProxyCommand e o utilitário nc ou corkscrew. Mas muitos proxies corporativos proíbem essas conexões. O caminho mais simples e previsível é trocar os endereços remotos para HTTPS: git remote set-url origin https://github.com/user/repo.git e usar um token de acesso em vez de senha.

Dica: para não guardar a senha do proxy no ~/.gitconfig em texto aberto, você pode colocá-la em um arquivo separado com permissões 600 e incluí-lo com a diretiva include. Crie o ~/.gitconfig-proxy com a seção [http], e no arquivo principal adicione [include] path = ~/.gitconfig-proxy. Assim a configuração principal pode ser mostrada tranquilamente aos colegas.

Verificação: execute git ls-remote https://github.com/git/git.git HEAD. Em alguns segundos retornará uma linha com o hash do commit e a palavra HEAD. O comando não cria arquivos nem clona nada, é o teste perfeito da parte de rede. Depois verifique a exceção: git ls-remote até o servidor interno deve funcionar mesmo com o proxy fora do ar.

Possíveis problemas

  • Failed to connect to proxy ou Could not resolve proxy: erro de digitação no endereço.
  • Received HTTP code 407 from proxy after CONNECT: erro de autenticação, verifique a codificação da senha.
  • SSL certificate problem: unable to get local issuer certificate: é preciso http.sslCAInfo. Não use http.sslVerify false de forma permanente.
  • A regra para URL não é aplicada: o prefixo deve coincidir com o início do endereço no remote. Se o remote estiver escrito como https://www.github.com, a regra para https://github.com não funcionará.

Verificando o resultado: checklist consolidado

Depois de configurar as cinco ferramentas, faça a verificação final. Ela foi construída justamente para excluir a influência das variáveis de ambiente e confirmar que são as configurações que estão funcionando.

  1. Abra um novo terminal e remova as variáveis, caso estejam definidas: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. No PowerShell: Remove-Item Env:HTTP_PROXY e o equivalente para as outras.
  2. Verifique o npm: npm view express version. Espera-se o número da versão.
  3. Verifique o pip: pip download six --no-deps -d /tmp/t. Espera-se o arquivo whl baixado.
  4. Verifique o apt: sudo apt update. Esperam-se linhas Hit ou Get sem Err.
  5. Verifique o Docker: docker pull hello-world e docker run --rm alpine env | grep -i proxy. Espera-se a imagem baixada e as variáveis no contêiner.
  6. Verifique o git: git ls-remote https://github.com/git/git.git HEAD. Espera-se o hash do commit.

Indicadores de sucesso

  • Todos os seis comandos funcionaram sem variáveis de ambiente no console.
  • Nos arquivos .npmrc, pip.conf, 80proxy, daemon.json, config.json e .gitconfig está gravada a mesma linha de referência do proxy.
  • Os arquivos com senhas (80proxy, daemon.json, .npmrc, pip.conf, .gitconfig) têm permissões 600 ou são acessíveis apenas ao root.
  • As exceções para hosts internos funcionam: o acesso a eles passa mesmo com o proxy desligado.
  • Os backups dos arquivos originais estão por perto e você sabe como restaurá-los.

Verificação: se ao menos um item não for cumprido, volte à seção da ferramenta correspondente e compare o seu arquivo com o exemplo do guia caractere por caractere. Em nove de cada dez casos, a causa é um erro de digitação ou um caractere não codificado na senha.

Erros comuns e soluções

Erro 1: código 407 Proxy Authentication Required em tudo

Causa: a senha contém um caractere especial (@, :, #, %) que não foi codificado, e a ferramenta interpretou o endereço incorretamente.

Solução: codifique os caracteres com códigos percentuais (@ vira %40, : vira %3A, # vira %23, % vira %25) e teste a nova linha com curl -x antes de gravá-la nas configurações.

Erro 2: funciona no terminal, não funciona com sudo

Causa: o sudo limpa o ambiente e você ainda não criou a configuração. Clássico do apt.

Solução: crie /etc/apt/apt.conf.d/80proxy como no Passo 4. Para outras ferramentas sob root, lembre-se de que o root lê o próprio diretório pessoal /root, e não o seu: se precisar de npm ou pip como root, a configuração deve estar em /root/.npmrc ou /root/.config/pip/pip.conf.

Erro 3: o Docker não inicia após editar o daemon.json

Causa: JSON inválido: vírgula a mais depois do último elemento, chave faltando, aspas simples em vez de duplas.

Solução: execute sudo journalctl -u docker -n 30, encontre a linha com o erro, corrija o arquivo e verifique-o com python3 -m json.tool antes do próximo reinício. Em último caso, restaure o daemon.json.bak.

Erro 4: docker pull funciona, mas o apt-get dentro do Dockerfile falha

Causa: o daemon está configurado, mas o cliente não. Processos dentro do contêiner não herdam as configurações do daemon.

Solução: crie ~/.docker/config.json com o bloco proxies.default como na parte C do Passo 5. Depois disso, o docker build transmitirá automaticamente as variáveis para as etapas RUN.

Erro 5: erros de certificado SSL em todas as ferramentas

Causa: o proxy faz inspeção de tráfego e insere o próprio certificado, no qual o sistema não confia.

Solução: obtenha o certificado raiz do proxy em formato PEM com o administrador e configure-o: npm cafile, pip cert, git http.sslCAInfo. Para apt e Docker, basta adicionar o certificado ao repositório do sistema: copie para /usr/local/share/ca-certificates/ e execute sudo update-ca-certificates, depois reinicie o Docker. Não desative a verificação de certificados com as flags strict-ssl, trusted-host e sslVerify.

Erro 6: o pip ignora o pip.conf

Causa: a máquina tem várias versões do Python, e você edita a configuração de uma enquanto executa outra. Ou o arquivo está em um local obsoleto que aquela versão específica não lê.

Solução: execute python3 -m pip config debug com o mesmo comando que você usa para instalar pacotes. A saída mostrará quais arquivos foram encontrados. Mova as configurações para o caminho do usuário encontrado.

Erro 7: o git passa pelo proxy até para o servidor interno

Causa: a regra de exceção foi definida para uma URL que não coincide com o endereço no remote. Ou foi definida no .git/config local de outro repositório.

Solução: veja o endereço exato com git remote -v, copie o início dele até o nome do host e defina a regra http.URL_EXATA.proxy com valor vazio via --global.

Erro 8: tudo funcionava, e depois de trocar a senha do proxy parou

Causa: a senha está gravada em cinco arquivos diferentes, e não foram atualizados todos.

Solução: use o comando grep -rl 'senha_antiga' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker e sudo grep -rl para /etc/apt/apt.conf.d e /etc/docker, para encontrar todas as ocorrências, e atualize cada uma. Depois rode o checklist consolidado.

Recursos adicionais

Agregador de proxy local como ponto de entrada único

Se as credenciais do proxy mudam com frequência ou o pool de endereços rotaciona, é prático subir na sua máquina um proxy leve (por exemplo, em 127.0.0.1:3128), que sabe para onde ir e com quais dados. Assim, nas cinco configurações entra um único endereço sem senha, e a troca de credenciais é feita em um só lugar. Isso também resolve o problema de ferramentas que lidam mal com autenticação na URL.

Espelhos e proxies de cache para pacotes

O proxy não precisa ser universal. Para o apt existem proxies de cache que armazenam arquivos deb localmente e os servem para todo o escritório. Para npm e pip, as empresas montam registros privados que fazem proxy dos públicos e ainda fazem cache. Nesse caso, em vez da chave proxy, usa-se registry no .npmrc e index-url no pip.conf, e o proxy para o mundo externo é configurado nesse próprio registro. Para o Docker, um papel semelhante é desempenhado pela chave registry-mirrors no daemon.json.

Configurações separadas para projetos diferentes

O .npmrc de projeto ao lado do package.json, o pip.conf dentro da venv e o .git/config local permitem que um projeto passe pelo proxy e outro vá direto. Só não faça commit de arquivos com senhas no repositório: adicione-os ao .gitignore ou use variáveis de substituição como ${PROXY_URL}, que o npm consegue expandir do ambiente ao ler o .npmrc.

Automatização da distribuição

As cinco configurações são arquivos de texto simples. É prático distribuí-las por script ou sistema de gerenciamento de configuração: o script recebe a linha de referência como um parâmetro e gera os arquivos nos formatos necessários. Para verificar após a distribuição, use os comandos do checklist consolidado: eles não exigem interatividade e servem para testes automatizados.

Segurança no armazenamento de senhas

O mínimo é permissões 600 em cada arquivo com senha. Melhor ainda é levar os segredos para arquivos separados incluídos (include no git, arquivo separado no apt.conf.d apenas para linhas com autenticação). Ainda melhor é um proxy sem autenticação por senha, mas com restrição por IP, ou um agregador local, como mencionado acima. E nunca envie configurações com senhas inteiras em chats e tickets.

FAQ: perguntas frequentes sobre configuração

Preciso agora remover as variáveis http_proxy do .bashrc?

Não necessariamente. As configurações das ferramentas têm prioridade sobre as variáveis, não haverá conflito. Mas se você quer que apenas os gerenciadores de pacotes passem pelo proxy e o navegador e outros programas vão direto, é melhor remover as variáveis: elas afetam tudo.

Por que no https-proxy do npm se escreve um endereço com http://, e não com https://

Porque esse é o endereço do próprio servidor proxy, e não o protocolo do recurso de destino. A maioria dos proxies aceita conexões por HTTP comum e tunelam HTTPS por dentro. Se o seu proxy realmente aceita conexões TLS, então escreva https://, mas isso é raro.

É possível usar proxy SOCKS5?

npm - não, ele suporta apenas proxy HTTP. pip - sim, com o pacote pysocks instalado e endereço no formato socks5://host:port. git - sim, formato socks5h://host:port, a letra h significa resolução de nomes do lado do proxy. apt - só através de transportes adicionais, de forma padrão não. Docker - não. Na prática, é mais simples obter uma porta HTTP com o provedor.

Como desativar rapidamente o proxy em todas as ferramentas

npm: npm config delete proxy e npm config delete https-proxy. pip: pip config unset global.proxy. git: git config --global --unset http.proxy. apt: apague ou renomeie /etc/apt/apt.conf.d/80proxy. Docker: remova o bloco proxies do daemon.json e do config.json, reinicie o serviço. Ou simplesmente restaure os arquivos .bak dos backups.

Onde armazenar as configurações no Windows

npm: C:\Users\NOME\.npmrc. pip: C:\Users\NOME\AppData\Roaming\pip\pip.ini. git: C:\Users\NOME\.gitconfig. Docker: C:\Users\NOME\.docker\config.json para o cliente e as configurações do Docker Desktop para o daemon. O apt não é usado no Windows, exceto no WSL, onde se aplicam os caminhos Linux dentro do subsistema.

Isso funciona dentro do WSL?

Sim, o WSL é um Linux comum, todas as configurações ficam nos caminhos Linux dentro da distribuição. Lembre-se de que o Docker Desktop com integração WSL usa o daemon do lado do Windows, então as configurações do daemon são feitas no Docker Desktop, e o config.json do cliente - dentro do WSL, no diretório pessoal.

Como saber qual arquivo cada ferramenta leu

npm config list --json, pip config debug, apt-config dump, docker info, git config --show-origin --list. Cada comando mostra não só os valores, mas também a origem de onde foram tirados. É a primeira coisa a rodar ao depurar.

Por que o Docker Compose não vê o proxy

O Compose é um cliente, ele usa o mesmo daemon e o mesmo ~/.docker/config.json. Se o docker pull funciona, mas o docker compose pull não, verifique se você está rodando o compose com o mesmo usuário e se no arquivo do compose não há variáveis de ambiente dos contêineres que sobreponham o proxy.

É possível definir proxies diferentes para npm e pip?

Sim, e essa é justamente a vantagem das configurações próprias. Cada arquivo é independente. Por exemplo, o npm pode passar por um proxy, e o pip por outro, com IP e geolocalização diferentes, se a tarefa exigir.

Conclusão

Vamos recapitular. Você verificou o proxy com curl e obteve uma linha de referência de conexão com a senha devidamente codificada. Depois a inseriu em cinco lugares: no ~/.npmrc para o npm, no pip.conf para o pip, em /etc/apt/apt.conf.d/80proxy para o apt, no daemon.json e ~/.docker/config.json para o Docker, e no ~/.gitconfig para o git. Para cada ferramenta você definiu exceções para hosts internos onde isso é suportado, e confirmou que tudo funciona mesmo com o ambiente completamente limpo. É justamente isso que diferencia as configurações próprias das variáveis de ambiente: elas não dependem de quem, de onde e por qual serviço o comando foi executado.

O que fazer a seguir. Salve os cinco arquivos de referência em uma pasta pessoal e escreva um pequeno script que os distribua em uma nova máquina. Verifique as permissões dos arquivos com senha. Se você tem colegas com o mesmo problema, compartilhe o checklist consolidado com eles: economiza horas de depuração.

Para onde evoluir. O próximo nível são os proxies de cache e registros privados de pacotes, um agregador de proxy local como ponto de entrada único e verificação automatizada de configurações de rede em pipelines. E se você precisar configurar proxy não para ferramentas, mas para uma sessão específica de terminal ou tarefa em CI, existe um guia separado sobre variáveis de ambiente. Agora você sabe exatamente onde terminam as possibilidades dele e começam as das configurações.