Fehlerbehebung

Diagnose von Docker-Desktop-Integration, MongoDB-Start, Windows-Zugriff auf localhost und Sandboxed Compiles unter WSL 2.

Führen Sie Toolkit- und Docker-Befehle in Ubuntu aus, sofern sie nicht mit PowerShell gekennzeichnet sind. Behalten Sie Konfiguration und Daten bei, während Sie Fehler diagnostizieren.

​

WSL oder Docker meldet, dass die Virtualisierung nicht verfügbar ist

Das WSL 2-Backend benötigt Hardware-Virtualisierung und Virtual Machine Platform, nicht das vollständige Hyper-V-Feature, das vom alternativen Hyper-V-Backend von Docker verwendet wird. Beginnen Sie mit diesen Prüfungen:

1. Prüfen Sie in Windows unter Task-Manager → Leistung → CPU, ob Virtualisierung: Aktiviert angezeigt wird. Falls deaktiviert, aktivieren Sie Intel VT-x/VMX oder AMD-V/SVM im BIOS/UEFI gemäß den Anweisungen Ihres PC-Herstellers.
2. Prüfen Sie in PowerShell als Administrator die Windows-Features:

Get-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform
Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Wenn erforderliche Features deaktiviert sind, aktivieren Sie sie und starten Sie Windows neu, bevor Sie WSL erneut versuchen:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

3. Wenn die Features und die BIOS-Einstellung aktiviert sind, der Fehler 0x80370102 aber bestehen bleibt, prüfen Sie in PowerShell als Administrator:

bcdedit /enum | findstr -i hypervisorlaunchtype

Wenn ausdrücklich Off gemeldet wird, stellen Sie den Hypervisor-Start wieder her und starten Sie Windows neu:

bcdedit /set hypervisorlaunchtype auto

4. Wenn Windows selbst in einer VM läuft, muss der äußere Hypervisor verschachtelte Virtualisierung bereitstellen. Das Aktivieren eines Kontrollkästchens in Windows allein kann fehlende virtuelle CPU-Funktionen nicht bereitstellen.

Folgen Sie für den jeweiligen Fehler der Reparaturanleitung von Microsoft für den WSL-Fehler 0x80370102 und der Fehlerbehebung zur Virtualisierung von Docker. Diese Reparaturen ändern Windows-Features oder die Boot-Konfiguration; führen Sie nur diejenigen aus, die für Ihre Diagnose relevant sind.

​

Docker Desktop benötigt ein Update oder kann keine Images herunterladen

Bei WSL update required führen Sie wsl --update in PowerShell aus, starten Windows bei Aufforderung neu und öffnen dann Docker Desktop und Ubuntu erneut. Wenn die Zeile für Ubuntu weiterhin WSL 1 anzeigt, konvertieren Sie die Distribution wie in Schritt 0 beschrieben.

Prüfen Sie bei Registry-Timeouts, DNS-, Proxy- oder Zertifikatsfehlern in der Ausgabe des Downloads, welche Registry genau fehlschlägt. Konfigurieren Sie den Proxy und das Zertifikatsvertrauen von Windows bzw. Docker Desktop, falls Ihr Netzwerk dies erfordert; deaktivieren Sie nicht die TLS-Überprüfung. Ein erfolgreicher GitHub-Klon beweist nicht, dass Docker ghcr.io oder Docker Hub erreichen kann. Siehe Proxy-Einstellungen von Docker Desktop. Sobald die Verbindung funktioniert, führen Sie bin/up -d erneut aus; die konfigurierten Image-Namen müssen konsistent bleiben.

​

Docker ist in Ubuntu nicht verfügbar

Wenn docker nicht gefunden wird, öffnen Sie Docker Desktop in Windows, aktivieren Sie Ubuntu unter Settings → Resources → WSL Integration, übernehmen Sie die Änderung und öffnen Sie Ubuntu erneut. Prüfen Sie den Namen und den WSL-Modus der Distribution mit wsl --list --verbose in PowerShell. Sie muss WSL 2 verwenden.

Wenn der Client vorhanden ist, aber den Daemon nicht erreicht, prüfen Sie, ob die Engine vollständig gestartet ist. Prüfen Sie docker context ls und eventuelle benutzerdefinierte Einstellungen für DOCKER_HOST/DOCKER_CONTEXT; eine entfernte Engine oder ein alter Engine-Socket in Ubuntu ist nicht das lokale Desktop-Setup dieser Anleitung. Beheben Sie dies nicht, indem Sie einen weiteren Daemon installieren oder den Socket für alle beschreibbar machen.

​

MongoDB startet nicht

bin/up initialisiert das MongoDB-Replica-Set, bevor die Anwendung gestartet wird. Wenn es bei Waiting for Mongo... stehen bleibt, untersuchen Sie die Datenbank in einem zweiten Ubuntu-Terminal:

cd "$HOME/ayakaleaf-toolkit"
bin/docker-compose ps -a
bin/docker-compose logs --tail=150 mongo
docker inspect mongo --format 'Exit={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}'
docker info --format '{{.KernelVersion}}'

Wenn mongo fehlt und die Ausgabe einen Fehler beim Herunterladen des Images zeigt, beheben Sie zuerst den Registry-Zugriff oder den Speicherplatzmangel; der Start der Datenbank wurde dann noch nicht erreicht. Sobald die Ursache behoben ist, führen Sie bin/up -d erneut aus.

Hinweis	Was zu prüfen ist
OOMKilled=true	Erhöhen Sie den für WSL/Docker verfügbaren Arbeitsspeicher oder reduzieren Sie andere Workloads und versuchen Sie es dann erneut
No space left on device	Prüfen Sie den Speicher des Windows-Hosts, df -h in Ubuntu und die Festplattennutzung von Docker; schaffen Sie Platz, ohne laufende Datenbankdaten zu löschen
Berechtigungs- oder Speicherfehler unter /data/db	Belassen Sie MONGO_DATA_PATH im Linux-Dateisystem von Ubuntu. Prüfen Sie den tatsächlichen Bind-Mount und die Eigentümerschaft; wenden Sie kein chmod -R 777 an
Illegal instruction / Fehler zu CPU-Funktionen	Prüfen Sie, ob die CPU und die Virtualisierung die von Ihrer MongoDB-Version benötigten Funktionen bereitstellen; ein Ändern des Ports behebt dies nicht
Fehler zum Datenbankformat oder Upgrade bei vorhandenen Daten	Folgen Sie dem unterstützten Upgrade-Verfahren; richten Sie kein beliebiges älteres MongoDB-Image auf neuere Daten

Wenn MongoDB läuft, prüfen Sie das Replica Set:

bin/docker-compose exec -T mongo mongosh --quiet --eval 'rs.status().ok'

Das Ergebnis sollte 1 sein. bin/up -d führt die anfängliche Einrichtung des Replica Sets durch; wenn Sie bei einer neuen Bereitstellung Compose-Dienste direkt starten, wird dieser Schritt des Toolkit übersprungen.

Wenden Sie einen MongoDB-Kernel-Workaround nur an, wenn Ihre Docker-Engine einen betroffenen Kernel verwendet. Wenn die MongoDB-Logs auf ein Kernel-Problem hinweisen, vergleichen Sie den tatsächlichen Kernel der Engine mit MongoDBs Production Notes und aktualisieren Sie WSL/Docker entsprechend. Löschen Sie data/mongo niemals als allgemeine Lösung für Startprobleme.

​

Windows kann localhost nicht öffnen

Testen Sie zuerst in Ubuntu:

bin/docker-compose ps
bin/docker-compose port sharelatex 80
curl -I http://localhost:8080/launchpad

Testen Sie dann in PowerShell:

curl.exe -I http://localhost:8080/launchpad

Wenn beides fehlschlägt, prüfen Sie die Anwendungslogs und die Port-Konfiguration. Wenn nur Windows fehlschlägt, prüfen Sie, ob ein anderer Windows-Prozess Port 8080 belegt, ob benutzerdefinierte WSL-Netzwerkeinstellungen, VPN-/Proxy-Regeln oder Sicherheitssoftware im Spiel sind. Deaktivieren Sie die Firewall nicht global. Ein geänderter Port erfordert passende Werte für OVERLEAF_PORT, OVERLEAF_SITE_URL und die Browser-URL, gefolgt von bin/up -d.

​

Sandboxed Compiles schlagen fehl

Prüfen Sie alle drei Teile: Das Image existiert in dieser Docker-Engine, die Anwendung kann den Engine-Socket verwenden, und der Geschwister-Container kann das Kompilierungsverzeichnis einbinden:

docker image inspect ghcr.io/ayaka-notes/texlive-basic:2026.1 --format '{{.Architecture}} {{.Id}}'
docker inspect sharelatex --format '{{json .Mounts}}'
bin/logs -f clsi

Verwenden Sie das in config/variables.env konfigurierte Image. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true und DOCKER_SOCKET_PATH=/var/run/docker.sock gehören in config/overleaf.rc. Führen Sie nach Änderungen bin/up -d aus; bin/start allein aktualisiert die Umgebung des Containers nicht.

Ein Fehler No such image bedeutet, dass Docker das genaue Image, das dieses Projekt anfordert, nicht finden kann. Halten Sie TEX_LIVE_DOCKER_IMAGE und ALL_TEX_LIVE_DOCKER_IMAGES konsistent, laden Sie das Image in derselben Engine herunter und prüfen Sie die TeX Live-Auswahl des Projekts. Bestehende Projekte behalten möglicherweise eine ältere Image-Auswahl.

Bei einem Mount-Fehler oder einem leeren /compile-Verzeichnis stellen Sie sicher, dass das Toolkit unter dem Home-Verzeichnis von Ubuntu liegt und die Integration von Docker Desktop für genau diese Distribution aktiviert ist. Ersetzen Sie den WSL-Host-Pfad nicht durch einen Windows-Pfad C:\.... Das Toolkit berechnet den Pfad für den Geschwister-Container aus OVERLEAF_DATA_PATH.

Eine fehlende ctexart.cls oder Schrift mit basic ist eine Einschränkung des Pakets bzw. Images. Prüfen Sie zuerst den einfachen article aus Schritt 6; verwenden Sie für Projekte, die zusätzliche Pakete benötigen, ein umfangreicheres Image. Deaktivieren Sie die Sandbox nicht, um ein fehlendes TeX-Paket zu beheben.

​

Shell-Skripte melden CRLF-Fehler

Führen Sie die Skripte in Ubuntu Bash aus. Bearbeiten Sie die Konfiguration mit LF-Zeilenenden. Fehler, die bash\r oder $'\r' erwähnen, bedeuten meist, dass Dateien in Windows-CRLF konvertiert wurden. Stellen Sie das betroffene Skript aus dem Repository wieder her oder konvertieren Sie seine Zeilenenden und bewahren Sie dabei lokale Konfigurationsänderungen.

​

Container verschwinden nach einem Neustart

Prüfen Sie, ob Docker Desktop läuft und die Ubuntu-Integration aktiviert ist. docker ps zeigt nur laufende Container; prüfen Sie auch docker ps -a. Wenn die Engine eine andere ist als die bei der Einrichtung verwendete, wechseln Sie zurück zum richtigen Kontext, statt eine weitere leere Installation zu initialisieren.

Bei vorhandenen, aber gestoppten Containern führen Sie bin/start aus und prüfen die Logs. Folgen Sie Die Instanz verfügbar halten für den Start bei der Anmeldung, Restart-Richtlinien und die Windows-Energiesparmodus-Einstellungen.