¿Qué deberías comprobar cuando una aplicación autoalojada se abre localmente, pero no se puede acceder a su API?

Que una página se abra localmente no demuestra que su ruta de API funcione; la interfaz del navegador y la solicitud al backend pueden usar hosts, puertos, protocolos o credenciales diferentes.

En un servidor doméstico, el HTML y los recursos estáticos pueden cargarse desde un proxy inverso, la caché del navegador o un contenedor web local, mientras que las llamadas a la API viajan a otro servicio, subruta, endpoint de WebSocket o URL base configurada externamente. Empieza capturando una solicitud fallida en el navegador, repitiéndola desde el límite de red correspondiente y separando después el enrutamiento, TLS, la autenticación, la política del navegador y la configuración de la aplicación, en lugar de tratar la página visible como prueba de que toda la pila es accesible.

Demuestra si la página y la API usan la misma ruta de red

Abre las herramientas de desarrollo del navegador y vuelve a cargar la acción que falla. Registra la URL de la solicitud, el método, el estado, el cuerpo de la respuesta, la dirección remota, el iniciador y si el fallo corresponde a una solicitud HTTP normal, WebSocket, evento enviado por el servidor o consulta en segundo plano.

Un caso de Baserow autoalojado mostró una interfaz utilizable que informaba repetidamente de una reconexión porque el canal de eventos seguía una ruta de proxy diferente. El síntoma visible era una conexión de eventos fallida, no una interrupción completa del servidor web.

Compara carácter por carácter la solicitud correcta del documento con la solicitud fallida a la API: esquema, nombre de host, puerto, prefijo de ruta y cadena de consulta. Si difieren, investiga la primera capa que cambió. Si son idénticos, continúa con las cabeceras, las cookies, el procesamiento de la respuesta y el enrutamiento del backend.

Repite la solicitud exacta desde cada límite de red relevante

Copia una solicitud fallida como comando y repítela desde el cliente, el host del proxy inverso y un contenedor temporal conectado a la red de la aplicación. Conserva el método, la cabecera de autorización, el tipo de contenido, el cuerpo y el nombre de host esperado.

Una API puede ser accesible en las capas TCP y HTTP y aun así rechazar la solicitud real porque falta un token o una cabecera. Una conversación sobre la API de FreshRSS acotó un fallo externo a la falta de contexto de autorización, no a una falta general de conectividad del contenedor.

Interpreta el primer límite que falla. Un fallo de DNS apunta a la resolución de nombres; el rechazo de conexión apunta al proceso que escucha, al puerto o a la red; un error de TLS apunta a la identidad o la confianza; los códigos 401 o 403 apuntan a la autenticación o la política; un 404 suele apuntar al enrutamiento o a la reescritura de subrutas; y una llamada directa correcta junto con una llamada fallida desde el navegador orienta el diagnóstico hacia las reglas del proxy o del navegador.

Comprueba la URL base de la API, el puerto y la subruta

Inspecciona la URL pública de la aplicación, la URL de la API, la URL de WebSocket, la ruta base y las variables de compilación del frontend. Una interfaz servida localmente puede contener una dirección absoluta de la API que apunte a un dominio antiguo, una IP privada, un puerto incorrecto o una ruta raíz que solo existe en el servidor.

Las implementaciones en subrutas son especialmente sensibles al uso de barras y a las reglas de reescritura. Un caso de Frigate tras un proxy inverso atribuyó los recursos fallidos al comportamiento de reescritura de subrutas, aunque se podía acceder a la interfaz principal.

Prueba el endpoint de la API con y sin el prefijo configurado únicamente para identificar la ruta correcta; después, configura la aplicación y el proxy para que coincidan en una única ruta canónica. No mantengas excepciones de reescritura duplicadas que hagan funcionar algunos métodos mientras las cargas, las devoluciones de llamada o los endpoints de transmisión siguen evitando el backend previsto.

Featured

ZimaCube 2 NAS personal en la nube para el hogar

ZimaCube2

$799.00 - $2,499.00

Buy Now

Verifica las cabeceras del proxy inverso, TLS y la compatibilidad con la transmisión

Compara la ruta del proxy para las páginas normales con la ruta para las solicitudes de API, WebSocket y transmisión. Confirma el nombre del servicio ascendente, el puerto interno, la versión HTTP, el comportamiento de actualización de la conexión, el tiempo de espera de lectura, la política de almacenamiento en búfer y las cabeceras reenviadas de host y protocolo.

Usuarios de Open WebUI han informado de una interfaz que parece funcionar mientras la salida de la API a través del proxy se detiene porque el almacenamiento en búfer o el comportamiento de transmisión difieren del acceso directo. El foco del diagnóstico es la ruta de transmisión a través del proxy, no la página estática.

Envía el nombre de host y el esquema originales al backend mediante cabeceras de proxy de confianza configuradas de forma restringida. Activa las actualizaciones de WebSocket solo en las rutas que las necesiten, desactiva el almacenamiento en búfer inadecuado para los endpoints de transmisión y verifica que el proxy utilice el proceso que escucha internamente en la aplicación, en lugar del puerto del host publicado por accidente.

Separa la política del navegador de la accesibilidad del servidor

Cuando un comando directo funciona pero el navegador falla, inspecciona la consola del navegador en busca de errores de CORS, contenido mixto, certificados, cookies y solicitudes previas. El servidor puede responder correctamente mientras el navegador se niega a exponer o enviar la solicitud.

Una conversación sobre Open WebUI tras un proxy inverso relaciona los fallos de WebSocket y de la API con el origen y el manejo del protocolo reenviado, lo que demuestra por qué la identidad del origen y del protocolo debe mantenerse coherente a través del proxy.

Confirma que una página HTTPS nunca llame a una API HTTP, que la API permita únicamente el origen necesario, que las solicitudes previas lleguen a la misma ruta y que las cookies de sesión usen el dominio, la ruta y los atributos Secure y SameSite correctos. Evita desactivar globalmente las protecciones del navegador; corrige en su lugar la identidad pública y la política del servidor.

Valida el flujo completo de la API desde todas las redes necesarias

Después de que funcione la primera solicitud fallida, prueba el inicio de sesión, la enumeración o búsqueda, la creación o actualización, la carga, la descarga, los eventos en segundo plano y una renovación del token desde la LAN y desde todas las rutas remotas compatibles. Una única solicitud GET correcta no demuestra que las escrituras autenticadas o las conexiones de larga duración estén reparadas.

El flujo de ZimaSpace para separar la accesibilidad por IP del enrutamiento por dominio es el siguiente paso cuando las llamadas directas a la API funcionan mediante la dirección, pero fallan a través del nombre de host público.

El problema solo está resuelto cuando el navegador y el cliente ajeno al navegador utilizan el endpoint canónico previsto, el proxy llega al backend correcto, la autenticación sobrevive a las redirecciones, la política del navegador acepta la respuesta y las sesiones de transmisión o WebSocket permanecen estables. Conserva la solicitud fallida capturada como prueba de regresión para futuras actualizaciones.