> 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/nl/ondersteuning/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migratie v5.5.7) Migratie van binaire bestanden ## Migratie van binaire bestanden De aankomende grote versie `6.0` uitgave van Server Pro en Community Edition zal het opslaggebruik van binaire bestanden halveren. Een online migratie is inbegrepen in versie `5.5.7` , waardoor minimale downtime mogelijk is als onderdeel van de upgrade. Sinds Server Pro `4.x`, worden binaire bestanden twee keer opgeslagen: in de actieve bestandsopslag in "filestore" en in het systeem voor volledige projectgeschiedenis. Voortaan wordt van elk bestand één kopie opgeslagen in het systeem voor volledige projectgeschiedenis. De migratie naar het geconsolideerde opslagsysteem bestaat uit twee delen: een nieuwe vlag voor het beheren van de fase van de migratie en een script dat alle actieve en soft-deleted projecten verwerkt. Fasen: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (standaard), bestanden worden gelezen en geschreven naar filestore. Bestanden worden asynchroon naar history geschreven. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , worden bestanden gelezen uit history met terugval naar filestore en geschreven naar zowel filestore als de history. Downgraden naar `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` is mogelijk. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` bestanden worden alleen gelezen uit en geschreven naar history. Downgraden naar `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` is niet mogelijk, tenzij dit "offline" is uitgevoerd. Bij het opslaan van gegevens in [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) en bij gebruik van aparte serviceaccounts voor filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) en history (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Geef de filestore-gebruiker leesrechten op de history-bucket voor blobs `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . De filestore-service zal voortaan leesverzoeken van de compiler-service afhandelen. {% hint style="warning" %} Het wordt sterk aanbevolen om de migratie van binaire bestanden eerst uit te voeren in een niet-productie-/sandboxomgeving. {% endhint %} {% hint style="success" %} De standaard Server Pro-licentie staat toe dat u de applicatie draait in een productieomgeving en ook in een niet-productie-/sandboxomgeving; het wordt sterk aanbevolen om een niet-productieomgeving in te richten voor testen. {% endhint %} {% hint style="info" %} Als u upgradet naar Server Pro/CE-versie `6.0` en later besluit dat u wilt downgraden naar een eerdere versie, dan moet u herstellen vanaf een volledige systeemback-up. {% endhint %} ### Migratieprocedure {% stepper %} {% step %} #### Maak een back-up Maak een volledige [back-up](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) van je instantie met een consistente snapshot van de **mongo**, **redis** en **sharelatex** mappen. {% endstep %} {% step %} #### Werk bij **Toolkit:** Gebruik het `$ bin/upgrade` script om de **toolkit** bij te werken naar de nieuwste versie. Als daarom wordt gevraagd, **niet** bevestig de prompt **Upgraden** image? — bewerk in plaats daarvan handmatig **config/version** bestand en stel de waarde in op `5.5.7`. **Oud docker-compose.yml:** Werk de versie van de `sharelatex` service in op `5.5.7`. {% endstep %} {% step %} #### Schat het aantal getroffen projecten {% code overflow="wrap" %} ```bash # Gebruikers van Overleaf Toolkit: $ 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" # Gebruikers van de oude docker-compose.yml: $ 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 %} Voorbeelduitvoer: {% code fullWidth="false" %} ``` Huidige status: - Totaal aantal projecten: 10 - Totaal aantal verwijderde projecten: 5 1000 projecten steekproefsgewijs nemen om de voortgang te schatten... Gemonsterde statistieken voor projecten: - Gemonsterde projecten: 9 (90% van alle projecten) - Gemonsterde projecten waarbij alle hashes aanwezig zijn: 5 - Percentage projecten dat backfill van hashes nodig heeft: 44% (geschat) - Gemonsterde projecten hebben 11 bestanden die moeten worden gecontroleerd tegen het systeem voor volledige projectgeschiedenis. - Gemonsterde projecten hebben 3 bestanden die moeten worden geüpload naar het systeem voor volledige projectgeschiedenis (schatting: 27% van alle bestanden). Gemonsterde statistieken voor verwijderde projecten: - Gemonsterde verwijderde projecten: 4 (80% van alle verwijderde projecten) - Gemonsterde verwijderde projecten waarbij alle hashes aanwezig zijn: 3 - Percentage verwijderde projecten dat backfill van hashes nodig heeft: 25% (geschat) - Gemonsterde verwijderde projecten hebben 2 bestanden die moeten worden gecontroleerd tegen het systeem voor volledige projectgeschiedenis. - Gemonsterde verwijderde projecten hebben 1 bestand dat moet worden geüpload naar het systeem voor volledige projectgeschiedenis (schatting: 50% van alle bestanden). ``` {% endcode %} {% endstep %} {% step %} #### Wachtrijen voor projectgeschiedenis leegmaken {% code overflow="wrap" %} ```bash # Gebruikers van Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Gebruikers van de oude docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Herhaal het leegmaken totdat alle projecten zijn leeggemaakt (`"project_ids":0`). ``` gevonden projecten {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} totaal {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Als "failedProjects" niet nul is, neem dan contact op met support en ga niet verder met de migratie van binaire bestanden. {% endhint %} {% endstep %} {% step %} #### De migratiefase naar 1 brengen Toolkit: Stel `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`. Oud docker-compose.yml: Stel `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` in het `omgeving` sectie van de `sharelatex` service. {% endstep %} {% step %} #### Pas de configuratiewijziging toe en start de instantie Toolkit: `bin/up -d` Oud docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Toegang tot binaire bestanden controleren Open een project in de Overleaf-editor in de browser en selecteer een binair bestand, zoals een afbeelding. {% endstep %} {% step %} #### Voer het migratiescript uit {% code overflow="wrap" %} ```bash # Gebruikers van Overleaf Toolkit: $ 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" # Gebruikers van de oude docker-compose.yml: $ 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" %} Als u [logbestanden](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) buiten de **sharelatex** container bewaart, zorg er dan voor dat de eigenaar van de logs-map is ingesteld op de `www-data` gebruiker (uid=33) zodat het uitgevoerde logbestand kan worden weggeschreven. {% endhint %} De uitvoer zou er als volgt uit moeten zien: ```bash Stel UV_THREADPOOL_SIZE=16 in {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Backend laden","time":"2025-07-25T15:00:58.166Z","v":0} Logbestanden wegschrijven naar /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Back-up van projectbestanden starten... Globale blobs geladen: 0 Niet-verwijderde projecten verwerken... 1 project verwerkt, verstreken tijd 0s Bijwerken van actieve projecten voltooid Verwijderde projecten verwerken... De verzameling deletedProjects lijkt leeg te zijn. Bijwerken van verwijderde projecten voltooid Klaar. ``` Als de migratie succesvol is, krijg je een exitcode van `0`, en de laatste regels geven aan dat er geen mislukkingen zijn: ```bash Klaar. ``` Het logbestand ziet er als volgt uit (gebruik het pad zoals uitgeprint door het script): {% 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":"batch daadwerkelijk voltooid","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":"statistieken voor bestandsmigratie","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Instantie stoppen Toolkit: `bin/stop sharelatex` Oud docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Oude bestanden ontoegankelijk maken voor de applicatie U kunt de oude bestanden nu verplaatsen naar secundaire opslag. We raden aan de bestanden nog een tijd te bewaren voor het geval er later problemen optreden. {% code overflow="wrap" %} ```bash # Gebruikers van Toolkit: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Gebruikers van de oude docker-compose.yml: # We gaan ervan uit dat u de standaard bind-mount in /var/lib/overleaf gebruikt $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Als u selectieve bind-mounts gebruikt, kunt u eenvoudig de bind-mount voor /var/lib/overleaf/data/user_files binnen de container verwijderen. ``` {% endcode %} {% endstep %} {% step %} #### De migratiefase naar 2 brengen Toolkit: Stel `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`. Oud docker-compose.yml: Stel `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` in het `omgeving` sectie van de `sharelatex` service. {% endstep %} {% step %} #### Pas de configuratiewijziging toe en start de instantie Toolkit: `bin/up -d` Oud docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Toegang tot binaire bestanden controleren Open een project in de Overleaf-editor in de browser en selecteer een binair bestand, zoals een afbeelding. {% endstep %} {% endstepper %} #### Offline migratie Als u wilt voorkomen dat gebruikers kunnen inloggen terwijl het migratiescript voor binaire bestanden draait, volg dan deze stappen: * Log in op je Overleaf-instantie met een beheerdersaccount * Klik op de **Beheerder** knop en kies **Site beheren** * Klik de **Editor openen/sluiten** tabblad * Klik op de **Editor sluiten** knop * Klik op de **Alle gebruikers loskoppelen** knop Zodra dit is gedaan, worden ingelogde gebruikers doorgestuurd naar de onderhoudspagina, en nieuwe gebruikers die de inlogpagina bezoeken zien de onderhoudspagina en **wordt niet** kunnen inloggen. U moet deze stappen herhalen wanneer u de instantie opnieuw start. Om de site opnieuw te openen, start u de instantie eenvoudig opnieuw. #### Online migratie Het is mogelijk om de migratiescripts uit te voeren terwijl de applicatie nog draait. Er zijn een paar aandachtspunten om rekening mee te houden: * Het migratieproces is IO-intensief; u moet het resourcegebruik bewaken terwijl het script draait. * Bij een hoge verwerkingsconcurrentie kan de event loop in `filestore` de service enige blokkering ervaren, wat zou leiden tot een verminderde gebruikerservaring. We raden aan te beginnen met de standaardwaarden van `--concurrency=10` en `--concurrent-batches=1` . * U kunt het script op elk moment stoppen. Als u het opnieuw start, worden de eerdere projecten gevalideerd en worden bestanden die al zijn verwerkt overgeslagen. Dit is handig als u de migratie liever buiten de drukste uren uitvoert (bijv. 's nachts). Onze aanbeveling is om de site te sluiten en de migratie offline uit te voeren in een onderhoudsvenster wanneer uw projectaantal minder dan 1000 is (zie de uitvoer van het migratiescript bij gebruik van `--report`). Als het aantal projecten groot is, kun je het script uitvoeren en de voortgang bewaken, en vervolgens op basis van je specifieke situatie beslissen of je het online of offline blijft uitvoeren. #### Oude binaire bestandsgegevens opschonen Wanneer u klaar bent met de migratie en hebt gecontroleerd dat projecten nog steeds toegang hebben tot al hun bestanden, kunt u de oude bestandsopslag in `/var/lib/overleaf/data/user_files`. We raden sterk aan deze bestanden nog een tijd te bewaren - u kunt ze eerst ontoegankelijk maken voor de applicatie door de map te hernoemen. ### Probleemoplossing We zullen hier advies voor probleemoplossing toevoegen. Houd er rekening mee dat we normaal gesproken alleen support bieden aan Server Pro-klanten, maar gezien de aard van deze migratie zullen we ook ons best doen om CE-klanten te ondersteunen die problemen ervaren die specifiek zijn voor de migratie van binaire bestanden. Als het migratiescript voor binaire bestanden mislukt (d.w\.z. eindigt met een fout of een niet-nul aantal mislukte projecten afdrukt), stuur dan de volgende details per e-mail naar ons supportteam [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), met details over: Onderwerp: Probleem met migratie van binaire bestanden Bericht: * Type instantie: CE of Server Pro (verwijder waar van toepassing) * Installatietype: Overleaf toolkit of `docker-compose.yml` of anders (verwijder waar van toepassing) * Versie: 5.5.x (toolkit: `$ cat config/version`) * Uitvoer van het migratiescript (die zich in de container zou moeten bevinden onder `/var/log/overleaf`) * Rapport: (voer migratiescript uit met `--report`) * Verwerkte projecten: (volgens de laatste run van het script) * Duur van de migratie: * `bin/doctor` uitvoer (bij gebruik van toolkit) * Toolkitversie: `$ git rev-parse HEAD` (bij gebruik van Toolkit) Overweeg de logbestanden voor de `filestore` service aan de e-mail. U kunt het vinden op `/var/log/overleaf/filestore.log` binnen de `sharelatex` container en exporteer ze als volgt: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # vervang door de tijdstempel zoals uitgeprint door het script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Verwijder gevoelige informatie uit de logbestanden voordat je ze toevoegt. #### Ontbrekende bestanden Oudere versies van Server Pro/CE maakten bestandsboomvermeldingen aan voordat gebruikersuploads waren voltooid, waardoor bestanden als ontbrekend konden verschijnen wanneer een upload mislukte. U kunt een paar van deze gevallen als fouten gerapporteerd zien wanneer alle bestandsbomen worden verwerkt. Als het aantal ontbrekende bestanden laag is, overweeg dan deze gevallen handmatig te beoordelen en ze in de browser uit de editor te verwijderen. Als het aantal ontbrekende bestanden hoog is, overweeg dan contact op te nemen met support; zie het e-mailsjabloon hierboven. #### Kapotte bestandstrees vinden De migratie kan mislukken voor projecten met een foutief opgebouwde bestandstree (bijvoorbeeld wanneer bestandsnamen leeg zijn). Je kunt een lijst van deze problemen vinden met het `find_malformed_filetrees` script dat alle projecten in de database controleert: {% 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 %} Gebruik om de ongeldige paden te herstellen het `fix_malformed_filetree` script, waarbij je het commando één keer uitvoert voor elk slecht pad: {% 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/nl/ondersteuning/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.