Operating Hydranos FR

🇬🇧 English · 🇫🇷 Français

Exploiter Hydranos

S'applique à Hydranos 4.4.

Pour qui fait tourner une instance au quotidien : comment l'arrêter sans perdre l'état de reprise, ce que font les boutons de redémarrage, à quoi ressemble le démarrage, quoi sauvegarder et comment le restaurer, que faire quand le store refuse de s'ouvrir ou que le mot de passe est perdu, et comment mettre à jour sous Docker, Linux et Windows.

En bref : chaque arrêt et chaque redémarrage (Docker, systemd, la zone de notification, les boutons de redémarrage de l'interface web) passe par le même arrêt propre ; gardez la limite d'arrêt du superviseur au-dessus de HYDRANOS_STOP_TIMEOUT + 10 s. Pour sauvegarder : arrêtez Hydranos, copiez son ou ses dossiers, redémarrez-le.

Démarrer et arrêter

Plateforme	Démarrer	Arrêt propre
Docker	docker compose up -d	docker compose stop / docker stop hydranos (SIGTERM, puis SIGKILL à la fin du délai de grâce)
Linux (systemd)	sudo systemctl start hydranos	sudo systemctl stop hydranos (SIGTERM, puis SIGKILL après TimeoutStopSec)
Linux (dans un shell)	hydranos --config /path/to/default.toml	Ctrl+C (SIGINT) ou kill <pid> (SIGTERM)
Windows	hydranos.exe (double-clic, raccourci ou dossier Démarrage ; --config facultatif)	zone de notification › Quit Hydranos ; dans une console (--console), Ctrl+C, Ctrl+Pause ou fermeture de la fenêtre

Hydranos s'arrête de la même façon quel que soit le déclencheur (signal, zone de notification, événement de console, demande d'arrêt de l'outil de mise à jour Windows, redémarrage demandé depuis l'interface ou l'API) :

1. Le flux d'événements de l'interface (/api/events) et le suivi en direct des Journaux (Logs) se terminent d'eux-mêmes ; le serveur HTTP cesse d'accepter des connexions et laisse se terminer les requêtes en cours, pendant 5 s au plus.
2. Départs : chaque torrent qui a annoncé started envoie stopped à ses trackers, moteurs race d'abord, 5 s au plus pour l'ensemble.
3. L'état de reprise de chaque moteur est écrit (chaque moteur sur son propre thread, en parallèle), dans la limite de HYDRANOS_STOP_TIMEOUT.
4. Les tunnels WireGuard gérés sont démontés.
5. Sortie avec le code 0, ou 75 quand l'arrêt est un redémarrage (voir Redémarrer depuis l'interface).

Rien n'est écrit dans le store à ce moment-là : les modifications du store sont validées au fil de l'eau.

sequenceDiagram
    participant S as Superviseur - Docker, systemd ou vous
    participant M as hydranos
    participant H as Serveur HTTP
    participant T as trackers
    participant R as Thread du moteur race
    participant D as Thread du moteur hoard
    S->>M: SIGTERM, SIGINT, Ctrl+C, un événement de console Windows, Quit Hydranos dans la zone de notification ou une demande de redémarrage
    M->>H: fin du flux d'événements et du suivi du journal, cesse d'accepter des connexions
    H-->>M: requêtes en cours terminées, ou 5 s écoulées
    M->>T: stopped pour chaque torrent démarré, race d'abord, 5 s au plus
    par un thread par moteur
        M->>R: écrit chaque ligne de reprise dans race/state.db
        R-->>M: resume data saved, took_ms
    and
        M->>D: écrit chaque ligne de reprise dans hoard/state.db
        D-->>M: resume data saved, took_ms
    end
    alt chaque moteur a fini dans HYDRANOS_STOP_TIMEOUT
        M->>M: journalise shutdown flush complete, took_s
    else budget atteint
        M->>M: journalise WARN shutdown flush hit HYDRANOS_STOP_TIMEOUT, part avec ce qui est enregistré
    end
    M->>M: démonte les tunnels WireGuard gérés
    M-->>S: code de sortie 0, ou 75 pour un redémarrage
    Note over S,M: Si le délai de grâce du superviseur expire avant, il envoie SIGKILL.<br/>Les lignes pas encore écrites retombent sur la dernière sauvegarde à 300 s.

Loading

Les moteurs supplémentaires ont chacun leur thread de la même manière. Ce que vous voyez dans le journal (Linux) :

WARN SIGTERM received, draining the API and flushing resume data
INFO stopped sent to the trackers departed=… of=…
INFO resume data saved engine=race took_ms=…
INFO resume data saved engine=hoard took_ms=…
INFO shutdown flush complete took_s=…

La ligne stopped sent to the trackers n'est absente que si aucun torrent n'avait annoncé started. La première ligne nomme le déclencheur (SIGINT, restart request…) ; sous Windows, elle s'écrit <trigger>: draining the API and flushing resume data, par exemple tray quit:, console closed:, system shutdown:. Un onglet qui garde encore une connexion après 5 s ajoute WARN connections still open 5 s into the drain (event stream, log tail); flushing without them. Avec WireGuard géré, INFO wireguard: tunnels taken down tunnels=… suit l'écriture.

Un arrêt demandé pendant le chargement du catalogue est pris en compte : le chargement se termine, rien d'autre ne démarre, et Hydranos journalise stop requested during startup; flushing and leaving, envoie les départs, écrit l'état de reprise et se termine.

Laissez assez de temps au superviseur

HYDRANOS_STOP_TIMEOUT (120 par défaut) borne l'écriture : au-delà, Hydranos cesse d'attendre, journalise shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved (budget_s=…) et se termine avec ce qui est écrit ; le state.db de chaque moteur valide par transaction, donc ce qui a été écrit le reste. Formes acceptées : 120, 60s, 2m, 1m30s, 1h (unités de la plus grande à la plus petite, chacune une fois). Toute autre valeur (30s1m, 1.5m, -5, vide) est refusée au démarrage avec WARN HYDRANOS_STOP_TIMEOUT="…" is not a duration (use 120, 60s, 2m or 1m30s); using 120 s. 0 signifie partir sans attendre l'écriture. La valeur est lue une seule fois, au démarrage.

Un arrêt prend au plus environ 5 s (vidange) + 5 s (départs) + HYDRANOS_STOP_TIMEOUT, soit 130 s par défaut. La limite du superviseur doit être au-dessus, sinon il tue l'écriture :

Superviseur	Réglage	Valeur livrée	À régler sur
Docker Compose	stop_grace_period	150s dans le fichier compose du dépôt	HYDRANOS_STOP_TIMEOUT + 10 s ou plus
docker run / Unraid	--stop-timeout	10 s par défaut dans Docker (installation de nœud par install.sh : 150)	idem ; Docker utilise 150
systemd	TimeoutStopSec	150 dans packaging/hydranos.service	idem
Windows	HYDRANOS_STOP_TIMEOUT lui-même (120 s par défaut)	—	quittez depuis la zone de notification avant d'éteindre Windows (à la déconnexion ou à l'arrêt, Windows n'accorde que quelques secondes) ; jamais avec Fin de tâche (End task)

Si vous augmentez HYDRANOS_STOP_TIMEOUT pour un gros catalogue, augmentez la limite du superviseur en même temps. Mesurez votre propre durée d'écriture après un arrêt :

docker logs hydranos 2>&1 | grep "shutdown flush"     # Docker
journalctl -u hydranos | grep "shutdown flush"        # systemd

Sous Windows, le journal est hydranos.log dans le dossier de configuration : findstr /C:"shutdown flush" C:\Hydranos\hydranos.log.

Si vous voyez SIGTERM received… mais ni shutdown flush complete ni shutdown flush hit HYDRANOS_STOP_TIMEOUT avant que le processus meure, le superviseur l'a tué avant : sa limite est inférieure à HYDRANOS_STOP_TIMEOUT + 10 s.

Arrêt de l'array Unraid, et conteneur VPN

• Arrêt de l'array. Arrêter l'array (ou le service Docker) arrête tous les conteneurs ; le mainteneur n'a pas testé si Unraid respecte alors le --stop-timeout du conteneur. Arrêtez d'abord vous-même le conteneur hydranos dans l'onglet Docker, attendez qu'il apparaisse arrêté, puis arrêtez l'array. Aucune ligne shutdown flush dans docker logs hydranos signifie que l'écriture a été coupée.
• Derrière gluetun (network_mode: "service:gluetun") : arrêtez hydranos avant gluetun. Si gluetun est redémarré ou mis à jour, hydranos garde un espace de noms réseau mort (pas de réseau, pas d'interface web) jusqu'à ce que vous le redémarriez lui aussi (comportement de Docker, non testé par le mainteneur). Recette : VPN & sortie réseau.

Redémarrer depuis l'interface

Plusieurs contrôles redémarrent Hydranos : Redémarrer maintenant (Restart now, bandeau de l'onglet Nodes après une modification de moteur), Appliquer et redémarrer (Apply & restart ou Apply and restart, après l'enregistrement d'un réglage qui l'exige, par exemple sur l'onglet Réseau (Network)), Enregistrer et redémarrer (Save and restart, carte Duplicate data et boîte de dialogue de sortie de page) et Réinitialiser et redémarrer (Reset and restart, voir Réinitialiser les réglages plus bas). Il se passe la même chose avec POST /api/restart et POST /api/settings/restart.

Le démon répond d'abord à la requête ({"ok":true,"restarting":true} ou {"status":"restarting"}), puis, 500 ms (/api/restart) ou 300 ms (/api/settings/restart) plus tard, journalise restart requested via API: stopping cleanly, then exiting for the supervisor (ou restart requested from settings: …) et passe par l'arrêt propre décrit plus haut : vidange, départs, écriture, démontage des tunnels. Il journalise ensuite restart: exiting with code 75 for the supervisor et se termine avec le code 75 (EX_TEMPFAIL), pas 0, pour qu'un superviseur qui relance en cas d'échec le fasse revenir.

flowchart TD
    A["Contrôle de redémarrage dans l'interface,<br/>ou POST /api/restart ou /api/settings/restart"] --> B["arrêt propre : vidange, départs,<br/>écriture de reprise, démontage des tunnels"]
    B --> C{"Qu'est-ce qui a lancé hydranos ?"}
    C -->|"Windows, tout lancement"| W["démarre son successeur avec les mêmes arguments,<br/>puis se termine avec le code 75"]
    W --> UP["Hydranos tourne de nouveau"]
    C -->|"Linux ou Docker"| E["code de sortie 75"]
    E --> D{"Politique du superviseur"}
    D -->|"Docker restart: unless-stopped, always ou on-failure"| UP
    D -->|"systemd Restart=on-failure - l'unité livrée - ou always"| UP
    D -->|"Docker sans politique de redémarrage, ou lancé à la main dans un shell"| DOWN["reste arrêté"]

Loading

• Windows : rien ne supervise le processus, donc avant de se terminer il démarre lui-même son successeur (restart: successor started ; en cas d'échec ERROR restart: cannot start the successor: …, et rien ne revient : démarrez-le vous-même).
• Windows sous un wrapper de service (NSSM) : le successeur démarre hors du wrapper, et le wrapper voit le code 75 et peut en démarrer un autre : deux instances, dont l'une ne parvient pas à ouvrir le port et l'autre n'est pas supervisée. Déduit du code, non testé. Sous un service, redémarrez via le service, pas avec les boutons de l'interface.
• Après Appliquer et redémarrer (Apply & restart), la page se recharge 7 s plus tard (Redémarrer maintenant (Restart now) indique de se reconnecter dans environ 40 s) ; pendant une longue écriture, elle peut afficher une erreur de connexion jusqu'au retour d'Hydranos : rechargez-la alors. Une fois le port rouvert, vous obtenez l'écran de démarrage ci-dessous.

docker restart et systemctl restart envoient SIGTERM : ils passent donc par le même arrêt propre (code de sortie 0, puis le superviseur le démarre).

Pendant le démarrage

Depuis la 4.4, le port s'ouvre dans la première seconde (INFO hydra API listening (starting) addr=…), avant le chargement du catalogue : un port déjà pris échoue immédiatement. Tant que les moteurs ne sont pas chargés et que le store n'est pas ouvert, seule une surface de démarrage répond :

• / affiche l'écran de démarrage : le logo, HYDRANOS, une ligne de phase (Initialisation… (Initializing…), puis Restauration de l'état… (Restoring state…), Connexion au réseau… (Connecting to the network…), Ouverture de la base… (Opening the database…), Démarrage… (Starting…)), une barre et <restored> / <total> torrents. Il interroge /api/startup toutes les 500 ms et s'efface quand le démon est prêt. Le total ne compte que les moteurs qui ont commencé leur lecture : la barre peut donc reculer une fois par moteur.
• /health répond 200 avec "status": "starting", /metrics un jeu réduit, /api/startup la progression.
• Tout le reste (l'API, la connexion, l'API compatible qBittorrent /api/v2/*, /mcp) répond 503 avec Retry-After: 5 et Hydranos is starting (<phase>): <restored> of <total> torrents restored.

La fin du démarrage est INFO hydra API ready. Si le store ne s'ouvre pas, la phase devient rescue et la page se recharge sur le Mode de secours ci-dessous. Détails : Supervision & journaux.

Après un plantage

Un plantage, une coupure de courant, kill -9, Fin de tâche (End task) ou un SIGKILL envoyé par un superviseur sautent l'écriture. Chaque moteur repart alors de son dernier état de reprise enregistré :

Perdu	Pas perdu
Jusqu'à 300 s de progression des pièces, des compteurs envoyé/reçu et du temps de seed par moteur (la sauvegarde périodique de reprise tourne toutes les 300 s)	Les torrents ajoutés, terminés ou déplacés avant le plantage : leur ligne de reprise est écrite à ce moment-là
Les pièces terminées depuis la dernière sauvegarde : le démarrage suivant doit les vérifier à nouveau	Le contenu du store (catégories, tags, intention d'arrêt, métadonnées) : validé au fil de l'eau
Lors d'une coupure de courant uniquement : les toutes dernières secondes de validations de chaque fichier SQLite (synchronous=NORMAL)	Les jobs : ceux qui tournaient sont remis en file au démarrage suivant
Les tâches groupées lancées depuis le menu contextuel (elles vivent en mémoire)	Les magnets en attente de métadonnées : ils reprennent

Les revérifications après un plantage sont normales et limitées aux torrents concernés. Détails : Architecture.

Sauvegardes

Hydranos n'a pas de fonction de sauvegarde en 4.4 (ni bouton, ni endpoint, ni copie planifiée ; les sauvegardes sont l'affaire de l'exploitant, comme dans les autres clients BitTorrent). Vous copiez vous-même les fichiers ci-dessous. Les données (les fichiers de vos chemins de sauvegarde) sont à sauvegarder de votre côté, séparément ; Hydranos ne les copie pas.

Quoi sauvegarder

Fichier	Contient	Criticité	Peut-on le reconstruire ?
default.toml (le fichier de configuration)	moteurs, ports, réglages par tracker, mode réseau, kill switch, api_key, password_hash de l'admin, data_dir	haute	à la main seulement
<data dir>/hydra.db (+ hydra.db-wal, hydra.db-shm)	le store : chaque .torrent, les catégories, les tags, l'intention d'arrêt, les workflows, les flux et règles RSS, les nœuds, les jobs, les compteurs cumulés des torrents retirés	critique	non : c'est la seule copie des métadonnées, et Hydranos ne peut pas la reconstruire à partir des données sur disque (une installation mise à jour depuis la 3.x peut aussi garder des copies des .torrent dans <data dir>/uploads/, réimportées au démarrage : sauvegardez-le aussi)
<config dir>/<engine id>/state.db (+ -wal, -shm), un par moteur	l'état de reprise du moteur : quels torrents le moteur détient, chemins de sauvegarde, pièces vérifiées, compteurs, listes de trackers modifiées, temps de seed	critique	non : un moteur charge sa liste de torrents depuis ce fichier ; sans lui, le moteur démarre vide
<data dir>/wireguard/	fichiers .conf du fournisseur pour WireGuard géré (ils contiennent la clé privée du tunnel)	haute si vous l'utilisez	auprès de votre fournisseur VPN
<config dir>/<engine id>/resume/	anciens fichiers de reprise par torrent, importés une seule fois dans un state.db vide	faible	inutile une fois que state.db existe
<data dir>/bench.db	historique de l'onglet Performances (Benchmark)	faible	recréé vide
hydranos.log (+ .1 à .4)	le journal, avec rotation à 128 Mio	aucune	—

<config dir> est le dossier qui contient default.toml ; <data dir> est [daemon] data_dir. Les deux ne sont confondus que sous Docker.

Où sont les fichiers

Plateforme	Dossier de configuration (config, dossiers des moteurs, journal)	Dossier de données (hydra.db, bench.db)
Docker	/config (votre dossier hôte monté à cet endroit)	/config
Linux, packaging/install.sh ou les étapes de Linux (bare metal)	/etc/hydranos (donc /etc/hydranos/race/state.db, /etc/hydranos/hoard/state.db)	/var/lib/hydranos
Linux, binaire lancé avec un fichier --config qui n'existait pas encore	le dossier de ce fichier	<that folder>/data
Windows, lancé avec --config C:\Hydranos\default.toml qui n'existait pas encore	C:\Hydranos	C:\Hydranos\data
Windows, default.toml placé là par vous à partir du modèle livré	C:\Hydranos	\config sur le lecteur courant (le modèle indique data_dir = "/config")
Windows, lancé sans --config	le dossier de hydranos.exe (une installation 4.3 qui n'a que \config\default.toml sur le lecteur courant continue de l'utiliser ; son avertissement est affiché avant le rattachement de toute console, donc il n'apparaît pas dans une fenêtre de console)	<that folder>\data

Hydranos écrit une configuration de départ, avec data_dir réglé sur data à côté d'elle, uniquement quand le fichier de configuration n'existe pas. Dans le doute, lisez data_dir dans votre default.toml : c'est lui qui fait foi.

La recette de sauvegarde : arrêter, copier, démarrer

La recette recommandée, sur toutes les plateformes. hydra.db et chaque state.db doivent être copiés au même moment et en entier (avec leurs fichiers -wal) : un Hydranos arrêté garantit les deux, et son arrêt propre vient d'écrire le dernier état de reprise.

# Docker (compose project in /srv/hydranos, /config mounted from ./config)
cd /srv/hydranos
docker compose stop hydranos
tar czf /backup/hydranos-$(date +%F).tar.gz config
docker compose start hydranos

# Linux, packaged layout
sudo systemctl stop hydranos
sudo tar czf /backup/hydranos-$(date +%F).tar.gz /etc/hydranos /var/lib/hydranos
sudo systemctl start hydranos

• Unraid ou un NAS : arrêtez le conteneur dans l'onglet Docker (ou le gestionnaire de conteneurs du NAS), copiez tout le dossier monté en /config avec n'importe quel outil de fichiers ou application de sauvegarde, démarrez le conteneur.
• Windows : zone de notification › Quit Hydranos, attendez que l'icône disparaisse, puis copiez le dossier de configuration (et le dossier de données s'il est ailleurs) avec l'Explorateur, ou dans cmd : robocopy C:\Hydranos D:\Backup\Hydranos /E. Redémarrez Hydranos. Ni tar ni sqlite3 ne sont nécessaires.

Sur un partage réseau (/mnt/user d'Unraid, NFS, SMB), le store garde le journal de rollback de SQLite et n'a pas de fichier -wal ; la recette est la même.

Copier une instance en marche avec sqlite3

Possible quand vous ne pouvez pas arrêter Hydranos, avec l'outil sqlite3 sur l'hôte (il n'est pas dans l'image Docker) et les fichiers sur un disque local (mode WAL). Chaque copie est cohérente pour son propre fichier.

# Disposition Docker : hydra.db et les dossiers des moteurs dans ./config ; lancez en tant que propriétaire des fichiers
cd /srv/hydranos/config
mkdir -p /backup/hydranos-$(date +%F)
cp default.toml /backup/hydranos-$(date +%F)/
sqlite3 hydra.db ".backup '/backup/hydranos-$(date +%F)/hydra.db'"
for e in race hoard; do       # chaque identifiant de moteur
  mkdir -p /backup/hydranos-$(date +%F)/$e
  sqlite3 $e/state.db ".backup '/backup/hydranos-$(date +%F)/$e/state.db'"
done

Ce qu'elle ne vous donne pas, par rapport à une copie à l'arrêt :

• Le store et les fichiers state.db sont pris à des moments différents. Un torrent ajouté ou retiré entre deux copies peut manquer après une restauration (voir Restaurer : ignoré au chargement, ou sa ligne du store supprimée par la réconciliation). Copiez-les l'un après l'autre, à un moment calme.
• state.db contient l'état de reprise de la dernière sauvegarde périodique (toutes les 300 s) : après une restauration, les pièces récentes sont vérifiées à nouveau.
• Sur un store chargé, .backup recommence à chaque écriture d'Hydranos pendant la copie ; sqlite3 hydra.db "VACUUM INTO '/backup/…/hydra.db'" lit plutôt un seul instantané.
• Sur un partage réseau (journal de rollback) ou sous Windows, utilisez la copie à l'arrêt.

Copies que Hydranos fait de lui-même

• <config file>.bak-reset-<unix time> : la configuration précédente, écrite par Revenir aux valeurs par défaut (Reset to defaults, voir plus bas).
• hydra.db.bak-preconvert-<unix time> : le store avant une conversion en mode de secours (voir Mode de secours).

Elles ne sont pas supprimées automatiquement.

Restaurer

Le store et l'état de reprise des moteurs doivent provenir de la même sauvegarde. Au démarrage, chaque moteur charge les torrents listés dans son state.db et prend leur .torrent dans le store ; ensuite, juste après store open puis toutes les 5 minutes, une réconciliation du store compare, moteur par moteur, les lignes du store avec les torrents que le moteur a chargés :

• store plus ancien, state.db plus récent : un torrent dont le store n'a pas de ligne est ignoré au chargement (WARN [resume] skip …: no metainfo in the store), sauf si <data dir>/uploads/<hash>.torrent existe (installations reprises de la 3.x) : il est alors d'abord importé dans le store. Ajoutez à nouveau ceux qui ont été ignorés.
• store plus récent, state.db plus ancien : le store a des lignes pour des torrents que le moteur n'a pas chargés. La réconciliation les considère comme des restes d'un retrait et les supprime, .torrent compris, quand leur nombre est au plus max(rows of that engine in the store ÷ 100, 50) ; une ligne en INFO : store reconcile: rows without a torrent removed engine=… dropped=N. Au-delà de ce plafond, elle ne supprime rien et journalise en WARN store reconcile: refusing to drop that many rows at once (would_drop, of), puis refuse à nouveau toutes les 5 minutes. Un moteur qui n'a chargé aucun torrent (state.db absent) est ignoré, donc ses lignes sont conservées.

À 1 million de lignes, ce plafond est de 10 000 torrents, et ces .torrent n'existent nulle part ailleurs. La réconciliation ne supprime que la ligne de ce moteur : une copie du même torrent détenue par un autre moteur garde la sienne. Les lignes des enregistrements refusés par le chargeur (leur .torrent sur disque est un autre torrent) sont conservées aussi (store reconcile: rows kept for records the loader refused).

Procédure :

1. Arrêtez Hydranos et laissez-le arrêté.

2. Remettez default.toml au chemin avec lequel vous lancez Hydranos. Si la nouvelle machine utilise d'autres chemins, corrigez-y data_dir.

3. Remettez hydra.db dans le dossier de données. Supprimez tout hydra.db-wal et hydra.db-shm déjà présent, sauf s'ils proviennent de la même sauvegarde : un -wal périmé à côté d'une autre copie du fichier la corrompt.

4. Remettez chaque dossier de moteur en <config dir>/<engine id>/ avec son state.db (même règle pour state.db-wal / -shm), issu de la même sauvegarde que hydra.db. Le nom du dossier doit être égal à l'identifiant de moteur dans la configuration (race, hoard, ou l'identifiant d'un moteur supplémentaire) : un moteur dont le dossier manque ou a été renommé démarre vide.

5. Faites exister les chemins de sauvegarde aux mêmes emplacements qu'avant (mêmes montages sous Docker).

6. Corrigez les propriétaires : l'utilisateur PUID/PGID sous Docker, ou hydranos:hydranos avec l'arborescence Linux packagée.

7. Gardez une copie du hydra.db restauré de côté, hors du dossier de données. Si la réconciliation supprime malgré tout des lignes, leur .torrent est toujours dans cette copie.

8. Facultatif, si vous avez la CLI sqlite3 sur l'hôte : comptez, par moteur, les lignes du store qui n'ont pas de ligne dans state.db (une borne basse de ce que la réconciliation peut supprimer). Tout résultat autre que 0 signifie que les fichiers ne correspondent pas ; 0 n'exclut pas des lignes supprimées parce que leur .torrent ne se lit pas.

   cd /srv/hydranos/config      # the folder holding hydra.db and the engine folders
   for e in race hoard; do
     sqlite3 hydra.db "ATTACH '$e/state.db' AS s; SELECT '$e', count(*) FROM torrents WHERE session = '$e' AND info_hash NOT IN (SELECT lower(info_hash) FROM s.torrent_state);"
   done

9. Démarrez, et vérifiez le journal : une ligne engine state loaded par moteur avec torrents=… (comparez avec vos chiffres d'avant), aucune ligne [resume] skip, engines up, store open, hydra API ready, et aucune ligne store reconcile: rows without a torrent removed.

bench.db peut être restauré ou laissé de côté (l'onglet Performances (Benchmark) repart alors vide).

Mode de secours

Si hydra.db ne peut pas être ouvert, ou si sa table torrents n'a pas toutes ses colonnes, Hydranos journalise the store could not be opened: <why> -- starting in rescue mode en ERROR et sert une surface minimale sur l'écoute déjà ouverte, donc sur vos api_host et api_port (0.0.0.0:8199 par défaut). L'interface web n'est pas servie : http://<host>:8199/ répond le texte hydra: the store could not be opened (un écran de démarrage encore ouvert dans un navigateur se recharge dessus). Les moteurs ont été démarrés avant l'ouverture du store et continuent de tourner (Architecture).

Le mode de secours ne demande aucune clé API : quiconque atteint le port peut lancer la conversion et le redémarrage. Ne laissez le port accessible qu'à des hôtes de confiance, comme pour l'interface normale.

Route (sans clé API)	Effet
GET /health	répond ok
GET /api/store/repair (identique à GET /api/setup)	diagnostic : needed, targets (chemin), on_network, in_wal, hot_wal
POST /api/store/repair	la conversion ci-dessous, uniquement quand needed vaut true
POST /api/settings/restart	sortie avec le code 75 après 300 ms (Windows : démarre d'abord son successeur) ; sans écriture de reprise

L'interface web contient un écran Hydranos ne peut pas ouvrir sa base de données (Hydranos cannot open its database) avec un bouton Sauvegarder puis convertir (Back up and convert), mais en 4.4 il n'apparaît jamais : le mode de secours ne sert pas l'interface, et l'API normale indique toujours qu'aucune réparation n'est nécessaire. Utilisez directement les routes :

curl http://127.0.0.1:8199/api/store/repair
curl -X POST http://127.0.0.1:8199/api/store/repair

La seule réparation concerne un store en mode WAL sur un système de fichiers réseau (needed = on_network et in_wal). Sous Linux, « réseau » signifie NFS, SMB/CIFS ou FUSE (mergerfs, /mnt/user d'Unraid) ; sous Windows, un chemin UNC ou un lecteur réseau mappé. Cela arrive typiquement quand un store créé sur un disque local est déplacé sur un partage.

flowchart TD
    A["POST /api/store/repair<br/>(mode de secours uniquement)"] --> B{"sur un système de fichiers réseau et en WAL ?"}
    B -->|non| S["renvoie le diagnostic, ne change rien"]
    B -->|oui| C["copie hydra.db vers hydra.db.bak-preconvert-unix time"]
    C -->|"échec de la copie"| E5["500, rien n'a changé"]
    C -->|"copie faite"| D["PRAGMA journal_mode=DELETE"]
    D -->|ok| OK["200, method pragma"]
    D -->|"échec, fichier WAL vide"| H["réécrit les octets 18-19 de l'en-tête,<br/>supprime -wal et -shm"]
    H -->|ok| OK2["200, method header"]
    H -->|"échec de l'écriture"| E6["500, sauvegarde conservée"]
    D -->|"échec, le fichier WAL contient des données"| E4["409, store laissé intact"]

Loading

Après une conversion réussie, redémarrez : curl -X POST http://127.0.0.1:8199/api/settings/restart se termine avec le code 75, ce qui fait revenir Hydranos sous Docker avec une politique de redémarrage, avec l'unité systemd livrée (Restart=on-failure) et sous Windows (successeur) ; ou redémarrez via votre superviseur (docker restart hydranos, sudo systemctl restart hydranos). En cas de 409, le -wal contient encore des validations : remettez les fichiers sur un disque local, démarrez-y Hydranos une fois et arrêtez-le proprement, puis déplacez-les de nouveau ; ou mieux, gardez data_dir sur un disque local.

Pour toute autre cause (permissions, disque plein, fichier endommagé), POST /api/store/repair ne fait rien : corrigez la raison indiquée dans le journal, ou restaurez une sauvegarde (Restaurer).

En mode de secours, un SIGTERM (ou Ctrl+C) arrête quand même proprement le serveur HTTP et le processus se termine avec le code 0, mais sans départs ni écriture de reprise : l'état des moteurs est celui de la dernière sauvegarde périodique. Déduit du code, non testé.

Mettre à jour

Lisez d'abord les notes de version dans le changelog. L'onglet Journal des changements (Changelog) (et /changelog.md) affiche le changelog compilé dans la version que vous faites tourner : il ne mentionne donc pas la nouvelle version. Faites une sauvegarde (copie à l'arrêt) avant chaque mise à jour : c'est aussi votre chemin de retour.

Docker

Épinglez une étiquette de version et changez-la pour mettre à jour :

cd /srv/hydranos
# edit your compose file: image: ghcr.io/kheopsian/hydranos:v4.4.1 → the new tag
docker compose pull
docker compose up -d

up -d arrête l'ancien conteneur avec votre stop_grace_period (arrêt propre), puis démarre la nouvelle image sur le même /config. Rien dans le conteneur ne se met à jour tout seul. Unraid : changez l'étiquette dans le champ Repository puis Apply. Détails : Docker.

Linux (bare metal)

hydranos-update télécharge l'archive de la version pour votre architecture depuis les releases de github.com/Kheopsian/Hydranos, vérifie son SHA-256 avec le .sha256 publié à côté, et remplace les binaires.

sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml --check
sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml   # download, verify, ask, replace
sudo systemctl restart hydranos

Option	Effet
--check	affiche installed: et available: puis se termine
--dir <path>	dossier contenant hydranos (par défaut : le dossier courant)
--config <file>	la configuration du démon (par défaut : default.toml dans --dir) ; les téléchargements de l'outil de mise à jour sortent alors comme ceux du démon ([daemon] egress, kill switch). Un fichier qui ne se lit pas est un refus ; pas de fichier signifie la route par défaut
--tag vX.Y.Z	une version donnée au lieu de la dernière ; les versions plus anciennes sont autorisées (retour arrière)
--yes, -y	pas de confirmation (replace the binaries with <tag>? [y/N])

• Rien n'est remplacé si le téléchargement échoue, si le .sha256 manque (refusing to install unverified bytes) ou si la somme de contrôle diffère (checksum mismatch -- nothing replaced).
• Il ne remplace que hydranos et hydranos-update déjà présents dans --dir (l'archive ne contient pas de hydranos-engine ; un ancien laissé dans le dossier n'est pas touché) ; la configuration, le store, les dossiers des moteurs et le journal ne sont jamais touchés.
• Sous Linux, il ne redémarre rien (note: restart the service for the new binaries to take effect).
• packaging/install.sh installe hydranos-update à côté de hydranos dans /opt/hydranos (Linux (bare metal)).

Sans l'outil de mise à jour : téléchargez et vérifiez la nouvelle archive, décompressez-la, relancez sudo ./install.sh (il conserve la configuration), puis redémarrez.

Windows

Zone de notification › Check for updates ouvre une fenêtre cmd qui exécute hydranos-update.exe --dir <folder of hydranos.exe> ; mêmes options et mêmes vérifications que ci-dessus. Une fois que vous avez répondu y, l'outil de mise à jour demande à l'Hydranos en marche de s'arrêter via un événement nommé (Local\HydranosStop), le même arrêt propre que Quit Hydranos, attend jusqu'à 60 s que hydranos.exe se termine, remplace les fichiers et affiche updated to <tag>. Start hydranos again. Si l'arrêt prend plus de 60 s (une écriture proche de HYDRANOS_STOP_TIMEOUT), il affiche hydranos is still running after 60s -- stop it yourself, nothing was replaced : attendez que l'icône de la zone de notification disparaisse et relancez-le. Un démon antérieur à la 4.4 n'a pas cet événement : quittez-le d'abord depuis la zone de notification. La marche à suivre détaillée est sur Windows.

Le badge de mise à jour

Quand une version plus récente existe, un lien màj vX.Y.Z (update vX.Y.Z) apparaît à côté de la version dans l'en-tête. Le serveur lit les 100 premières étiquettes (tags) de github.com/Kheopsian/Hydranos (pas les releases) et garde une réponse réussie pendant 6 heures. Un échec (pas de réseau, limite de requêtes, délai de 5 s dépassé) vaut « pas de mise à jour » et n'est pas gardé : le serveur interroge donc GitHub de nouveau à la requête suivante. Désactivez-le avec update_check_disabled = true dans [daemon].

Le badge ne fait qu'informer : le démon ne télécharge ni n'applique rien. Si vous venez de la 3.x, lisez d'abord Mettre à jour depuis la 3.x.

Réinitialiser les réglages

Onglet Config › Paramètres avancés (default.toml) (Advanced settings (default.toml)) › bouton de la barre d'outils Revenir aux valeurs par défaut (Reset to defaults) › Réinitialiser et redémarrer (Reset and restart) :

1. La configuration actuelle est copiée à côté d'elle vers <config file>.bak-reset-<unix time> (par exemple /config/default.toml.bak-reset-1759600000).
2. default.toml est remplacé par le modèle livré, en ne gardant que votre identifiant admin (username, password_hash), api_key et data_dir (chaînes non vides uniquement).
3. Hydranos redémarre via l'arrêt propre de Redémarrer depuis l'interface (code de sortie 75).

Tout le reste revient aux valeurs par défaut : les ports (16171 race, 16172 hoard), les réglages par tracker, le réglage fin des moteurs, les limites de file, de partage et de débit, le mode réseau, les réglages du kill switch, du proxy et de WireGuard géré (les fichiers du fournisseur dans <data dir>/wireguard/ restent), et les moteurs supplémentaires (leurs dossiers restent sur le disque, mais ils ne sont plus démarrés). Le store (catégories, workflows, flux et règles RSS) et l'état de reprise ne sont pas touchés. Pour annuler : arrêtez Hydranos, copiez le fichier .bak-reset-… par-dessus default.toml, démarrez.

La carte Personnalisation (Personalisation) du même onglet a un bouton portant le même libellé, Revenir aux valeurs par défaut : il ne réinitialise que le thème et les onglets masqués dans ce navigateur et ne touche à rien sur le serveur.

Mot de passe admin perdu

Une fois connecté, changez-le sous Config › Compte (Account) › Changer le mot de passe (Change password) (8 caractères minimum ; s'applique immédiatement). Si vous êtes bloqué dehors, définissez-en un nouveau sur l'hôte avec hydranos reset-password <password> [path/to/default.toml], puis redémarrez :

# Docker (config en /config/default.toml dans le conteneur ; passez le chemin si vous avez changé HYDRANOS_CONFIG_DIR)
docker exec hydranos hydranos reset-password 'new-password-here'
docker restart hydranos

# Linux, packaged layout
sudo /opt/hydranos/hydranos reset-password 'new-password-here' /etc/hydranos/default.toml
sudo systemctl restart hydranos

Sous Windows : hydranos.exe reset-password "new-password-here" dans cmd, dans le dossier de hydranos.exe (la configuration par défaut est celle qui est à côté), puis Quit Hydranos et redémarrez-le (non testé sous Windows).

• Elle écrit un [auth] password_hash bcrypt dans le fichier, vérifie que le fichier se lit toujours, affiche hydranos: password set in <path>. Restart Hydranos for it to apply. et se termine. Le démon en marche garde l'ancien hash jusqu'au redémarrage ; username et api_key ne changent pas.
• Sans chemin, elle utilise /config/default.toml (Windows : default.toml à côté de hydranos.exe, ou le \config\default.toml laissé par une installation 4.3 quand il n'y en a pas là). Refus : moins de 8 caractères (hydranos: the password must be at least 8 characters, code de sortie 2), un fichier qu'elle ne peut ni lire ni écrire, ou une modification qui ne se lirait plus (… would not parse after the edit; nothing written).
• Le mot de passe est un argument de ligne de commande : il reste dans l'historique de votre shell et apparaît dans ps pendant l'exécution de la commande.

hydranos hash-password <password> ne fait qu'afficher un hash bcrypt, pour modifier password_hash à la main. Plus sur les comptes et les clés : Sécurité & accès.

Voir aussi

• Supervision & journaux : /health, /metrics, le fichier journal et l'onglet Journaux.
• Dépannage : symptômes et solutions.
• Docker, Linux (bare metal), Windows : particularités de chaque plateforme.
• Architecture : ordre de démarrage, fichiers sur disque, résistance aux plantages.
• Mettre à jour depuis la 3.x.