Vianmääritys

Docker Desktop -integraation, MongoDB:n käynnistyksen, Windowsin localhost-yhteyden ja hiekkalaatikkokäännösten vianmääritys WSL 2:ssa.

Aja Toolkitin ja Dockerin komennot Ubuntussa, ellei niitä ole merkitty PowerShell-komennoiksi. Säilytä määritykset ja data vikoja selvittäessäsi.

​

WSL tai Docker ilmoittaa, että virtualisointi ei ole käytettävissä

WSL 2 -taustajärjestelmä tarvitsee laitteistovirtualisoinnin ja Virtual Machine Platform -ominaisuuden, ei täyttä Hyper-V-ominaisuutta, jota Dockerin vaihtoehtoinen Hyper-V-taustajärjestelmä käyttää. Aloita näillä tarkistuksilla:

1. Tarkista Windowsin kohdasta Task Manager → Performance → CPU, että Virtualization: Enabled. Jos se on pois käytöstä, ota Intel VT-x/VMX tai AMD-V/SVM käyttöön BIOS/UEFI-asetuksissa tietokoneen valmistajan ohjeiden mukaisesti.
2. Tarkista Windowsin ominaisuudet PowerShellissä järjestelmänvalvojana:

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

Jos tarvittavat ominaisuudet ovat pois käytöstä, ota ne käyttöön ja käynnistä Windows uudelleen ennen kuin yrität WSL:ää uudelleen:

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

3. Jos ominaisuudet ja BIOS-asetus ovat käytössä mutta virhe 0x80370102 jatkuu, tarkista PowerShellissä järjestelmänvalvojana:

bcdedit /enum | findstr -i hypervisorlaunchtype

Jos se ilmoittaa nimenomaisesti Off, palauta hypervisorin käynnistys ja käynnistä Windows uudelleen:

bcdedit /set hypervisorlaunchtype auto

4. Jos Windows itse toimii virtuaalikoneessa, ulomman hypervisorin on tarjottava sisäkkäinen virtualisointi. Pelkkä Windowsin valintaruudun käyttöönotto ei voi tarjota puuttuvia virtuaalisen suorittimen ominaisuuksia.

Noudata vastaavan virheen kohdalla Microsoftin WSL-virheen 0x80370102 korjausohjetta ja Dockerin virtualisoinnin vianmääritystä. Nämä korjaukset muuttavat Windowsin ominaisuuksia tai käynnistysmäärityksiä; suorita vain ne, jotka liittyvät diagnoosiisi.

​

Docker Desktop tarvitsee päivityksen tai ei pysty hakemaan imageja

Jos saat ilmoituksen WSL update required, suorita PowerShellissä wsl --update, käynnistä Windows uudelleen pyydettäessä ja avaa sitten Docker Desktop ja Ubuntu uudelleen. Jos Ubuntu-rivillä lukee edelleen WSL 1, muunna jakelu vaiheessa 0 kuvatulla tavalla.

Jos saat rekisterin aikakatkaisuja tai DNS-, välityspalvelin- tai varmennevirheitä, tarkista hakutulosteesta, mikä rekisteri tarkalleen epäonnistuu. Määritä Windowsin/Docker Desktopin välityspalvelin ja varmenteiden luottamus, jos verkkosi tarvitsee niitä; älä poista TLS-varmennusta käytöstä. Onnistunut GitHub-kloonaus ei todista, että Docker tavoittaa ghcr.io:n tai Docker Hubin. Katso Docker Desktopin välityspalvelinasetukset. Kun yhteys toimii, suorita bin/up -d uudelleen; määritettyjen imagenimien on pysyttävä johdonmukaisina.

​

Docker ei ole käytettävissä Ubuntussa

Jos docker-komentoa ei löydy, avaa Docker Desktop Windowsissa, ota Ubuntu käyttöön kohdassa Settings → Resources → WSL Integration, ota muutos käyttöön ja avaa Ubuntu uudelleen. Tarkista jakelun nimi ja WSL-tila komennolla wsl --list --verbose PowerShellissä. Sen on käytettävä WSL 2:ta.

Jos asiakasohjelma on olemassa mutta ei tavoita daemonia, tarkista, että moottori on käynnistynyt kokonaan. Tarkastele komennon docker context ls tulostetta ja mahdollisia mukautettuja DOCKER_HOST/DOCKER_CONTEXT-asetuksia; etämoottori tai vanha Ubuntun Engine-socket ei ole tämän oppaan paikallinen Desktop-kokoonpano. Älä korjaa tätä asentamalla toista daemonia tai tekemällä socketista kaikille kirjoitettavaa.

​

MongoDB ei käynnisty

bin/up alustaa MongoDB:n replica setin ennen sovelluksen käynnistämistä. Jos se pysähtyy kohtaan Waiting for Mongo..., tarkastele tietokantaa toisessa Ubuntu-päätteessä:

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}}'

Jos mongo puuttuu ja tulosteessa näkyy imagen hakuvirhe, ratkaise ensin rekisterin käyttö tai levytila; tietokannan käynnistykseen ei ole vielä päästy. Kun syy on korjattu, suorita bin/up -d uudelleen.

Havainto	Mitä tarkistaa
OOMKilled=true	Lisää WSL:n/Dockerin käytettävissä olevaa muistia tai vähennä muita kuormia ja yritä uudelleen
No space left on device	Tarkista Windows-isännän tallennustila, Ubuntun df -h ja Dockerin levynkäyttö; vapauta tilaa poistamatta elävää tietokantadataa
Käyttöoikeus- tai tallennusvirheet hakemistossa /data/db	Pidä MONGO_DATA_PATH Ubuntun Linux-tiedostojärjestelmässä. Tarkista todellinen bind-liitos ja omistajuus; älä käytä komentoa chmod -R 777
Illegal instruction / suorittimen ominaisuusvirheet	Tarkista, että suoritin ja virtualisointi tarjoavat MongoDB-versiosi vaatimat ominaisuudet; portin vaihtaminen ei korjaa tätä
Tietokannan muoto- tai päivitysvirheet olemassa olevan datan kanssa	Noudata tuettua päivitysmenettelyä; älä osoita mielivaltaista vanhempaa MongoDB-imagea uudempaan dataan

Kun MongoDB on käynnissä, tarkista replica set:

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

Tuloksen pitäisi olla 1. bin/up -d tekee replica setin alkumäärityksen; Compose-palveluiden käynnistäminen suoraan uudessa käyttöönotossa ohittaa tämän Toolkitin vaiheen.

Käytä MongoDB:n ydinkiertotietä vain, jos Docker-moottorisi käyttää ongelmallista ydintä. Jos MongoDB:n lokit viittaavat ydinongelmaan, vertaa moottorin todellista ydintä MongoDB:n tuotanto-ohjeisiin ja päivitä WSL/Docker tarpeen mukaan. Älä koskaan tyhjennä hakemistoa data/mongo yleisenä käynnistyskorjauksena.

​

Windows ei pysty avaamaan localhostia

Testaa ensin Ubuntussa:

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

Testaa sitten PowerShellissä:

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

Jos molemmat epäonnistuvat, tarkista sovelluksen lokit ja porttimääritykset. Jos vain Windows epäonnistuu, tarkista, käyttääkö jokin muu Windows-prosessi porttia 8080, sekä mukautetut WSL-verkkoasetukset, VPN-/välityspalvelinsäännöt ja tietoturvaohjelmistot. Älä poista palomuuria käytöstä yleisesti. Vaihdettu portti vaatii vastaavat OVERLEAF_PORT- ja OVERLEAF_SITE_URL-arvot sekä selaimen URL-osoitteen, minkä jälkeen suoritetaan bin/up -d.

​

Hiekkalaatikkokäännökset epäonnistuvat

Varmista kaikki kolme osaa: image on olemassa tässä Docker-moottorissa, sovellus voi käyttää moottorin socketia ja rinnakkainen kontti voi liittää käännöshakemiston:

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

Käytä tiedostossa config/variables.env määritettyä imagea. SERVER_PRO=true, SIBLING_CONTAINERS_ENABLED=true ja DOCKER_SOCKET_PATH=/var/run/docker.sock kuuluvat tiedostoon config/overleaf.rc. Suorita muokkausten jälkeen bin/up -d; pelkkä bin/start ei päivitä kontin ympäristöä.

Virhe No such image tarkoittaa, ettei Docker löydä projektin pyytämää tarkkaa imagea. Pidä TEX_LIVE_DOCKER_IMAGE ja ALL_TEX_LIVE_DOCKER_IMAGES johdonmukaisina, hae image samaan moottoriin ja tarkista projektin TeX Live -valinta. Olemassa olevat projektit saattavat säilyttää vanhemman imagevalinnan.

Jos saat liitosvirheen tai /compile-hakemisto on tyhjä, varmista, että Toolkit on Ubuntun kotihakemiston alla ja että Docker Desktopin integraatio on käytössä samalle jakelulle. Älä korvaa WSL-isäntäpolkua Windowsin C:\...-polulla. Toolkit laskee rinnakkaisen kontin polun arvosta OVERLEAF_DATA_PATH.

Puuttuva ctexart.cls tai fontti basic-imagella on paketti- tai imagerajoitus. Varmista ensin yksinkertainen article vaiheesta 6; käytä täydellisempää imagea projekteille, jotka tarvitsevat lisäpaketteja. Älä poista hiekkalaatikkoa käytöstä puuttuvan TeX-paketin korjaamiseksi.

​

Komentotulkkiskriptit ilmoittavat CRLF-virheistä

Aja skriptit Ubuntun Bashissa. Muokkaa määrityksiä LF-rivinvaihdoilla. Virheet, joissa mainitaan bash\r tai $'\r', tarkoittavat yleensä, että tiedostot on muunnettu Windowsin CRLF-muotoon. Palauta kyseinen skripti repositoriosta tai muunna sen rivinvaihdot säilyttäen paikalliset määritysmuutokset.

​

Kontit katoavat uudelleenkäynnistyksen jälkeen

Tarkista, että Docker Desktop on käynnissä ja Ubuntun integraatio on käytössä. docker ps näyttää vain käynnissä olevat kontit; tarkastele myös komentoa docker ps -a. Jos moottori on eri kuin asennuksen aikana käytetty, vaihda takaisin oikeaan kontekstiin sen sijaan, että alustaisit uuden tyhjän asennuksen.

Jos kontit ovat olemassa mutta pysäytettyinä, suorita bin/start ja tarkastele lokeja. Noudata kohtaa Pidä instanssi saatavilla kirjautumisen yhteydessä tapahtuvan käynnistyksen, uudelleenkäynnistyskäytäntöjen ja Windowsin lepotila-asetusten osalta.