Tu nueva aplicación funciona bien en el servidor, en 127.0.0.1:3000, y Apache ya responde en los puertos 80 y 443 para la web de la empresa. Quieres que app.example.com llegue a la aplicación, con el certificado que Apache ya gestiona. Añades una línea ProxyPass, abres la página, pulsas «Iniciar sesión» y el navegador salta a http://127.0.0.1:3000/login, una dirección que solo funciona dentro del propio servidor. Ese estado a medias es el primer resultado más habitual de un proxy inverso con Apache.
Esta guía monta la configuración en orden: módulos, un VirtualHost mínimo, redirecciones y nombres de host, cabeceras reenviadas, HTTPS, WebSocket, tiempos de espera, balanceo de carga, pruebas y los mensajes de error que te vas a encontrar. Las directivas salen de la documentación de Apache HTTP Server 2.4; el comportamiento del backend lo probamos con una aplicación Node de diez líneas en 127.0.0.1.
¿Qué hace un proxy inverso con Apache?
Un proxy inverso (reverse proxy) con Apache recibe las peticiones de tu sitio, las pasa a un servidor de aplicaciones situado detrás y devuelve la respuesta de ese servidor como si la hubiera generado Apache. El visitante solo habla con Apache; la aplicación en 127.0.0.1 o en una red privada queda fuera de su alcance. La diferencia con el proxy que un cliente configura para sí mismo se explica en Forward proxy y reverse proxy: ¿en qué se diferencian?.
Esto es lo que le pasa a una petición:
- Apache elige el VirtualHost cuyo
ServerNamecoincide con la cabeceraHostque envió el navegador. - Revisa las reglas
ProxyPassen orden; gana la primera ruta que coincide. mod_proxy_httpabre una conexión con el backend y reenvía la petición, añadiendoX-Forwarded-For,X-Forwarded-HostyX-Forwarded-Server.- El backend responde. Si la respuesta es una redirección,
ProxyPassReversecambia la dirección del backend en la cabeceraLocationpor la pública. - Apache envía la respuesta al visitante, con su propio certificado TLS si el VirtualHost usa HTTPS.
¿Qué módulos de Apache necesitas?
Necesitas mod_proxy, que aporta la maquinaria del proxy, y además un módulo de protocolo para el tipo de backend con el que hablas. La documentación de mod_proxy los enumera; abajo están los que usa una configuración típica.
| Módulo | Qué hace | Lo necesitas para |
|---|---|---|
mod_proxy | Funciones básicas del proxy | Cualquier configuración |
mod_proxy_http | Habla HTTP con el backend | Aplicaciones en Node, Python, Java o Go |
mod_headers | Directiva RequestHeader | X-Forwarded-Proto |
mod_ssl | TLS para el sitio | HTTPS |
mod_proxy_balancer | Grupos de backends | Balanceo de carga |
mod_lbmethod_byrequests | Un método de reparto | Balanceo de carga |
mod_proxy_wstunnel | Túnel WebSocket | Apache anterior a 2.4.47 |
mod_proxy_fcgi | Backends FastCGI | PHP-FPM |
Debian y Ubuntu guardan los módulos en /etc/apache2/mods-available y los activan con a2enmod, que crea enlaces en mods-enabled. La guía de Ubuntu Server sobre los módulos de Apache usa los mismos comandos:
sudo a2enmod proxy proxy_http headers ssl
sudo systemctl restart apache2Los sistemas de la familia RHEL cargan los módulos con líneas LoadModule en /etc/httpd/conf.modules.d/. En el paquete de CentOS Stream 9, 00-proxy.conf ya carga mod_proxy, mod_proxy_http, mod_proxy_balancer, los métodos de reparto y mod_proxy_wstunnel, mientras que mod_ssl es un paquete aparte (sudo dnf install mod_ssl). Si falta un módulo, la línea tiene este aspecto:
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.soComprueba qué está cargado con apachectl -M | grep -i proxy. En Windows, esas mismas líneas LoadModule están en conf\httpd.conf.
¿Cómo se escribe una configuración mínima de ProxyPass?
Pon una línea ProxyPass y su línea ProxyPassReverse correspondiente dentro del VirtualHost que responde al nombre público. Esta es la configuración útil más pequeña para la aplicación de la introducción:
<VirtualHost *:80>
ServerName app.example.com
ProxyRequests Off
ProxyPreserveHost On
# lo sirve el propio Apache, no la aplicación
ProxyPass "/.well-known/acme-challenge/" "!"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"
ErrorLog ${APACHE_LOG_DIR}/app-error.log
CustomLog ${APACHE_LOG_DIR}/app-access.log combined
</VirtualHost>${APACHE_LOG_DIR} está definido en Debian y Ubuntu; en los sistemas de la familia RHEL escribe logs/app-error.log en su lugar. Guarda el archivo como /etc/apache2/sites-available/app.conf y actívalo con sudo a2ensite app, o déjalo en /etc/httpd/conf.d/app.conf.
Tres reglas deciden si las líneas se comportan como esperas:
- Las barras tienen que coincidir. Si el primer argumento termina en
/, el segundo también, y al revés. Si no coinciden, las URL del backend pierden una barra o la duplican, y eso suele aparecer como un 404 de la aplicación. - El orden importa. Apache revisa las reglas
ProxyPassen el orden en que aparecen y usa la primera que coincide, así que pon primero las rutas más largas:/api/antes que/. - Las exclusiones van primero. Una regla
!deja una ruta fuera del proxy, aquí la carpeta que se usa para validar el certificado, y solo funciona por encima de la regla general.
En una subruta, ProxyPass "/app/" "http://127.0.0.1:3000/" envía /app/orders al backend como /orders; la aplicación tiene que generar entonces enlaces que empiecen por /app/, normalmente mediante un ajuste del tipo «base path».
¿Qué cambian ProxyPassReverse y ProxyPreserveHost?
ProxyPassReverse corrige las redirecciones y ProxyPreserveHost decide qué nombre de host ve el backend. Los dos importan porque las aplicaciones construyen URL absolutas a partir de la cabecera Host de la petición que reciben.
Nuestra aplicación de prueba en 127.0.0.1:3901 hizo justo eso. Al pedirle /admin con su propia dirección en la cabecera Host, respondió 302 con Location: http://127.0.0.1:3901/login; con la misma petición y Host: www.example.com, respondió Location: http://www.example.com/login. Por defecto Apache envía el host del destino de ProxyPass, que es el primer caso: el enlace de inicio de sesión roto de la introducción.
ProxyPassReverse lo arregla reescribiendo las cabeceras Location, Content-Location y URI de las redirecciones: un valor que empieza por la URL del backend vuelve a ser tu dirección pública. Los enlaces dentro del HTML o del JavaScript no se tocan. Para las cookies, ProxyPassReverseCookieDomain y ProxyPassReverseCookiePath reescriben el dominio y la ruta en Set-Cookie.
ProxyPreserveHost On pasa al backend la cabecera Host original del visitante, de modo que la aplicación construye URL correctas desde el principio. La documentación de Apache indica que, en condiciones normales, esta opción debe quedar desactivada, porque un backend que solo conoce su nombre interno puede rechazar el público. Actívala cuando la aplicación compruebe el nombre de host, genere enlaces absolutos o sirva varios dominios.
¿Cómo conoce el backend la IP y el protocolo del visitante?
Mediante cabeceras de petición que Apache añade a la entrada. En modo de proxy inverso, mod_proxy_http añade tres por su cuenta, controladas por ProxyAddHeaders, que está activada por defecto:
X-Forwarded-For: la dirección IP del visitante.X-Forwarded-Host: la cabeceraHostque envió el visitante.X-Forwarded-Server: el nombre de host del propio proxy.
X-Forwarded-Proto, que le dice a la aplicación si el visitante usó HTTPS, no se añade automáticamente. Defínela con mod_headers en el VirtualHost de HTTPS: RequestHeader set X-Forwarded-Proto "https". La acción set sustituye cualquier valor que haya enviado el cliente.
Trata estas cabeceras como pistas, no como pruebas. Si una petición ya trae X-Forwarded-For, Apache añade su valor al final, así que el backend recibe una lista separada por comas. Nuestra aplicación de prueba recibió 198.51.100.9, 203.0.113.7 tal como lo escribimos con curl y no pudo saber qué entrada había añadido un proxy. Vincula la aplicación a 127.0.0.1 para que solo Apache pueda llegar a ella, y haz que el framework confíe en las cabeceras reenviadas solo cuando vengan de ese proxy.
¿Cómo se añade HTTPS a un proxy inverso con Apache?
Termina TLS en Apache: un VirtualHost en el puerto 443 guarda el certificado, descifra la petición y pasa HTTP sin cifrar a la aplicación en la máquina local. El puerto 80 entonces solo redirige:
<VirtualHost *:80>
ServerName app.example.com
Redirect permanent "/" "https://app.example.com/"
</VirtualHost>
<VirtualHost *:443>
ServerName app.example.com
SSLEngine on
SSLCertificateFile /etc/ssl/app.example.com/fullchain.pem
SSLCertificateKeyFile /etc/ssl/app.example.com/privkey.pem
ProxyRequests Off
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"
</VirtualHost>Las rutas de los certificados son marcadores; usa los archivos que genere tu herramienta de certificados. Desde Apache 2.4.8, SSLCertificateFile puede contener los certificados intermedios detrás del certificado del servidor, lo que sustituye al antiguo SSLCertificateChainFile. Si tu herramienta de certificados valida el dominio por HTTP sin cifrar, comprueba que sigue funcionando después de añadir la redirección; muchas herramientas añaden su propia regla para el puerto 80.
Si el propio backend habla HTTPS, escribe https:// en ProxyPass y añade SSLProxyEngine on. Apache comprueba entonces por defecto el nombre del certificado del backend (SSLProxyCheckPeerName), y si no coincide el resultado es un 502. Como mod_proxy_http tiene que leer la ruta, Apache siempre descifra la petición; no deja pasar intacto el flujo cifrado del visitante.
¿Cómo se pasan las conexiones WebSocket por el proxy?
Desde Apache 2.4.47, añade upgrade=websocket a la línea ProxyPass que sirve la ruta de WebSocket. mod_proxy_http reenvía entonces la petición Upgrade del navegador y convierte la conexión en un túnel solo si el backend responde 101 Switching Protocols:
ProxyPass "/socket/" "http://127.0.0.1:3000/socket/" upgrade=websocket
ProxyPassReverse "/socket/" "http://127.0.0.1:3000/socket/"
ProxyPass "/" "http://127.0.0.1:3000/"
ProxyPassReverse "/" "http://127.0.0.1:3000/"Comprueba tu versión con apachectl -v. En la 2.4.46 y anteriores, carga mod_proxy_wstunnel y apunta la ruta de WebSocket a una URL ws://: ProxyPass "/socket/" "ws://127.0.0.1:3000/socket/". En ambos casos, la regla de WebSocket va encima de la regla general /. El navegador puede seguir usando wss:// mientras Apache habla ws sin cifrar con la aplicación local, porque TLS termina en Apache; a eso se refiere la gente cuando habla de «WebSocket sobre SSL» con Apache.
¿Cómo se configuran los tiempos de espera de un proxy inverso?
Apache espera hasta ProxyTimeout a que el backend envíe datos, y ProxyTimeout toma por defecto el valor general Timeout del servidor, que es de 60 segundos. Por eso, una página de informes cuyo backend trabaja dos minutos antes de enviar el primer byte falla al llegar al minuto, a menos que subas uno de los dos valores:
ProxyTimeout 180
ProxyPass "/reports/" "http://127.0.0.1:3000/reports/" timeout=300 connectiontimeout=5
ProxyPass "/" "http://127.0.0.1:3000/"ProxyTimeout se aplica a todo el VirtualHost. El parámetro timeout= lo sustituye para un destino concreto, y connectiontimeout= limita la espera de la propia conexión, de modo que un backend caído falla en segundos. retry= fija cuánto tiempo queda fuera de uso un backend que ha fallado (60 segundos por defecto). Sube los tiempos de espera solo donde haga falta, porque cada petición en espera ocupa un worker de Apache.
¿Cómo se balancea la carga con mod_proxy_balancer?
Define un grupo balancer:// con un BalancerMember por backend y apunta ProxyPass al grupo. Además de mod_proxy y mod_proxy_http, esto necesita mod_proxy_balancer y al menos un módulo de método, como mod_lbmethod_byrequests:
<Proxy "balancer://appcluster">
BalancerMember "http://10.0.0.11:3000" route=a
BalancerMember "http://10.0.0.12:3000" route=b
BalancerMember "http://10.0.0.13:3000" status=+H
ProxySet lbmethod=byrequests stickysession=ROUTEID
</Proxy>
Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/" env=BALANCER_ROUTE_CHANGED
ProxyPass "/" "balancer://appcluster/"
ProxyPassReverse "/" "balancer://appcluster/"byrequests reparte las peticiones a partes iguales, bytraffic reparte según los bytes y bybusyness elige el miembro menos ocupado. status=+H convierte el tercer servidor en una reserva en caliente (hot standby) que solo recibe tráfico cuando fallan los demás. Los valores route y la cookie ROUTEID (definida con mod_headers) mantienen a cada visitante en un mismo miembro, algo importante cuando una aplicación guarda las sesiones en memoria.
La guía de proxy inverso de Apache también trata las comprobaciones de estado (health checks) con mod_proxy_hcheck y la página de estado balancer-manager, que debe quedar limitada a direcciones de confianza, por ejemplo con Require host localhost.
La comparación entre los métodos se explica en ¿Qué es el balanceo de carga? Algoritmos y tipos.
¿Por qué ProxyRequests debe quedarse en Off?
Porque ProxyRequests On convierte Apache en un forward proxy que descarga cualquier URL para quien se lo pida, y ProxyPass funciona sin esa opción; además, Off es el valor por defecto. Un forward proxy abierto en un servidor público acaba descubierto y usado por desconocidos para spam y ataques. Esas peticiones salen desde la dirección IP de tu servidor, que termina en listas de bloqueo y en denuncias de abuso dirigidas a tu proveedor de hosting. Escribe ProxyRequests Off de forma explícita, para que una línea copiada de un tutorial antiguo no pueda activarlo sin que te des cuenta; un forward proxy para tus propias máquinas necesita un bloque <Proxy "*"> con Require ip.
¿Cómo se prueba la configuración?
Prueba en tres pasos: la sintaxis, el backend por sí solo y el recorrido a través de Apache. Ejecuta esto en el servidor:
sudo apachectl configtest # revisa la sintaxis; indica archivo y línea del error
sudo apachectl -S # qué VirtualHost responde a cada nombre y puerto
curl -I http://127.0.0.1:3000/ # solo el backend
sudo systemctl reload apache2 # familia RHEL: sudo systemctl reload httpd
curl -I https://app.example.com/ # el recorrido completo a través de Apachecurl -I muestra solo la línea de estado y las cabeceras. Si el backend responde directamente pero no a través de Apache, el problema está en las líneas del proxy; si no responde ninguno, arranca primero la aplicación. En una redirección, la cabecera Location tiene que mostrar el nombre público, nunca 127.0.0.1. Cuando algo falle, lee el registro de errores: /var/log/apache2/error.log en Debian y Ubuntu, /var/log/httpd/error_log en los sistemas de la familia RHEL, o el archivo que indique el VirtualHost.
¿Es el mismo tipo de proxy que venden los servicios de proxy?
No. Un proxy inverso se coloca delante de tu servidor y habla en su nombre; los proxies que vende un proveedor se colocan delante de tu cliente. Los Proxies HTTPS son forward proxies: tu navegador, tu script o tu servidor les envía las peticiones salientes, y el sitio de destino ve la dirección IP del proxy.
Los dos pueden coincidir en un mismo sistema, por ejemplo cuando la aplicación que está detrás de tu Apache llama a la API de un socio que solo acepta una dirección incluida en su lista de permitidos. Los Proxies de centro de datos dan a ese tráfico saliente una dirección IPv4 dedicada y fija; los productos por IP vienen por defecto con una restricción de sitios de destino, así que comprueba que el host del socio sea accesible con tus IP.
Dónde se usan los proxies inversos con Apache
El caso clásico es un servidor de aplicaciones que no debe estar expuesto directamente a internet: una aplicación Node, Python o Go en un puerto local, o una aplicación Java en Tomcat en el puerto 8080, mientras Apache se ocupa de los certificados y los registros. Los servidores que ya usan Apache para otros sitios reciben una línea ProxyPass en lugar de un segundo servidor web. Los equipos también lo usan para reunir varias aplicaciones bajo un mismo dominio, para ejecutar PHP mediante PHP-FPM con mod_proxy_fcgi y para mantener en línea una aplicación heredada detrás de una configuración TLS actual.
Errores comunes del proxy inverso en Apache
La mayoría de los problemas deja una línea clara en el registro de errores:
Invalid command 'ProxyPass', perhaps misspelled or defined by a module not included in the server configuration:mod_proxyno está cargado. Actívalo y vuelve a ejecutarconfigtest.- 503 Service Unavailable con
AH00957: … attempt to connect to 127.0.0.1:3000 … failedyAH01114: HTTP: failed to make connection to backend: no hay nada escuchando en la dirección del backend. Arranca la aplicación o corrige el puerto. Después, Apache deja ese backend fuera de uso durante el periodo deretry=(60 segundos por defecto) y anotaAH00940 … disabled connection, así que el 503 puede durar hasta un minuto más que el problema. - 502 Bad Gateway con
Error reading from remote server: el backend aceptó la conexión, pero la cerró o se quedó en silencio más allá del tiempo de espera. Revisa el log de la propia aplicación y después los ajustes de tiempo de espera. Todas las causas de este código están reunidas en Error 502 Bad Gateway: qué significa y cómo solucionarlo. - 502 después de pasar el backend a
https://: faltaSSLProxyEngine, o el certificado del backend no coincide con su nombre. - Redirecciones a
127.0.0.1o al host interno: faltaProxyPassReverse, su URL no coincide con el destino deProxyPasso la aplicación necesitaProxyPreserveHost On. - El navegador avisa de demasiadas redirecciones: la aplicación recibe HTTP sin cifrar desde Apache y redirige a HTTPS una y otra vez. Envía
X-Forwarded-Proto "https"y dile al framework que confíe en esa cabecera. - 404 inesperados de la aplicación: la barra final no coincide entre los dos argumentos de
ProxyPass, o hay una subruta que la aplicación no conoce. - La conexión WebSocket falla o se cierra al instante: falta
upgrade=websocket, la regla de WebSocket está debajo de la regla/o el servidor usa una versión anterior a la 2.4.47 sinmod_proxy_wstunnel.
Guía de decisión
| Necesidad | Recomendación |
|---|---|
| Publicar una aplicación en un dominio | ProxyPass + ProxyPassReverse en su VirtualHost |
| La aplicación genera enlaces absolutos | ProxyPreserveHost On |
| La aplicación debe saber que hay HTTPS | RequestHeader set X-Forwarded-Proto "https" |
| HTTPS para los visitantes | VirtualHost del puerto 443 con SSLEngine on |
| El backend habla HTTPS | Destino https:// + SSLProxyEngine on |
| WebSocket con Apache 2.4.47 o posterior | upgrade=websocket |
| WebSocket con un Apache más antiguo | mod_proxy_wstunnel + ws:// |
| Las páginas lentas agotan el tiempo de espera | timeout= en esa ruta, o ProxyTimeout |
| Varios servidores de aplicaciones | balancer:// con mod_proxy_balancer |
| Dejar una ruta en manos de Apache | ProxyPass "/path/" "!" encima de la regla principal |
Preguntas frecuentes
¿Qué diferencia hay entre ProxyPass y ProxyPassReverse?
ProxyPass envía al backend las peticiones de una ruta; ProxyPassReverse reescribe la dirección del backend en las cabeceras de redirección a la vuelta. Usa los dos con los mismos argumentos, o las redirecciones de la aplicación mandarán a los visitantes a una dirección a la que no pueden llegar.
¿Necesito ProxyRequests On para un proxy inverso?
No. ProxyRequests solo controla el modo de forward proxy, y ProxyPass funciona con esa opción desactivada, que es su valor por defecto. Activarla sin reglas de acceso estrictas crea un proxy abierto que cualquiera puede usar.
¿Cómo pongo varios dominios o aplicaciones detrás de un proxy inverso con Apache?
Dale a cada dominio su propio VirtualHost con su propio ServerName y sus líneas ProxyPass, o divide un dominio por rutas con varias reglas ProxyPass, la ruta más larga primero. apachectl -S muestra qué VirtualHost responde a cada nombre.
¿Cómo paso WebSocket sobre SSL por Apache?
Termina TLS en el VirtualHost del puerto 443 como siempre y añade upgrade=websocket a la línea ProxyPass de la ruta del socket. El navegador se conecta con wss://, y Apache habla WebSocket sin cifrar con el backend local.
¿Cómo aumento el tiempo de espera del proxy inverso en Apache?
Define ProxyTimeout en el VirtualHost, o añade timeout= a una sola línea ProxyPass para cambiar solo esa ruta. Ambos valores van en segundos y, sin ellos, Apache usa el Timeout del servidor, de 60 segundos.
¿Puedo usar Apache como proxy inverso en Windows?
Sí. Las directivas son las mismas; activas mod_proxy y mod_proxy_http quitando el # de sus líneas LoadModule en conf\httpd.conf. El proyecto Apache solo publica el código fuente, así que la versión para Windows viene de una distribución de terceros.
En resumen
Un proxy inverso con Apache necesita mod_proxy con mod_proxy_http y un VirtualHost con líneas ProxyPass y ProxyPassReverse que coincidan; ProxyPreserveHost y X-Forwarded-Proto permiten que la aplicación genere URL correctas. Termina HTTPS en el puerto 443, añade upgrade=websocket para los sockets, sube timeout= solo donde las páginas sean lentas y usa balancer:// para varios backends. Mantén ProxyRequests Off, ejecuta apachectl configtest antes de cada recarga y lee el registro de errores antes de cambiar cualquier otra cosa.




