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 6 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.app 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.app 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.app → 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. (Offizielles Home Assistant Community Add-on - 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 eintragen (Feld tunnel_token bzw. je nach Add-on-Version über die angezeigte cloudflared service install-Zeile; das Add-on übernimmt das Token-Handling, kein manueller cloudflared-Aufruf per SSH nötig).
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.app
   • 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.app selbst - kein Subdomain-Präfix, siehe "Ein einziger Hostname genügt" in REVERSE_PROXY.md).
3. Domain: datametric360.app
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.

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

7. Server-Adresse in der App eintragen

Auf jedem Gerät, auf dem die companion-app sideload-installiert ist: beim (erneuten) Einrichten https://datametric360.app 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 6 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").