Erste Schritte

Installationsanleitung

Von null zu einem funktionierenden WireGuard-VPN-Admin-Panel in weniger als fünf Minuten.

Voraussetzungen

  • Ein Linux-Server, der von dem Ort aus erreichbar ist, von dem Sie ihn verwalten
  • Docker und Docker Compose installiert
  • Ein Domainname, der auf die IP Ihres Servers zeigt
  • Die Ports 80 und 443 offen für Caddy sowie der WireGuard-UDP-Port offen (standardmäßig 51820)

Caddy benötigt einen gültigen DNS-Namen, intern oder öffentlich, der auf Ihren Server zeigt, damit SSL-Zertifikate automatisch bezogen und erneuert werden können.

Bereitstellung

mkdir wireguard_webadmin && cd wireguard_webadmin
wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml

Erstellen Sie im selben Verzeichnis eine Datei namens .env. Setzen Sie SERVER_ADDRESS auf Ihre Domain:

SERVER_ADDRESS=vpn.example.com
DEBUG_MODE=False
TIMEZONE=America/Sao_Paulo

Alle verfügbaren Variablen finden Sie weiter unten in der .env-Referenz.

docker compose up -d

Rufen Sie das Panel unter https://vpn.example.com auf. Caddy bezieht und erneuert SSL-Zertifikate automatisch.

.env-Referenz

VariableErforderlichBeschreibung
SERVER_ADDRESSJaDNS-Name oder IP Ihres Servers. Muss genau dem entsprechen, was Sie im Browser eingeben, sonst kommt es zu CSRF-Fehlern.
DEBUG_MODENeinSetzen Sie den Wert auf True, um den Django-Debug-Modus zu aktivieren. Niemals in Produktion verwenden. Standard: False.
TIMEZONENeinZeitzone der Anwendung. Verwenden Sie einen Wert aus der tz-Datenbank. Standard: America/Sao_Paulo.
EXTRA_ALLOWED_HOSTSNeinZusätzliche Hostnamen, die Django akzeptieren soll, kommagetrennt. SERVER_ADDRESS ist immer enthalten. Beispiel: app1.example.com,app2.example.com:8443.
WIREGUARD_STATUS_CACHE_ENABLEDNeinZwischenspeichert den WireGuard-Status, um Aufrufe von wg zu reduzieren. Standard: True.
WIREGUARD_STATUS_CACHE_REFRESH_INTERVALNeinWie oft der Cache aktualisiert wird, in Sekunden. Erlaubte Werte: 30, 60, 150, 300. Standard: 60.
WIREGUARD_STATUS_CACHE_WEB_LOAD_PREVIOUS_COUNTNeinWie viele zwischengespeicherte Snapshots beim Laden der Seite vorgeladen werden sollen (0-9). Höhere Werte befüllen Traffic-Diagramme sofort. Niedriger setzen, wenn die Peer-Liste langsam wirkt. Standard: 9.

Upgrade

Die Daten werden in Docker-Volumes gespeichert. Ein Upgrade wirkt sich nicht auf Ihre Peers, Firewall-Regeln, DNS-Einträge oder andere Konfigurationen aus.

01
Ins Projektverzeichnis wechseln
cd wireguard_webadmin
02
Dienste stoppen und neueste Images abrufen
docker compose down
docker compose pull
03
Ihre Daten sichern
tar cvfz wireguard-webadmin-backup-$(date +%Y-%m-%d-%H%M%S).tar.gz \
  /var/lib/docker/volumes/wireguard_webadmin_wireguard/_data/ \
  /var/lib/docker/volumes/wireguard_webadmin_rrd_data/_data/
04
Compose-Datei aktualisieren
wget -O docker-compose.yml \
  https://raw.githubusercontent.com/eduardogsilva/wireguard_webadmin/main/docker-compose-caddy.yml
05
Aktualisierten Stack starten
docker compose up -d
06
Logs auf unerwartete Fehler prüfen
docker compose logs wireguard_webadmin

Fehlerbehebung

Caddy erhält kein Zertifikat

  • Prüfen Sie, ob der A-Record Ihrer Domain auf die öffentliche IP des Servers zeigt
  • Vergewissern Sie sich, dass die Ports 80 und 443 offen sind und upstream nicht blockiert werden
  • Prüfen Sie die Caddy-Logs: docker compose logs caddy

Das Panel lädt nicht

  • Prüfen Sie, ob alle Container laufen: docker compose ps
  • Suchen Sie nach Fehlern: docker compose logs wireguard_webadmin
  • Vergewissern Sie sich, dass SERVER_ADDRESS in .env exakt dem entspricht, was Sie im Browser eingeben

CSRF-Fehler beim Login

SERVER_ADDRESS ist falsch konfiguriert. Er muss genau dem Hostnamen entsprechen, inklusive Port bei nicht standardmäßigen Ports, unter dem das Panel aufgerufen wird. Aktualisieren Sie .env und starten Sie mit docker compose up -d neu.

WireGuard-Peers können keine Verbindung herstellen

  • Vergewissern Sie sich, dass der WireGuard-UDP-Port auf der Host-Firewall offen ist. Standardmäßig ist das 51820, aber bei mehreren Instanzen benötigt jede ihren eigenen Port.
  • Stellen Sie sicher, dass der in docker-compose.yml deklarierte UDP-Portbereich mit der Konfiguration jeder WireGuard-Instanz im Panel übereinstimmt. Bei einer Abweichung veröffentlicht der Container nicht den richtigen Port auf dem Host.
  • Prüfen Sie, ob IP-Forwarding auf dem Host aktiviert ist: sysctl net.ipv4.ip_forward

Laufende Dienste

DienstRolle
wireguard-webadminDjango-Anwendung — Weboberfläche und API
caddyReverse Proxy und automatisches TLS
auth-gatewayZero-Trust-Autorisierungsschicht — erzwingt Identitätsprüfungen, bevor an den Upstream weitergeleitet wird
cronGeplante Aufgaben — Peer-Aktivierung/-Deaktivierung, Cache-Aktualisierung
rrdtoolTraffic-Verlauf — RRD-Datenerfassung und Diagramme
dnsdnsmasq-basierter Resolver mit Unterstützung für kategoriebasierte Sperrlisten