Skip to content

v0.4.4 — Hotfix: Initial-Reconcile als Background-Task, kein 502 mehr beim Start

Choose a tag to compare

View all tags
@dibi73 dibi73 released this 03 May 20:47
· 15 commits to main since this release
v0.4.4
52ad06e
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Hotfix — kein 502 mehr beim Container-Start

v0.4.3 bringt Container, Qdrant und Embedder sauber hoch — aber bei einer Erstinstallation mit vielen Markdown-Files hängt der FastAPI-Lifespan synchron im Initial-Reconcile: jede Datei braucht ~1-2 Sek auf aarch64-CPU für das Embedding, und solange der Sweep läuft, bindet uvicorn keinen Port. HA-Ingress gibt während dieser ganzen Zeit 502 zurück — bei großen Exports problemlos 30+ Minuten.

Fix

pipeline.reconcile_all() läuft jetzt als Background-Task statt im Lifespan-kritischen Pfad:

reconcile_task = asyncio.create_task(_run_initial_reconcile(pipeline))

Konkret: asyncio.to_thread() schiebt den synchronen Reconcile in einen Thread-Pool, der asyncio-Loop bleibt frei, Lifespan yieldet innerhalb von Sekunden. Uvicorn bindet sofort den Port, Web-UI lädt, Queries werden gegen den partiell befüllten Index beantwortet, der sich im Hintergrund weiter füllt.

Watcher wird VOR der Reconcile-Task gestartet, also werden Filesystem-Events während des Sweeps trotzdem verarbeitet. Die Hash-basierte Idempotenz der Pipeline garantiert: ein Watcher-Event während Reconcile hasht halt eine Datei die der Bulk-Sweep eh angefasst hätte — keine Duplikate, keine Race-Conditions.

Was du im Add-on-Log nach Update siehst

INFO:app.main:Starting BookStack RAG v0.4.4
INFO:app.embedder:Loading embedding model nomic-ai/nomic-embed-text-v1.5
INFO:app.embedder:Embedding model loaded — vector size 768
INFO:app.main:Initial reconcile dispatched as background task — API is now ready
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
                                                  ← API ist hier sofort responsive
... (Reconcile läuft im Hintergrund weiter, du siehst „Indexed ..."-Zeilen tropfenweise)
INFO:app.main:Initial reconcile (background) complete: indexed=N unchanged=0 ...

Update auf v0.4.4

In HA: Update-Button auf der BookStack-RAG-Karte. Build dauert wegen Layer-Cache 1-2 Min. Container startet, innerhalb von 30 Sek (statt vorher endlos) ist die UI erreichbar. Kein 502 mehr.

/api/status zeigt während des Background-Reconciles:

  • markdown_files: N — wie viele Files auf der Disk liegen (fix)
  • indexed: K — wie viele schon im Qdrant-Index sind (wächst)

Also kannst du in der UI live verfolgen wie der Index wächst.

Was bleibt offen (für v0.5.0)

  • home-assistant/builder GitHub-Action für vorgebaute Multi-Arch-Images auf ghcr.io
  • image: in config.yaml → Erstinstall geht von 5-15 Min auf ~2 Min runter
  • Plus: echter docker run-Smoke-Test im CI — würde diese Klasse von Bug („Container hochfahren und prüfen dass /api/status antwortet") in CI fangen statt erst beim User
  • Damit hätten wir die ganze Hotfix-Serie v0.4.1 → v0.4.4 in einer einzigen CI-Phase abgefangen

Vollständiger Change-Log

CHANGELOG.md

Assets 2
Loading