Skip to main content

17_Komga

komga

Imagegotson/komga
Version1.25.0
EtatUp 9 hours
Compose projectkomga
Reseaukomga_default
URLhttps://komga.juxjux.ovh
Sourcehttps://github.com/gotson/komga

Ports

HoteContainerIP
2560025600/tcp0.0.0.0
2560025600/tcp::

Volumes

Source (hote)DestinationTypeMode
/home/debian/docker/komga/config/configbindrw
/home/debian/komga/databindrw
/etc/timezone/etc/timezonebindro
/tmpvolumerw

Integration Claude Code — MCP

Statut MCPMCP actif
Outils (prefix)mcp__komga__
ConfigurationScript Python : C:\Users\eliob\.claude\mcp_komga.py | Auth : Basic Auth (Base64 login:password)

Outils disponibles

  • get_libraries
  • get_series
  • get_series_detail
  • get_series_books
  • get_book
  • get_book_metadata
  • get_books
  • get_latest_books
  • get_new_series
  • get_updated_series
  • get_on_deck
  • get_read_lists
  • get_read_list
  • get_collections
  • get_collection
  • search
  • mark_series_read
  • update_book_progress
  • get_recently_added

Ce que nous pouvons faire ensemble

  • Parcourir la bibliothèque comics/manga par série et tome
  • Voir les dernières acquisitions et séries mises à jour
  • Marquer une série comme lue ou mettre à jour la progression
  • Gérer les listes de lecture et collections
  • Rechercher dans toute la bibliothèque

Lenteur d'affichage des pages PDF — diagnostic et correctif (2026-08-30)

Symptome : temps d'attente de 4 a 6 secondes a chaque page d'un PDF, y compris sur une page deja consultee. Decourageant a l'usage.

Ce qui n'est PAS en cause : la definition de rendu

Premier reflexe : abaisser la definition des pages. Ce n'est pas possible, et cela n'aurait pratiquement rien change.

La resolution de rasterisation des PDF est cablee en dur dans Komga, dans StaticConfiguration.kt :

@Bean("pdfResolution") fun pdfResolution(): Float = 3200F
@Bean("pdfImageType")  fun pdfImageType() = ImageType.JPEG

PdfExtractor calcule scale = 3200 / min(largeur, hauteur), soit 3200 px sur le petit cote : une page A4 sort en 3200 × 4040 = 12,9 Mpx, 0,75 a 1,4 Mo de JPEG.

Aucune propriete komga.pdf.* n'existe dans les metadonnees de configuration Spring du jar (verifie sur la 1.25.0 installee), et la documentation officielle n'expose rien de tel.

Attention — deux variables inertes dans la stack Portainer 7 : KOMGA_PDF_RENDERING_DPI=72 et KOMGA_IMAGE_QUALITY=LOW ne correspondent a aucune propriete existante. Spring les ignore en silence. Elles laissent croire a un reglage actif : ne pas s'y fier. Laissees en place le 2026-08-30 sur decision de Julien.

La vraie cause : le montage rclone etait en cache d'ecriture seule

kdrive-komga.service tournait en --vfs-cache-mode writes, qui ne met en cache que les ecritures. Chaque lecture repartait vers kDrive, indefiniment. Or PDFBox saute d'abord a la table xref en fin de fichier, puis picore les objets : plusieurs allers-retours reseau par page.

C'etait le seul montage kDrive reste en writes : music, livres, audiobooks, photo et romans etaient deja en full avec un plafond de 10G. Une exception oubliee, pas un choix.

Mesures — ou passait reellement le temps

Livre temoin : Geo 2012 - Iles de Reve.pdf, 96,8 Mo, 140 pages.

OperationResultat
Page rendue en JPEG12,9 Mpx — 4,5 a 6,0 s
Page PDF brute (aucun rendu)60 a 90 Ko — 3,8 a 4,2 s
Acces aleatoire de 1 Mo sur le montage0,52 a 0,67 s, identique a la 2e lecture
Lecture sequentielle du fichier entier84 a 111 Mo/s (97 Mo en ~1 s)

Le plancher de ~3,9 s etait commun au rendu et a la page brute : la preuve que le coupable etait l'I/O, pas la rasterisation, qui n'ajoutait que 0,6 a 2 s.

Consequence contre-intuitive : lire un fichier de 100 Mo de bout en bout (~1 s) coute moins cher que d'y picorer trois pages en acces aleatoire (~2 s). C'est le principe du prechauffage decrit plus bas.

Correctif applique le 2026-08-30

Options ajoutees a l'ExecStart de kdrive-komga.service (sauvegarde : kdrive-komga.service.bak-260830) :

--vfs-cache-mode full --vfs-cache-max-size 8G --vfs-cache-max-age 6h
--vfs-cache-poll-interval 1m --vfs-read-chunk-size 32M
--vfs-read-chunk-size-limit 512M
Avant (writes)Apres (full)
1re page d'un livre froid4,5 a 6,0 s3,4 s
Pages suivantes4,5 a 6,0 s0,69 a 0,84 s
Meme page redemandee6,0 s (aucun gain)0,99 s

Facteur 6 a 7 sur tout ce qui suit la premiere page. Les 0,7 s residuels sont la rasterisation PDFBox : le plancher est desormais le CPU du VPS, plus rien a voir avec kDrive.

Pieges a ne pas refaire

  • Redemarrer le container Komga apres le remontage — il garde sinon l'ancienne reference FUSE et continue de lire dans le vide. Meme piege que le correctif :shared du 2026-06-08.
  • Ne jamais passer un mount en full sans --vfs-cache-max-size. Six montages en full totalisent 58 Go de plafond theorique pour 34 Go libres sur /home/debian. En pratique le cache reel plafonne vers 4,3 Go, car --vfs-cache-max-age purge bien avant que la taille ne morde — mais l'incident du 2026-06-24 (spool rclone de 14 Go, disque plein, VPS a terre) rappelle ce qui arrive sans bornage.
  • Le choix est l'inverse de celui retenu pour Jellyfin (minimal), et a juste titre : un film est lu une fois en flux lineaire, un PDF subit des acces aleatoires repetes sur le meme fichier.
  • L'API renvoie le chemin vu par le container (/data/...) : le retraduire en /home/debian/komga/... cote hote.

Piste non deployee : le prechauffage a l'ouverture

--vfs-cache-mode full telecharge a la demande, pas d'un bloc. Un demon peut forcer la lecture sequentielle complete des l'ouverture du livre, ce qui supprime les 3,4 s de la premiere page.

Ecrit et teste, non installe (le cache seul suffisait) : Jux-scripts/Komga-Cache/precharger_komga.py + komga-precharge.service, avec un README.md detaillant mesures, deploiement et retour arriere.

Declencheur retenu : GET /api/v1/books/{id}/manifest dans le journal nginx — appel emis par le lecteur web avant la premiere page (verifie dans le JS du webreader). Repli sur pages/1-3 pour les clients tiers. La suppression du fichier est deleguee a rclone : --vfs-cache-max-age vaut mieux qu'une suppression a la fermeture, car un livre rouvert dix minutes plus tard reste chaud.

Retour arriere

sudo cp /etc/systemd/system/kdrive-komga.service.bak-260830 \
        /etc/systemd/system/kdrive-komga.service
sudo systemctl daemon-reload
sudo systemctl restart kdrive-komga.service
sudo docker restart komga

Note : la section « Integration Claude Code — MCP » ci-dessus est perimee. Le script C:\Users\eliob\.claude\mcp_komga.py a disparu avec le profil Windows eliob ; il a ete reecrit sans dependance dans Jux-scripts/MCP/mcp_komga.py, mais n'est pas enregistre sur le poste julie (seuls bookstack et kdrive le sont).

Back to top