> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-pro.ayaka.space/on-premises/fi/tuki/support-guides/v5.5.7-migration-binary-files-migration.md). # (v5.5.7-migraatio) Binääritiedostojen migraatio ## Binääritiedostojen migraatio Tuleva pääversio `6.0` Server Pron ja Community Editionin julkaisu puolittaa binääritiedostojen tallennustilan käytön. Verkkopohjainen migraatio sisältyy versioon `5.5.7` , mikä mahdollistaa mahdollisimman lyhyen käyttökatkon osana päivitystä. Koska Server Pro `4.x`, binääritiedostot tallennetaan kahteen kertaan: aktiivisten tiedostojen tallennustilaan "filestore" ja koko projektihistoriajärjestelmään. Jatkossa kustakin tiedostosta tallennetaan yksi kopio koko projektihistoriajärjestelmään. Migraatio keskitettyyn tallennusjärjestelmään koostuu kahdesta osasta: uudesta lipusta migraatiovaiheen ohjaamiseen ja skriptistä, joka käsittelee kaikki aktiiviset ja pehmeästi poistetut projektit. Vaiheet: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (oletus), tiedostot luetaan filestoren kautta ja kirjoitetaan sinne. Tiedostot kirjoitetaan historiaan asynkronisesti. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , tiedostot luetaan historiasta, tarvittaessa filestoren varmistuksella, ja kirjoitetaan sekä filestoreen että historiaan. Alentaminen versioon `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` on mahdollista. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` tiedostot luetaan ja kirjoitetaan vain historiaan. Alentaminen versioon `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` ei ole mahdollista, ellei sitä ole 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 historian säilöön blob-tiedostoille `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Filestore-palvelu palvelee jatkossa kääntäjäpalvelun lukupyyntöjä. {% hint style="warning" %} On erittäin suositeltavaa suorittaa binääritiedostojen migraatio ensin ei-tuotanto-/hiekkalaatikkoympäristössä. {% endhint %} {% hint style="success" %} Standardi Server Pro -lisenssi sallii sovelluksen ajamisen tuotantoympäristössä sekä yhdessä ei-tuotanto-/hiekkalaatikkoympäristössä; on erittäin suositeltavaa määrittää 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 aiempaan versioon, sinun tulee 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 johdonmukaisella tilannekuvalla **mongo**, **redis** ja **sharelatex** hakemistoista. {% endstep %} {% step %} #### Päivitä **Työkalupaketti:** Käytä `$ bin/upgrade` skripti työkalupaketin päivittämiseen **työkalupaketti** uusimpaan versioon. Kun sinua pyydetään, älä **ei** vahvista kehotetta **Päivitä** kuva? — sen sijaan muokkaa käsin **config/version** tiedostoa ja aseta arvoksi `5.5.7`. **Perinteinen docker-compose.yml:** Päivitä `sharelatex` palvelu arvoon `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" # Perinteisen 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 Lasketaan 1000 projektin otos etenemisen arvioimiseksi... Otosprojektien tilastot: - Otosprojekteja: 9 (90 % kaikista projekteista) - Otosprojekteja, joissa kaikki tiivisteet ovat olemassa: 5 - Arvio projekteilta, joille tarvitaan tiivisteiden takatäyttö: 44 % (arvio) - Otosprojekteissa on 11 tiedostoa, jotka on tarkistettava koko projektihistoriajärjestelmää vasten. - Otosprojekteissa on 3 tiedostoa, jotka on ladattava koko projektihistoriajärjestelmään (arvioiden 27 % kaikista tiedostoista). Poistettujen projektien otostilastot: - Otospoistettuja projekteja: 4 (80 % kaikista poistetuista projekteista) - Otospoistettuja projekteja, joissa kaikki tiivisteet ovat olemassa: 3 - Arvio poistetuista projekteista, joille tarvitaan tiivisteiden takatäyttö: 25 % (arvio) - Otospoistetuissa projekteissa on 2 tiedostoa, jotka on tarkistettava koko projektihistoriajärjestelmää vasten. - Otospoistetuissa projekteissa on 1 tiedosto, joka on ladattava koko 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 # Perinteisen 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 binääritiedostojen migraatiota. {% endhint %} {% endstep %} {% step %} #### Siirrä migraatiovaihe arvoon 1 Työkalupaketti: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` tiedostossa `config/variables.env`. Perinteinen docker-compose.yml: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` tiedostossa `ympäristö` osion `sharelatex` palvelu. {% endstep %} {% step %} #### Tee määritysmuutos käyttöön ja käynnistä instanssi Työkalupaketti: `bin/up -d` Perinteinen docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Varmista pääsy binääritiedostoihin Avaa projekti Overleaf-editorissa selaimessa ja valitse binääritiedosto, kuten kuva. {% endstep %} {% step %} #### Suorita siirtoskripti {% 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" # Perinteisen 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 tuotettu 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ää ladataan","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... Globaaleja blob-tiedostoja ladattu: 0 Käsitellään poistamattomia projekteja... Käsitelty 1 projekti, kulunut aika 0 s Aktiivisten projektien päivitys valmis Käsitellään poistettuja projekteja... Kokoelma deletedProjects näyttää olevan tyhjä. Poistettujen projektien päivitys valmis Valmis. ``` Jos siirto onnistuu, saat poistumiskoodiksi `0`, ja viimeisillä riveillä näkyy, 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 lopulta","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":"tiedostomigraatiotilastot","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Pysäytä instanssi Työkalupaketti: `bin/stop sharelatex` Perinteinen docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Tee vanhoista tiedostoista sovellukselle saavuttamattomia Voit nyt siirtää vanhat tiedostot toissijaiseen tallennustilaan. Suosittelemme säilyttämään tiedostot jonkin aikaa siltä varalta, että myöhemmin ilmenee ongelmia. {% code overflow="wrap" %} ```bash # Työkalupaketin 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 # Perinteisen 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-mountteja, voit yksinkertaisesti poistaa bind-mountin polulle /var/lib/overleaf/data/user_files säiliön sisältä. ``` {% endcode %} {% endstep %} {% step %} #### Siirrä migraatiovaihe arvoon 2 Työkalupaketti: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` tiedostossa `config/variables.env`. Perinteinen docker-compose.yml: Aseta `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` tiedostossa `ympäristö` osion `sharelatex` palvelu. {% endstep %} {% step %} #### Tee määritysmuutos käyttöön ja käynnistä instanssi Työkalupaketti: `bin/up -d` Perinteinen docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Varmista pääsy binääritiedostoihin Avaa projekti Overleaf-editorissa selaimessa ja valitse binääritiedosto, kuten kuva. {% endstep %} {% endstepper %} #### Siirto offline-tilassa Jos haluat estää käyttäjiä kirjautumasta sisään samalla kun binääritiedostojen migraatioskripti on käynnissä, noudata näitä ohjeita: * Kirjaudu Overleaf-instanssiisi ylläpitäjätilillä * 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, kaikki kirjautuneet käyttäjät ohjataan huoltosivulle, ja uudet käyttäjät, jotka vierailevat kirjautumissivulla, näkevät huoltosivun ja **ei** voivat kirjautua sisään. Sinun on toistettava nämä vaiheet, kun käynnistät instanssin uudelleen. Avataksesi sivuston uudelleen, käynnistä instanssi vain uudelleen. #### Siirto verkossa Siirtoskriptit on mahdollista suorittaa samalla kun sovellus on edelleen käynnissä. On kuitenkin muutamia seikkoja, jotka on otettava huomioon: * Migraatioprosessi on I/O-intensiivinen, joten sinun tulisi seurata resurssien käyttöä skriptin ollessa käynnissä. * Suurella käsittelyrinnakkaisuudella `filestore` palvelun tapahtumasilmukka saattaa kokea jonkin verran estymistä, mikä heikentäisi käyttökokemusta. Suosittelemme aloittamaan oletusarvoilla `--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 suorittaa migraation vähemmän ruuhkaisina aikoina (esim. yöllä). Suosittelemme sulkemaan sivuston ja suorittamaan migraation offline-tilassa huoltokatkon aikana, kun projektien määräsi on alle 1000 projektia (katso migraatioskriptin tuloste, kun sitä ajetaan parametrilla `--report`). Jos projektien määrä on suuri, voit suorittaa skriptin ja seurata sen edistymistä, ja päättää sitten oman tilanteesi perusteella, jatkatko sen ajamista verkossa vai offline-tilassa. #### Puhdista vanhat binääritiedot Kun olet valmis migraation kanssa ja varmistanut, että projektit pääsevät edelleen kaikkiin tiedostoihinsa, voit poistaa vanhan tiedostojen tallennuksen kohteessa `/var/lib/overleaf/data/user_files`. Suosittelemme vahvasti säilyttämään nämä tiedostot jonkin aikaa - voit tehdä niistä ensin sovellukselle saavuttamattomia nimeämällä kansion uudelleen. ### Vianmääritys Lisäämme tänne vianmääritysohjeita. Huomaa, että vaikka tarjoamme normaalisti tukea vain Server Pro -asiakkaille, tämän migraation luonteen vuoksi teemme parhaamme tukeaksemme myös CE-asiakkaita, joilla ilmenee binääritiedostojen migraatioon liittyviä ongelmia. Jos binääritiedostojen 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 eritellen: Aihe: Binääritiedostojen 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 (työkalupaketti: `$ cat config/version`) * Siirtoskriptin tuloste (jonka pitäisi sijaita kontissa polulla `/var/log/overleaf`) * Raportti: (aja migraatioskripti parametrilla `--report`) * Käsitellyt projektit: (skriptin viimeisimmän ajon mukaan) * Siirron kesto: * `bin/doctor` tuloste (kun käytössä on toolkit) * Toolkitin versio: `$ git rev-parse HEAD` (kun käytössä on Toolkit) Harkitse lokitiedostojen liittämistä `filestore` palvelun sähköpostiin. Löydät sen osoitteesta `/var/log/overleaf/filestore.log` kontin `sharelatex` sisältä 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 niiden liittämistä. #### Puuttuvat tiedostot Server Pro/CE:n vanhemmat versiot loivat tiedostopuu-merkintöjä ennen kuin käyttäjän lataukset valmistuivat, mikä saattoi aiheuttaa tiedostojen näkymisen puuttuvina, jos 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 tarkistamista manuaalisesti ja poista ne selaimen editorista. Jos puuttuvien tiedostojen määrä on suuri, harkitse yhteydenottoa tukeen; katso yllä oleva sähköpostipohja. #### Rikkinäisten tiedostopuuhien etsiminen Siirto voi epäonnistua projekteissa, joilla on virheellinen tiedostopuu (esimerkiksi kun tiedostonimet ovat tyhjiä). Löydät listan 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ä ja suorita komento kerran kutakin virheellistä polkua kohti: {% 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://overleaf-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.