🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page donne en dix minutes le modèle mental de Hydranos à quelqu'un qui ne l'a jamais fait tourner. Lisez-la avant les pages d'installation si vous voulez savoir ce que vous installez. À la fin, vous saurez ce que sont un moteur, une catégorie, un nœud et un job, où Hydranos garde son état, et quel mot le reste du wiki emploie pour chaque idée (le glossaire en bas de page).

Une instance est un processus hydranos en cours d'exécution, avec son fichier de configuration et son store. Tout se passe dans ce seul processus : l'interface web, les API et chaque session BitTorrent. Il n'y a aucun processus moteur séparé à lancer ou à superviser.

Un moteur est une session BitTorrent à l'intérieur du processus. Chaque moteur a son propre port d'écoute (TCP, et uTP sur le même numéro de port), ses propres connexions sortantes, son propre nœud DHT (actif sauf si enable_dht = false), son propre planificateur d'annonces, son propre peer id et son propre état de reprise. Son nom est l'identifiant de moteur. Chaque moteur a aussi sa propre sortie : tout ce qu'il envoie (connexions aux pairs, annonces, DHT, LSD) sort par son interface, son tunnel WireGuard géré ou son proxy ; deux moteurs sur deux tunnels sont donc deux identités distinctes dans l'essaim (voir VPN & sortie réseau).

• Toute instance a toujours deux moteurs, race et hoard, même si le fichier de configuration n'a ni section [race] ni section [hoard].
• Vous pouvez ajouter des moteurs supplémentaires (par exemple vpn1) avec des blocs engine dans le fichier de configuration (tableau de tables TOML, voir Config : moteurs & drain race) ou via Nodes › This node › + Add an engine. Les moteurs sont construits au démarrage : un nouveau moteur ne démarre donc qu'après un redémarrage.
• Chaque moteur a un rôle, race ou hoard. Le rôle est un comportement, pas un nom : un moteur supplémentaire vpn1 avec role = "race" se comporte comme le moteur race (annonces race, drain race).

Détails, valeurs par défaut et recettes de moteurs supplémentaires : Moteurs : race & hoard. Comment le processus est construit : Architecture.

flowchart LR
    B["Navigateur (interface web)"] --> P
    A["Sonarr, Radarr, autobrr, cross-seed<br/>shim qBittorrent /api/v2"] --> P
    S["Scripts<br/>API REST /api"] --> P
    M["Client IA<br/>MCP : POST /mcp"] --> P
    P["processus hydranos<br/>port 8199, une seule clé API"] --> R["moteur race"]
    P --> H["moteur hoard"]
    P --> X["moteurs supplémentaires (facultatifs)"]
    R --> T["Trackers et pairs"]
    H --> T
    X --> T

Les deux moteurs intégrés existent parce que les torrents qui ne font que passer et ceux qui restent ont des besoins opposés. Aucun des deux moteurs ne transfère plus vite que l'autre : pairs, pièces et disque sont le même code, et un torrent race télécharge et envoie exactement aussi vite qu'un torrent hoard. Ce qui change, c'est tout ce qui entoure la vie d'un torrent : comment il s'annonce, et s'il est fait pour repartir.

• Race est le moteur du roulement : des torrents récupérés dès leur publication, qui font la course dans l'essaim tant qu'il est jeune, puis qu'on laisse partir pour faire place aux suivants. Il s'annonce à tous les trackers du torrent pour être présent dans chaque essaim, et le drain race libère ses disques quand ils se remplissent : il supprime les torrents dont l'obligation de seed du tracker est remplie, et fait graduer les autres si leur catégorie désigne une catégorie Passer vers (Graduate to) sur un autre moteur ; un torrent qui ne remplit aucune des deux conditions reste en place et est compté comme bloqué.
• Hoard est pour les torrents qui restent : une bibliothèque seedée pendant des mois, quelle que soit sa taille. Ses annonces s'arrêtent au premier palier de trackers qui répond, ce qui garde un trafic d'annonces proportionné quand vous seedez un très grand nombre de torrents. Le drain race n'y touche jamais. Un seul balayage supprime des torrents hoard avec leurs données : le balayage de transit, et seulement dans une catégorie marquée Transit area dans laquelle une autre catégorie fait graduer, une fois l'obligation de seed remplie. Une catégorie hoard ordinaire n'est jamais vidée automatiquement.

Dans le doute, classez vos catégories en Hoard. Race sert à faire la course sur les uploads frais, et le drain race peut supprimer des torrents race avec leurs données. Les torrents importés depuis qBittorrent ou Transmission arrivent toujours dans hoard, quel que soit le mode de leur catégorie.

La comparaison complète est sur Moteurs : race & hoard. Le drain, la graduation et les obligations de seed sont sur Drain race & graduation.

Une catégorie est un nom associé à un Mode (race ou hoard) et à un Chemin d'enregistrement (Save Path). Vous les gérez dans l'onglet Catégories (Categories). Quand un torrent est ajouté :

• une catégorie de mode hoard l'envoie au moteur hoard ; tout autre mode l'envoie à race ;
• une catégorie inconnue (ou l'absence de catégorie) l'envoie à race ;
• le chemin de sauvegarde est celui donné dans la requête, sinon celui de la catégorie ;
• il n'y a pas de chemin de sauvegarde par défaut : sans l'un ni l'autre, l'ajout est refusé (no save path: …).

Le mode d'une catégorie ne peut pas désigner un moteur supplémentaire. Pour placer un torrent sur vpn1, indiquez un engine explicite lors d'un ajout par l'API REST native, d'un ajout MCP ou dans un dossier surveillé : il l'emporte sur le mode de la catégorie. Les routes d'ajout natives et l'onglet d'ajout peuvent aussi indiquer un mode (race ou hoard), qui choisit le moteur de ce rôle. Le shim qBittorrent n'a aucun moyen de désigner un moteur. Un nom de moteur qui n'existe pas est refusé avec HTTP 400 par les deux routes d'ajout natives (POST /api/torrents/upload et POST /api/torrents, magnets compris), refusé par un ajout MCP de fichier (un résultat d'outil avec isError : unknown engine …), et l'enregistrement d'un dossier surveillé qui en nomme un est refusé (400 no engine "…") ; un magnet MCP l'ignore et se rabat sur la catégorie (comme un dossier surveillé dont le moteur a été retiré après son enregistrement).

flowchart TD
    A["Torrent ajouté, avec ou sans catégorie"] --> E{"Moteur explicite indiqué ?<br/>(REST, MCP, dossier surveillé)"}
    E -- "oui, et il existe" --> EX["Ce moteur"]
    E -- "oui, mais inconnu" --> UK{"Quel chemin d'ajout ?"}
    UK -- "routes d'ajout natives, fichier MCP, enregistrement d'un dossier surveillé" --> R400["Refusé : aucun moteur de ce nom"]
    UK -- "magnet MCP, dossier surveillé dont le moteur a été retiré" --> K
    E -- non --> MO{"mode indiqué ?<br/>(routes natives, onglet d'ajout)"}
    MO -- oui --> ROLE["Le moteur de ce rôle"]
    MO -- non --> K{"Catégorie connue ?"}
    K -- "oui, mode hoard" --> HO["Moteur hoard"]
    K -- "oui, tout autre mode" --> RA["Moteur race"]
    K -- non --> RA
    EX --> SP{"Chemin de sauvegarde dans la requête ?"}
    ROLE --> SP
    HO --> SP
    RA --> SP
    SP -- oui --> U["L'utiliser"]
    SP -- non --> CP{"La catégorie a un chemin de sauvegarde ?"}
    CP -- oui --> UC["Utiliser le chemin de sauvegarde de la catégorie"]
    CP -- non --> REF["Refusé : pas de chemin de sauvegarde"]

La règle de placement complète, y compris le refus d'ajout race (add-block) et la revendication de chemin (un torrent dont un autre torrent détient déjà les fichiers), est sur Catégories & routage.

Ce qui se passe après le placement dépend de ce qui se trouve déjà dans le chemin de sauvegarde.

• Téléchargement. Aucun fichier du torrent n'existe dans le chemin de sauvegarde : le moteur le télécharge.
• Revérification des données existantes. Au moins un fichier existe déjà : Hydranos vérifie par hachage ce qui est sur le disque, seede les pièces qui sont valides et télécharge le reste. C'est le comportement par défaut sur tous les chemins d'ajout : pointer un torrent vers des données existantes est donc sans risque ; cela ne coûte que des lectures disque.
• Mode seed. L'appelant affirme que les données sont complètes (seed_mode, ou skip_checking sur le shim qBittorrent) : le torrent commence à seeder immédiatement, sans vérification par hachage et sans même vérifier que les fichiers existent. Ne l'utilisez que si vous en êtes sûr. Sur l'onglet + Ajouter un torrent (+ Add Torrent), c'est la case Skip the hash check, the data is already on disk ; l'assistant d'import l'applique automatiquement aux torrents qui sont complets dans l'ancien client et dont il trouve les données.

Les torrents qui téléchargent attendent un emplacement libre quand le moteur fait tourner une file (active_downloads, File, limites de partage & de débit). Détails, magnets, dossiers surveillés et liens physiques pour les données en double : Ajouter des torrents & données existantes.

data_dir est une clé de [daemon]. Dans l'image Docker, il vaut /config : tout se trouve donc dans le seul dossier /config. Quand le binaire écrit lui-même sa première configuration ailleurs, data_dir est le dossier data situé à côté du fichier de configuration.

Le store est la seule copie des métadonnées (metainfo) que Hydranos lit au démarrage : il ne se rabat pas sur des fichiers .torrent. Sauvegardez hydra.db et les dossiers des moteurs ensemble. Fichiers par plateforme et ordre de démarrage : Architecture. Sauvegardes et arrêt propre : Exploiter Hydranos.

Tout est servi par le processus unique sur le port 8199 ([daemon] api_port), et une seule information d'identification ouvre l'ensemble : la clé API ([daemon] api_key, générée au démarrage si elle est vide, comme à la livraison, ou encore réglée sur l'ancienne valeur d'exemple publiée change-me-in-production). Un cookie de session issu d'une connexion par nom d'utilisateur et mot de passe (l'interface web, la connexion du shim qBittorrent) est accepté sur les mêmes routes.

curl -s -H 'X-Api-Key: YOUR_API_KEY' http://127.0.0.1:8199/api/categories

Comment la clé, le compte admin et la connexion du shim s'articulent : Sécurité & accès.

Un nœud est une autre instance Hydranos complète, sur une autre machine, que cette instance connaît. Il n'existe aucun mode nœud particulier : le nœud fait tourner le même hydranos, avec ses propres moteurs, son store et sa clé API. L'instance où vous l'avez ajouté est son contrôleur. Soit vous enrôlez une nouvelle machine (+ Enrol a machine : un jeton à usage unique et une commande d'installation), soit vous déclarez une instance déjà en marche (+ Declare an existing one : URL et sa clé API).

Le contrôleur appelle l'API HTTP normale du nœud avec la clé du nœud, et le nœud n'appelle jamais le contrôleur, à une exception près : à la fin d'un enrôlement, le script d'installation enregistre une fois la nouvelle machine auprès du contrôleur (POST /api/nodes/register), avec le jeton à usage unique au lieu d'une clé API. Le contrôleur affiche la santé du nœud et fusionne ses torrents dans la liste hoard, et des torrents peuvent être poussés vers un nœud ou rapatriés depuis lui. Les données circulent entre les moteurs par BitTorrent, jamais par l'API. Quelques actions par torrent (Modifier les tags › (Edit tags ›), Forcer le téléchargement (Force download), Limites de partage… (Share limits…)) ne sont pas relayées aux lignes qui appartiennent à un autre nœud : voir Nœuds & plusieurs machines.

• Workflows (onglet Workflows) : un déclencheur (à intervalle régulier (on a timer), quand un téléchargement se termine (when a download completes), quand un torrent est ajouté (when a torrent is added)), des conditions dans un arbre When, et des actions dans Then. Voir Workflows.
• RSS (onglet RSS) : des flux récupérés chacun à son propre intervalle, et des règles de téléchargement automatique qui ajoutent les articles correspondants par le pipeline d'ajout normal. Voir Flux RSS & téléchargements automatiques.
• File et limites de partage : par moteur, combien de torrents tournent à la fois et quand un seed est arrêté ou supprimé (ratio, temps de seed). Voir File, limites de partage & de débit.
• Jobs (onglet Jobs) : déplacements de données persistants en arrière-plan (move_data, graduate) qui survivent à un redémarrage. Le mot « job » ne désigne que ceux-là.
• Actions groupées : actions du menu contextuel sur une sélection de torrents. Elles s'exécutent comme une tâche groupée en mémoire avec un panneau de progression, n'apparaissent pas dans l'onglet Jobs et sont perdues au redémarrage.

Jobs et actions groupées : Jobs, actions groupées & déplacement.

Un nom par concept ; chaque page de ce wiki emploie la colonne Terme. « Libellé de l'interface » est ce sur quoi vous cliquez ; « Nom config / API » est ce que vous tapez.