Usando Proxy con Gestores de Paquetes

Para usar un proxy con gestores de paquetes como npm, pip y composer, configure los ajustes del proxy ya sea a través de variables de entorno (HTTP_PROXY, HTTPS_PROXY), argumentos de línea de comandos o archivos de configuración específicos de cada gestor de paquetes.

Muchos entornos de desarrollo operan detrás de firewalls corporativos o requieren monitoreo de tráfico, lo que hace necesario el uso de un servidor proxy HTTP o HTTPS para las conexiones salientes. Los gestores de paquetes, que descargan dependencias de registros externos, deben configurarse para enrutar sus solicitudes de red a través de dichos proxies para funcionar correctamente.

Conceptos Generales de Configuración de Proxy

Los servidores proxy pueden interceptar y reenviar tráfico HTTP y HTTPS. A menudo se requiere autenticación para acceder a estos proxies.

Formato de URL del Proxy

El formato estándar para una URL de proxy, incluyendo la autenticación opcional, es:

protocol://[user:password@]host:port

• protocol: http o https
• user:password: Credenciales opcionales para la autenticación del proxy.
• host: El nombre de host o la dirección IP del servidor proxy.
• port: El puerto en el que escucha el servidor proxy (por ejemplo, 8080, 3128).

Ejemplo: http://user:password@proxy.example.com:8080

Variables de Entorno

El método más común y a menudo universalmente reconocido para configurar proxies en varias herramientas, incluidos los gestores de paquetes, es a través de variables de entorno estándar.

• HTTP_PROXY o http_proxy: Especifica el servidor proxy para solicitudes HTTP.
• HTTPS_PROXY o https_proxy: Especifica el servidor proxy para solicitudes HTTPS.
• NO_PROXY o no_proxy: Una lista de nombres de host, dominios o direcciones IP separados por comas que deben omitir el proxy. Esto es crucial para acceder directamente a recursos internos o servidores de desarrollo locales.

Estas variables suelen ser insensibles a mayúsculas y minúsculas en Windows, pero sensibles a mayúsculas y minúsculas en sistemas tipo Unix. Es una práctica común establecer ambas versiones, UPPER_CASE y lower_case, para una máxima compatibilidad.

# Ejemplo para sistemas tipo Unix (Linux, macOS)
export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080" # A menudo el mismo que HTTP_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

# Para el Símbolo del sistema de Windows
set HTTP_PROXY=http://user:password@proxy.example.com:8080
set HTTPS_PROXY=http://user:password@proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,.internal.domain.com

# Para Windows PowerShell
$env:HTTP_PROXY="http://user:password@proxy.example.com:8080"
$env:HTTPS_PROXY="http://user:password@proxy.example.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

npm (Node Package Manager)

npm se puede configurar utilizando su sistema de configuración integrado o mediante variables de entorno.

Configuración a través de npm config

El método preferido para npm es establecer la configuración del proxy directamente en su configuración. Esto almacena la configuración de forma persistente.

# Establecer proxy HTTP
npm config set proxy http://user:password@proxy.example.com:8080

# Establecer proxy HTTPS (a menudo el mismo que el proxy HTTP)
npm config set https-proxy http://user:password@proxy.example.com:8080

# Para deshabilitar un proxy
npm config rm proxy
npm config rm https-proxy

# Verificar la configuración
npm config get proxy
npm config get https-proxy

Si su proxy no requiere autenticación, omita el segmento user:password@.

Problemas con Certificados SSL

Al usar un proxy HTTPS o un registro HTTPS a través de un proxy HTTP, npm podría encontrar problemas de verificación de certificados SSL. Esto puede ocurrir si el proxy intercepta y vuelve a cifrar el tráfico HTTPS con su propio certificado, que no es de confianza para su sistema.

Para solucionar esto, puede:
1. Agregar el certificado CA del proxy al almacén de confianza de su sistema. Este es el enfoque seguro recomendado.
2. Indicar a npm que use un archivo de certificado CA específico:
bash npm config set cafile /path/to/proxy/ca-certificate.pem
3. Deshabilitar la verificación SSL estricta (no recomendado para producción):
bash npm config set strict-ssl false
Esto omite la validación del certificado y puede exponerlo a ataques de intermediario (man-in-the-middle). Úselo solo para depuración temporal en entornos controlados.

Configuración del Registro

Si su organización utiliza un registro npm privado (por ejemplo, Nexus, Artifactory) que es accesible directamente o a través de un proxy diferente, asegúrese de que la configuración registry sea correcta.

npm config set registry https://my-private-registry.example.com/npm/

pip (Python Package Installer)

pip admite la configuración de proxy a través de indicadores de línea de comandos, variables de entorno o un archivo de configuración.

Indicador de Línea de Comandos

Para un solo comando pip, use el indicador --proxy:

pip install some-package --proxy http://user:password@proxy.example.com:8080

Archivo de Configuración

Para la configuración persistente del proxy, modifique o cree el archivo de configuración de pip.
* Linux/macOS: ~/.config/pip/pip.conf o ~/.pip/pip.conf
* Windows: %APPDATA%\pip\pip.ini o %HOME%\pip\pip.ini

Agregue lo siguiente a la sección [global]:

# ~/.config/pip/pip.conf o %APPDATA%\pip\pip.ini
[global]
proxy = http://user:password@proxy.example.com:8080

Variables de Entorno

pip respeta las variables de entorno estándar HTTP_PROXY, HTTPS_PROXY y NO_PROXY. Si se establecen, estas se usarán automáticamente.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
pip install some-package

Problemas con Certificados SSL

Similar a npm, pip puede encontrar errores SSL.
1. Agregar el certificado CA del proxy al almacén de confianza del sistema.
2. Especificar un host de confianza para el índice:
ini # ~/.config/pip/pip.conf o %APPDATA%\pip\pip.ini [global] trusted-host = pypi.org
Esto le dice a pip que confíe en el host especificado incluso si la validación SSL falla para él. Úselo con precaución.
3. Especificar un paquete de CA personalizado:
ini # ~/.config/pip/pip.conf o %APPDATA%\pip\pip.ini [global] cert = /path/to/proxy/ca-bundle.pem
O a través de la línea de comandos: pip install some-package --cert /path/to/proxy/ca-bundle.pem

Índices de Paquetes Privados

Si utiliza un índice de paquetes Python privado (por ejemplo, Artifactory, Nexus), configure index-url o extra-index-url:

# ~/.config/pip/pip.conf o %APPDATA%\pip\pip.ini
[global]
index-url = https://my-private-pypi.example.com/simple/

Composer (PHP Dependency Manager)

Composer depende en gran medida de las variables de entorno para la configuración del proxy y también puede necesitar la configuración del proxy de Git para los repositorios obtenidos a través de Git.

Variables de Entorno

Composer utiliza principalmente las variables de entorno estándar HTTP_PROXY, HTTPS_PROXY y NO_PROXY.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
composer install

Configuración de Composer (config.json)

Aunque Composer no tiene una configuración proxy directa en su config.json para el tráfico HTTP/HTTPS general, es posible configurar los ajustes de proxy para repositorios VCS específicos si no son detectados por las variables de entorno o si se necesitan diferentes proxies.

Por ejemplo, para configurar un proxy para Git:

{
    "config": {
        "github-oauth": {
            "github.com": "YOUR_OAUTH_TOKEN"
        }
    }
}

Esto no es una configuración de proxy directamente, pero demuestra dónde podrían ir otras configuraciones relacionadas con la red. Para el proxying real de Git, consulte la siguiente sección.

Configuración de Proxy de Git

Composer a menudo obtiene paquetes directamente de repositorios Git (por ejemplo, GitHub, GitLab). Si su tráfico de Git necesita pasar por un proxy, debe configurar Git mismo.

# Establecer proxy HTTP para Git
git config --global http.proxy http://user:password@proxy.example.com:8080

# Establecer proxy HTTPS para Git
git config --global https.proxy http://user:password@proxy.example.com:8080

# Para deshabilitar
git config --global --unset http.proxy
git config --global --unset https.proxy

# Verificar
git config --global --get http.proxy
git config --global --get https.proxy

Esto es especialmente importante si su composer.json utiliza repositorios vcs o URLs directas de Git.

Problemas con Certificados SSL

Composer, como otras herramientas, puede enfrentar problemas de SSL.
1. Agregar el certificado CA del proxy al almacén de confianza del sistema.
2. Configurar Git para deshabilitar la verificación SSL (no recomendado):
bash git config --global http.sslVerify false
Esto debe ser un último recurso y usarse con extrema precaución.

Solución de Problemas Comunes de Proxy

• Dirección/Puerto de Proxy Incorrectos: Verifique dos veces el nombre de host, la dirección IP y el puerto. Un error común es usar HTTP para un proxy HTTPS o viceversa.
• Fallo de Autenticación: Asegúrese de que el nombre de usuario y la contraseña en la URL del proxy sean correctos y estén codificados en URL si contienen caracteres especiales.
• Errores de Certificado SSL: Si encuentra SSL_ERROR_SYSCALL, certificate verify failed o errores similares, su proxy podría estar realizando una intercepción SSL. Instale el certificado CA raíz del proxy en el almacén de confianza de su sistema o configure el gestor de paquetes para que confíe en un paquete de CA específico (como se detalla anteriormente).
• Problemas con NO_PROXY: Si los servicios internos aún intentan pasar por el proxy, verifique que su configuración NO_PROXY sea correcta y completa. Asegúrese de que incluya localhost, 127.0.0.1 y cualquier sufijo de dominio interno relevante.
• Bloqueo de Firewall: Confirme que el firewall de su máquina o los grupos de seguridad de red permitan conexiones salientes a la IP y el puerto del servidor proxy.
• Configuración Mixta HTTP/HTTPS: Algunos proxies manejan HTTP y HTTPS de manera diferente. Asegúrese de haber configurado tanto HTTP_PROXY como HTTPS_PROXY si corresponde, o sus equivalentes específicos del gestor de paquetes.

Comparación de Métodos de Configuración de Proxy