vogto/Auto-Outline-Doku-Proxmox-Inventory

Files

T

Claude 2f1171e0d4 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

2026-07-29 18:47:35 +00:00

5.4 KiB

Raw Permalink Blame History

Auto Outline Doku Proxmox Inventory

Automatischer Abgleich zwischen Proxmox-Inventar und der Homelab-Dokumentation in Outline.

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. 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

Script konfigurieren: In scripts/proxmox-inventory-json.sh die Variable N8N_WEBHOOK_URL auf die echte n8n-Webhook-URL setzen (aktuell ein Platzhalter, da diese pro Installation individuell ist). Wichtig: Produktions-Pfad (/webhook/...) verwenden, nicht /webhook-test/... – der Test-Pfad funktioniert nur, während der Workflow im n8n-Editor auf "Listen for test event" steht.
n8n-Workflow importieren: JSON-Datei in n8n importieren und aktivieren/publishen (der Webhook reagiert sonst nicht auf den Produktions-Pfad). Folgende Credentials werden benötigt (nicht im Export enthalten, aus Sicherheitsgründen):
- Outline Bearer Auth (Header Auth, Authorization: Bearer <Outline-API-Token>) – für alle outline.vogt.de.com/api/...-Requests
- NTFY Bearer Auth (Header Auth) – für die ntfy-Benachrichtigung am Ende
Webhook-Pfad in n8n mit der URL im Script abgleichen.
Erst mit --vmids=<einzelne-VMID> --dry-run testen, bevor der volle Sync scharf geschaltet wird.

Automatischer Betrieb per Cron

Auf dem Proxmox-Host crontab -e und folgende Zeile eintragen, um das Script stündlich zwischen 07:00 und 20:00 Uhr laufen zu lassen:

0 7-20 * * * /root/proxmox-inventory-json.sh >> /var/log/proxmox-inventory-sync.log 2>&1

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:

grep -i "command not found" /var/log/proxmox-inventory-sync.log

Optionale Logrotate-Regel, damit das Log nicht unbegrenzt wächst:

cat > /etc/logrotate.d/proxmox-inventory-sync << 'EOF'
/var/log/proxmox-inventory-sync.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}
EOF

Vor dem Scharfschalten prüfen:

Läuft das Script lokal auf dem Host mit der echten (nicht der Platzhalter-)Webhook-URL?
Ist der n8n-Workflow aktiviert (active: true)?
Ein manueller Testlauf (./proxmox-inventory-json.sh --dry-run) zeigt das gebaute JSON ohne etwas zu senden – guter erster Check nach jeder Änderung.

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 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
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.

5.4 KiB Raw Permalink Blame History Unescape Escape