proxmox-gitea/docs/TROUBLESHOOTING.md

Gitea Troubleshooting

Haeufige Probleme und Loesungen

1. Container startet nicht

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

Loesung:

# Logs pruefen
docker logs gitea

# Oft: Berechtigungsprobleme
docker exec gitea ls -la /data

# Oder Volume-Probleme
docker volume inspect gitea_gitea-data

2. "Permission denied" Fehler auf Proxmox

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

Ursache: Proxmox VE Bare Metal hat strikte Kernel-Hardening

Loesung: security_opt in docker-compose.yml hinzufuegen:

security_opt:
  - apparmor=unconfined
  - seccomp=unconfined

3. Falscher Datenbanktyp bei Ersteinrichtung

Symptom: Fehlermeldung "unable to open tcp connection with host 'localhost:3306'"

Loesung:

• Dropdown "Datenbanktyp" auf SQLite3 aendern
• NICHT MSSQL oder MySQL auswaehlen

4. Externer Zugriff funktioniert nicht

Symptom: https://eckardt-vault.duckdns.org/git/ nicht erreichbar

Checkliste:

# 1. Pruefen ob Gitea laeuft
docker ps | grep gitea

# 2. Pruefen ob Port offen ist (auf Proxmox)
curl http://localhost:3000

# 3. WireGuard Tunnel pruefen (auf VPS)
ping 10.0.0.2

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

# 5. nginx neu starten (auf VPS)
net stop nginx && net start nginx

5. SSH Clone funktioniert nicht

Symptom: git clone ssh://... schlaegt fehl

Loesung:

# SSH Key in Gitea hinzufuegen
# Settings -> SSH/GPG Keys -> Add Key

# Public Key anzeigen
cat ~/.ssh/id_ed25519.pub

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

6. Health-Check schlaegt fehl

Symptom: Container Status "unhealthy"

Loesung:

# Health-Endpoint manuell testen
docker exec gitea curl -f http://localhost:3000/api/healthz

# Falls curl nicht installiert:
docker exec gitea wget -q --spider http://localhost:3000/api/healthz

7. Backup schlaegt fehl

Symptom: Backup-Script gibt Fehler aus

Loesung:

# Volume-Pfad pruefen
docker volume inspect gitea_gitea-data

# Manuelles Backup erstellen
docker exec gitea gitea dump -c /data/gitea/conf/app.ini

8. Nach Update: Gitea startet nicht mehr

Symptom: Nach docker compose pull funktioniert nichts mehr

Loesung:

# Alte Version wiederherstellen
docker compose down
docker image tag gitea/gitea:latest gitea/gitea:backup
docker pull gitea/gitea:1.21  # oder gewuenschte Version
docker compose up -d

# Oder: Datenbank-Migration manuell ausfuehren
docker exec gitea gitea migrate

Diagnose-Befehle

# Container Status
docker ps -a | grep gitea

# Container Ressourcen
docker stats gitea --no-stream

# Netzwerk pruefen
docker network inspect gitea_gitea-net

# Alle Logs (letzte 100 Zeilen)
docker logs gitea --tail 100

# Live Logs
docker logs gitea -f

# In Container einloggen
docker exec -it gitea /bin/sh

# Gitea Version
docker exec gitea gitea --version

# Gitea Admin-Befehle
docker exec gitea gitea admin user list

Kontakt / Weitere Hilfe

• Gitea Dokumentation: https://docs.gitea.io/
• Gitea GitHub Issues: https://github.com/go-gitea/gitea/issues