update

2026-09-28 17:37:46 +02:00
parent 95797e4a3b
commit 50406e22d1
5 changed files with 487 additions and 3 deletions
@@ -0,0 +1,144 @@
+# PostgreSQL mit DBeaver über einen SSH-Tunnel
+
+Ein SSH-Tunnel erlaubt den Zugriff auf eine Datenbank, die nur von einer
+entfernten VM aus erreichbar ist. Der Tunnel löst dabei nicht automatisch alle
+Netzwerkprobleme: Der Zielhost und Zielport werden aus Sicht der VM bewertet.
+
+## Verbindungsweg
+
+```text
+DBeaver auf dem eigenen Rechner
+        |
+        | lokaler Tunnel-Endpunkt
+        v
+SSH-Client  ───────────────►  SSH-Server auf der VM
+                                  |
+                                  | Zielhost:Zielport
+                                  v
+                           PostgreSQL auf der VM
+                           oder PostgreSQL-Container
+```
+
+Ein möglicher manueller Tunnel sieht so aus:
+
+```bash
+ssh -L 15432:127.0.0.1:5432 <user>@<vm-host>
+```
+
+Danach ist die Datenbank vom eigenen Rechner aus typischerweise über
+`127.0.0.1:15432` erreichbar. Bei DBeaver hängen die genauen Felder von der
+verwendeten SSH-Tunnel-Konfiguration ab. Wichtig ist, die lokale
+Datenbankadresse nicht mit dem entfernten Ziel der Weiterleitung zu
+verwechseln.
+
+## Docker als Datenbank-Host
+
+Wenn PostgreSQL in Docker läuft, gibt es mehrere mögliche Ziele:
+
+| Situation | Typisches Ziel aus Sicht der VM |
+| --- | --- |
+| PostgreSQL läuft direkt auf der VM | `127.0.0.1:5432` |
+| PostgreSQL-Port ist veröffentlicht | `127.0.0.1:<veröffentlichter Port>` |
+| Zugriff aus einem anderen Container | Compose-Service-Name, z. B. `postgres:5432` |
+| Direkter Zugriff auf einen Container | aktuelle Container-IP, z. B. `172.19.0.2:5432` |
+
+Eine Container-IP sollte nur zum Testen verwendet werden. Sie kann sich nach
+dem Neustart oder Neuerstellen des Containers ändern. Für eine dauerhafte
+Konfiguration sind ein Compose-Service-Name innerhalb des Docker-Netzwerks
+oder ein veröffentlichter Host-Port vorzuziehen.
+
+## Schrittweise Diagnose
+
+### 1. Den aktuellen Container und seine Ports prüfen
+
+Auf der VM:
+
+```bash
+docker ps
+docker inspect <postgres-container>
+sudo ss -ltnp | grep 5432
+```
+
+Bei `docker ps` auf die Spalte `PORTS` achten. Eine Ausgabe wie
+`127.0.0.1:5432->5432/tcp` bedeutet, dass PostgreSQL auf der VM lokal
+veröffentlicht ist. Eine Ausgabe wie `0.0.0.0:15432->5432/tcp` bedeutet, dass
+der Host-Port `15432` zum Container-Port `5432` weiterleitet.
+
+### 2. Den Zielendpunkt von der VM aus testen
+
+```bash
+nc -vz <zielhost> <zielport>
+psql -h <zielhost> -p <zielport> -U <user> -d <database>
+```
+
+Diese Tests müssen mit dem Host und Port durchgeführt werden, die der
+SSH-Tunnel aus Sicht der VM erreichen soll. Ein funktionierendes `psql` ohne
+`-h` kann beispielsweise über einen lokalen Unix-Socket verbinden und sagt
+nichts über die TCP-Verbindung aus.
+
+### 3. PostgreSQL-Logs beobachten
+
+```bash
+docker logs --tail 100 -f <postgres-container>
+```
+
+Dann in DBeaver den Verbindungstest ausführen:
+
+- **Kein neuer Logeintrag:** DBeaver erreicht PostgreSQL nicht. Tunnel,
+  Zielhost, Zielport oder lokale/entfernte Portzuordnung prüfen.
+- **Eintrag mit Authentifizierungsfehler:** Netzwerkweg funktioniert; Benutzer,
+  Passwort, Datenbank oder `pg_hba.conf` prüfen.
+- **Verbindung wird sofort beendet:** SSL-Modus, PostgreSQL-Treiber und
+  Tunnelziel vergleichen.
+
+## Typische Fehler
+
+### `hostname -I` liefert mehrere Adressen
+
+`hostname -I` zeigt alle Adressen der VM. Dazu können die Azure-Adresse und
+mehrere Docker-Bridge-Adressen gehören. Die Ausgabe ist keine Liste von
+gleichwertigen Datenbankadressen:
+
+```text
+10.2.0.4     VM-Adresse im privaten Azure-Netzwerk
+172.19.0.1   Docker-Bridge-Gateway
+172.19.0.2   möglicherweise PostgreSQL-Container
+```
+
+Mit `docker network inspect <network-name>` lässt sich prüfen, welchem
+Container eine Docker-Adresse aktuell zugeordnet ist.
+
+### SSH funktioniert, DBeaver meldet `EOF Exception`
+
+Ein erfolgreicher SSH-Aufbau beweist nur, dass der SSH-Server erreichbar ist.
+Der weitergeleitete TCP-Stream kann trotzdem am falschen Ziel oder Port enden.
+Prüfen:
+
+1. Welcher lokale Port wird von DBeaver verwendet?
+2. Welcher entfernte Host und Port werden durch den Tunnel angesprochen?
+3. Ist der PostgreSQL-Container noch unter derselben IP erreichbar?
+4. Lauscht PostgreSQL auf TCP und nicht nur auf einem Unix-Socket?
+5. Verwendet DBeaver denselben SSL-Modus wie `psql`?
+6. Erscheint der Test in den PostgreSQL-Logs?
+
+Die Verbindung sollte zunächst mit einer expliziten TCP-Verbindung geprüft
+werden:
+
+```bash
+psql -h 127.0.0.1 -p <port> -U <user> -d <database>
+```
+
+Dabei muss `<port>` dem tatsächlich veröffentlichten Port oder dem lokalen
+Port des SSH-Tunnels entsprechen.
+
+## Sicherheits- und Wartungshinweise
+
+- Keine Passwörter oder produktiven Zugangsdaten in Notizen oder
+  Verbindungsdefinitionen im Klartext speichern.
+- Container-IPs nicht als langfristige Infrastrukturkonfiguration verwenden.
+- Für dauerhafte Zugriffe DNS-Namen, Compose-Service-Namen oder stabile
+  Host-Port-Zuordnungen bevorzugen.
+- Für einen Diagnosefall die verwendeten Hosts, Ports, SSL-Einstellungen und
+  den Verbindungsweg dokumentieren, aber sensible Werte anonymisieren.
+
+Siehe auch [[SSH Verbindung in Linux]], [[psql]] und [[Docker]].