Siirry pääsisältöön
Ayakaleaf Prossa on mahdollisuus ajaa käännökset suojatussa hiekkalaatikkoympäristössä yritystason tietoturvan takaamiseksi. Tämä toteutetaan ajamalla jokainen projekti omassa suojatussa Docker-ympäristössään.

Parannettu tietoturva

Hiekkalaatikkokäännökset (Sandboxed Compiles) ovat suositeltu lähestymistapa Ayakaleaf Prossa, koska monet LaTeX-dokumentit vaativat tai mahdollistavat mielivaltaisten komentotulkkikomentojen suorittamisen osana PDF-käännösprosessia. Kun käytät hiekkalaatikkokäännöksiä, jokainen käännös ajetaan erillisessä Docker-kontissa rajoitetuin oikeuksin, joita ei jaeta muiden käyttäjien tai projektien kanssa, eikä kontilla ole pääsyä ulkoisiin resursseihin, kuten isäntäkoneen verkkoon.
Jos yrität ajaa Ayakaleaf Prota ilman hiekkalaatikkokäännöksiä, käännös ajetaan muiden samanaikaisten käännösten rinnalla pää-Docker-kontin sisällä, ja käyttäjillä on täydet luku- ja kirjoitusoikeudet sharelatex-kontin resursseihin (tiedostojärjestelmä, verkko ja ympäristömuuttujat) LaTeX-käännöksiä ajettaessa.

Helpompi pakettien hallinta

Pakettien manuaalisen asentamisen välttämiseksi suosittelemme hiekkalaatikkokäännösten käyttöönottoa. Tämä on Ayakaleaf Prossa määritettävä asetus, joka antaa käyttäjillesi pääsyn samaan TeX Live -ympäristöön kuin overleaf.comissa, mutta omassa paikallisessa asennuksessasi. Hiekkalaatikkokäännösten käyttämät TeX Live -imaget sisältävät suosituimmat paketit ja fontit, jotka on testattu galleriamme mallipohjia vasten, mikä varmistaa parhaan mahdollisen yhteensopivuuden paikallisten projektien kanssa. Kun hiekkalaatikkokäännökset ovat käytössä, voit määrittää, mistä TeX Live -versioista käyttäjät voivat valita projektissaan, sekä asettaa uusille projekteille oletusarvoisen TeX Live -imagen version.
Jos yrität ajaa Ayakaleaf Prota ilman hiekkalaatikkokäännöksiä, instanssisi käyttää käännöksiin oletuksena TeX Liven perusskeemaversiota. Tämä perusversio on kevyt ja sisältää vain hyvin rajallisen osajoukon LaTeX-paketeista, mikä todennäköisesti aiheuttaa käyttäjillesi puuttuvien pakettien virheitä, erityisesti jos he yrittävät käyttää valmiita mallipohjia.
Koska Ayakaleaf Pro on suunniteltu toimimaan ilman verkkoyhteyttä, overleaf.comin gallerian mallipohjia ei voi integroida automaattisesti paikalliseen asennukseesi; se on kuitenkin mahdollista tehdä manuaalisesti mallipohja kerrallaan. Lisätietoja tämän toiminnasta on oppaassamme mallipohjien siirtämisestä overleaf.comista: #transferring-templates-from-overleaf.com.
Hiekkalaatikkokäännökset edellyttävät, että sharelatex-kontilla on pääsy isäntäkoneen Docker-sokettiin (bind-liitoksen kautta), jotta se voi hallita näitä rinnakkaisia käännöskontteja.

Miten se toimii

Kun hiekkalaatikkokäännökset ovat käytössä, Docker-soketti liitetään isäntäkoneelta sharelatex-konttiin, jotta kontin käännöspalvelu voi luoda uusia Docker-kontteja isäntäkoneelle. Tämän jälkeen jokaisella kääntäjän ajokerralla kussakin projektissa LaTeX-käännöspalvelu (CLSI) tekee seuraavat toimenpiteet:
  • Kirjoittaa projektin tiedostot sijaintiin OVERLEAF_DATA_PATH-polun sisällä.
  • Käyttää liitettyä Docker-sokettia luodakseen käännösajoa varten uuden texlive-kontin.
  • Antaa texlive-kontin lukea projektin datan OVERLEAF_DATA_PATH-polun alla olevasta sijainnista.
  • Kääntää projektin texlive-kontin sisällä.

Hiekkalaatikkokäännösten käyttöönotto

Toolkitin käyttäjille

Ota hiekkalaatikkokäännökset (tunnetaan myös nimellä Sibling containers) käyttöön asettamalla seuraavat konfiguraatioasetukset tiedostoon overleaf-toolkit/config/overleaf.rc:
config/overleaf.rc
Poista ne käytöstä asettamalla SIBLING_CONTAINERS_ENABLED=false ja suorittamalla bin/up. Käännökset ajetaan silloin sharelatex-säilössä sen perus-TeX Livellä.

Docker Composen käyttäjille

TeX Live -imagen määrittäminen

Manner-Kiinan käyttäjät voivat nopeuttaa latausta hakemalla imaget ghcr.nju.edu.cn-peilistä ja merkitsemällä ne sitten niiden ghcr.io-nimellä:
ÄLÄ käytä ghcr.nju.edu.cn-osoitetta Toolkitin ympäristöasetuksissa: pidä niissä ghcr.io-nimet. Estääksesi bin/up-komentoa hakemasta imageja uudelleen ghcr.io:sta aseta SIBLING_CONTAINERS_PULL=false tiedostoon config/overleaf.rc. Jos haluat pitää imaget ajan tasalla peilin kautta, katso TeX Live Full -imagejen automaattinen päivittäminen.
Ayakaleaf Pro käyttää kolmea ympäristömuuttujaa määrittääkseen, mitä TeX Live -imageja hiekkalaatikkokäännöksissä käytetään:
  • TEX_LIVE_DOCKER_IMAGE (valinnainen), TeX Live -image, jota uudet projektit käyttävät. Sen on oltava yksi muuttujan ALL_TEX_LIVE_DOCKER_IMAGES imageista. Jos sitä ei ole asetettu, uudet projektit käyttävät muuttujan ALL_TEX_LIVE_DOCKER_IMAGES ensimmäistä imagea.
  • ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (valinnainen), Pilkuin eroteltu luettelo imagejen nimistä samassa järjestyksessä, näytetään kääntäjäasetuksissa. Jos sitä ei ole asetettu tai se on lyhyempi kuin imageluettelo, image näytetään tagillaan, esimerkiksi 2026.1.
  • ALL_TEX_LIVE_DOCKER_IMAGES (pakollinen), Pilkuin eroteltu luettelo käytettävistä TeX Live -imageista. Jos käyttöönotossa käytetään Overleaf Toolkitia, nämä imaget ladataan tai päivitetään. Voit ohittaa latauksen asettamalla SIBLING_CONTAINERS_PULL=false tiedostoon config/overleaf.rc.
Kun käynnistät Ayakaleaf Pro -instanssin komennolla bin/up, Toolkit hakee automaattisesti kaikki muuttujassa ALL_TEX_LIVE_DOCKER_IMAGES luetellut imaget. Tässä esimerkissä uusien projektien oletuksena on TeX Live 2026, ja vanhoissa projekteissa käytetään edelleen versiota 2025.
Seuraava konfiguraatio asentaa kaikki täydet TeX Live Docker -imaget vuosilta 2025–2026. Suosittelemme, että käytettävissä on vähintään 64 Gt tallennustilaa ennen tämän konfiguraation käyttöä.
config/variables.env
On erittäin suositeltavaa määrittää vähintään 2 texlive-full-imagea. Yksityiskohtainen syy on kerrottu kohdassa #known-issues

Saatavilla olevat TeX Live -imaget

Nämä ovat Overleafia varten erityisesti optimoituja TeX Live -imageja, jotka voidaan lisätä myös muuttujiin TEX_LIVE_DOCKER_IMAGE ja ALL_TEX_LIVE_DOCKER_IMAGES:
  • ghcr.io/ayaka-notes/texlive-full:2026.1 (myös tagi latest)
  • ghcr.io/ayaka-notes/texlive-full:2025.1
  • ghcr.io/ayaka-notes/texlive-full:2024.1
  • ghcr.io/ayaka-notes/texlive-full:2023.1
  • ghcr.io/ayaka-notes/texlive-full:2022.1
  • ghcr.io/ayaka-notes/texlive-full:2021.1
  • ghcr.io/ayaka-notes/texlive-full:2020.1
Imagejen tagien muodolle on tiukka skeema, jota on noudatettava (käytetään säännöllistä lauseketta ^[0-9]+.[0-9]+, jossa ensimmäinen numero määrittää TeX Liven vuoden ja toinen korjausversion).

Voinko käyttää muuta image-rekisteriä

Jotkut saattavat miettiä, voiko ghcr.io:n korvata toisella peilisivustolla tai vaihtaa texliven toiseen Docker Hubin imageen?
Ei, emme suosittele sitä, koska konfigurointi on melko monimutkaista. Jos lataat peilisivustolta, voit nimetä imagesi uudelleen muotoon ghcr.io/ayaka-notes/texlive-full. Jos kuitenkin todella haluat käyttää omaa image-rekisteriäsi, lisää:
config/variables.env
Sen jälkeen sinun on varmistettava, että kaikki texlive-imaget ovat repositoriossa your-repo, esimerkiksi
  • hub.your.com/your-repo/texlive-full:2025.1
  • hub.your.com/your-repo/texlive-full:2024.1
Lisätietoja saat lukemalla alla olevan lähdekoodin, josta näet, miten ympäristömuuttujasi jäsennetään:
sandboxed-compiles/index.mjs

TeX Live -imagen automaattinen synkronointi

Jotta sinun ei tarvitsisi joka kerta päivittää instanssiasi manuaalisesti komennolla bin/up, voit automatisoida TeX Live -imagen päivitykset. Katso updating-tex-live-full-images-automatically.md.

Tunnetut ongelmat

Tämä on todellinen tapaus Overleaf-yhteisöstä:
Käytän versiota 6.0.1-ext-v3.3, ja minulla on nämä asetukset tiedostossa variables.env:
Tämä toimii hyvin imagella texlive/texlive:latest-full. Hain kuitenkin toisen texlive-imagen danteev/texlive:2025-10-15 ja vaihdoin molempiin muuttujiin uuden imagen nimen, mutta se ei toimi:
Lokeissa näen seuraavaa:
Vaikuttaa siltä, että tiedoston variables.env päivitetyt asetukset eivät tule voimaan. Käännös yrittää edelleen ajaa imagea texlive/texlive:latest-full eikä uutta imagea. Kokeilin uudelleenkäynnistystä sekä konttien poistamista ja uudelleenajoa, mutta ongelma on edelleen sama. Onko ratkaisuja?
Teknisten rajoitusten vuoksi, jos määrität vain yhden Docker TeXLive -imagen, kuten texlive-fullA:latest
ja haluat jonkin aikaa Overleaf-instanssin ajamisen jälkeen vaihtaa TeXLive-imagen imageen texlive-fullB:latest, huomaat, etteivät käyttäjäsi pysty kääntämään yhtään projektia.
Tämä johtuu siitä, että kunkin projektin TeXLive-Full-imagen nimi (hiekkalaatikkokäännöstä varten) tallennetaan pysyvästi tietokantaan. Imagen nimi muuttuu tietokannassa vain, kun käyttäjä vaihtaa projektinsa TeXLive-versiota, esimerkiksi versiosta 2024 versioon 2025. Kun CLSI kääntää projektin, se käyttää tietokannasta löytyvää konttiimagen nimeä projektin kääntämiseen suoraan. Jos tarjoat vain yhden Docker-imagen, käyttäjät eivät voi muuttaa projektin kääntämiseen käytettävää imagea. Tällöin sinun on kirjoitettava skripti, joka muuttaa manuaalisesti kaikkien käyttäjäprojektien TeXLive-imagen MongoDB:ssä.

Virheenjäljitys ja raportointi

Tarkista CLSI:n loki Toolkitin kautta suorittamalla seuraava komento:
Jos kohtaat ongelmia kääntäessäsi TeX Live -imageilla, lähetä issue täällä: https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml Ongelman toistamiseksi ja selvittämiseksi sinua saatetaan pyytää lataamaan projektisi Overleafiin. Haemme sen jälkeen projektin ja ajamme käännöstestit GitHub Actionin avulla.

Q&A

Vastaus: Kontit ja käännöstiedostot poistetaan viiveellä; TeX Live -imageja ei poisteta.
  • Käännöskontteja (project-<project id>-<hash>) käytetään uudelleen saman projektin käännöksissä, joten ne jäävät jäljelle käännöksen jälkeen. Tarkistus suoritetaan tunnin välein, ja se poistaa kontit, jotka ovat yli tunnin vanhoja ja joiden projektia ei ole käännetty viimeisen tunnin aikana. Kontti on yleensä poissa yhdestä kahteen tuntia viimeisen käännöksen jälkeen. Overleafin uudelleenkäynnistys ei poista niitä; seuraava tunnittainen tarkistus poistaa.
  • Sanamäärä-, SyncTeX- ja muunnoskontit poistetaan heti, kun ne valmistuvat.
  • Käännöstiedostot (data/overleaf/data/compiles ja output) poistetaan, kun projektia ei ole käytetty yhteen päivään, ja tämä tarkistetaan 10 minuutin välein. Kun levytila käy vähiin, tätä jaksoa lyhennetään asteittain puoleen päivään asti.
  • TeX Live -imageja ei koskaan poisteta, koska jokainen käännös tarvitsee niitä. Vapauttaaksesi tilaa imagen poistamisen jälkeen muuttujasta ALL_TEX_LIVE_DOCKER_IMAGES poista se komennolla docker image rm <image>.
Näitä kontteja ei tarvitse poistaa käsin.
Vastaus: Ei. Jokainen käännöskontti liittää vain oman projektinsa käännöshakemiston polkuun /compile, eikä sillä ole verkkoyhteyttä. Muita isäntäkoneen hakemistoja ei voi liittää siihen millään asetuksella. Lataa sen sijaan projektin tarvitsemat tiedostot projektiin.
Vastaus: Kyllä. ghcr.io/ayaka-notes/texlive-basic:<year>.1 (2020.1–2026.1) sisältää TeX Liven basic-skeeman sekä muutamia paketteja, kuten latexmk, xetex ja fontspec, ilman täyttä fonttivalikoimaa. Se on paljon pienempi kuin texlive-full, mutta muita paketteja käyttävät projektit saavat puuttuvista paketeista johtuvia virheitä. TeX Live 2025 basicille:
config/variables.env
ghcr.io/ayaka-notes/texlive-full:base ei ole basic-image: siinä ei ole TeX Liveä, eikä sillä voi kääntää.
Vastaus: Editori ei näytä sitä, ja clsi-loki kirjaa sen vain debug-tasolla. Jokainen käännöspyyntö kuitenkin palauttaa sen: avaa selaimen kehittäjätyökalut, siirry Network-välilehdelle, käännä uudelleen ja valitse compile-pyyntö. Sen JSON-vastauksessa on timings millisekunteina, jossa compileE2E on koko käännös käännöspalvelussa ja compile on itse LaTeX-ajo.
Viimeksi muokattu 13. marraskuuta 2026