> 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/on-premises-cs/podpora/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migrace v5.5.7) Migrace binárních souborů ## Migrace binárních souborů Připravovaná hlavní verze `6.0` vydání Server Pro a Community Edition sníží využití úložiště binárních souborů na polovinu. Online migrace je součástí verze `5.5.7` , což umožňuje minimální výpadek v rámci aktualizace. Od Server Pro `4.x`se binární soubory ukládají dvakrát: v aktivním úložišti souborů v „filestore“ a v systému úplné historie projektu. Do budoucna bude v systému úplné historie projektu uložena jedna kopie každého souboru. Migrace na konsolidovaný úložný systém se skládá ze dvou částí: nového příznaku pro řízení fáze migrace a skriptu, který zpracuje všechny aktivní a měkce smazané projekty. Fáze: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (výchozí), soubory se čtou a zapisují do filestore. Soubory se do historie zapisují asynchronně. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , soubory se čtou z historie s návratem na filestore a zapisují se do filestore i do historie. Downgrade na `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` je možný. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` soubory se čtou a zapisují pouze do historie. Downgrade na `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` není možný, pokud nebyl proveden „offline“. Při ukládání dat do [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) a použití samostatných servisních účtů pro filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) a historii (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Udělte prosím uživateli filestore přístup pro čtení k bucketu historie pro bloby `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Služba filestore bude nadále zajišťovat čtení ze služby kompilátoru. {% hint style="warning" %} Důrazně doporučujeme provést migraci binárních souborů nejprve v neprodukčním/sandboxovém prostředí. {% endhint %} {% hint style="success" %} Standardní licence Server Pro umožňuje provozovat aplikaci v produkčním prostředí i v jednom neprodukčním/sandboxovém prostředí; důrazně doporučujeme zřídit neprodukční prostředí pro testování. {% endhint %} {% hint style="info" %} Pokud aktualizujete na verzi Server Pro/CE `6.0` a později se rozhodnete vrátit na starší verzi, měli byste obnovit celý systém ze zálohy. {% endhint %} ### Postup migrace {% stepper %} {% step %} #### Vytvořte zálohu Vytvořte úplnou [zálohu](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) vaší instance s konzistentním snímkem **mongo**, **redis** a **sharelatex** adresářů. {% endstep %} {% step %} #### Aktualizujte **Toolkit:** Použijte `$ bin/upgrade` skript pro aktualizaci **toolkitu** na nejnovější verzi. Když budete vyzváni, **ne** potvrďte výzvu **Upgradovat** image? — místo toho ručně upravte **config/version** soubor a nastavte hodnotu na `5.5.7`. **Starý docker-compose.yml:** Aktualizujte verzi `sharelatex` službu na `5.5.7`. {% endstep %} {% step %} #### Odhadnout počet dotčených projektů {% code overflow="wrap" %} ```bash # Uživatelé 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" # Uživatelé starého 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 %} Ukázkový výstup: {% code fullWidth="false" %} ``` Aktuální stav: - Celkový počet projektů: 10 - Celkový počet smazaných projektů: 5 Vzorkování 1000 projektů pro odhad postupu... Statistiky vzorku projektů: - Vzorkované projekty: 9 (90 % všech projektů) - Vzorkované projekty se všemi přítomnými hashi: 5 - Procento projektů, které potřebují doplnit hashe: 44 % (odhad) - Vzorkované projekty mají 11 souborů, které je třeba zkontrolovat vůči systému úplné historie projektu. - Vzorkované projekty mají 3 soubory, které je třeba nahrát do systému úplné historie projektu (odhad 27 % všech souborů). Statistiky vzorku smazaných projektů: - Vzorkované smazané projekty: 4 (80 % všech smazaných projektů) - Vzorkované smazané projekty se všemi přítomnými hashi: 3 - Procento smazaných projektů, které potřebují doplnit hashe: 25 % (odhad) - Vzorkované smazané projekty mají 2 soubory, které je třeba zkontrolovat vůči systému úplné historie projektu. - Vzorkované smazané projekty mají 1 soubor, který je třeba nahrát do systému úplné historie projektu (odhad 50 % všech souborů). ``` {% endcode %} {% endstep %} {% step %} #### Vyprázdnit fronty historie projektu {% code overflow="wrap" %} ```bash # Uživatelé Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Uživatelé starého docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Opakujte vyprázdnění, dokud nebudou vyprázdněny všechny projekty (`"project_ids":0`). ``` nalezené projekty {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} celkem {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Pokud "failedProjects" není nula, obraťte se prosím na podporu a nepokračujte v migraci binárních souborů. {% endhint %} {% endstep %} {% step %} #### Přepnout fázi migrace na 1 Toolkit: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` v `config/variables.env`. Starý docker-compose.yml: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` v `prostředí` sekce `sharelatex` služby. {% endstep %} {% step %} #### Použijte změnu konfigurace a spusťte instanci Toolkit: `bin/up -d` Starý docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Ověřte přístup k binárním souborům Otevřete projekt v editoru Overleaf v prohlížeči a vyberte binární soubor, například obrázek. {% endstep %} {% step %} #### Spusťte migrační skript {% code overflow="wrap" %} ```bash # Uživatelé 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" # Uživatelé starého 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" %} Pokud [persistujete logy](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) souborů mimo **sharelatex** kontejner, ujistěte se, že vlastník adresáře s logy je nastaven na `www-data` uživatele (uid=33), aby bylo možné zapsat výsledný log soubor. {% endhint %} Výstup by měl vypadat takto: ```bash Nastavte UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Načítám backend","time":"2025-07-25T15:00:58.166Z","v":0} Zápis logů do /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Spouštím zálohování souborů projektu... Načteno globálních blobů: 0 Zpracovávám nesmazané projekty... Zpracován 1 projekt, uplynulý čas 0 s Aktualizace živých projektů dokončena Zpracovávám smazané projekty... Kolekce deletedProjects se zdá být prázdná. Aktualizace smazaných projektů dokončena Hotovo. ``` Pokud je migrace úspěšná, získáte návratový kód `0`, a poslední řádky budou indikovat, že nedošlo k žádným selháním: ```bash Hotovo. ``` Soubor logu bude vypadat takto (použijte cestu vypsanou skriptem): {% 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":"skutečně dokončený dávkový běh","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":"statistiky file-migration","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Zastavte instanci Toolkit: `bin/stop sharelatex` Starý docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Znepřístupnit staré soubory aplikaci Nyní můžete přesunout staré soubory do sekundárního úložiště. Doporučujeme soubory ještě nějakou dobu ponechat pro případ, že se později vyskytnou potíže. {% code overflow="wrap" %} ```bash # Uživatelé toolkitu: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Uživatelé starého docker-compose.yml: # Předpokládáme, že používáte výchozí bind-mount v /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 # Pokud používáte selektivní bind-mounty, můžete jednoduše odstranit bind-mount pro /var/lib/overleaf/data/user_files uvnitř kontejneru. ``` {% endcode %} {% endstep %} {% step %} #### Přepnout fázi migrace na 2 Toolkit: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` v `config/variables.env`. Starý docker-compose.yml: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` v `prostředí` sekce `sharelatex` služby. {% endstep %} {% step %} #### Použijte změnu konfigurace a spusťte instanci Toolkit: `bin/up -d` Starý docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Ověřte přístup k binárním souborům Otevřete projekt v editoru Overleaf v prohlížeči a vyberte binární soubor, například obrázek. {% endstep %} {% endstepper %} #### Offline migrace Pokud chcete zabránit uživatelům v přihlašování během běhu skriptu pro migraci binárních souborů, postupujte takto: * Přihlaste se do své instance Overleaf pomocí administrátorského účtu * Klikněte na tlačítko **Správce** tlačítko a zvolte **Spravovat web** * Klikněte na tlačítko **Otevřít/Zavřít editor** kartu * Klikněte na tlačítko **Zavřít editor** tlačítko * Klikněte na tlačítko **Odpojit všechny uživatele** tlačítko Jakmile to bude hotové, pokud budou nějací uživatelé přihlášeni, budou přesměrováni na stránku údržby a všichni noví uživatelé navštěvující přihlašovací stránku uvidí stránku údržby a **nebudou** se moci přihlásit. Tyto kroky je třeba zopakovat při restartu instance. Pro znovuotevření webu stačí instanci restartovat. #### Online migrace Migrační skripty je možné spustit, i když aplikace stále běží. Je třeba vzít v úvahu několik věcí: * Proces migrace je náročný na I/O, během běhu skriptu byste měli sledovat využití zdrojů. * Při vysoké souběžnosti zpracování může event loop ve `filestore` službě zaznamenat určité blokování, což by vedlo ke zhoršenému uživatelskému zážitku. Doporučujeme začít s výchozími hodnotami `--concurrency=10` a `--concurrent-batches=1` . * Skript můžete kdykoli zastavit. Jeho opětovné spuštění ověří předchozí projekty a přeskočí soubory, které už byly zpracovány. To je užitečné, pokud chcete migraci provádět v méně vytížených hodinách (např. v noci). Doporučujeme web uzavřít a spustit migraci offline v údržbovém okně, pokud máte méně než 1000 projektů (viz výstup migračního skriptu při spuštění s `--report`). Pokud je počet projektů velký, můžete skript spustit a sledovat jeho průběh, pak se podle svého konkrétního případu rozhodnout, zda pokračovat online nebo offline. #### Vyčištění starých dat binárních souborů Až budete s migrací hotovi a ověříte, že projekty stále mohou přistupovat ke všem svým souborům, můžete odstranit staré úložiště souborů v `/var/lib/overleaf/data/user_files`. Důrazně doporučujeme ponechat tyto soubory ještě nějakou dobu - můžete je nejprve znepřístupnit aplikaci přejmenováním složky. ### Řešení problémů Sem přidáme rady pro řešení problémů. Upozorňujeme, že i když běžně poskytujeme podporu pouze zákazníkům Server Pro, vzhledem k povaze této migrace se budeme snažit co nejlépe podpořit i zákazníky CE, kteří narazí na problémy specifické pro migraci binárních souborů. Pokud skript pro migraci binárních souborů selže (tj. skončí s chybou nebo vypíše nenulový počet neúspěšných projektů), pošlete prosím následující údaje našemu týmu podpory e-mailem [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), s uvedením: Předmět: Problém s migrací binárních souborů Tělo: * Typ instance: CE nebo Server Pro (v případě potřeby smažte) * Typ instalace: Overleaf toolkit nebo `docker-compose.yml` nebo jiné (v případě potřeby smažte) * Verze: 5.5.x (toolkit: `$ cat config/version`) * Výstup migračního skriptu (který by měl být umístěn v kontejneru v `/var/log/overleaf`) * Report: (spusťte migrační skript s `--report`) * Zpracované projekty: (dle posledního spuštění skriptu) * Doba trvání migrace: * `bin/doctor` výstup (při použití toolkitu) * Verze toolkitu: `$ git rev-parse HEAD` (při použití toolkitu) Zvažte přiložení log souborů pro `filestore` služby do e-mailu. Najdete ho na `/var/log/overleaf/filestore.log` v `sharelatex` kontejneru a exportujte je takto: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # nahraďte časovým údajem vypsaným skriptem $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Před přiložením prosím z log souborů odstraňte všechny citlivé informace. #### Chybějící soubory Starší verze Server Pro/CE vytvářely záznamy stromu souborů ještě před dokončením nahrávání uživatelem, což mohlo způsobit, že se soubory jevily jako chybějící, když nahrávání selhalo. Několik těchto případů můžete najít nahlášených jako chyby při zpracování všech stromů souborů. Pokud je počet chybějících souborů nízký, zvažte ruční kontrolu těchto případů a jejich smazání v editoru v prohlížeči. Pokud je počet chybějících souborů vysoký, zvažte kontaktování podpory, viz šablona e-mailu výše. #### Hledání poškozených stromů souborů Migrace může selhat u projektů, které mají chybně vytvořený strom souborů (například pokud jsou názvy souborů prázdné). Seznam těchto problémů můžete najít pomocí `find_malformed_filetrees` skriptu, který kontroluje všechny projekty v databázi: {% 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 %} Chcete-li opravit neplatné cesty, použijte `fix_malformed_filetree` skript, přičemž spusťte příkaz jednou pro každou špatnou cestu: {% 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/on-premises-cs/podpora/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.