feat(linux): add persistent Avahi discovery for InfluxDB

Add a Debian NUC installer, IPv4 service definition and usage guide with backup and legacy alias migration. Document the user-confirmed SEN54-to-InfluxDB connection without including credentials.
This commit is contained in:
root
2026-11-07 20:00:02 +00:00
parent 3dcfdedc18
commit 45b05d045a
4 changed files with 251 additions and 0 deletions
+158
View File
@@ -0,0 +1,158 @@
# InfluxDB auf dem Linux-NUC per Avahi bekannt machen
Diese Dateien richten eine dauerhafte mDNS/DNS-SD-Ankündigung für die vorhandene
ESP32-Firmware ein. Avahi läuft auf dem **Debian-13-NUC**, außerhalb von Docker.
Die Konfiguration wird nach einem NUC-Neustart automatisch geladen.
## Vorgesehener Aufbau
| Einstellung | Wert |
| --- | --- |
| NUC-WLAN/AP-Interface | `wlp2s0` |
| NUC-WLAN-Adresse | `192.168.50.1/24` |
| InfluxDB-URL für den ESP | `http://192.168.50.1:8086` |
| Diensttyp | `_influxdb2._tcp.local.` |
| Dienstname | `nanoPSX InfluxDB NUC` |
| mDNS-Hostname | vorhandener Avahi-Hostname, auf diesem NUC `nuc.local` |
Der ESP muss mit dem NUC-WLAN verbunden sein. Der InfluxDB-Container muss Port
8086 an `192.168.50.1` veröffentlichen; das ist beim untersuchten NUC bereits
eingerichtet. Ein fehlender Listener an `127.0.0.1:8086` ist dabei erwartbar.
Der Dienst verwendet den vorhandenen Avahi-Hostnamen (`nuc.local` auf diesem
NUC). Es wird kein zusätzlicher Hostname für dieselbe IP registriert, da dies bei
Avahi eine lokale Namenskollision verursachen kann. Auf dem WLAN muss die
Auflösung `192.168.50.1` liefern; dies nach der Installation prüfen. Die allgemeine
Avahi-Interface-Konfiguration bleibt erhalten. Die Ankündigung kann auch auf
anderen von Avahi bedienten Interfaces sichtbar sein. Kein mDNS-Reflector wird
eingerichtet.
## Installation
1. Das Projekt oder mindestens den vollständigen Ordner `linux-app` auf den NUC
kopieren. Die folgenden Befehle dort in einer lokalen Shell ausführen.
2. Das frühere Python-mDNS-Skript bzw. dessen Systemdienst für diese
InfluxDB-Ankündigung beenden und dessen Autostart deaktivieren. Ebenso einen
laufenden Test mit `avahi-publish-service` beenden. Andere mDNS-Dienste erhalten.
3. Im Projektverzeichnis ausführen:
```bash
sudo bash linux-app/install-avahi.sh
```
Das Skript prüft die AP-Adresse und InfluxDB `/health`, installiert mit APT
`avahi-daemon`, `avahi-utils`, `curl` und `python3`, sichert vorhandene Dateien
unter `/var/backups/nanopsx-avahi/install.*` und installiert:
- `/etc/avahi/services/nanopsx-influxdb.service`
- keinen neuen Eintrag in `/etc/avahi/hosts`. Der exakt markierte Alias der ersten
Skriptversion wird nach Sicherung entfernt, falls vorhanden.
Andere Hosteinträge und Dienste bleiben erhalten. Eine unbekannte abweichende
Dienstdatei führt zum Abbruch. Die unveränderte erste Version der mitgelieferten
Dienstdatei wird anhand ihres SHA-256 erkannt und automatisch aktualisiert.
Wiederholtes Ausführen mit unveränderten Einstellungen erzeugt keine doppelten
Hosteinträge. Ein fehlgeschlagener Installationslauf ist kein Erfolgsnachweis;
die ausgegebenen Fehler zuerst prüfen. Bereits installierte Pakete bleiben bei
einem späteren Fehler installiert.
Es werden weder Docker, Firewall, WireGuard, SSH noch ESP-Firmware geändert.
Es sind keine Influx-Tokens oder WLAN-Passwörter in diesen Dateien erforderlich.
## Funktion prüfen
Auf dem NUC:
```bash
systemctl is-enabled avahi-daemon.service
systemctl is-active avahi-daemon.service
curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health
avahi-browse -r -t _influxdb2._tcp
```
Erwartet: `enabled`, `active`, Health-Status `pass` und beim aufgelösten Dienst
auf Interface `wlp2s0` mit IPv4 die Adresse `192.168.50.1`, Port `8086`
und Hostname `nuc.local` (sofern der Rechnername nicht geändert wurde).
`avahi-browse` unterstützt weder `-4` noch `-i`; die Ausgabe enthält Interface
und IP-Protokoll als Spalten.
Zusätzlich von einem anderen Linux-Rechner im NUC-WLAN prüfen, sofern verfügbar:
```bash
avahi-browse -r -t _influxdb2._tcp
curl --noproxy '*' -fsS --max-time 5 http://192.168.50.1:8086/health
```
Ein lokaler NUC-Test allein beweist noch keine Erreichbarkeit vom ESP.
Die Firmware sucht ungefähr alle 60 Sekunden, bis sie einen Dienst gefunden
hat, und speichert dessen URL. Hat sie bereits einen anderen Dienst gefunden,
den ESP einmal neu starten, nachdem die richtige Ankündigung aktiv ist.
Die seriellen ESP-Logs sollen anschließend `mDNS URL: http://192.168.50.1:8086`
zeigen. Erst erfolgreiche Influx-Schreibvorgänge mit HTTP-Status `204` und
aktuelle Messwerte im Influx-Bucket bestätigen die vollständige Verbindung.
Organisation, Bucket und ein Token mit Schreibrecht für diesen Bucket müssen
zusätzlich im ESP-Konfigurationsportal hinterlegt sein. Tokens dort lokal
eingeben und nicht in Git oder Diagnoseausgaben veröffentlichen.
Avahi kündigt statisch an: Es überwacht die Verfügbarkeit des Containers nicht.
Die Installation prüft `/health` einmalig. Nach einem NUC-Neustart kann die
Ankündigung schon sichtbar sein, bevor InfluxDB bereit ist; die Firmware muss
Verbindungsversuche wiederholen.
## Fehler untersuchen
```bash
journalctl -u avahi-daemon.service -b --no-pager -n 80
ip -br -4 addr
ss -ltn '( sport = :8086 )'
```
- Kein Dienst gefunden: Avahi-Status und Logs prüfen. In
`/etc/avahi/avahi-daemon.conf` darf `wlp2s0` nicht ausgeschlossen und Publishing
nicht deaktiviert sein. Das Installationsskript überschreibt diese Einstellungen
bewusst nicht.
- Nur lokal sichtbar: Firewall für mDNS (UDP 5353, IPv4-Multicast
`224.0.0.251`) auf dem WLAN und mögliche AP-Client-Isolation prüfen.
- HTTP-Timeout: TCP 8086 vom WLAN, Docker-Portfreigabe und Firewall prüfen.
- HTTP 401/403: Influx-Token und dessen Bucket-Schreibrechte prüfen.
- Mehrere Influx-Dienste: Die Firmware nimmt einen passenden Treffer. Alte
konkurrierende Ankündigungen entfernen, bevor die Erkennung erneut startet.
Keine Firewall-Regeln pauschal löschen und keine unbekannten Dienste abschalten.
Für einen anderen AP die Adresse und das Interface im Installationsskript
gezielt anpassen und die Auflösung auf dem neuen WLAN prüfen.
## Ankündigung entfernen
Nur die von dieser Einrichtung angelegten Einträge entfernen:
```bash
sudo rm /etc/avahi/services/nanopsx-influxdb.service
sudo systemctl reload avahi-daemon.service
```
Falls die Dateien inzwischen manuell geändert wurden, vor dem Entfernen prüfen.
Vorhandene Hosteinträge bleiben erhalten. Avahi und seine anderen Dienste bleiben aktiv. Die Sicherung enthält
die vorherigen Dateien; diese nicht pauschal zurückkopieren, wenn inzwischen
weitere Änderungen vorgenommen wurden.
## Referenzen
- [Debian: statische Avahi-Dienste](https://manpages.debian.org/trixie/avahi-daemon/avahi.service.5.en.html)
- [Debian: avahi-browse und gültige Optionen](https://manpages.debian.org/trixie/avahi-utils/avahi-browse.1.en.html)
- [InfluxDB: Health-Prüfung](https://docs.influxdata.com/influxdb/v2/api/health/)
## Getesteter Stand (2026-11-07)
Skriptsyntax, XML, Installation und Migration der ersten Konfiguration wurden
im Entwicklungscontainer mit isolierten Systemaufrufen geprüft. Der Benutzer
hat die Konfiguration auf dem Debian-NUC installiert und die korrigierte
Dienstdatei ohne zusätzlichen Hostnamen eingesetzt. Seine `avahi-browse`-Ausgabe
bestätigt auf `wlp2s0` die Auflösung von `nuc.local` zu `192.168.50.1:8086`.
Serielle Tests des ESP bestätigten anschließend HTTP-Verbindungen zu dieser
Adresse. Nach Einrichtung von Organisation `Home`, Bucket `nanoPSX` und einem
passenden Token hat der Benutzer die funktionierende SEN54-Übertragung zu
InfluxDB bestätigt. Diese abschließende Funktionsbestätigung stammt vom Benutzer;
eine weitere serielle Aufzeichnung mit erfolgreichen Schreibantworten wurde
danach nicht erstellt. Zugangsdaten gehören nicht in diese Dokumentation.