> 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/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ů Nadcházející 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`, binární soubory jsou ukládány dvakrát: v aktivním úložišti souborů v „filestore“ a v systému úplné historie projektu. Do budoucna bude jedna kopie každého souboru uložena v systému úplné historie projektu. Migrace na sjednocený úložný systém se skládá ze dvou částí: Nový příznak pro řízení fáze migrace a skript, který zpracovává 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 zapisují do historie asynchronně. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , soubory se čtou z historie s návratem na filestore a zapisují se jak do filestore, tak do historie. Přechod zpět na `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` je možné. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` soubory se čtou a zapisují pouze do historie. Přechod zpět na `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` není možné, ledaže byla provedena „offline“. Při ukládání dat do [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) a při 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í do bucketu historie pro bloby `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Služba filestore bude nově obsluhovat čtení ze služby kompilátoru. {% hint style="warning" %} Důrazně se doporučuje provést migraci binárních souborů nejprve v neprodukčním/sandboxovém prostředí. {% endhint %} {% hint style="success" %} Standardní licence Server Pro vám umožňuje provozovat aplikaci v produkčním prostředí i v jednom neprodukčním/sandboxovém prostředí; důrazně se doporučuje zřídit neprodukční prostředí pro testování. {% endhint %} {% hint style="info" %} Pokud upgradujete na verzi Server Pro/CE `6.0` a později se rozhodnete vrátit na starší verzi, měli byste obnovit z úplné zálohy systému. {% 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 **Nástrojová sada:** Použijte `$ bin/upgrade` skript pro aktualizaci **nástrojové sady** na nejnovější verzi. Když budete vyzváni, proveďte **ne** potvrďte výzvu **Upgradujte** obrázek? — místo toho ručně upravte **config/version** soubor a nastavte hodnotu na `5.5.7`. **Zastaralý docker-compose.yml:** Aktualizujte verzi `sharelatex` službu na `5.5.7`. {% endstep %} {% step %} #### Odhadněte 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é zastaralé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 %} Příklad výstupu: {% code fullWidth="false" %} ``` Aktuální stav: - Celkový počet projektů: 10 - Celkový počet smazaných projektů: 5 Vzorkuji 1000 projektů pro odhad postupu... Statistiky vzorku projektů: - Vzorkované projekty: 9 (90 % všech projektů) - Vzorkované projekty se všemi hashi přítomnými: 5 - Odhadované procento projektů, které potřebují doplnit hashe: 44 % - 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 hashi přítomnými: 3 - Odhadované procento smazaných projektů, které potřebují doplnit hashe: 25 % - 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 projektů {% code overflow="wrap" %} ```bash # Uživatelé Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Uživatelé zastaralé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" %} V případě, že "failedProjects" není nula, obraťte se prosím na podporu a nepokračujte v migraci binárních souborů. {% endhint %} {% endstep %} {% step %} #### Posuňte fázi migrace na 1 Nástrojová sada: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` v `config/variables.env`. Zastaralý docker-compose.yml: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` v `prostředí` sekce v `sharelatex` službu. {% endstep %} {% step %} #### Proveďte změnu konfigurace a spusťte instanci Nástrojová sada: `bin/up -d` Zastaralý 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é zastaralé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 [ukládáte log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) soubory 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ýstupní 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ání backendu","time":"2025-07-25T15:00:58.166Z","v":0} Zapisují se logy do /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Spouští se záloha souborů projektu... Načtené globální blob objekty: 0 Zpracovávají se nesmazané projekty... Zpracováno 1 projekt, uplynulý čas 0 s Aktualizace aktivních projektů dokončena Zpracovávají se 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 žádná selhání: ```bash Hotovo. ``` Log soubor bude vypadat takto (použijte cestu vytištěnou 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":"skupina byla skutečně dokončena","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 migrace souborů","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Zastavte instanci Nástrojová sada: `bin/stop sharelatex` Zastaralý docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Znepřístupněte staré soubory aplikaci Nyní můžete přesunout staré soubory do sekundárního úložiště. Doporučujeme ponechat soubory ještě nějakou dobu pro případ, že se později objeví problémy. {% code overflow="wrap" %} ```bash # Uživatelé nástrojové sady: $ 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é zastaralé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 %} #### Posuňte fázi migrace na 2 Nástrojová sada: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` v `config/variables.env`. Zastaralý docker-compose.yml: Nastavte `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` v `prostředí` sekce v `sharelatex` službu. {% endstep %} {% step %} #### Proveďte změnu konfigurace a spusťte instanci Nástrojová sada: `bin/up -d` Zastaralý 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í, zatímco běží skript migrace binárních souborů, postupujte prosím takto: * Přihlaste se do své instance Overleaf pomocí administrátorského účtu * Klikněte na tlačítko **Administrátor** tlačítko a zvolte **Spravovat web** * Klikněte na tlačítko **Otevřít/Zavřít editor** karta * Klikněte na tlačítko **Zavřít editor** tlačítko * Klikněte na tlačítko **Odpojit všechny uživatele** tlačítko Jakmile bude toto provedeno, budou se případní přihlášení uživatelé přesměrováni na stránku údržby a noví uživatelé navštěvující přihlašovací stránku uvidí stránku údržby a **nebude** budou se moci přihlásit. Tyto kroky je třeba zopakovat při restartování instance. Chcete-li web znovu otevřít, stačí instanci restartovat. #### Online migrace Je možné spouštět migrační skripty i při běžícím aplikačním serveru. Je třeba vzít v úvahu několik aspektů: * Proces migrace je náročný na I/O, během běhu skriptu byste měli sledovat využití prostředků. * Při vysoké souběžnosti zpracování může event loop v `filestore` službě zaznamenat určité blokování, což by vedlo ke zhoršení uživatelského 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é již byly zpracovány. To je užitečné, pokud dáváte přednost spuštění migrace v méně vytížených hodinách (např. v noci). Naše doporučení je web uzavřít a spustit migraci offline v době údržby, když je počet vašich projektů menší než 1000 (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, poté se na základě vaší konkrétní situace rozhodnout, zda ho necháte běžet online nebo offline. #### Vyčistěte stará data binárních souborů Když dokončíte migraci a ověříte, že projekty stále mají přístup 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 znepřístupnit aplikaci tím, že nejprve přejmenujete složku. ### Řešení problémů Zde doplníme rady pro řešení problémů. Upozorňujeme, že i když obvykle 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 migrace 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 (smažte podle potřeby) * Typ instalace: Overleaf toolkit nebo `docker-compose.yml` nebo jiné (smažte podle potřeby) * Verze: 5.5.x (nástrojová sada: `$ 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: (podle 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řipojení log souborů pro `filestore` službu do e-mailu. Najdete ji na `/var/log/overleaf/filestore.log` uvnitř `sharelatex` kontejneru a exportujte je takto: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # nahraďte časovým údajem vytištěným skriptem $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Před přiložením prosím z log souborů odstraňte veškeré citlivé informace. #### Chybějící soubory Starší verze Server Pro/CE vytvářely záznamy stromu souborů před dokončením nahrávání uživatelem, což mohlo způsobit, že soubory vypadaly jako chybějící, když se nahrávání nezdařilo. Při zpracování všech stromů souborů můžete najít několik takových případů nahlášených jako chyby. Pokud je počet chybějících souborů nízký, zvažte ruční kontrolu těchto případů a jejich odstranění v editoru v prohlížeči. Pokud je počet chybějících souborů vysoký, zvažte kontaktování podpory, viz výše šablona e-mailu. #### Hledání poškozených stromů souborů Migrace může selhat u projektů, které mají chybně vytvořený strom souborů (například když 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 a spusťte příkaz jednou pro každou chybnou 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://ayakaleaf-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.