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

Eva Wong est la rédactrice technique et bricoleuse résidente chez ZimaSpace. Geek depuis toujours, passionnée par les laboratoires informatiques personnels et les logiciels open source, elle se spécialise dans la vulgarisation de concepts techniques complexes au moyen de guides pratiques et concrets. Eva pense que l’hébergement personnel doit être amusant, et non intimidant. À travers ses tutoriels, elle aide la communauté à démystifier les configurations matérielles, de la construction de leur premier NAS à la maîtrise des conteneurs Docker.

Le fait qu’une page s’ouvre en local ne prouve pas que son chemin API fonctionne ; l’interface du navigateur et la requête du 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 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 le point du réseau concerné, 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 preuve que toute la pile est accessible.

Vérifiez si la page et l’API empruntent 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 code d’état, le corps de la réponse, l’adresse distante, l’initiateur et indiquez si l’échec concerne une requête HTTP ordinaire, un WebSocket, un événement envoyé par le serveur ou une récupération en arrière-plan.

Un cas Baserow auto-hébergé a montré une interface utilisable qui signalait continuellement une reconnexion parce que le canal d’événements du navigateur empruntait un chemin différent dans le proxy. Le symptôme visible était une connexion aux é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 fonctionne avec la requête API qui échoue : schéma, nom d’hôte, port, préfixe du chemin et chaîne de requête. S’ils diffèrent, examinez la première couche modifiée. S’ils sont identiques, poursuivez avec les en-têtes, les cookies, le traitement de la réponse et le routage du backend.

Rejouez la requête exacte depuis chaque point du réseau concerné

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 rattaché 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 au niveau TCP et HTTP, mais rejeter la véritable requête si un jeton ou un en-tête est manquant. Une discussion sur l’API FreshRSS a permis de ramener un problème externe à un contexte d’autorisation manquant, plutôt qu’à un problème général d’accessibilité du conteneur.

Interprétez le premier point de défaillance. Un échec DNS indique un problème de résolution de noms ; un refus de connexion indique un problème au niveau du service à l’écoute, du port ou du réseau ; une erreur TLS indique un problème d’identité ou de confiance ; une erreur 401 ou 403 indique un problème d’authentification ou de politique ; une erreur 404 indique souvent un problème de routage ou de réécriture du sous-chemin ; et si un appel direct réussit alors qu’un appel depuis le navigateur échoue, orientez le diagnostic vers le proxy ou les règles 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 du WebSocket, le chemin de base et les variables de compilation du frontend. Une interface servie localement peut contenir une adresse d’API absolue pointant 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 reverse proxy Frigate, l’échec des ressources a été attribué au comportement de réécriture du sous-chemin, alors que 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 configurez l’application et le proxy pour qu’ils utilisent un chemin canonique unique. Ne conservez pas d’exceptions de réécriture en double qui font fonctionner certaines méthodes alors que les téléversements, les rappels ou les points de terminaison de streaming continuent de contourner le backend prévu.

Vérifier les en-têtes du reverse proxy, le TLS et la prise en charge du streaming

Comparez la route du proxy pour les pages ordinaires avec celle utilisée pour l’API, les WebSockets et les requêtes en streaming. 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, ainsi que les en-têtes transmis pour l’hôte et le protocole.

Les utilisateurs d’Open WebUI ont signalé une interface qui semble fonctionner alors que les réponses de l’API transitant par un proxy se bloquent, car le comportement de mise en mémoire tampon ou de streaming diffère de celui d’un accès direct. Le diagnostic porte sur le chemin de streaming via le proxy, et non sur la page statique.

Transmettez le nom d’hôte et le schéma d’origine au serveur principal via des en-têtes de proxy de confiance configurés de façon restrictive. Activez les mises à niveau WebSocket uniquement sur les routes qui en ont besoin, désactivez la mise en tampon inappropriée pour les points de terminaison de streaming et vérifiez que le proxy utilise le port d’écoute interne de l’application plutôt que, par erreur, le port hôte publié.

Distinguez la politique du navigateur de l’accessibilité du serveur

Lorsqu’une commande directe réussit, mais que le navigateur échoue, examinez sa console pour repérer les erreurs CORS, de contenu mixte, de certificat, de cookie et de requête préliminaire. 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 des WebSockets et de l’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 préliminaires atteignent la même route et que les cookies de session utilisent les attributs domain, path, Secure et SameSite corrects. Évitez de désactiver globalement les protections du navigateur ; corrigez plutôt l’identité publique et la politique du serveur.

Validez l’ensemble du workflow API depuis chaque réseau requis

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

Le workflow ZimaSpace pour distinguer l’accessibilité par IP du routage par domaine est l’étape suivante lorsque les appels API directs fonctionnent avec une adresse, mais échouent via le nom d’hôte public.

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

Assistance et conseils

À lire aussi

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.