audi-app/homeassistant/INTERNET_ZUGRIFF_EINRICHTEN.md

Internetzugriff für DataMetric360 einrichten

Schritt-für-Schritt-Anleitung, damit die native Companion-App (iOS-Sideload, siehe ../COMPANION_APP_ARCHITECTURE.md §1) von unterwegs (Mobilfunk, fremdes WLAN) funktioniert - nicht nur im Heimnetz/über Tailscale. Home Assistant selbst bleibt dabei durchgehend lokal, ohne offenen Port; nur ein eng begrenzter, pfad-gefilterter Ausschnitt der API wird über einen Cloudflare-Tunnel erreichbar gemacht. Architektur/Begründung: ../COMPANION_APP_ARCHITECTURE.md §4. Die technische Pfad-Freigabeliste selbst, die in Schritt 4 unten eingetragen wird: REVERSE_PROXY.md.

Wer was macht: Kontoerstellung, Domain-/Nameserver-Verwaltung bei Cloudflare bzw. all-inkl und das Klicken durch die HA-Add-on-Oberfläche sind ausschließlich Sache des Fahrzeughalters selbst - dafür gibt es hier keine Automatisierung, nur die genauen Schritte. Alles, was als Datei/Konfiguration vorbereitet werden konnte, ist bereits fertig (REVERSE_PROXY.mds Regeln).

Voraussetzungen, die bereits erfüllt sind (nichts davon ist hier noch zu tun):

• datametric360.de ist bei all-inkl registriert (siehe ../COMPANION_APP_ARCHITECTURE.md §5 Punkt 4)
  • eigens dafür, ohne Webseite/Postfach darauf.
• Die companion-app spricht bereits ausschließlich REST/WebSocket gegen eine konfigurierbare "Server-Adresse" (kein hass-Objekt, kein fest verdrahteter Hostname) - dieser Schritt ändert nur, welche Adresse dort später eingetragen wird, nicht die App selbst.

---

1. Cloudflare-Konto anlegen, Domain hinzufügen

1. Auf cloudflare.com ein (kostenloses) Konto anlegen.
2. Im Dashboard Add a Site → datametric360.de eingeben.
3. Plan Free wählen - reicht vollständig aus (Tunnel und DNS sind im Free-Plan enthalten, nur das "partial/CNAME setup" ohne Nameserver-Wechsel wäre Business-only, siehe Schritt 2).
4. Cloudflare scannt bestehende DNS-Einträge der Domain und schlägt zwei Nameserver vor (z. B. xxx.ns.cloudflare.com, yyy.ns.cloudflare.com) - notieren, die werden in Schritt 2 gebraucht.

2. Nameserver bei all-inkl auf Cloudflare umstellen

Das ist der eigentliche Knackpunkt - erst danach kann der Tunnel überhaupt einen Hostnamen veröffentlichen.

1. Bei all-inkl (KAS-Verwaltung) einloggen → Domains → datametric360.de → Nameserver-Einstellungen.
2. Von all-inkls eigenen Nameservern auf die beiden von Cloudflare vorgeschlagenen (Schritt 1.4) umstellen - das ist ein "Full setup": die komplette DNS-Verwaltung der Domain wandert zu Cloudflare, nicht nur ein einzelner Eintrag. Das ist hier folgenlos, weil auf dieser Domain nichts anderes liegt (keine Webseite, kein Postfach) - siehe die Einschränkung in ../COMPANION_APP_ARCHITECTURE.md §5 Punkt 4, warum die Domain extra dafür angelegt wurde.
3. Umstellung kann laut Cloudflare bis zu 24 Stunden dauern (meist deutlich schneller). Status im Cloudflare-Dashboard prüfen - die Domain wechselt dort von "Pending Nameserver Update" auf "Active".
4. Erst wenn "Active" angezeigt wird, mit Schritt 3 weitermachen (ein Tunnel-Hostname lässt sich vorher zwar anlegen, aber die DNS-Auflösung funktioniert erst danach).

3. Cloudflared-Add-on installieren und Tunnel einrichten

1. In Home Assistant: Einstellungen → Add-ons → Add-on Store → nach "Cloudflared" suchen, installieren. Empfohlen und geprüft: homeassistant-apps/app-cloudflared (Tobias Brenner, MIT-lizenziert, aktiv gepflegt, >1.500 GitHub-Stars) - kein offizielles Home-Assistant-Add-on, aber das etablierte Community-Add-on für genau diesen Zweck; nicht die eigenständige cloudflared-CLI von Hand einrichten.
2. Im Cloudflare-Dashboard: Zero Trust → Networks → Tunnels → Create a tunnel → Typ "Cloudflared" → Namen vergeben (z. B. datametric360).
3. Cloudflare zeigt einen Tunnel-Token an - diesen im HA-Add-on unter Konfiguration im Feld tunnel_token eintragen ("Remote Tunnel Setup" in den Add-on-Docs; alle anderen Konfigurationsfelder des Add-ons werden dann ignoriert). Kein manueller cloudflared-Aufruf per SSH nötig, und kein Cloudflare-API-Token nötig - das Add-on hat neben diesem Weg auch einen zweiten, browserbasierten Modus ("Local Tunnel Setup", legt den Tunnel selbst per Login-Link an), der hier bewusst nicht verwendet wird: der manuelle Weg über den Tunnel-Token macht sichtbar und nachvollziehbar, welcher Tunnel mit welchem Namen existiert, statt das dem Add-on zu überlassen.
4. Add-on starten. Im Cloudflare-Dashboard sollte der Tunnel danach als "Healthy"/verbunden angezeigt werden - das bestätigt die ausgehende Verbindung vom HAOS-Host zu Cloudflares Edge (kein Router-Port nötig, kein Port-Forward einzurichten).
5. Öffentlichen Hostnamen noch nicht auf Home Assistant selbst zeigen lassen - das kommt erst in Schritt 5, nachdem der Reverse Proxy (Schritt 4) steht. Der Tunnel zeigt am Ende auf den Reverse Proxy, nie direkt auf Port 8123.

4. Nginx Proxy Manager installieren und Pfad-Freigabeliste eintragen

1. Einstellungen → Add-ons → Add-on Store → "Nginx Proxy Manager" installieren, starten.
2. Die Weboberfläche des Add-ons öffnen (Standard-Login beim ersten Start: admin@example.com / changeme - sofort ändern, siehe Add-on-Dokumentation).
3. Hosts → Proxy Hosts → Add Proxy Host:
   • Domain Names: datametric360.de
   • Forward Hostname/IP: homeassistant (interner Name im Supervisor-Docker-Netz; alternativ localhost/homeassistant.local.hass.io, je nach Add-on-Version - im Zweifel im Add-on-Log nachsehen, mit welchem Namen sich homeassistant:8123 von dort aus auflösen lässt)
   • Forward Port: 8123
   • SSL: eigenes Cloudflare-Zertifikat reicht (der Tunnel terminiert TLS bereits an Cloudflares Edge) - hier kann "Force SSL" aktiv bleiben, ein eigenes Let's-Encrypt-Zertifikat ist nicht zwingend nötig, schadet aber auch nicht.
4. Im Tab Advanced den kompletten nginx-Codeblock aus REVERSE_PROXY.md (Abschnitt "Nginx Proxy Manager") unverändert einfügen - das ist die eigentliche Pfad-Freigabeliste: nur /api/, /api/states/sensor.audi_dashboard_*, /api/services/audi_dashboard/*, /api/services/homeassistant/restart, /api/websocket, /audi_dashboard_static/app/* und /local/bilder/*.{webp,png,jpg,svg} kommen durch - alles andere (/lovelace, /config, /auth/*, die HA-Oberfläche selbst) liefert 404.
5. Speichern.

5. Cloudflare-Tunnel auf den Reverse Proxy zeigen lassen

1. Zurück im Cloudflare-Dashboard: Zero Trust → Networks → Tunnels → den Tunnel aus Schritt 3 öffnen → Public Hostname → Add a public hostname.
2. Subdomain: leer lassen (Apex-Domain datametric360.de selbst - kein Subdomain-Präfix, siehe "Ein einziger Hostname genügt" in REVERSE_PROXY.md).
3. Domain: datametric360.de
4. Service Type: HTTPS (nicht HTTP - Nginx Proxy Manager terminiert selbst wieder TLS).
5. URL: die interne Adresse des Nginx-Proxy-Manager-Add-ons, üblicherweise der Add-on-Hostname im Supervisor-Netz plus dessen konfigurierten Port (im Add-on selbst unter Info nachsehen, welcher interne Port/Hostname das ist - nicht Port 8123, das wäre HA direkt).
6. Speichern. Danach unbedingt gegenprüfen, welche URL hier tatsächlich hinterlegt ist - zeigt sie aus Versehen auf homeassistant:8123 statt auf den NPM-Port, läuft die komplette HA-Oberfläche samt Login öffentlich, ohne dass die Pfad-Freigabeliste aus Schritt 4 überhaupt greift. Das ist der größte praktische Stolperstein dieser ganzen Einrichtung.

6. Sicherheitseinstellungen (Cloudflare + Nginx Proxy Manager)

Zusätzlich zur reinen Pfad-Freigabeliste (Schritt 4) - die eigentliche Sicherheit hängt an genau zwei Dingen: dem Zugriffstoken und daran, dass wirklich nur die gelisteten Pfade durchkommen. Alles hier ist zusätzliche Härtung, kein Ersatz dafür.

Cloudflare, Tab DNS:

• Prüfen, ob beim Domain-Import aus dem alten all-inkl-Bestand zusätzliche DNS-Einträge übernommen wurden (z. B. eine Parkseiten-A-Eintragung) - außer dem vom Tunnel selbst angelegten Eintrag soll nichts auf der Domain liegen.
• Der vom Tunnel angelegte Eintrag muss "Proxied" (orange Wolke) sein, nicht "DNS only" (grau).

Cloudflare, Tab SSL/TLS:

• Verschlüsselungsmodus "Full", nicht "Flexible".
• "Always Use HTTPS" aktivieren.
• Unter Edge Certificates: HSTS aktivieren (moderate max-age, z. B. 6 Monate) - gleicht aus, dass .de (anders als das ursprünglich erwogene .app) nicht auf der HSTS-Preload-Liste steht, siehe COMPANION_APP_ARCHITECTURE.md §5 Punkt 4.

Cloudflare, Tab Security:

• Bot Fight Mode NICHT aktivieren - die native App ist kein Browser und würde von den Bot-Heuristiken vermutlich mitblockiert.
• Optional: eine Rate-Limiting-Regel auf /api/* (im Free-Plan in Grenzen enthalten) bremst reines Durchprobieren, ersetzt aber nicht den Token.

Nginx Proxy Manager, Proxy Host:

• "Block Common Exploits" und "Websockets Support" aktivieren. "Force SSL" braucht ihr nur, wenn ihr dem Host ein eigenes Zertifikat gebt - bei "HTTP Only" (siehe SSL-Abschnitt oben, kein eigenes Zertifikat nötig, da Cloudflare die Verschlüsselung nach außen übernimmt) ist die Option ohnehin ausgegraut.
• ⚠️ Echter, live gefundener Fehler (2026-08-28) - include conf.d/include/proxy.conf; NICHT verwenden. Der Codeblock in REVERSE_PROXY.md enthielt ursprünglich diese Zeile in jedem location-Block (Standard-Praxis bei der vanilla jc21-nginx-proxy-manager-Doku). Beim homeassistant-apps/app-cloudflared-Gegenstück - genauer: bei diesem NPM-Add-on (homeassistant-apps, Frenck) - enthält diese geteilte Datei selbst bereits ein proxy_pass, zusammen mit dem eigenen proxy_pass im Block ergibt das nginx: [emerg] "proxy_pass" directive is duplicate - die Konfiguration lädt dann gar nicht mehr (nginx startet nicht, das Add-on crash-loopt). Symptom, falls das passiert: alle Pfade liefern "Not Found", auch die, die eigentlich erlaubt sein sollten, und das Protokoll zeigt diese [emerg]-Zeile beim Start. Ein einfacher Neustart des Add-ons behebt das NICHT (die Datei bleibt kaputt) - nötig war eine komplette Deinstallation + Neuinstallation des Add-ons. Der aktuelle, korrigierte Codeblock in REVERSE_PROXY.md verzichtet deshalb auf die include-Zeile und schreibt die nötigen proxy_set_header-Zeilen direkt in jeden Block.

Zugriffstoken:

• Pro Gerät ein eigener Token, nicht denselben auf mehreren Handys - dann lässt sich ein verlorenes Gerät gezielt aussperren (Profil → Sicherheit → Zugriffstoken), ohne das andere neu einzurichten.
• Ausschließlich als Authorization: Bearer-Header, nie in der URL/Query-String.

Router:

• Sicherstellen, dass kein Port-Forward auf 8123 existiert (auch keiner mehr aus früheren Versuchen anderer Ports/Zwecke).

7. Prüfen

Von einem Netz ohne VPN/Tailscale (z. B. Mobilfunk, WLAN-Tethering vom Handy) die Prüfbefehle aus REVERSE_PROXY.md (Abschnitt "Nach der Einrichtung prüfen") ausführen. Kurzfassung: GET /api/ und GET /api/states/sensor.audi_dashboard_profil (mit gültigem Zugriffstoken) müssen funktionieren; GET /auth/authorize und GET /api/config müssen 404/403 liefern; ohne Token muss /api/states/... mit 401 statt 200 antworten. Und: Port 8123 darf von außen gar nicht antworten (z. B. über einen externen Port-Checker prüfen, oder curl gegen http://<öffentliche-WAN-IP>:8123, das muss ins Leere laufen).

8. Server-Adresse in der App eintragen

Auf jedem Gerät, auf dem die companion-app sideload-installiert ist: beim (erneuten) Einrichten https://datametric360.de als Server-Adresse eintragen, den bestehenden Zugriffstoken wiederverwenden oder einen neuen erzeugen. Ab hier funktionieren sowohl die normalen Datenabrufe als auch Fern-OTA-Updates (AGENTS.md, Abschnitt zu @capgo/capacitor-updater) über denselben Weg - lokal im Heimnetz weiterhin genauso wie zuvor, da HA selbst unverändert nur lokal erreichbar bleibt und die App ohnehin dieselbe Server-Adresse für beide Fälle verwendet.

Was danach noch offen bleibt

• Ein Fehlschlag in Schritt 7 zuerst hier prüfen, in dieser Reihenfolge: Ist die Domain in Cloudflare "Active" (Schritt 2)? Zeigt der Tunnel "Healthy" (Schritt 3.4)? Antwortet der Nginx-Proxy-Manager-Host lokal überhaupt (curl von der HA-Konsole gegen die in Schritt 5.5 eingetragene interne Adresse)? Erst danach die Pfad-Regeln selbst (Schritt 4) noch einmal gegen REVERSE_PROXY.md vergleichen.
• Ein Gerät verlieren/kompromittiert vermuten: den betroffenen Zugriffstoken im HA-Profil zurückziehen (Profil → Sicherheit → Zugriffstoken (Long-Lived Access Tokens)) - das sperrt sofort aus, unabhängig vom Tunnel/Reverse-Proxy.
• Diese Anleitung deckt nur den Netzwerkweg ab. Für alles rund um Xcode-Signierung/Sideload der App selbst: ../COMPANION_APP_ARCHITECTURE.md §1 ("Distribution: sideload only").