fix: eliminate race condition on multi-field updates, add PATH fix for cron

- n8n workflow: apply all field changes to full document text in one pass,
  send single documents.update per container/VM instead of multiple patch
  calls (fixed race condition where parallel patches to the same doc could
  partially overwrite each other, e.g. RAM update lost when Swap changed
  simultaneously)
- n8n workflow: add HTTP Request Doc Info (documents.info) node to fetch
  fresh document content by ID instead of relying on the search index
  snapshot, which can lag slightly behind
- n8n workflow: add Aggregate node after documents.update so the
  Loop Over Items (Split In Batches) counter stays correct regardless of
  how many fields changed
- proxmox-inventory-json.sh: explicit PATH export so pct/qm are found
  under cron's restricted PATH (fixes empty containers/vms payload in
  production cron runs while manual testing looked fine)
- README: document all of the above + known limitation with Outline table
  column width metadata not being touched by content-only sync
This commit is contained in:
Claude
2026-07-29 18:47:35 +00:00
parent 7015e26fdf
commit 2f1171e0d4
3 changed files with 42 additions and 12 deletions
+16 -5
View File
@@ -5,8 +5,8 @@ Automatischer Abgleich zwischen Proxmox-Inventar und der Homelab-Dokumentation i
## Inhalt
- `scripts/proxmox-inventory.sh` Text-Ausgabe des Proxmox-Inventars (VMID, Status, Ressourcen, Netzwerk inkl. Subnetzmaske/Gateway), zum manuellen Ausführen und Copy-Paste.
- `scripts/proxmox-inventory-json.sh` Baut dieselben Daten als JSON und sendet sie per `curl` an einen n8n-Webhook. Unterstützt `--dry-run`, `--print-only` und `--vmids=101,102,...` zum gezielten Testen einzelner Container/VMs.
- `n8n-workflows/auto-outline-doku-proxmox-inventory.json` Exportierter n8n-Workflow, der die vom Script gesendeten Daten mit Outline abgleicht: Fakten (RAM, CPU, Swap, Disk, IP, Gateway, Subnetz, MAC) patchen, neue VMIDs automatisch als Outline-Seite anlegen, und eine ntfy-Benachrichtigung mit Zusammenfassung senden.
- `scripts/proxmox-inventory-json.sh` Baut dieselben Daten als JSON und sendet sie per `curl` an einen n8n-Webhook. Unterstützt `--dry-run`, `--print-only` und `--vmids=101,102,...` zum gezielten Testen einzelner Container/VMs. Erkennt außerdem per `--vmids` angeforderte, aber in Proxmox nicht mehr existierende VMIDs und meldet sie im Payload (`missing_vmids`).
- `n8n-workflows/auto-outline-doku-proxmox-inventory.json` Exportierter n8n-Workflow, der die vom Script gesendeten Daten mit Outline abgleicht: Fakten (RAM, CPU, Swap, Disk, IP, Gateway, Subnetz, MAC) aktualisieren, neue VMIDs automatisch als Outline-Seite anlegen, und eine ntfy-Benachrichtigung mit Zusammenfassung senden.
## Setup
@@ -28,6 +28,11 @@ Auf dem Proxmox-Host `crontab -e` und folgende Zeile eintragen, um das Script st
- `7-20` = jede volle Stunde von 7 bis 20 Uhr (14 Läufe/Tag)
- Ausgabe (inkl. Fehler) landet in `/var/log/proxmox-inventory-sync.log`
**Wichtig PATH in Cron:** Cron nutzt einen deutlich eingeschränkteren `PATH` als eine interaktive Shell; `pct`/`qm` liegen meist unter `/usr/sbin` und werden von Cron sonst nicht gefunden (Symptom: leere `containers`/`vms`-Arrays im Payload, keine Fehlermeldung beim manuellen Testlauf). Das Script setzt den `PATH` deshalb selbst explizit am Anfang bei Problemen zuerst prüfen:
```bash
grep -i "command not found" /var/log/proxmox-inventory-sync.log
```
Optionale Logrotate-Regel, damit das Log nicht unbegrenzt wächst:
```bash
@@ -50,12 +55,18 @@ EOF
## Funktionsweise (Kurzfassung)
- Script sammelt Proxmox-Daten (LXC + VM) → sendet JSON an n8n
- n8n sucht pro VMID die passende Outline-Seite (`documents.search`), lädt den aktuellen Inhalt separat nach (`documents.info`, um Suchindex-Verzögerungen zu vermeiden)
- Bei Abweichungen: gezielter Patch nur der betroffenen Felder (`documents.update`, editMode `patch`)
- n8n sucht pro VMID die passende Outline-Seite (`documents.search`), lädt den aktuellen Inhalt **separat per ID nach** (`documents.info`), um zu verhindern, dass ein leicht veralteter Suchindex-Snapshot verwendet wird
- Bei Abweichungen: **alle** betroffenen Felder werden in einem einzigen Rutsch im JS-Code auf den Volltext angewendet, danach genau **ein** `documents.update`-Call pro Container/VM (kein mehrfaches Patchen mehr) das verhindert Race Conditions, bei denen zwei parallele Patch-Requests auf dasselbe Dokument sich gegenseitig teilweise überschreiben
- Bei keinem Treffer: neue Seite wird automatisch aus den bekannten Fakten angelegt (`documents.create`), unbekannte Felder wie Zweck/Ports bleiben als Platzhalter
- Am Ende: Zusammenfassung aller Änderungen/Auffälligkeiten per ntfy
- Ein **Aggregate**-Node fasst die Update-Response wieder zu einem Item zusammen, bevor es zurück in die "Loop Over Items"-Schleife (Split In Batches) läuft nötig, damit die Schleife bei Items mit mehreren geänderten Feldern nicht durcheinanderkommt
- Am Ende: Zusammenfassung aller Änderungen/Auffälligkeiten per ntfy (nur Zeilen mit echten Änderungen oder Auffälligkeiten, keine "keine Änderung"-Flut)
## Bewusst nicht automatisiert
- Kategorisierung, Zweck-Beschreibung, Ports/URLs in der zentralen Übersichtstabelle (nicht aus Proxmox ableitbar)
- Umbenennen/Archivieren bei VMID-Wiederverwendung (z. B. wenn eine VMID gelöscht und für einen neuen Container wiederverwendet wird) das bleibt manuelle Review-Arbeit
## Bekannte Einschränkung
Wenn eine Tabellen-Spaltenbreite in Outline manuell per Drag verändert wurde, bleibt diese (von unserem Sync unberührte) Breiten-Metadaten bestehen, auch wenn sich der Zellinhalt durch den Sync ändert das kann optisch zu leicht verschobenen Trennlinien führen. Der Sync schreibt nur den Markdown-Inhalt, nicht die internen Tabellen-Layout-Metadaten von Outline. Workaround: Spaltenbreite einmalig manuell in Outline nachziehen.