La discussion source de juillet 2025 a commencé par un échec d’installation de qBittorrent depuis l’App Store et s’est terminée par l’installation manuelle d’un conteneur LinuxServer.io. Auparavant, la version courte de cette page passait trop rapidement de « échec de récupération » à « utiliser LinuxServer ». La discussion complète contient un détour important concernant les versions : IceWhale a demandé à l’utilisateur de tester ZimaOS 1.4.2 beta1, car le comportement d’installation des applications y avait été amélioré ; la bêta s’est installée, mais a créé un nouveau problème lié au GPU GTX 1070 de l’utilisateur, qui est finalement revenu à la version 1.4.1.
Le conteneur qBittorrent installé manuellement a suffisamment bien fonctionné pour l’utilisateur d’origine, mais la solution de contournement historique pour l’interface Web désactivait la validation de l’en-tête Host et la protection CSRF. Cela ne doit pas être repris comme correctif par défaut dans une installation actuelle.
L’échec initial concernait la récupération d’une image
Une erreur de récupération d’image est différente d’un conteneur qui démarre, puis plante. Le dépannage doit cibler la référence de l’image, l’accès au registre, la définition de l’App Store ou la couche d’installation des applications de ZimaOS.
IceWhale a suggéré ZimaOS 1.4.2 Beta1
Zima-Giorgio a demandé à l’utilisateur d’essayer la version bêta1 de ZimaOS 1.4.2, alors la plus récente, car cette version améliorait l’installation des applications et pouvait résoudre le problème. Lorsque la mise à jour n’est pas apparue automatiquement, Giorgio a fourni la procédure officielle de mise à jour hors ligne pour cette version bêta historique.
Ces commandes appartiennent à une version de prépublication de 2025 et ne doivent pas être réutilisées sur un serveur actuel. Leur importance est historique : IceWhale considérait que l’échec de récupération depuis l’App Store pouvait être lié à la version de ZimaOS.
La version bêta a créé un autre problème pour l’utilisateur
L’utilisateur a installé la version bêta, puis est revenu à la version 1.4.1 car, selon ses propres termes, la bêta ignorait le GPU GTX 1070. Cela montre pourquoi une mise à niveau vers une version bêta visant uniquement à réparer une application doit inclure des vérifications de régression pour le reste du serveur.
Un système actuel doit utiliser la version stable actuelle de ZimaOS, sauf raison précise liée à l’assistance nécessitant de tester une version préliminaire.
L’utilisateur a ensuite installé l’image qBittorrent de LinuxServer.io
Le qBittorrent LinuxServer.io actuel utilise lscr.io/linuxserver/qbittorrent. Ses paramètres persistants et réseau importants comprennent :
-
/configpour la configuration de qBittorrent ; - un dossier de téléchargements de l’hôte mappé dans le conteneur ;
- PUID et PGID pour la propriété des fichiers ;
- un port WebUI ;
- un port d’écoute BitTorrent en TCP et UDP.
Utilisez les paramètres actuels du conteneur qBittorrent LinuxServer.io au lieu de reconstruire de mémoire la configuration de 2025.
Garder WEBUI_PORT et la correspondance des ports Docker synchronisés
L’image actuelle fournit normalement la WebUI sur le port 8080. Si vous souhaitez utiliser un autre port hôte, vous pouvez mapper ce port hôte vers le service du conteneur. Si le port WebUI interne lui-même est modifié, LinuxServer.io exige la WEBUI_PORT variable d’environnement et la correspondance Docker afin qu’elles concordent.
Un port WebUI qui ne correspond pas peut provoquer des échecs de connexion ressemblant à des problèmes d’authentification ou d’en-têtes de sécurité.
Utiliser le mot de passe temporaire du journal de démarrage
L’utilisateur à l’origine de la source a correctement indiqué que le premier mot de passe se trouvait dans les journaux. Le comportement actuel de LinuxServer.io génère un mot de passe temporaire pour le admin compte au démarrage.
Ouvrez le journal du conteneur qBittorrent, utilisez la valeur temporaire lors de la première connexion, puis définissez immédiatement un mot de passe permanent depuis la WebUI.
Ne désactivez pas HostHeaderValidation et CSRFProtection par défaut
L’utilisateur à l’origine de la source a ajouté :
WebUI\HostHeaderValidation=false
WebUI\CSRFProtection=falsevers le fichier de configuration de qBittorrent. Ils ont indiqué que l’application semblait alors fonctionner, mais que ces options affaiblissent délibérément les contrôles de sécurité destinés au navigateur.
Pour une installation actuelle, il faut d’abord résoudre correctement la configuration du port, de l’URL de l’interface Web, des en-têtes du proxy inverse et de l’authentification. Ne faites pas de « désactiver la protection CSRF » la réponse standard à un problème d’accès à l’interface Web.
Si un proxy inverse est utilisé, configurez-le correctement
Les erreurs liées à l’en-tête Host apparaissent souvent lorsqu’une application est accessible via un nom d’hôte ou un proxy que l’interface Web n’attend pas. La bonne solution consiste normalement à configurer correctement le proxy et les paramètres de l’interface Web de qBittorrent, et non à désactiver globalement toute validation.
Le trafic de l’interface Web et le trafic des pairs BitTorrent utilisent des ports différents
Le port utilisé pour administrer qBittorrent dans un navigateur n’est pas celui utilisé pour les connexions entrantes des pairs. Publiez le port d’écoute torrent choisi en TCP et en UDP, et faites correspondre ce réglage à celui du port d’écoute de qBittorrent.
Si le serveur se trouve derrière un NAT et que la connectivité entrante des pairs est souhaitée, la conception du routeur ou du VPN constitue une décision distincte du mappage des ports Docker.
Mapper les téléchargements vers le véritable stockage ZimaOS
Ne laissez pas de gros torrents s’accumuler dans la couche de conteneur temporaire ou sur un petit disque système. Mappez le répertoire de téléchargement vers l’espace de stockage ZimaOS prévu à cet effet et vérifiez que l’utilisateur du conteneur peut y écrire avant de lancer un téléchargement volumineux.
Conserver /config avant de recréer le conteneur
Les préférences, catégories, chemins et l’état de l’application qBittorrent se trouvent dans le répertoire de configuration persistant. Sauvegardez-le avant de changer d’image ou de remplacer une installation depuis l’App Store par un conteneur personnalisé.
FAQ qBittorrent sur ZimaOS
Le problème initial était-il un plantage de qBittorrent ?
Non. L’installation depuis l’App Store a échoué lors de l’étape de téléchargement de l’image Docker.
Pourquoi l’utilisateur est-il revenu de la version bêta à ZimaOS 1.4.1 ?
Ils ont signalé que la version bêta ne gérait pas leur GTX 1070 comme prévu.
D’où vient le premier mot de passe qBittorrent ?
Les conteneurs LinuxServer.io actuels affichent un mot de passe administrateur temporaire dans le journal de démarrage.
Faut-il désactiver la protection CSRF pour que l’interface Web fonctionne ?
Non comme approche par défaut. Corrigez d’abord la configuration actuelle du port, du proxy, du nom d’hôte et de l’authentification.
