> 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/nl/ondersteuning/support-guides/v5.5.7-migration-binary-files-migration.md). # (v5.5.7-migratie) Migratie van binaire bestanden ## Migratie van binaire bestanden De aankomende grote versie `6.0` 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 onderdelen: een nieuwe vlag voor het aansturen van de migratiefase en een script dat alle actieve en zacht verwijderde projecten verwerkt. Fasen: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (standaard) worden bestanden gelezen en geschreven naar filestore. Bestanden worden asynchroon naar de geschiedenis geschreven. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , worden bestanden uit de geschiedenis gelezen met terugval naar filestore en naar zowel filestore als de geschiedenis geschreven. Teruggaan naar `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` is mogelijk. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` bestanden worden alleen uit de geschiedenis gelezen en geschreven. Teruggaan 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 het gebruik van aparte serviceaccounts voor filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) en geschiedenis (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Geef de filestore-gebruiker leesrechten op de geschiedenis-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 je toe de applicatie zowel in een productieomgeving als in één niet-productie-/sandboxomgeving te draaien; het wordt sterk aanbevolen een niet-productieomgeving voor testen in te richten. {% endhint %} {% hint style="info" %} Als je upgradet naar Server Pro/CE-versie `6.0` en later besluit terug te gaan naar een eerdere versie, dan moet je 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 uw instantie met een consistente snapshot van de **mongo**, **redis** en **sharelatex** mappen. {% endstep %} {% step %} #### Bijwerken **Toolkit:** Gebruik het `$ bin/upgrade` script om de **toolkit** bij te werken naar de nieuwste versie. Als daarom wordt gevraagd, doe dan **nog** bevestig de prompt niet **Upgrade** image? — bewerk in plaats daarvan handmatig **config/version** bestand en zet de waarde op `5.5.7`. **Legacy docker-compose.yml:** Werk de versie van de `sharelatex` service bij naar `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 legacy 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 bemonsteren om de voortgang te schatten... Bemonsterde statistieken voor projecten: - Bemonsterde projecten: 9 (90% van alle projecten) - Bemonsterde projecten met alle hashes aanwezig: 5 - Percentage projecten waarvoor hashes achteraf moeten worden aangevuld: 44% (geschat) - Bemonsterde projecten hebben 11 bestanden die moeten worden gecontroleerd tegen het volledige projecthistoriesysteem. - Bemonsterde projecten hebben 3 bestanden die naar het volledige projecthistoriesysteem moeten worden geüpload (schatting: 27% van alle bestanden). Bemonsterde statistieken voor verwijderde projecten: - Bemonsterde verwijderde projecten: 4 (80% van alle verwijderde projecten) - Bemonsterde verwijderde projecten met alle hashes aanwezig: 3 - Percentage verwijderde projecten waarvoor hashes achteraf moeten worden aangevuld: 25% (geschat) - Bemonsterde verwijderde projecten hebben 2 bestanden die moeten worden gecontroleerd tegen het volledige projecthistoriesysteem. - Bemonsterde verwijderde projecten hebben 1 bestand dat naar het volledige projecthistoriesysteem moet worden geüpload (schatting: 50% van alle bestanden). ``` {% endcode %} {% endstep %} {% step %} #### Projectgeschiedenis-queues leegmaken {% code overflow="wrap" %} ```bash # Gebruikers van Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Gebruikers van legacy docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Herhaal het leegmaken totdat alle projecten zijn geleegd (`"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 %} #### Breng de migratiefase op 1 Toolkit: Zet `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` in `config/variables.env`. Legacy docker-compose.yml: Zet `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` in de `omgeving` sectie van de `sharelatex` service. {% endstep %} {% step %} #### Pas de configuratiewijziging toe en start de instantie Toolkit: `bin/up -d` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifieer toegang tot binaire bestanden 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 legacy 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 je [logbestanden](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) bestanden 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 uitvoerlogbestand geschreven kan worden. {% 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} Logs schrijven 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 live projecten voltooid Verwijderde projecten verwerken... De verzameling deletedProjects lijkt leeg te zijn. Bijwerken van verwijderde projecten voltooid Klaar. ``` Als de migratie succesvol is, krijgt u een exitcode van `0`, en de laatste regels geven aan dat er geen fouten zijn: ```bash Klaar. ``` Het logbestand ziet er als volgt uit (gebruik het pad zoals afgedrukt 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 bestandsmigratie","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Stop de instantie Toolkit: `bin/stop sharelatex` Legacy docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Maak oude bestanden ontoegankelijk voor de applicatie Je kunt de oude bestanden nu naar secundaire opslag verplaatsen. We raden aan de bestanden nog een tijdje te bewaren voor het geval er later problemen ontstaan. {% code overflow="wrap" %} ```bash # Toolkit-gebruikers: $ 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 legacy docker-compose.yml: # We gaan ervan uit dat je de standaard bind-mount gebruikt in /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 # Als je selectieve bind-mounts gebruikt, kun je de bind-mount voor /var/lib/overleaf/data/user_files binnen de container eenvoudig verwijderen. ``` {% endcode %} {% endstep %} {% step %} #### Breng de migratiefase op 2 Toolkit: Zet `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` in `config/variables.env`. Legacy docker-compose.yml: Zet `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` in de `omgeving` sectie van de `sharelatex` service. {% endstep %} {% step %} #### Pas de configuratiewijziging toe en start de instantie Toolkit: `bin/up -d` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifieer toegang tot binaire bestanden Open een project in de Overleaf-editor in de browser en selecteer een binair bestand, zoals een afbeelding. {% endstep %} {% endstepper %} #### Offline migratie Als je wilt voorkomen dat gebruikers kunnen inloggen terwijl het migratiescript voor binaire bestanden draait, volg dan deze stappen: * Log in op uw Overleaf-instantie met een beheerdersaccount * Klik op de **Admin** knop en kies **Site beheren** * Klik op het **tabblad Editor openen/sluiten** tabblad * Klik op de **Sluit de editor** knop * Klik op de **Verbreek de verbinding met alle gebruikers** knop Zodra dit is gedaan, worden aangemelde gebruikers doorgestuurd naar de onderhoudspagina, en nieuwe gebruikers die de inlogpagina bezoeken zien de onderhoudspagina en **zullen niet** kunnen inloggen. Je moet deze stappen herhalen wanneer je de instantie opnieuw start. Om de site opnieuw te openen, start je de instantie gewoon opnieuw. #### Online migratie Het is mogelijk om de migratiescripts uit te voeren terwijl de applicatie nog draait. Er zijn enkele aandachtspunten om rekening mee te houden: * Het migratieproces is IO-intensief; je moet het resourcegebruik monitoren terwijl het script draait. * Bij hoge verwerkingsconcurrentie kan de event loop in `filestore` service enige blokkering ondervinden, wat zou leiden tot een verslechterde gebruikerservaring. We raden aan te beginnen met de standaardwaarden van `--concurrency=10` en `--concurrent-batches=1` . * Je kunt het script op elk moment stoppen. Als je het opnieuw start, worden de vorige projecten gevalideerd en worden bestanden die al verwerkt zijn overgeslagen. Dit is handig als je de migratie liever uitvoert tijdens rustigere uren (bijv. 's nachts). Onze aanbeveling is om de site te sluiten en de migratie offline uit te voeren in een onderhoudsvenster wanneer je minder dan 1000 projecten hebt (zie de uitvoer van het migratiescript wanneer je draait met `--report`). Als het aantal projecten groot is, kunt u het script uitvoeren en de voortgang volgen, en daarna op basis van uw specifieke situatie beslissen of u het online of offline verder laat draaien. #### Oude binaire bestandsgegevens opschonen Wanneer je klaar bent met de migratie en hebt geverifieerd dat projecten nog steeds toegang hebben tot al hun bestanden, kun je de oude bestandsopslag verwijderen in `/var/lib/overleaf/data/user_files`. We raden sterk aan deze bestanden nog een tijdje te bewaren — je kunt ze eerst ontoegankelijk maken voor de applicatie door de map eerst te hernoemen. ### Probleemoplossing We zullen hier advies voor probleemoplossing toevoegen. Let op: hoewel we normaal gesproken alleen ondersteuning bieden aan Server Pro-klanten, zullen we, gezien de aard van deze migratie, 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. met een fout afsluit of een niet-nul aantal mislukte projecten afdrukt), stuur dan de volgende gegevens 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 vermelding van: Onderwerp: Probleem met migratie van binaire bestanden Tekst: * Instantietype: CE of Server Pro (verwijder indien van toepassing) * Installatietype: Overleaf toolkit of `docker-compose.yml` of anders (verwijder indien 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 het migratiescript uit met `--report`) * Verwerkte projecten: (volgens de laatste uitvoer 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 van de `filestore` service toe aan de e-mail. Je kunt deze vinden op `/var/log/overleaf/filestore.log` in de `sharelatex` container en ze zo exporteren: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # vervang door de tijdstempel zoals afgedrukt door het script $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Verwijder gevoelige informatie uit de logbestanden voordat u ze bijvoegt. #### Ontbrekende bestanden Oudere versies van Server Pro/CE maakten bestandssysteemvermeldingen aan voordat het uploaden door gebruikers voltooid was, waardoor bestanden als ontbrekend konden verschijnen wanneer een upload mislukte. Mogelijk vind je enkele van deze gevallen gerapporteerd als fouten bij het verwerken van alle bestandssystemen. Als het aantal ontbrekende bestanden laag is, overweeg dan deze gevallen handmatig te controleren 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. #### Beschadigde bestandstructuren vinden De migratie kan mislukken voor projecten met een misvormde bestandstructuur (bijvoorbeeld wanneer bestandsnamen leeg zijn). U kunt een lijst van deze problemen vinden met behulp van 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 u het commando eenmaal uitvoert voor elk ongeldig 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://overleaf-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.