> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/fi/tuki/support-guides/v5.5.7-migration-binary-files-migration.md). # (v5.5.7-migraatio) Binääritiedostojen migraatio ## Binaaritiedostojen migraatio Tuleva pääversio `6.0` Server Pro- ja Community Edition -version julkaisu vähentää binaaritiedostojen tallennustilan käyttöä puoleen. Verkkopohjainen migraatio sisältyy versioon `5.5.7` , mikä mahdollistaa mahdollisimman lyhyen käyttökatkon päivityksen yhteydessä. Koska Server Pro `4.x`, binaaritiedostot tallennetaan kahdesti: aktiivisten tiedostojen tallennukseen "filestore" sekä täydelliseen projektihistoriajärjestelmään. Jatkossa kustakin tiedostosta tallennetaan yksi kopio täydelliseen projektihistoriajärjestelmään. Migraatio yhtenäistettyyn tallennusjärjestelmään koostuu kahdesta osasta: uusi lippu migraation vaiheen hallintaan ja skripti, joka käsittelee kaikki aktiiviset ja pehmeästi poistetut projektit. Vaiheet: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (oletus), tiedostot luetaan ja kirjoitetaan filestoreen. Tiedostot kirjoitetaan historiaan asynkronisesti. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , tiedostot luetaan historiasta, ja tarvittaessa filestoresta, sekä kirjoitetaan sekä filestoreen että historiaan. Palautus versioon `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` on mahdollista. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` tiedostot luetaan ja kirjoitetaan vain historiaan. Palautus versioon `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ei ole mahdollista, ellei se tehty "offline-tilassa". Kun tietoja tallennetaan [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) ja käytetään erillisiä palvelutilejä filestorelle (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) ja historialle (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): anna filestore-käyttäjälle lukuoikeus historiabuckettiin blobien `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Filestore-palvelu hoitaa lukupyynnöt compiler-palvelulta eteenpäin. {% hint style="warning" %} On erittäin suositeltavaa suorittaa binaaritiedostojen migraatio ensin ei-tuotanto-/sandbox-ympäristössä. {% endhint %} {% hint style="success" %} Vakiomallinen Server Pro -lisenssi sallii sovelluksen käytön sekä tuotantoympäristössä että yhdessä ei-tuotanto-/sandbox-ympäristössä; on erittäin suositeltavaa ottaa käyttöön ei-tuotantoympäristö testausta varten. {% endhint %} {% hint style="info" %} Jos päivität Server Pro/CE-versioon `6.0` ja päätät myöhemmin alentaa versioon, sinun tulisi palauttaa koko järjestelmän varmuuskopiosta. {% endhint %} ### Migraatiomenettely {% stepper %} {% step %} #### Luo varmuuskopio Luo täydellinen [varmuuskopio](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) instanssistasi yhtenäisellä tilannevedoksella **mongo**, **redis** ja **sharelatex** hakemistoista. {% endstep %} {% step %} #### Päivitä **Toolkit:** Käytä `$ bin/upgrade` skripti, jolla päivitetään **toolkit** uusimpaan versioon. Kun sinulta kysytään, älä **ei** vahvista kehote **Päivitä** kuva? — sen sijaan muokkaa käsin **config/version** tiedosto ja aseta arvoksi `5.5.7`. **Vanha docker-compose.yml:** Päivitä `sharelatex` palvelu `5.5.7`. {% endstep %} {% step %} #### Arvioi vaikutuksen alaisina olevien projektien määrä {% code overflow="wrap" %} ```bash # Overleaf Toolkitin käyttäjät: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" # Vanhan docker-compose.yml:n käyttäjät: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" ``` {% endcode %} Esimerkkituloste: {% code fullWidth="false" %} ``` Nykyinen tila: - Projektien kokonaismäärä: 10 - Poistettujen projektien kokonaismäärä: 5 Otetaan 1000 projektin otos edistymisen arvioimiseksi... Otosprojektien tilastot: - Otosprojekteja: 9 (90 % kaikista projekteista) - Otosprojekteja, joilla kaikki hashit ovat olemassa: 5 - Niiden projektien osuus, jotka tarvitsevat hashien täydennystä: 44 % (arvio) - Otosprojekteissa on 11 tiedostoa, jotka on tarkistettava täydellistä projektihistoriajärjestelmää vasten. - Otosprojekteissa on 3 tiedostoa, jotka on ladattava täydelliseen projektihistoriajärjestelmään (arvioiden 27 % kaikista tiedostoista). Poistettujen projektien otostilastot: - Otettuja poistettuja projekteja: 4 (80 % kaikista poistetuista projekteista) - Otospoistoprojekteja, joilla kaikki hashit ovat olemassa: 3 - Niiden poistettujen projektien osuus, jotka tarvitsevat hashien täydennystä: 25 % (arvio) - Otetuissa poistetuissa projekteissa on 2 tiedostoa, jotka on tarkistettava täydellistä projektihistoriajärjestelmää vasten. - Otetuissa poistetuissa projekteissa on 1 tiedosto, joka on ladattava täydelliseen projektihistoriajärjestelmään (arvioiden 50 % kaikista tiedostoista). ``` {% endcode %} {% endstep %} {% step %} #### Tyhjennä projektihistorian jonot {% code overflow="wrap" %} ```bash # Overleaf Toolkitin käyttäjät: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Vanhan docker-compose.yml:n käyttäjät: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Toista tyhjennys, kunnes kaikki projektit on tyhjennetty (`"project_ids":0`). ``` löydetyt projektit {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} yhteensä {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Jos "failedProjects" ei ole nolla, ota yhteyttä tukeen äläkä jatka binaaritiedostojen migraatiota. {% endhint %} {% endstep %} {% step %} #### Siirrä migraatiovaihe tasolle 1 Toolkit: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` tiedostossa `config/variables.env`. Vanha docker-compose.yml: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` tiedostossa `ympäristö` osion `sharelatex` palvelu. {% endstep %} {% step %} #### Ota asetusten muutos käyttöön ja käynnistä instanssi Toolkit: `bin/up -d` Vanha docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Varmista pääsy binaaritiedostoihin Avaa projekti Overleaf-editorissa selaimessa ja valitse binaaritiedosto, kuten kuva. {% endstep %} {% step %} #### Suorita migraatiiskripti {% code overflow="wrap" %} ```bash # Overleaf Toolkitin käyttäjät: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" # Vanhan docker-compose.yml:n käyttäjät: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" ``` {% endcode %} {% hint style="danger" %} Jos olet [säilyttämässä loki](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) tiedostoja kontin ulkopuolella, **sharelatex** varmista, että lokihakemiston omistajaksi on asetettu `www-data` käyttäjä (uid=33), jotta tulostuva lokitiedosto voidaan kirjoittaa. {% endhint %} Tuloksen pitäisi näyttää tältä: ```bash Aseta UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Taustajärjestelmän lataus","time":"2025-07-25T15:00:58.166Z","v":0} Lokit kirjoitetaan tiedostoon /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Projektitiedostojen varmuuskopiointi käynnistyy... Globaalit blobit ladattu: 0 Käsitellään poistamattomia projekteja... Käsitelty 1 projekti, kulunut aika 0 s Käynnissä olevien projektien päivitys valmis Käsitellään poistettuja projekteja... deletedProjects-kokoelma näyttää olevan tyhjä. Poistettujen projektien päivitys valmis Valmis. ``` Jos migraatio onnistuu, saat poistumiskoodin `0`, ja viimeiset rivit osoittavat, ettei epäonnistumisia ole: ```bash Valmis. ``` Lokitiedosto näyttää tältä (käytä skriptin tulostamaa polkua): {% code overflow="wrap" %} ```bash $ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log . $ cat file-migration-2025-07-25T15_00_58_199Z.log {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"erä valmistui","time":"2025-07-25T15:00:58.379Z","v":0} {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration-tilastot","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Pysäytä instanssi Toolkit: `bin/stop sharelatex` Vanha docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Tee vanhoista tiedostoista sovellukselle saavuttamattomia Voit nyt siirtää vanhat tiedostot toissijaiseen tallennukseen. Suosittelemme pitämään tiedostot vielä jonkin aikaa, jos myöhemmin ilmenee ongelmia. {% code overflow="wrap" %} ```bash # Toolkitin käyttäjät: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Vanhan docker-compose.yml:n käyttäjät: # Oletamme, että käytät oletusarvoista bind-mountia polussa /var/lib/overleaf $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Jos käytät valikoivia bind-mounteja, voit yksinkertaisesti poistaa bind-mountin /var/lib/overleaf/data/user_files kontin sisältä. ``` {% endcode %} {% endstep %} {% step %} #### Siirrä migraatiovaihe tasolle 2 Toolkit: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` tiedostossa `config/variables.env`. Vanha docker-compose.yml: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` tiedostossa `ympäristö` osion `sharelatex` palvelu. {% endstep %} {% step %} #### Ota asetusten muutos käyttöön ja käynnistä instanssi Toolkit: `bin/up -d` Vanha docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Varmista pääsy binaaritiedostoihin Avaa projekti Overleaf-editorissa selaimessa ja valitse binaaritiedosto, kuten kuva. {% endstep %} {% endstepper %} #### Offline-migraatio Jos haluat estää käyttäjiä kirjautumasta sisään samalla kun binaaritiedostojen migraatiokomentosarja on käynnissä, toimi seuraavasti: * Kirjaudu Overleaf-instanssiisi ylläpitäjätunnuksella * Napsauta **Ylläpitäjä** painiketta ja valitse **Hallitse sivustoa** * Napsauta **Avaa/Sulje editori** välilehti * Napsauta **Sulje editori** painiketta * Napsauta **Katkaise kaikkien käyttäjien yhteys** painiketta Kun tämä on tehty, jos käyttäjiä on kirjautuneena sisään, heidät ohjataan ylläpitosivulle, ja kaikki uudet käyttäjät, jotka vierailevat kirjautumissivulla, näkevät ylläpitosivun ja **ei** voivat kirjautua sisään. Nämä vaiheet on toistettava, kun käynnistät instanssin uudelleen. Sivuston voi avata uudelleen yksinkertaisesti käynnistämällä instanssin uudelleen. #### Online-migraatio Migraatiokäsikirjoituksia on mahdollista ajaa samalla kun sovellus on edelleen käynnissä. On muutamia huomioitavia asioita: * Migraatioprosessi on I/O-intensiivinen, joten resurssien käyttöä kannattaa seurata skriptin ollessa käynnissä. * Suurella käsittelysamanaikaisuudella `filestore` palvelun event loopissa voi esiintyä jonkin verran estymistä, mikä johtaisi heikompaan käyttökokemukseen. Suosittelemme aloittamaan oletusarvoisilla arvoilla `--concurrency=10` ja `--concurrent-batches=1` . * Voit pysäyttää skriptin milloin tahansa. Sen käynnistäminen uudelleen validoi aiemmat projektit ja ohittaa tiedostot, jotka on jo käsitelty. Tämä on hyödyllistä, jos haluat ajaa migraation vähemmän kiireisinä aikoina (esim. yöllä). Suosittelemme sulkemaan sivuston ja ajamaan migraation offline-tilassa huoltokatkon aikana, kun projektien määrä on alle 1000 projektia (katso migraatioskriptin tuloste, kun sitä ajetaan komennolla `--report`). Jos projektien määrä on suuri, voit ajaa skriptin ja seurata sen etenemistä, ja päättää sitten, jatkatko sen ajamista online- vai offline-tilassa oman tilanteesi perusteella. #### Siivoa vanhat binaaritiedot Kun migraatio on valmis ja olet varmistanut, että projektit pääsevät edelleen kaikkiin tiedostoihinsa, voit poistaa vanhan tiedostotallennuksen kohdasta `/var/lib/overleaf/data/user_files`. Suosittelemme lämpimästi pitämään nämä tiedostot vielä jonkin aikaa - voit tehdä niistä ensin sovellukselle saavuttamattomia nimeämällä kansion uudelleen. ### Vianmääritys Lisäämme tähän vianmääritysohjeita. Huomaa, että vaikka tarjoamme normaalisti tukea vain Server Pro -asiakkaille, tämän migraation luonteen vuoksi pyrimme tukemaan myös CE-asiakkaita, jotka kohtaavat binaaritiedostojen migraatioon liittyviä ongelmia. Jos binaaritiedostojen migraatioskripti epäonnistuu (eli päättyy virheeseen tai tulostaa nollasta poikkeavan määrän epäonnistuneita projekteja), lähetä seuraavat tiedot tukitiimillemme sähköpostitse [support+filestoremigration@overleaf.com](mailto:support+filestoremigration@overleaf.com?subject=Binary%20file%20migration%20problem\&body=Instance%20Type%3A%20CE%20or%20Server%20Pro%20%28delete%20as%20appropriate%29%0A%0AInstallation%20Type%3A%20Overleaf%20toolkit%20or%20docker-compose.yml%20or%20other%20%28delete%20as%20appropriate%29%0A%0AScript%20output%3A%0A%0Abin%2Fdoctor%20output%20%28if%20using%20toolkit%29%3A%0A), ja erittele: Aihe: Binaaritiedostojen migraatio-ongelma Viesti: * Instanssityyppi: CE tai Server Pro (poista tarpeeton) * Asennustyyppi: Overleaf Toolkit tai `docker-compose.yml` tai muu (poista tarpeeton) * Versio: 5.5.x (toolkit: `$ cat config/version`) * Migraatiokäsikirjoituksen tuloste (jonka pitäisi sijaita kontainerissa kohdassa `/var/log/overleaf`) * Raportti: (aja migraatioskripti komennolla `--report`) * Käsitellyt projektit: (skriptin viimeisimmän ajon mukaan) * Migraation kesto: * `bin/doctor` tuloste (kun käytetään Toolkitia) * Toolkitin versio: `$ git rev-parse HEAD` (kun käytetään Toolkitiä) Harkitse liittämistä sähköpostiin myös `filestore` palvelun loki sähköpostiin. Löydät sen osoitteesta `/var/log/overleaf/filestore.log` kontainerin `sharelatex` sisällä ja vie ne näin: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # korvaa skriptin tulostamalla aikaleimalla $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Poista lokitiedostoista kaikki arkaluonteiset tiedot ennen kuin liität ne. #### Puuttuvat tiedostot Vanhemmat Server Pro/CE-versiot loivat tiedostopuun merkintöjä ennen kuin käyttäjän lataukset olivat valmistuneet, mikä saattoi aiheuttaa tiedostojen näyttämisen puuttuvina, kun lataus epäonnistui. Saatat löytää muutamia tällaisia tapauksia virheinä, kun kaikkia tiedostopuita käsitellään. Jos puuttuvien tiedostojen määrä on pieni, harkitse näiden tapausten manuaalista tarkistamista ja niiden poistamista selaimen editorissa. Jos puuttuvien tiedostojen määrä on suuri, harkitse yhteydenottoa tukeen; katso yllä oleva sähköpostimalli. #### Rikkinäisten tiedostopuiden etsiminen Migraatio voi epäonnistua projekteissa, joissa on virheellisesti muotoiltu tiedostopuu (esimerkiksi, kun tiedostonimet ovat tyhjiä). Löydät luettelon näistä ongelmista käyttämällä `find_malformed_filetrees` skriptiä, joka tarkistaa kaikki tietokannan projektit: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json" ``` {% endcode %} Korjataksesi virheelliset polut, käytä `fix_malformed_filetree` skriptiä, suorittaen komennon kerran jokaista virheellistä polkua kohden: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/fix_malformed_filetree.mjs --logs=/tmp/malformed-file-trees.json" ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/fi/tuki/support-guides/v5.5.7-migration-binary-files-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.