Que devez-vous vérifier lorsqu’une application auto-hébergée s’ouvre en local, mais que son API est inaccessible ?

Le fait qu’une page s’ouvre localement ne prouve pas que son chemin d’API fonctionne ; l’interface du navigateur et la requête vers le backend peuvent utiliser des hôtes, des ports, des protocoles ou des identifiants différents.

Sur un serveur domestique, le HTML et les ressources statiques peuvent être chargés depuis un proxy inverse, le cache du navigateur ou un conteneur web local, tandis que les appels d’API passent par un autre service, un sous-chemin, un point de terminaison WebSocket ou une URL de base configurée en externe. Commencez par capturer une requête en échec dans le navigateur, rejouez-la depuis la frontière réseau concernée, puis distinguez le routage, TLS, l’authentification, les règles du navigateur et la configuration de l’application, au lieu de considérer la page visible comme la preuve que toute la pile est accessible.

Vérifier si la page et l’API utilisent le même chemin réseau

Ouvrez les outils de développement du navigateur et rechargez l’action qui échoue. Notez l’URL de la requête, la méthode, le statut, le corps de la réponse, l’adresse distante, l’initiateur et indiquez s’il s’agit d’une requête HTTP standard, d’un WebSocket, d’un événement envoyé par le serveur ou d’une récupération en arrière-plan.

Un cas Baserow auto-hébergé montrait une interface utilisable qui signalait constamment une reconnexion, car le canal d’événements suivait un chemin de proxy différent. Le symptôme visible était une connexion d’événements en échec, et non une panne complète du serveur web.

Comparez caractère par caractère la requête du document qui réussit et celle de l’API qui échoue : schéma, nom d’hôte, port, préfixe de chemin et chaîne de requête. S’ils diffèrent, examinez la première couche qui change. S’ils sont identiques, poursuivez avec les en-têtes, les cookies, le traitement de la réponse et le routage du backend.

Rejouer la requête exacte depuis chaque frontière concernée

Copiez une requête en échec sous forme de commande et rejouez-la depuis le client, l’hôte du proxy inverse et un conteneur temporaire connecté au réseau de l’application. Conservez sa méthode, son en-tête d’autorisation, son type de contenu, son corps et le nom d’hôte attendu.

Une API peut être accessible aux niveaux TCP et HTTP tout en rejetant la requête réelle parce qu’un jeton ou un en-tête est absent. Une discussion sur l’API FreshRSS a ramené un échec externe à un contexte d’autorisation manquant, plutôt qu’à un problème général d’accessibilité du conteneur.

Interprétez la première frontière qui échoue. Une erreur DNS indique un problème de résolution de noms ; un refus de connexion pointe vers l’écouteur, le port ou le réseau ; une erreur TLS concerne l’identité ou la confiance ; les erreurs 401 ou 403 indiquent un problème d’authentification ou de stratégie ; une erreur 404 signale souvent un problème de routage ou de réécriture d’un sous-chemin ; et un appel direct réussi associé à un appel échoué dans le navigateur oriente le diagnostic vers les règles du proxy ou du navigateur.

Vérifier l’URL de base, le port et le sous-chemin de l’API

Inspectez l’URL publique de l’application, l’URL de l’API, l’URL WebSocket, le chemin de base et les variables définies lors de la compilation du frontend. Une interface servie localement peut contenir une adresse d’API absolue qui pointe vers un ancien domaine, une adresse IP privée, un port incorrect ou un chemin racine qui n’existe que sur le serveur.

Les déploiements sur un sous-chemin sont particulièrement sensibles à la gestion des barres obliques et aux règles de réécriture. Dans un cas de proxy inverse Frigate, l’échec du chargement des ressources a été attribué au comportement de réécriture du sous-chemin, même si l’interface principale restait accessible.

Testez le point de terminaison de l’API avec et sans le préfixe configuré uniquement pour identifier la route correcte, puis corrigez l’application et le proxy afin qu’ils utilisent un chemin canonique unique. Ne conservez pas de multiples exceptions de réécriture qui permettent à certaines méthodes de fonctionner tandis que les téléversements, les rappels ou les points de terminaison de diffusion continuent de contourner le backend prévu.

Featured

ZimaCube 2 NAS personnel Cloud à domicile

ZimaCube2

$799.00 - $2,499.00

Buy Now

Vérifier les en-têtes du proxy inverse, TLS et la prise en charge de la diffusion

Comparez la route du proxy pour les pages standard avec celle des requêtes d’API, WebSocket et de diffusion. Vérifiez le nom du service en amont, le port interne, la version HTTP, le comportement de mise à niveau de la connexion, le délai d’attente de lecture, la politique de mise en mémoire tampon et les en-têtes d’hôte et de protocole transmis.

Des utilisateurs d’Open WebUI ont signalé une interface qui semblait fonctionnelle alors que la sortie de l’API relayée par proxy se bloquait, car le comportement de mise en mémoire tampon ou de diffusion différait de l’accès direct. Le diagnostic doit se concentrer sur le chemin de diffusion via le proxy, et non sur la page statique.

Transmettez le nom d’hôte et le schéma d’origine au backend au moyen d’en-têtes de proxy de confiance configurés de manière restrictive. Activez les mises à niveau WebSocket uniquement sur les routes qui en ont besoin, désactivez la mise en mémoire tampon inappropriée pour les points de terminaison de diffusion et vérifiez que le proxy utilise l’écouteur interne de l’application, plutôt que le port publié de l’hôte par inadvertance.

Distinguer les règles du navigateur de l’accessibilité du serveur

Lorsqu’une commande directe réussit mais que le navigateur échoue, consultez la console du navigateur pour rechercher des erreurs CORS, de contenu mixte, de certificat, de cookie et de pré-vérification. Le serveur peut répondre correctement alors que le navigateur refuse d’exposer ou d’envoyer la requête.

Une discussion sur Open WebUI derrière un proxy inverse associe les échecs WebSocket et d’API à la gestion de l’origine et du protocole transmis, montrant pourquoi l’identité de l’origine et du protocole doit rester cohérente à travers le proxy.

Vérifiez qu’une page HTTPS n’appelle jamais une API HTTP, que l’API n’autorise que l’origine requise, que les requêtes de pré-vérification atteignent la même route et que les cookies de session utilisent le domaine, le chemin ainsi que les attributs Secure et SameSite appropriés. Évitez de désactiver globalement les protections du navigateur ; corrigez plutôt l’identité et la stratégie publiques du serveur.

Valider l’ensemble du flux d’API depuis chaque réseau requis

Une fois la première requête en échec fonctionnelle, testez la connexion, la liste ou la recherche, la création ou la mise à jour, le téléversement, le téléchargement, les événements en arrière-plan et un renouvellement de jeton depuis le réseau local et chaque chemin distant pris en charge. Un seul GET réussi ne prouve pas que les écritures authentifiées ou les connexions longue durée sont rétablies.

Le flux ZimaSpace consacré à la distinction entre l’accessibilité par IP et le routage par domaine constitue l’étape suivante lorsque les appels directs à l’API fonctionnent par adresse mais échouent via le nom d’hôte public.

Le problème n’est résolu que lorsque le navigateur et le client non navigateur utilisent le point de terminaison canonique prévu, que le proxy atteint le bon backend, que l’authentification est conservée lors des redirections, que la politique du navigateur accepte la réponse et que les sessions de diffusion ou WebSocket restent stables. Conservez la requête en échec capturée comme test de régression pour les futures mises à niveau.