2026 : échec d’installation des plugins Dify auto-hébergé ? Vérifiez d’abord Plugin Daemon

Le journal officiel des versions de Dify indique la publication de la version 1.18.0 le 23 octobre 2026 et renvoie à sa documentation de déploiement. Ce repère ne donne pas une configuration universelle : il confirme plutôt pourquoi il faut examiner les fichiers associés à la version que vous utilisez.

Cet article s’adresse à vous si vous administrez une installation auto-hébergée de Dify et que l’installation d’un plugin ou l’ouverture de sa page de gestion échoue.
Il s’adresse aussi aux personnes qui maintiennent un fichier Docker Compose personnalisé après une mise à niveau, et aux responsables qui évaluent la capacité d’un déploiement à fonctionner durablement.

Échec d’installation des plugins Dify auto-hébergé : symptômes différents, diagnostics différents

Ne commencez pas par redémarrer tous les services ni par modifier leur adresse. Notez d’abord l’action qui échoue et le message exact. Une installation interrompue, une page de gestion qui ne charge pas et une requête API refusée ne désignent pas nécessairement la même panne ; les regrouper sous « Plugin Daemon est hors service » peut vous faire corriger le mauvais composant.

Distinguez notamment ces situations :

• L’installation échoue, mais la page de gestion s’ouvre. Le problème peut concerner la requête de création ou le démarrage d’un plugin, plutôt que la connexion générale entre l’API et Daemon.
• La page de gestion ne charge pas ou affiche une erreur. Relevez le message visible, puis vérifiez si une requête correspondante apparaît dans les journaux de l’API et de Daemon.
• L’API indique une connexion refusée ou un délai dépassé. Cela oriente vers une adresse, un service à l’arrêt, un réseau ou un port inaccessible. Il faut confirmer ces pistes depuis le conteneur API.
• Les journaux contiennent une erreur liée au SDK d’un plugin. Elle peut concerner l’initialisation d’un plugin particulier. Elle ne démontre pas à elle seule que Daemon ne répond pas.

Pour conserver des éléments exploitables, notez l’heure de l’action, l’écran concerné, le texte complet de l’erreur et le service dont le journal contient un message correspondant. Un avertissement isolé, surtout s’il n’est pas lié temporellement à l’action qui échoue, n’est pas une preuve suffisante. Les problèmes publiés dans le dépôt officiel sont des signalements individuels : ils montrent que des utilisateurs rencontrent des symptômes, mais ne prouvent pas qu’une cause unique explique tous les cas.

Connexion API–Daemon : nom de service avant adresse IP

Dans un déploiement Compose, les services communiquent selon la configuration des réseaux et les noms déclarés pour le service. Docker documente cette découverte de service dans son guide sur le réseau Compose. L’adresse IP actuelle d’un conteneur n’est donc pas un substitut fiable au nom de service configuré : elle peut changer à la recréation du conteneur.

Commencez par vérifier que vous observez le projet Compose réellement exécuté, et non un fichier voisin ou une ancienne copie. Depuis le répertoire du déploiement, ces commandes permettent d’établir l’état des services et de lire leurs journaux :

docker compose ps
docker compose logs --since=10m api plugin_daemon

Les noms api et plugin_daemon sont des exemples à remplacer si votre fichier déclare d’autres services. Si la commande ne trouve pas l’un d’eux, vérifiez les noms de service dans votre configuration avant d’en conclure qu’il est absent.

Ensuite, testez la résolution du nom de Daemon depuis le conteneur API, car un test depuis votre poste ou depuis l’hôte ne valide pas le même chemin réseau :

docker compose exec api sh -lc 'getent hosts plugin_daemon'

Adaptez les noms à votre déploiement. Si l’outil de résolution n’est pas présent dans l’image, utilisez un outil disponible dans le conteneur ou un test équivalent ; l’absence de getent n’est pas, en soi, la preuve d’un défaut réseau.

Interprétez le résultat avec prudence :

• Aucune résolution du nom configuré : comparez le nom de service, les réseaux attribués aux conteneurs et le fichier Compose actif.
• Nom résolu, mais connexion impossible : vérifiez l’état de Daemon, l’adresse interne configurée et la disponibilité du port attendu par cette version.
• Connexion établie, mais réponse applicative en erreur : poursuivez l’examen des clés, des URL et des journaux applicatifs.

N’inscrivez pas une IP observée dans une configuration comme correction durable avant d’avoir identifié la raison pour laquelle le nom de service ne fonctionne pas. Une adresse codée en dur peut masquer temporairement le problème, puis devenir incorrecte après une recréation.

Adresses internes et clés : même mode de déploiement des deux côtés

Une résolution DNS correcte ne suffit pas : l’API doit viser l’adresse attendue par Daemon, et les paramètres d’authentification requis doivent être cohérents. Dify fournit un modèle officiel de variables d’environnement pour Plugin Daemon. Utilisez-le comme document de comparaison, non comme bloc à copier sans vérification : les variables et leur rôle doivent correspondre à votre version et à votre mode d’installation.

Contrôlez chaque valeur avec son origine :

• Où l’URL de Daemon est-elle définie dans votre déploiement ?
• Cette URL vise-t-elle un nom de service accessible depuis le conteneur API, ou une adresse réservée à un autre contexte ?
• Les clés concernées sont-elles renseignées là où l’API et Daemon les attendent ?
• Les deux services utilisent-ils les fichiers d’environnement et le réseau prévus ensemble ?

Une confusion fréquente concerne localhost. Dans un conteneur, cette adresse désigne le conteneur lui-même, pas automatiquement un autre service du projet. Si l’API utilise une URL avec localhost pour joindre Daemon, confrontez-la à la documentation de déploiement et au nom du service dans Compose avant de la corriger.

Évitez également de mélanger des paramètres d’une installation entièrement conteneurisée avec des exemples conçus pour un environnement de développement ou un service externe. Comparez les valeurs effectives des conteneurs aux fichiers utilisés pour démarrer le projet ; ne vous contentez pas de lire un fichier .env qui n’est peut-être pas chargé.

Mise à niveau et Compose personnalisé : contrôler les fichiers assortis

Un fichier Compose conservé puis modifié manuellement peut diverger du modèle correspondant à la version installée. Après une mise à niveau, vérifiez ensemble le fichier de déploiement, le modèle d’environnement et l’étiquette des images. Dify fournit, pour la version 1.18.0, une documentation officielle de déploiement Docker, un fichier Compose versionné et un modèle d’environnement versionné.

Ces documents constituent un point de comparaison pour cette version, pas une recette à appliquer indistinctement à toutes les installations. Si vous utilisez une autre version, partez de ses propres fichiers. Le numéro d’image de Daemon doit être comparé à la version et à la configuration de Dify effectivement déployées, plutôt qu’à une valeur retenue d’un ancien tutoriel.

Procédez par différence, pas par remplacement global :

• Comparez les noms de services, les réseaux et les dépendances de démarrage.
• Vérifiez les références d’images réellement chargées par le projet.
• Repérez les variables attendues par le modèle officiel de cette version, puis confirmez qu’elles sont fournies au bon service.
• Identifiez toute personnalisation locale avant de réappliquer une modification officielle.
• Gardez une copie de la configuration précédente afin de pouvoir revenir en arrière si un changement ciblé aggrave la panne.

Compose peut ordonner le démarrage des services, mais cet ordre ne garantit pas à lui seul que l’application distante est prête à répondre. La documentation Docker sur l’ordre de démarrage distingue le lancement des conteneurs et les conditions de disponibilité. Si Daemon démarre après l’API ou met du temps à devenir opérationnel, examinez l’état observé et le comportement après démarrage ; ne transformez pas une hypothèse de course au démarrage en diagnostic certain sans la reproduire.

Liste de contrôle : isoler, corriger et valider

Suivez ces étapes dans l’ordre. Elles limitent les changements non réversibles et conservent une trace claire de ce qui a rétabli le service.

• [ ] Décrire le symptôme. Notez si l’échec porte sur l’installation, la page de gestion ou une requête API, avec le message exact et l’heure.
• [ ] Relever les états. Exécutez docker compose ps, puis consultez les journaux de l’API et de Daemon autour de l’action. Distinguez un conteneur arrêté d’une application démarrée mais en erreur.
• [ ] Tester la découverte depuis l’API. Résolvez le nom de service de Daemon depuis le conteneur API, en utilisant les noms du fichier réellement lancé.
• [ ] Vérifier le chemin réseau. Si le nom se résout, testez l’adresse et le port prévus par la configuration de la version en place. Notez le résultat et l’outil utilisé.
• [ ] Comparer URL et clés. Confrontez les valeurs effectives aux modèles officiels ; vérifiez qu’elles appartiennent au même mode de déploiement et ne pointent pas vers localhost par erreur.
• [ ] Aligner les versions. Comparez les étiquettes des images, le Compose et le modèle d’environnement à la documentation officielle de la version installée.
• [ ] Modifier un seul élément à la fois. Après chaque changement, redémarrez uniquement ce qui est nécessaire selon votre procédure, puis répétez le test qui avait échoué.
• [ ] Valider de bout en bout. Vérifiez que la page de gestion se charge, que l’installation d’un plugin aboutit et que l’opération API concernée ne reproduit plus l’erreur. Conservez la version, les fichiers et les journaux utiles.

Un test réseau réussi n’équivaut pas à une validation fonctionnelle. Inversement, un message SDK dans les journaux ne justifie pas une modification du réseau si l’API joint Daemon et que le problème concerne l’initialisation d’un plugin. La correction doit correspondre à une cause observée et être confirmée par la répétition de l’action qui échouait.

Après rétablissement : distinguer panne de configuration et capacité serveur

Un échec de requête Plugin Daemon n’est pas, par défaut, un signe que votre serveur manque de ressources. Si les conteneurs sont actifs, que le réseau répond et que les journaux montrent une incohérence d’adresse, de clé ou de version, changer d’hébergement ne corrigera pas cette configuration. Consignez la version, le Compose effectif, les valeurs vérifiées et le résultat de l’essai de bout en bout : vous pourrez distinguer une récidive de déploiement d’une contrainte durable de capacité.

Pour un usage prolongé, évaluez séparément la charge totale : Dify et ses services associés, les données conservées, les sauvegardes que vous organisez et les autres applications installées sur la machine. Le nombre de services, leur consommation observée en fonctionnement et l’espace réellement occupé sont plus utiles qu’une estimation générique de configuration. Vous pouvez rapprocher ces mesures de notre guide sur la mémoire et le stockage d’un serveur, puis consulter les limites et caractéristiques du service avant de choisir un hébergement.

Une instance partagée peut être suffisante si la charge est légère et que ses limites conviennent à votre usage. En revanche, si des processus voisins partagent le calcul, si vous ne pouvez pas maîtriser les ressources affectées ou si vous devez faire tourner plusieurs services durablement, un serveur physique AMD dédié proposé par OSFP Cloud peut mieux correspondre à ce besoin d’exploitation stable. Cela ne remplace pas la vérification de Plugin Daemon : comparez d’abord vos mesures et vos exigences aux informations produit disponibles, puis retenez la solution dont les ressources, le stockage et le système répondent effectivement à votre déploiement. Les conditions de connexion et d’administration sont également à vérifier dans notre guide sur l’accès au serveur par shell.

Questions fréquentes

Erreur de requête vers Plugin Daemon

Relevez d’abord l’erreur et l’heure, puis comparez les journaux de l’API et de Daemon. Vérifiez depuis le conteneur API la résolution du nom de service, l’accès à l’adresse configurée et l’état des deux services. Si la connexion fonctionne, confrontez les clés et les versions avant de modifier la configuration.

Plugin impossible à installer : réseau ou autre cause ?

Pas nécessairement un problème réseau. Une résolution impossible ou une connexion refusée oriente vers le réseau ou le service ; une clé incorrecte ou une erreur d’initialisation peut pointer ailleurs. Corrélez le message affiché avec les journaux et un test effectué depuis le conteneur API, plutôt que de conclure à partir d’un avertissement SDK isolé.

Vérifier la connexion depuis le conteneur API

Utilisez le projet Compose actif pour ouvrir un shell dans le service API et résoudre le nom de service configuré pour Daemon. Si la résolution réussit, testez ensuite l’adresse et le port indiqués dans les fichiers de la version installée. Comparez ces résultats aux journaux : la résolution du nom ne confirme pas, à elle seule, que l’application répond correctement.

Page de gestion des plugins en erreur

Comparez l’adresse interne de Daemon, l’URL utilisée par l’API et les clés attendues par les deux services. Vérifiez aussi que les images, le fichier Compose et le modèle d’environnement correspondent à la même version et au même mode d’installation. Dans un conteneur, localhost désigne ce conteneur, pas son voisin.

Si le défaut persiste après ces vérifications, gardez les journaux et la configuration expurgée des secrets pour rapprocher le symptôme des fichiers officiels de votre version. Pour un déploiement durable, utilisez ensuite les données de capacité réellement observées afin de comparer une instance partagée à un serveur AMD dédié. Vous pouvez examiner les offres et les conditions d’OSFP Cloud ; le choix du serveur relève de la planification de charge, pas d’un correctif automatique à une erreur de Plugin Daemon.

Questions

Que vérifier quand Dify affiche une erreur de requête vers Plugin Daemon ?

Commencez par relever le message affiché, puis comparez-le aux journaux de l’API et de Plugin Daemon au même moment. Vérifiez ensuite la résolution du nom de service depuis le conteneur API, l’accès à l’adresse configurée et l’état des deux conteneurs. Si le réseau répond, confrontez les clés, les URL et les fichiers Compose à la version réellement déployée avant de modifier une valeur.

Une installation de plugin qui échoue indique-t-elle forcément un problème réseau ?

Non. Une résolution de nom impossible ou une connexion refusée oriente vers le réseau, le service ou son adresse, mais une erreur de clé, une configuration incohérente ou un échec d’initialisation du plugin peut produire un symptôme différent. Appuyez-vous sur les journaux corrélés et sur un test effectué depuis le conteneur API ; ne déduisez pas la cause d’une seule ligne mentionnant le SDK.

Comment tester la connexion à Plugin Daemon depuis le conteneur API ?

Avec le fichier Compose réellement utilisé, ouvrez un shell dans le service API et tentez de résoudre le nom de service configuré pour Plugin Daemon. Si la résolution fonctionne, testez ensuite l’adresse et le port indiqués par cette configuration, à l’aide d’un outil disponible dans le conteneur. Comparez le résultat aux journaux : un nom résolu ne prouve pas, à lui seul, que l’API applicative répond.

La page de gestion des plugins Dify échoue : quelles configurations comparer ?

Vérifiez que l’API et Plugin Daemon utilisent les paramètres prévus pour le même mode de déploiement : URL interne, adresse de service et clés partagées concernées. Comparez ces valeurs aux modèles officiels correspondant à votre version. Dans un conteneur, localhost désigne ce conteneur lui-même ; ne l’utilisez pas pour joindre l’autre service sans validation explicite.