Nginx como proxy inverso: configuración y diagnóstico

Nginx puede recibir peticiones HTTP y enviarlas a una aplicación que escucha en otro puerto. Eso permite centralizar TLS y acceso, pero requiere comprobar la comunicación interna. Un proxy configurado no vuelve segura una aplicación que acepta peticiones sin validación.

Este ejemplo supone Nginx instalado en Ubuntu y una aplicación de prueba escuchando en 127.0.0.1:3000. Si la aplicación está en otro contenedor o equipo, la dirección debe adaptarse a esa red.

Comprueba el servicio antes de configurar Nginx

curl -I http://127.0.0.1:3000
sudo ss -lntp

Verifica que la respuesta corresponde a tu aplicación y que escucha en la interfaz esperada. Si no responde directamente, configurar el proxy no resolverá el problema de fondo.

Crea un bloque de servidor

En el esquema habitual del paquete de Ubuntu, puedes guardar el sitio en /etc/nginx/sites-available/app-lab:

server {
    listen 80;
    server_name app.ejemplo.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Sustituye el dominio y configura su resolución hacia el servidor cuando corresponda. El ejemplo no configura HTTPS todavía. No copies reglas de otros sitios sin revisar cómo se combinan con la configuración ya cargada.

Habilita, valida y recarga

sudo ln -s /etc/nginx/sites-available/app-lab \
  /etc/nginx/sites-enabled/app-lab
sudo nginx -t
sudo systemctl reload nginx
curl -I -H 'Host: app.ejemplo.com' http://127.0.0.1

Si el enlace ya existe, revísalo en lugar de crearlo otra vez. Ejecuta reload únicamente si la validación termina correctamente. Mantén una copia del archivo anterior para revertir un cambio que afecte otras rutas.

Cabeceras y direcciones de origen

La aplicación puede necesitar conocer host y esquema originales para generar enlaces o redirecciones. Debe confiar en cabeceras del proxy solo cuando la petición proviene de un intermediario autorizado.

Si la aplicación queda accesible directamente desde internet, un cliente puede intentar enviar sus propias cabeceras. Limitar el backend a loopback o a una red interna ayuda a separar esos accesos, pero también debes configurar correctamente la confianza en proxies del framework.

Barras, rutas y WebSocket

El tratamiento de rutas en proxy_pass cambia según la forma de location y de la URL del upstream. Antes de adaptar el ejemplo a /api/, prueba qué ruta recibe la aplicación. Una barra añadida por costumbre puede alterar el prefijo.

WebSocket necesita gestionar la actualización de protocolo con una configuración apropiada. No añadas cabeceras de upgrade indiscriminadamente sin revisar el protocolo de la aplicación y la documentación oficial.

Diagnóstico de errores

Un 502 suele exigir revisar si el upstream está disponible, si la dirección es correcta y si hay un error de protocolo o permisos. Un 504 puede relacionarse con espera de respuesta. Consulta logs por hora y petición.

sudo tail -n 50 /var/log/nginx/error.log
sudo journalctl -u nginx --since "15 minutes ago" --no-pager

No aumentes todos los timeouts para ocultar una aplicación bloqueada. Distingue una operación legítimamente larga de un proceso que no responde.

Preparar HTTPS

Una vez que HTTP funciona y el dominio está bien dirigido, configura certificados con el método apropiado. Comprueba redirecciones y esquema reconocido por la aplicación.

No publiques paneles administrativos o endpoints de métricas solo porque el proxy ya responde. Define autenticación y restricciones según la función.

Preguntas frecuentes

¿El backend debe escuchar en 0.0.0.0?

No si Nginx está en el mismo host y solo él necesita acceder. Loopback suele ser suficiente para ese diseño; entre contenedores o equipos la dirección cambia.

¿Un 502 significa que Nginx está mal instalado?

No necesariamente. Puede provenir de una aplicación caída, un puerto equivocado o un protocolo incorrecto. Prueba el upstream directamente.

¿Puedo cambiar el puerto externo sin cambiar la aplicación?

Sí, el proxy puede escuchar en otro puerto o terminar TLS. Debes revisar URLs, cabeceras y políticas de acceso para que el conjunto siga siendo coherente.

En pocas palabras

Un proxy inverso recibe solicitudes y las transmite a un servicio interno. Para que funcione, deben coincidir dirección del upstream, puertos, cabeceras y restricciones de acceso.

Conclusión

Prueba cada tramo por separado: cliente a Nginx y Nginx a la aplicación. Añade HTTPS y acceso público solo después de comprender las rutas, registrar errores y conservar una configuración de retorno.

Para continuar, revisa Cómo instalar Ubuntu desde una USB: paso a paso y Cómo instalar Docker en Ubuntu 24.04: guía práctica paso a paso.

Fuentes y documentación

Documentación de docs.nginx.com.

Documentación de nginx.org.