> 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/pl/wsparcie/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migracja v5.5.7) Migracja plików binarnych ## Migracja plików binarnych Nadchodząca główna wersja `6.0` wydanie Server Pro i Community Edition zmniejszy zużycie miejsca przez pliki binarne o połowę. Migracja online jest uwzględniona w wersji `5.5.7` , umożliwiając minimalny przestój w ramach aktualizacji. Od Server Pro `4.x`, pliki binarne są przechowywane dwukrotnie: w aktywnym magazynie plików w „filestore” oraz w pełnym systemie historii projektu. Od tej pory pojedyncza kopia każdego pliku będzie przechowywana w pełnym systemie historii projektu. Migracja do skonsolidowanego systemu przechowywania składa się z dwóch części: nowej flagi do kontrolowania etapu migracji oraz skryptu, który przetwarza wszystkie aktywne i miękko usunięte projekty. Etapy: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (domyślnie), pliki są odczytywane i zapisywane do filestore. Pliki są zapisywane do historii asynchronicznie. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , pliki są odczytywane z historii z fallbackiem do filestore i zapisywane zarówno do filestore, jak i do historii. Powrót do `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` jest możliwy. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` pliki są odczytywane i zapisywane wyłącznie do historii. Powrót do `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` nie jest możliwy, chyba że został przeprowadzony „offline”. Podczas przechowywania danych w [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) i korzystaniu z oddzielnych kont usług dla filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) i historii (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Prosimy nadać użytkownikowi filestore dostęp do odczytu do bucketu historii dla blobów `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Od tej pory usługa filestore będzie obsługiwać odczyty z usługi kompilacji. {% hint style="warning" %} Zdecydowanie zaleca się najpierw przeprowadzić migrację plików binarnych w środowisku innym niż produkcyjne/sandbox. {% endhint %} {% hint style="success" %} Standardowa licencja Server Pro pozwala uruchamiać aplikację zarówno w środowisku produkcyjnym, jak i w jednym środowisku innym niż produkcyjne/sandbox; zdecydowanie zalecamy przygotowanie środowiska nieprodukcyjnego do testów. {% endhint %} {% hint style="info" %} Jeśli zaktualizujesz do wersji Server Pro/CE `6.0` i później zdecydujesz, że chcesz wrócić do wcześniejszej wersji, powinieneś przywrócić pełną kopię zapasową systemu. {% endhint %} ### Procedura migracji {% stepper %} {% step %} #### Utwórz kopię zapasową Utwórz pełną [kopię zapasową](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) swojej instancji wraz ze spójnym zrzutem **mongo**, **redis** i **sharelatex** katalogów. {% endstep %} {% step %} #### Aktualizacja **Toolkit:** Użyj `$ bin/upgrade` skryptu, aby zaktualizować **toolkit** do najnowszej wersji. Gdy zostaniesz o to poproszony, nie **nie** potwierdzaj monitu **Aktualizuj** obraz? — zamiast tego ręcznie edytuj **config/version** plik i ustaw wartość na `5.5.7`. **Stary docker-compose.yml:** Zaktualizuj wersję `sharelatex` usługi do `5.5.7`. {% endstep %} {% step %} #### Oszacuj liczbę dotkniętych projektów {% code overflow="wrap" %} ```bash # Użytkownicy 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żytkownicy starego 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 %} Przykładowy wynik: {% code fullWidth="false" %} ``` Aktualny status: - Łączna liczba projektów: 10 - Łączna liczba usuniętych projektów: 5 Próbkowanie 1000 projektów w celu oszacowania postępów... Statystyki próbki dla projektów: - Projekty w próbce: 9 (90% wszystkich projektów) - Projekty w próbce, w których wszystkie hasze są obecne: 5 - Procent projektów wymagających uzupełnienia haszy: 44% (szacunkowo) - Projekty w próbce mają 11 plików, które trzeba sprawdzić w pełnym systemie historii projektu. - Projekty w próbce mają 3 pliki, które trzeba przesłać do pełnego systemu historii projektu (szacując 27% wszystkich plików). Statystyki próbki dla usuniętych projektów: - Usunięte projekty w próbce: 4 (80% wszystkich usuniętych projektów) - Usunięte projekty w próbce, w których wszystkie hasze są obecne: 3 - Procent usuniętych projektów wymagających uzupełnienia haszy: 25% (szacunkowo) - Usunięte projekty w próbce mają 2 pliki, które trzeba sprawdzić w pełnym systemie historii projektu. - Usunięte projekty w próbce mają 1 plik, który trzeba przesłać do pełnego systemu historii projektu (szacując 50% wszystkich plików). ``` {% endcode %} {% endstep %} {% step %} #### Opróżnij kolejki historii projektu {% code overflow="wrap" %} ```bash # Użytkownicy Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Użytkownicy starego docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Powtarzaj opróżnianie, aż wszystkie projekty zostaną opróżnione (`"project_ids":0`). ``` znalezione projekty {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} łącznie {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Jeśli "failedProjects" nie jest równe zero, skontaktuj się z pomocą techniczną i nie kontynuuj migracji plików binarnych. {% endhint %} {% endstep %} {% step %} #### Przejdź do fazy migracji 1 Toolkit: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` w `config/variables.env`. Stary docker-compose.yml: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` w `środowiska` sekcji `sharelatex` usługi. {% endstep %} {% step %} #### Zastosuj zmianę konfiguracji i uruchom instancję Toolkit: `bin/up -d` Stary docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Sprawdź dostęp do plików binarnych Otwórz projekt w edytorze Overleaf w przeglądarce i wybierz plik binarny, na przykład obraz. {% endstep %} {% step %} #### Uruchom skrypt migracji {% code overflow="wrap" %} ```bash # Użytkownicy 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żytkownicy starego 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" %} Jeśli [trwale przechowujesz logi](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) pliki poza **sharelatex** kontenerem, upewnij się, że właściciel katalogu logs jest ustawiony na `www-data` użytkownika (uid=33), aby wygenerowany plik dziennika mógł zostać zapisany. {% endhint %} Wynik powinien wyglądać tak: ```bash Ustaw UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Ładowanie backendu","time":"2025-07-25T15:00:58.166Z","v":0} Zapisywanie logów do /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Rozpoczynanie kopii zapasowej plików projektu... Załadowane globalne bloby: 0 Przetwarzanie nieusuniętych projektów... Przetworzono 1 projekt, upłynęło 0 s Zakończono aktualizację aktywnych projektów Przetwarzanie usuniętych projektów... Wygląda na to, że kolekcja deletedProjects jest pusta. Zakończono aktualizację usuniętych projektów Gotowe. ``` Jeśli migracja zakończy się powodzeniem, otrzymasz kod wyjścia `0`, a ostatnie wiersze będą wskazywać brak niepowodzeń: ```bash Gotowe. ``` Plik dziennika będzie wyglądał tak (użyj ścieżki wydrukowanej przez skrypt): {% 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":"partia faktycznie ukończona","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":"statystyki migracji plików","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Zatrzymaj instancję Toolkit: `bin/stop sharelatex` Stary docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Spraw, by stare pliki były niedostępne dla aplikacji Możesz teraz przenieść stare pliki do magazynu dodatkowego. Zalecamy pozostawić te pliki przez jakiś czas na wypadek, gdyby później pojawiły się problemy. {% code overflow="wrap" %} ```bash # Użytkownicy 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 # Użytkownicy starego docker-compose.yml: # Zakładamy, że używasz domyślnego montowania bind w /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 # Jeśli używasz selektywnych montowań bind, możesz po prostu usunąć montowanie bind dla /var/lib/overleaf/data/user_files wewnątrz kontenera. ``` {% endcode %} {% endstep %} {% step %} #### Przejdź do fazy migracji 2 Toolkit: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` w `config/variables.env`. Stary docker-compose.yml: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` w `środowiska` sekcji `sharelatex` usługi. {% endstep %} {% step %} #### Zastosuj zmianę konfiguracji i uruchom instancję Toolkit: `bin/up -d` Stary docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Sprawdź dostęp do plików binarnych Otwórz projekt w edytorze Overleaf w przeglądarce i wybierz plik binarny, na przykład obraz. {% endstep %} {% endstepper %} #### migracja offline Jeśli chcesz uniemożliwić użytkownikom logowanie się, gdy skrypt migracji plików binarnych jest uruchomiony, wykonaj następujące kroki: * Zaloguj się do swojej instancji Overleaf na konto administratora * Kliknij **Administrator** przycisk i wybierz **Zarządzaj witryną** * Kliknij **Otwórz/Zamknij edytor** kartę * Kliknij **Zamknij edytor** przycisk * Kliknij **Rozłącz wszystkich użytkowników** przycisk Po wykonaniu tego, jeśli jacykolwiek użytkownicy są zalogowani, zostaną przekierowani na stronę konserwacyjną, a wszyscy nowi użytkownicy odwiedzający stronę logowania zobaczą stronę konserwacyjną i **nie zostanie** będą mogli się zalogować. Musisz powtórzyć te kroki po ponownym uruchomieniu instancji. Aby ponownie otworzyć witrynę, po prostu uruchom instancję ponownie. #### Migracja online Możliwe jest uruchamianie skryptów migracji, gdy aplikacja nadal działa. Należy wziąć pod uwagę kilka kwestii: * Proces migracji jest intensywny pod względem I/O, powinieneś monitorować wykorzystanie zasobów podczas działania skryptu. * Przy wysokiej współbieżności przetwarzania pętla zdarzeń w `magazyn plików` usłudze może doświadczyć pewnych blokad, co prowadziłoby do gorszego doświadczenia użytkownika. Zalecamy rozpoczęcie od domyślnych wartości `--concurrency=10` i `--concurrent-batches=1` . * Możesz zatrzymać skrypt w dowolnym momencie. Uruchomienie go ponownie zweryfikuje poprzednie projekty i pominie pliki, które zostały już przetworzone. Jest to przydatne, jeśli wolisz uruchamiać migrację w mniej obciążonych godzinach (np. w nocy). Nasza rekomendacja to zamknąć witrynę i uruchomić migrację offline w oknie serwisowym, gdy liczba projektów jest mniejsza niż 1000 (zobacz wynik skryptu migracji podczas uruchamiania z `--report`). Jeśli liczba projektów jest duża, możesz uruchomić skrypt i monitorować jego postęp, a następnie zdecydować, czy kontynuować uruchamianie online czy offline, w zależności od konkretnego przypadku. #### Wyczyść stare dane plików binarnych Gdy zakończysz migrację i potwierdzisz, że projekty nadal mają dostęp do wszystkich swoich plików, możesz usunąć stare magazynowanie plików w `/var/lib/overleaf/data/user_files`. Zdecydowanie zalecamy pozostawienie tych plików przez jakiś czas — możesz najpierw uczynić je niedostępnymi dla aplikacji, zmieniając nazwę folderu. ### Rozwiązywanie problemów Dodamy tutaj wskazówki dotyczące rozwiązywania problemów. Pamiętaj, że chociaż zwykle oferujemy wsparcie tylko klientom Server Pro, ze względu na charakter tej migracji zrobimy również wszystko, co w naszej mocy, aby pomóc klientom CE, którzy napotkają problemy specyficzne dla migracji plików binarnych. Jeśli skrypt migracji plików binarnych zakończy się niepowodzeniem (tj. zakończy działanie z błędem lub wypisze niezerową liczbę nieudanych projektów), wyślij następujące szczegóły do naszego zespołu wsparcia 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), podając: Temat: Problem z migracją plików binarnych Treść: * Typ instancji: CE lub Server Pro (usuń odpowiednio) * Typ instalacji: Overleaf Toolkit lub `docker-compose.yml` lub inne (usuń odpowiednio) * Wersja: 5.5.x (toolkit: `$ cat config/version`) * Wynik skryptu migracji (który powinien znajdować się w kontenerze w `/var/log/overleaf`) * Raport: (uruchom skrypt migracji z `--report`) * Przetworzone projekty: (zgodnie z ostatnim uruchomieniem skryptu) * Czas trwania migracji: * `bin/doctor` wynik (podczas korzystania z toolkit) * Wersja toolkit: `$ git rev-parse HEAD` (podczas korzystania z Toolkit) Rozważ dołączenie plików dziennika dla usług `magazyn plików` usługi do wiadomości e-mail. Możesz go znaleźć pod `/var/log/overleaf/filestore.log` wewnątrz `sharelatex` kontenera i wyeksportować je w ten sposób: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # zastąp znacznikiem czasu wydrukowanym przez skrypt $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Proszę zredagować wszelkie poufne informacje z plików dziennika przed ich dołączeniem. #### Brakujące pliki Starsze wersje Server Pro/CE tworzyły wpisy w drzewie plików przed zakończeniem przesyłania przez użytkownika, co mogło powodować, że pliki wyglądały na brakujące, gdy przesyłanie kończyło się niepowodzeniem. Możesz znaleźć kilka takich przypadków zgłoszonych jako błędy podczas przetwarzania wszystkich drzew plików. Jeśli liczba brakujących plików jest mała, rozważ ręczne przejrzenie tych przypadków i usunięcie ich z edytora w przeglądarce. Jeśli liczba brakujących plików jest duża, rozważ skontaktowanie się z pomocą techniczną; zobacz szablon wiadomości e-mail powyżej. #### Znajdowanie uszkodzonych drzew plików Migracja może zakończyć się niepowodzeniem dla projektów, które mają nieprawidłowo utworzone drzewo plików (na przykład gdy nazwy plików są puste). Listę tych problemów można znaleźć za pomocą skryptu `find_malformed_filetrees` który sprawdza wszystkie projekty w bazie danych: {% 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 %} Aby naprawić nieprawidłowe ścieżki, użyj skryptu `fix_malformed_filetree` uruchamiając polecenie raz dla każdej złej ścieżki: {% 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/pl/wsparcie/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.