proxmox-infrastruktur/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Inhaltsverzeichnis

1. Container Probleme
2. Netzwerk Probleme
3. SSL/Zertifikat Probleme
4. Service-spezifische Probleme
5. Backup/Restore Probleme
6. Performance Probleme

---

1. Container Probleme

Container startet nicht

Symptom: docker compose up -d laeuft, aber Container ist nicht aktiv

# Status pruefen
docker compose ps

# Logs anzeigen
docker logs <container-name>

# Detaillierte Infos
docker inspect <container-name>

Haeufige Ursachen:

1. Port bereits belegt

   # Port pruefen
   netstat -tulpn | grep <port>
   
   # Prozess beenden oder Port aendern
   

2. Volume-Berechtigungen

   # Berechtigungen korrigieren
   chown -R 1000:1000 /opt/docker/<service>
   chmod -R 755 /opt/docker/<service>
   

3. Fehlende .env Datei

   # Pruefen ob .env existiert
   ls -la /opt/docker/.env
   
   # Aus Template erstellen
   cp docker/.env.template docker/.env
   

"Permission denied" auf Proxmox

Symptom: socketpair() failed (13: Permission denied)

Loesung: security_opt in docker-compose.yml:

security_opt:
  - apparmor=unconfined
  - seccomp=unconfined

Container restarts staendig

Symptom: Container Status zeigt "Restarting"

# Exit-Code pruefen
docker inspect --format='{{.State.ExitCode}}' <container>

# Letzten Fehler anzeigen
docker logs --tail 50 <container>

# Health-Check deaktivieren zum Debuggen
docker compose up -d --no-healthcheck <service>

---

2. Netzwerk Probleme

WireGuard Tunnel nicht verbunden

Symptom: Keine Verbindung zu 10.0.0.x Adressen

# WireGuard Status
wg show wg0

# Interface pruefen
ip addr show wg0

# Tunnel neu starten
systemctl restart wg-quick@wg0

# Logs pruefen
journalctl -u wg-quick@wg0 -n 50

Checkliste:

• PrivateKey/PublicKey korrekt?
• Endpoint IP:Port erreichbar?
• Firewall-Regeln auf VPS?
• PersistentKeepalive gesetzt?

Service nicht extern erreichbar

# 1. Container laeuft?
docker ps | grep <service>

# 2. Port offen auf Proxmox?
curl http://localhost:<port>

# 3. WireGuard Tunnel aktiv?
ping 10.0.0.1  # VPS von Proxmox

# 4. nginx Config auf VPS testen
cd C:\nginx && nginx.exe -t

# 5. nginx neu laden
net stop nginx && net start nginx

DNS-Probleme

# DuckDNS IP pruefen
nslookup eckardt-vault.duckdns.org

# Eigene externe IP pruefen
curl ifconfig.me

# DuckDNS manuell aktualisieren
curl "https://www.duckdns.org/update?domains=eckardt-vault&token=<TOKEN>&ip="

---

3. SSL/Zertifikat Probleme

Zertifikat abgelaufen

Auf Windows VPS:

# Zertifikat erneuern
cd C:\winacme
wacs.exe --renew --force

# nginx neu laden
net stop nginx && net start nginx

Let's Encrypt Rate Limit

Symptom: "too many certificates already issued"

Loesung:

• 5 Zertifikate pro Domain pro Woche
• Warten oder Subdomain aendern
• Staging-Umgebung zum Testen nutzen

Mixed Content Warnung

Symptom: Browser zeigt "unsichere Inhalte"

Loesung: Alle Services muessen HTTPS nutzen

# In nginx.conf
proxy_set_header X-Forwarded-Proto $scheme;

---

4. Service-spezifische Probleme

Nextcloud

"Maintenance mode is enabled"

docker exec nextcloud php occ maintenance:mode --off

Datei-Upload schlaegt fehl

# PHP Limits anpassen
docker exec nextcloud bash -c 'echo "upload_max_filesize=10G" >> /usr/local/etc/php/conf.d/uploads.ini'
docker exec nextcloud bash -c 'echo "post_max_size=10G" >> /usr/local/etc/php/conf.d/uploads.ini'
docker restart nextcloud

"Trusted Domain" Fehler

docker exec nextcloud php occ config:system:set trusted_domains 1 --value=eckardt-cloud.duckdns.org

Vaultwarden

Admin-Seite nicht erreichbar

# Admin-Token pruefen
docker logs vaultwarden | grep -i admin

# URL: /admin mit Token aus .env

Sync-Fehler in Clients

# Verbindung testen
curl -v https://eckardt-vault.duckdns.org/vault/api/alive

Gitea

SSH Clone funktioniert nicht

# SSH-Verbindung testen
ssh -T -p 2222 git@192.168.178.111

# Authorized Keys pruefen
docker exec gitea cat /data/git/.ssh/authorized_keys

"Unable to find user" nach Restart

# Gitea User pruefen
docker exec gitea gitea admin user list

n8n

Webhooks funktionieren nicht

# Webhook-URL pruefen
# Muss WEBHOOK_URL in .env auf externe URL zeigen
docker logs n8n | grep -i webhook

---

5. Backup/Restore Probleme

Backup schlaegt fehl

# Berechtigungen pruefen
ls -la /opt/backups/

# Speicherplatz pruefen
df -h /opt/backups/

# Manuell testen
/opt/scripts/backup.sh nextcloud

Restore durchfuehren

# Container stoppen
docker compose stop <service>

# Altes Volume loeschen
rm -rf /opt/docker/<service>/*

# Backup entpacken
tar -xzf /opt/backups/<service>_YYYYMMDD.tar.gz -C /opt/docker/<service>/

# Container starten
docker compose up -d <service>

---

6. Performance Probleme

Hohe CPU-Last

# Top Prozesse
docker stats --no-stream

# Ressourcen-Limits pruefen
docker inspect --format='{{.HostConfig.NanoCpus}}' <container>

Speicher voll

# Docker Cleanup
docker system prune -a --volumes

# Alte Logs loeschen
truncate -s 0 /var/lib/docker/containers/*/*-json.log

# Alte Backups loeschen
find /opt/backups -mtime +30 -delete

Langsame Antwortzeiten

# Netzwerk-Latenz testen
ping -c 10 10.0.0.2

# Container-Ressourcen
docker stats <container>

# Disk I/O
iostat -x 1 5

---

Diagnose-Befehle Uebersicht

# Alle Container Status
docker compose ps

# Alle Logs (live)
docker compose logs -f

# Ressourcen-Nutzung
docker stats

# Netzwerke anzeigen
docker network ls

# Volumes anzeigen
docker volume ls

# System-Info
docker system df

# Health-Check ausfuehren
/opt/scripts/health-check.sh

---

Kontakt / Hilfe

• Gitea Issues: https://eckardt-git.duckdns.org/Martin/proxmox-infrastruktur/issues
• Docker Docs: https://docs.docker.com/
• Nextcloud Docs: https://docs.nextcloud.com/
• Vaultwarden Wiki: https://github.com/dani-garcia/vaultwarden/wiki