channel.db auf LND Lightning Nodes verkleinern

Wer eine LND-Node länger betreibt, muss irgendwann die channel.db verkleinern: Die Kanaldatenbank wächst mit jedem Kanal, jeder Rechnung und jeder Weiterleitung, und von allein gibt sie freien Platz nicht an das Dateisystem zurück. LND bringt dafür seit Langem eine eingebaute Kompaktierung mit, die sich mit zwei Zeilen in der lnd.conf steuern lässt. Diese Anleitung zeigt, wie das auf Umbrel, dem BTCPay Server und dem RaspiBlitz geht, was die Kompaktierung technisch tut und welche der oft mitkopierten Zusatzoptionen ihr euch besser spart. Sie richtet sich an fortgeschrittene Noderunner mit vielen Kanälen, viel Routing oder vielen Rechnungen, etwa Händler — nicht an eine frische, kleine persönliche Node.

Wer gerade erst eine Node aufsetzt, legt sich diese Anleitung für später zur Seite. Eine Datenbank, die nie aufräumt, benimmt sich wie ein Keller: Lange fällt nichts auf, und dann passt eines Tages das Fahrrad nicht mehr hinein. Die Anleitung erschien erstmals im März 2024 und ist im September 2026 gegen die aktuelle LND-Beispielkonfiguration, den Quelltext von LND sowie die Repositories von RaspiBlitz und BTCPay Server geprüft worden.

Warum die channel.db wächst und wann ihr sie verkleinern solltet

Die channel.db ist die zentrale Datenbank einer LND-Node im Lightning-Netzwerk, der Zahlungsschicht auf Bitcoin. Darin liegen Kanalzustände, Rechnungen, Zahlungen und der Netzwerkgraph. Sie liegt im Unterordner data/graph/mainnet/ des LND-Verzeichnisses und wächst mit der Zeit immer weiter an.

Der Grund liegt im Speicherformat. LND verwendet standardmässig die Datenbank bbolt; laut der Beispielkonfiguration sample-lnd.conf ist bolt weiterhin das voreingestellte Backend, Postgres und SQLite sind Alternativen. Die Projektbeschreibung von bbolt hält fest, dass die Datenbank ihre Datei nicht kürzen und freie Seiten nicht an das Dateisystem zurückgeben kann; sie führt sie intern in einer Freiliste und verwendet sie später wieder. Die Datei wird also nicht kleiner, auch wenn darin weniger steht. Erst eine Kompaktierung schreibt den Inhalt dicht gepackt in eine neue Datei. Eine kleinere Datei heisst weniger Arbeit beim Start und weniger Speicherbedarf; wer in letzter Zeit merkt, dass seine Node träge reagiert, findet hier oft eine Ursache.

Eine Einschränkung vorweg: Seit einigen Versionen kann LND Rechnungen und den Graphen auch in nativen SQL-Tabellen führen (db.use-native-sql, Vorgabe false). Wer seine Node auf Postgres oder SQLite betreibt, hat keine bbolt-Kanaldatenbank und kann diese Anleitung überspringen. Für die üblichen Node-Pakete wie Umbrel, RaspiBlitz und BTCPay Server gilt sie.

Warum ich diesen Artikel geschrieben habe: Auf GitHub gibt es etliche Beiträge über grosse Datenbankdateien und immer langsamere Nodes, aber kaum eine zusammenhängende Anleitung, wie ihr die Kompaktierung selbst einrichtet.

channel.db Grösse überprüfen

Die Grösse der channel.db prüft ihr mit ls -lh. Als Faustregel aus meinem eigenen Betrieb: Ab rund 3 GB lohnt sich die erste Kompaktierung. Das ist ein Erfahrungswert, keine Vorgabe von LND. Je nach System liegt die Datei hier:

Umbrel (Pfad aus der Zeit vor umbrelOS 1.x, siehe Hinweis unten)

ls -lh /root/umbrel/app-data/lightning/data/lnd/data/graph/mainnet/

RaspiBlitz

sudo ls -lh /mnt/hdd/app-data/lnd/data/graph/mainnet/

BTCPay Server

ls -lh /var/lib/docker/volumes/generated_lnd_bitcoin_datadir/_data/data/graph/mainnet/

Beim RaspiBlitz stand hier früher /mnt/hdd/lnd/. Die aktuellen Installations- und Prüfskripte des Projekts (lnd.install.sh, lnd.check.sh) arbeiten durchgehend mit /mnt/hdd/app-data/lnd/. Beim Umbrel-Pfad gilt: Er stammt aus der Zeit vor umbrelOS 1.x. Ob er auf einem heutigen umbrelOS noch genau so lautet, liess sich für diese Überarbeitung nicht prüfen.

Exemplarisch, bei mir war die channel.db nach der Kompaktierung 2,6 GB gross, vorher rund 4,7 GB:

Wie LND die Datenbank kompaktiert

Bevor es an die einzelnen Systeme geht, lohnt ein Blick darauf, was die Kompaktierung tatsächlich tut. Das erklärt nämlich zwei Aussagen, die in älteren Anleitungen — auch in der ersten Fassung dieser hier — falsch standen.

Gesteuert wird sie über zwei Optionen im Abschnitt [bolt] der lnd.conf. db.bolt.auto-compact schaltet sie ein; laut sample-lnd.conf ist sie ab Werk aus, weil sie während des Vorgangs zusätzlichen Speicherplatz braucht. db.bolt.auto-compact-min-age legt fest, wie lange die letzte Kompaktierung zurückliegen muss, bevor LND beim nächsten Start erneut kompaktiert. Die Vorgabe ist 168h, also eine Woche. Wer 0 einträgt, kompaktiert bei jedem Start.

Daraus folgt: Wer nur db.bolt.auto-compact=true setzt, kompaktiert nicht bei jedem Neustart, sondern höchstens einmal pro Woche. Die Zeile db.bolt.auto-compact-min-age=168h schadet nicht, wiederholt aber nur den Standardwert. Und wer die Kompaktierung ausschaltet, bekommt keine Kompaktierung — nicht etwa eine bei jedem Start.

Den Ablauf beschreibt der Quelltext in kvdb/backend.go: LND schreibt den verdichteten Inhalt in eine temporäre Datei namens temp-dont-use.db und tauscht sie erst danach per Umbenennen gegen die alte aus. Vorher prüft kvdb/bolt_compact.go, ob auf dem Datenträger genug Platz für eine vollständige Kopie plus zehn Prozent Reserve frei ist; sonst beginnt die Kompaktierung gar nicht erst. Den Zeitpunkt der letzten Kompaktierung merkt sich LND in einer Datei neben der Datenbank, channel.db.last-compacted. Fehlt diese Datei, kompaktiert LND beim nächsten Start.

channel.db kompaktieren auf Umbrel, BTCPay Server und RaspiBlitz

Wir schauen uns die Kompaktierung auf drei Systemen an: BTCPay Server, Umbrel und dem RaspiBlitz. Welche Zusatzoptionen dabei sinnvoll sind, steht gesammelt im Abschnitt danach.

Umbrel Fullnode

Auf Umbrel geschieht das über die Oberfläche der Lightning-Node-App. Öffnet die App und geht oben rechts über die drei Punkte in die Einstellungen. Die folgenden Bildschirmfotos stammen vom März 2024 und zeigen die Oberfläche vor umbrelOS 1.x; wie die Einstellungen heute genau heissen und wo sie sitzen, liess sich für diese Überarbeitung nicht prüfen.

Navigiert hinunter zu den Optimierungen und aktiviert diese Einstellungen:

db.bolt.auto-compact=true
db.bolt.auto-compact-min-age=168h
gc-canceled-invoices-on-startup=true
gc-canceled-invoices-on-the-fly=true
ignore-historical-gossip-filters=true
stagger-initial-reconnect=true

Achtet auf die kleine, rot markierte Beschriftung, dann findet ihr die richtigen Schalter:

Die erste Fassung dieser Anleitung empfahl hier zusätzlich sync-freelist und payments-expiration-grace-period=9999h. Beides steht nicht mehr in der Liste; warum, erklärt der Abschnitt über die übrigen Optionen.

BTCPay Server

Auf dem BTCPay Server gibt es für die Kompaktierung ein fertiges Fragment namens opt-lnd-autocompact. Es tut genau eines: Es hängt die Zeile db.bolt.auto-compact=true an die LND-Konfiguration. Loggt euch per SSH ein, werdet root und wechselt in das Verzeichnis, in das btcpayserver-docker bei der Installation geklont wurde — nach der Installationsanleitung im Repository ist das BTCPayServer/btcpayserver-docker im Home-Verzeichnis von root:

sudo su -
cd BTCPayServer/btcpayserver-docker
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-lnd-autocompact"
. ./btcpay-setup.sh -i

Vergesst den Punkt vor ./btcpay-setup.sh nicht. Danach erzeugt das Skript die Docker-Konfiguration neu und startet die Container mit den neuen Einstellungen. Die aktuelle Dokumentation im Repository nennt dafür inzwischen auch den kürzeren Befehl btcpay-fragments add opt-lnd-autocompact; im Fragmentkatalog steht das Fragment als „Enable LND database auto-compaction“.

In der ersten Fassung stand hier, der Server kompaktiere mit diesem Fragment bei jedem Neustart, und db.bolt.auto-compact-min-age lasse sich nur über einen Umweg setzen. Das stimmt nicht: Weil LND ohne weitere Angabe den Standardwert von 168 Stunden nimmt, kompaktiert der Server höchstens einmal pro Woche.

Wer weitere Optionen setzen will, legt ein eigenes Fragment an. Wichtig, und in der ersten Fassung falsch: Ein Fragment ist eine YAML-Datei im Format von Docker Compose, keine lnd.conf. Die LND-Zeilen gehören in die Variable LND_EXTRA_ARGS des Dienstes lnd_bitcoin, genau so wie im mitgelieferten Fragment. Laut der Anleitung zur Anpassung enden eigene Fragmente auf .custom.yml, damit Git sie bei Updates in Ruhe lässt:

nano docker-compose-generator/docker-fragments/opt-lnd-additionals.custom.yml

services:
  lnd_bitcoin:
    environment:
      LND_EXTRA_ARGS: |
        gc-canceled-invoices-on-startup=true
        gc-canceled-invoices-on-the-fly=true
        ignore-historical-gossip-filters=true
        stagger-initial-reconnect=true

Speichert mit Strg+O und beendet mit Strg+X. Der Generator hängt mehrzeilige Werte aus mehreren Fragmenten aneinander, statt sie zu überschreiben; die Zeilen landen also zusätzlich zu den bestehenden. Aktiviert das Fragment wie oben:

export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-lnd-additionals.custom"
. ./btcpay-setup.sh -i

Die Liste aller mitgelieferten Fragmente steht im Fragmentkatalog der BTCPay-Dokumentation.

RaspiBlitz Fullnode

Auf dem RaspiBlitz ist die Kompaktierung bereits eingeschaltet. Das Installationsskript schreibt in den Abschnitt [bolt] der lnd.conf die Zeilen db.bolt.auto-compact=true und db.bolt.auto-compact-min-age=672h; kompaktiert wird also höchstens alle vier Wochen, jeweils beim Start von LND. Die übrigen empfehlenswerten Optionen — gc-canceled-invoices-on-startup, gc-canceled-invoices-on-the-fly, ignore-historical-gossip-filters und stagger-initial-reconnect — setzt es bei Neuinstallationen ebenfalls schon.

Die erste Fassung empfahl an dieser Stelle, die Zahl in der lnd.conf herunterzusetzen. Das hält nicht: Vor jedem Start von LND läuft lnd.check.sh prestart und setzt beide Werte im Abschnitt [bolt] wieder auf true und 672h zurück. Eine Handänderung ist nach dem nächsten Neustart weg.

Wollt ihr die Kompaktierung sofort auslösen, statt bis zu vier Wochen zu warten, geht das über die Zeitstempeldatei aus dem Abschnitt oben. Fehlt sie, kompaktiert LND beim nächsten Start. Stoppt zuerst LND:

sudo systemctl stop lnd.service

Prüft, ob die Datei vorhanden ist, und entfernt sie:

sudo ls -l /mnt/hdd/app-data/lnd/data/graph/mainnet/
sudo rm /mnt/hdd/app-data/lnd/data/graph/mainnet/channel.db.last-compacted

Startet LND wieder:

sudo systemctl start lnd.service

Den Verlauf verfolgt ihr im LND-Log, das der RaspiBlitz hier ablegt:

sudo tail -f /mnt/hdd/app-data/lnd/logs/bitcoin/mainnet/lnd.log

LND meldet den Beginn mit „Compacting database file at …“ und den Abschluss mit „DB compaction of … successful“ samt Grösse vorher und nachher. Wenn LND gar nicht erst hochkommt, hilft sudo journalctl -u lnd weiter; mehr dazu steht in der Anleitung zur Problembehebung im systemd.

Das folgende Bildschirmfoto vom März 2024 zeigt, wo die Optionen in der lnd.conf stehen. Die db.bolt-Zeilen gehören unter [bolt], die übrigen unter [Application Options]; so ist auch die sample-lnd.conf aufgebaut. Die Datei liegt heute unter /mnt/hdd/app-data/lnd/lnd.conf.

Wer seinen RaspiBlitz ohnehin aktualisieren will, findet die Schritte in der Anleitung RaspiBlitz auf die neueste Version aktualisieren. Welches der beiden Node-Pakete zu euch passt, klärt RaspiBlitz VS Umbrel.

Was die übrigen Optionen tun — und welche ihr weglasst

In vielen Anleitungen, auch in der ersten Fassung dieser hier, wird ein ganzer Block an Optionen mitkopiert. Was jede davon laut sample-lnd.conf tut:

• gc-canceled-invoices-on-startup=true räumt beim Start abgebrochene Rechnungen aus der Datenbank. Sinnvoll für alle, die viele Rechnungen erzeugen.
• gc-canceled-invoices-on-the-fly=true löscht neu abgebrochene Rechnungen sofort, statt sie aufzubewahren.
• ignore-historical-gossip-filters=true beantwortet Anfragen anderer Nodes nach historischen Gossip-Daten nicht. Laut Beschreibung senkt das Speicher- und Bandbreitenbedarf.
• stagger-initial-reconnect=true verteilt die Wiederverbindung zu festen Peers beim Start zufällig über 0 bis 30 Sekunden; die ersten zehn Verbindungen laufen trotzdem sofort.

Zwei Optionen aus der ersten Fassung sind gestrichen:

sync-freelist stand dort als start sync-freelist=1. Das Wort „start“ davor gehört nicht zum Optionsnamen; so eingetragen ist die Zeile schlicht ungültig. Wichtiger ist die Sache selbst: Laut sample-lnd.conf verkürzt die Option die Startzeit, kann aber bei sehr grossen Datenbanken die Leistung verschlechtern und den Speicherbedarf erhöhen — also genau bei den Nodes, für die diese Anleitung gedacht ist. Das RaspiBlitz-Projekt hat sie nach Issue 3251 („don't use sync-freelist=true in lnd.conf“) aus der Vorgabe genommen; ein Nutzer berichtet dort von einer channel.db, die mit der Option um 600 MB bis 1 GB pro Tag wuchs und ohne sie um 100 MB in sieben Tagen. Das Installationsskript kommentiert die Option inzwischen mit dem Rat, sie bei Nodes mit vielen Kanälen auf false zu setzen.

payments-expiration-grace-period=9999h hat mit der Datenbankgrösse nichts zu tun. Laut Beschreibung ist das die Wartezeit, bevor LND einen Kanal schliesst, in dem eine selbst ausgelöste Zahlung abgelaufen ist; die Vorgabe ist 0s, das Beispiel in der Dokumentation 30s. 9999 Stunden sind gut 416 Tage und schalten diese Schutzreaktion für eigene Zahlungen damit praktisch ab. Wer das will, soll es bewusst entscheiden — in einer Anleitung zum Aufräumen der Datenbank hat es nichts verloren.

Achtung: Kompaktierung braucht Zeit und freien Speicher

Auf einem kleinen System kann die Kompaktierung lange dauern. Auf einem RaspiBlitz mit mehreren Dutzend Kanälen und einer channel.db von mehreren Gigabyte habe ich ein bis drei Stunden erlebt. Solange sie läuft, ist LND noch nicht gestartet und die Node nicht erreichbar. Wartet ab. Startet die Node in dieser Zeit nicht neu und zieht nicht den Stecker.

In der ersten Fassung stand hier, bei einem Abbruch seien alle Kanäle mit hoher Wahrscheinlichkeit beschädigt. Das gibt der Quelltext nicht her: Weil LND in eine temporäre Datei schreibt und die alte erst nach erfolgreichem Abschluss ersetzt, bleibt die ursprüngliche channel.db bei einem Abbruch unangetastet, und beim nächsten Kompaktierungslauf löscht LND die halbfertige Kopie, bevor es neu beginnt. Ein harter Stromausfall bleibt trotzdem ein Risiko für jede Datenbank und jede SSD — dafür braucht es keine Kompaktierung.

Der RaspiBlitz gibt LND beim Start übrigens TimeoutStartSec=1200, also zwanzig Minuten, und begründet das in der Unit-Datei ausdrücklich mit der Datenbankkompaktierung. Wer eine sehr grosse Datenbank hat und beobachtet, dass LND während der Kompaktierung neu gestartet wird, findet hier den ersten Anhaltspunkt.

Bevor ihr LND neu startet

• Freien Platz prüfen. Auf dem Datenträger muss mindestens die Grösse der channel.db plus zehn Prozent frei sein, sonst bricht LND die Kompaktierung vor dem Start ab. Bei einer vollen SSD hilft zuerst mehr Platz, etwa mit der Anleitung Fullnode 1TB SSD auf 2TB SSD klonen.
• Kanalsicherung aktuell halten. Die Kompaktierung ist kein Backup und ersetzt keines. Wie ihr eine Node richtig sichert und warum eine alte channel.db nie zurückgespielt werden darf, steht im Backup- und Restore-Leitfaden für Lightning Fullnodes; eine automatische Sicherung der Kanal-Notfalldatei beschreibt RaspiBlitz SCB Backup auf einer Nextcloud.
• Zeit einplanen. Löst die Kompaktierung nicht mitten in einer Phase aus, in der ihr die Node dringend braucht, etwa vor einer erwarteten Zahlung.
• Keine Optionen doppelt setzen. Auf dem RaspiBlitz sind die meisten Optionen schon gesetzt; wer sie ein zweites Mal in die lnd.conf schreibt, erzeugt nur Verwirrung beim nächsten Nachsehen.
• Das Log mitlesen. Nur die Meldung „DB compaction of … successful“ sagt euch, dass es geklappt hat und wie viel es gebracht hat.

Fazit: Die Kompaktierung ist ein Schalter, kein Eingriff

Die channel.db zu verkleinern ist kein riskantes Handwerk an der offenen Datenbank. Es ist eine Funktion, die LND selbst mitbringt, die ab Werk ausgeschaltet ist und die mit einer Zeile dauerhaft läuft. Auf dem RaspiBlitz ist sie schon an, auf dem BTCPay Server reicht ein Fragment, auf Umbrel ein Schalter. Mit den ls -lh-Befehlen oben prüft ihr anschliessend, was es gebracht hat.

Die Kanaldatenbank wächst trotzdem weiter. Nach einem Jahr Routing mit vielen Kanälen habe ich Datenbanken von 15 bis 20 GB gesehen. Wichtig ist, regelmässig zu kompaktieren und dafür genug Ressourcen zu haben. Für grössere Routing-Nodes ist ein RaspiBlitz auf einem Raspberry Pi deshalb nicht die richtige Hardware; mehr zur Frage, was eine Bitcoin Full Node leisten muss, steht im Grundlagenartikel. Und wer von der Kompaktierung die Lösung aller Probleme erwartet, sollte wissen: Sie räumt den Keller auf, sie baut keinen grösseren.

Quellen und weiterführende Links

• LND: sample-lnd.conf (Beschreibung und Vorgabewerte aller genannten Optionen)
• LND: kvdb/backend.go (Ablauf der Kompaktierung, temporäre Datei, .last-compacted)
• LND: kvdb/bolt_compact.go (Prüfung des freien Speichers)
• LND: Releases
• bbolt: Projektbeschreibung, Abschnitt zu Einschränkungen (Datei schrumpft nicht)
• RaspiBlitz: lnd.install.sh und lnd.check.sh
• RaspiBlitz: Issue 3251, „don't use sync-freelist=true in lnd.conf“
• BTCPay Server: Fragment opt-lnd-autocompact, Anleitung zu eigenen Fragmenten und Fragmentkatalog
• BTCPay Server: btcpayserver-docker, Installationsanleitung