Tutoriales de VPS
Nginx proxy_pass: conservar, eliminar o sustituir el prefijo de una API
Si el backend funciona directamente pero devuelve 404 con Nginx, compara tres formas de proxy_pass y verifica la ruta upstream, los parámetros, POST y las redirecciones.

El backend responde al acceder directamente, pero devuelve 404 a través de Nginx. Antes de cambiar la configuración, compara la ruta que recibe la aplicación. El cliente solicita /api/users; el backend quizá espere /users o ya tenga definida /api/users. Una barra en proxy_pass puede enviar la petición a otra ruta.
Esta guía explica cómo conservar, eliminar o sustituir un prefijo en ubicaciones HTTP de tipo prefix. Confirma primero la URL que debe recibir el backend. Añadir reescrituras, redirecciones y fallbacks a la vez dificulta saber dónde cambió la petición.
Prueba desde el VPS las rutas reales del backend y sustituye el puerto de ejemplo por su dirección de escucha. Dentro de un contenedor, 127.0.0.1 no tiene por qué representar al host ni a otro contenedor.
curl -i 'http://127.0.0.1:3000/users?limit=1'
curl -i 'http://127.0.0.1:3000/api/users?limit=1'
curl -i 'https://app.example.com/api/users?limit=1'
sudo nginx -T
Una ruta que exige autenticación puede devolver 401 o 403 si faltan credenciales; eso no demuestra que no exista. Consulta el registro del backend para comprobar ruta, método y estado, y confirma el server y location que coinciden con el dominio. Elimina tokens, cookies y direcciones internas sensibles antes de compartir registros o configuración.
Si el registro actual incluye $status y $upstream_status, compara el estado enviado al cliente con el del upstream. Un estado upstream vacío exige revisar respuestas locales, caché y si la petición llegó al proxy. Las páginas de error personalizadas también pueden ocultar el origen; su aspecto no basta para identificarlo.
Si el backend no acepta conexiones y aparece un 502, revisa dirección, puerto y red de contenedores; consulta la guía de errores 502 y 504. Cambiar una barra normalmente no resuelve una conexión rechazada.
Supongamos una petición /api/users?limit=1, una location /api/ y ninguna reescritura adicional:
| Valor de proxy_pass | Ruta que recibe el upstream | Ruta esperada en el backend |
|---|---|---|
http://127.0.0.1:3000 | /api/users?limit=1 | Ya incluye /api/ |
http://127.0.0.1:3000/ | /users?limit=1 | Empieza en /users |
http://127.0.0.1:3000/v1/ | /v1/users?limit=1 | Necesita el prefijo /v1/ |
La diferencia relevante es si la dirección incluye una URI: / también es una URI. La referencia de proxy_pass de Nginx explica que, al incluirla, se sustituye con ella la parte coincidente del prefijo normalizado. Sin URI se conserva la URI original, con reglas específicas cuando una reescritura interna la modifica.
location /api/ {
proxy_pass http://127.0.0.1:3000;
}
Si el backend ya define /api/, no añadas la / final de este ejemplo. Esa barra eliminaría el prefijo y enviaría /users, una ruta que quizá no exista.
location /api/ {
proxy_pass http://127.0.0.1:3000/;
}
El prefijo /api/ se sustituye por /. Comprueba este mapeo antes de añadir otra regla rewrite. Si la API funciona pero la documentación o el inicio de sesión redirigen mal, revisa la URL pública de la aplicación.
location /api/ {
proxy_pass http://127.0.0.1:3000/v1/;
}
La petición /api/users llega a /v1/users. Conserva / en ambos límites. Si escribes /v1, la concatenación con el resto de la ruta puede producir /v1users, que es una ruta diferente.
Son tres alternativas de location. Elige solo la que corresponda al backend e intégrala en el sitio existente. Mantén certificados, autenticación, cabeceras, límites de peticiones y demás rutas; no introduzcas las tres en el mismo server. WebSocket y las interfaces de streaming necesitan además sus propias opciones de proxy.
Una location de prefijo terminada en / y gestionada mediante proxy puede generar automáticamente un 301 para el mismo nombre sin barra. En una configuración como /api/, /api redirige a /api/; consulta el tratamiento especial de location.
Examina el primer salto con curl sin -L. Seguir automáticamente las redirecciones puede ocultar el fallo. En callbacks de autenticación y peticiones POST, confirma método y destino finales; no dependas del comportamiento del cliente ante un 301.
Si /api debe funcionar como endpoint independiente, define una coincidencia exacta y su ruta upstream. No redirijas indiscriminadamente todas las peticiones a una versión con barra. Un prefijo normal /api/ tampoco trata /apiary como la misma ruta.
Los mapeos simples de la tabla conservan los parámetros del ejemplo. Para POST verifica también el método, el cuerpo y Content-Type. Que un GET funcione no confirma un pedido o una subida de archivos. Revisa las directivas existentes que puedan cambiar método, cuerpo o cabeceras.
Cambiar la ruta entrante no adapta automáticamente todas las URLs generadas por la aplicación. Redirecciones absolutas, recursos del HTML, Cookie Path y callbacks pueden seguir suponiendo la ruta raíz original. Configura primero la URL pública o el prefijo que la aplicación admite oficialmente; después evalúa si hace falta reescribir respuestas.
Cuando una aplicación no admite subrutas, un subdominio independiente suele ser más sencillo de mantener. Sustituir globalmente cada / por /api/ en HTML también puede modificar recursos, APIs y enlaces externos de forma incorrecta.
Las locations con expresiones regulares o con nombre, proxy_pass con variables y las peticiones modificadas mediante rewrite ... break pueden seguir reglas distintas. Si aparecen $request_uri, grupos de captura o varias redirecciones internas, contrasta cada paso con la configuración real y la documentación oficial.
Con varias locations, comprueba si otra regla más específica o una expresión regular toma el control. Conserva las peticiones originales con rutas codificadas, barras repetidas o parámetros firmados para compararlas. Los ejemplos de rutas simples no garantizan compatibilidad con codificación o firmas.
No conviertas el 404 de una API en la página principal del frontend. Aunque responda 200, el HTML seguirá fallando para un cliente que espera datos. Para recursos estáticos o recargas de una SPA, consulta la guía de 404 en Vue y React.
Guarda una copia de la configuración, valida la sintaxis y después recarga:
sudo nginx -t && sudo systemctl reload nginx
curl -i 'https://app.example.com/api/users?limit=1'
Usa peticiones de prueba permitidas para comprobar ruta upstream, parámetros, método y cuerpo. Revisa también redirecciones de inicio de sesión y recursos. Evita experimentar en producción con solicitudes que creen pedidos, cobren dinero o envíen mensajes.
El artículo original registra 12 comprobaciones aisladas con Nginx 1.19.6 y un backend simulado: los tres mapeos, parámetros, contenido POST y el 301 automático. Cuando el backend solo aceptaba /root-only, conservar el prefijo externo devolvía 404 y eliminarlo devolvía 200. Esa versión local no se recomienda como instalación de producción. Las pruebas no cubren autenticación real, TLS, CDN, WebSocket, inicio de sesión en el navegador ni reescritura de URLs en respuestas.