> 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/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 wersja główna `6.0` wydanie Server Pro i Community Edition zmniejszy o połowę wykorzystanie przestrzeni na pliki binarne. Migracja online jest zawarta w wersji `5.5.7` , co pozwala na minimalny przestój w ramach aktualizacji. Od wersji Server Pro `4.x`, pliki binarne są przechowywane podwójnie: w aktywnym magazynie plików w "filestore" oraz w pełnym systemie historii projektu. Od teraz pojedyncza kopia każdego pliku będzie przechowywana w pełnym systemie historii projektu. Migracja do ujednoliconego systemu przechowywania składa się z dwóch części: nowej flagi do sterowania fazą migracji oraz skryptu, który przetwarza wszystkie aktywne i miękko usunięte projekty. Fazy: * `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. Obniżenie do `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` jest możliwe. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` pliki są odczytywane i zapisywane wyłącznie do historii. Obniżenie do `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` nie jest możliwe, chyba że zostało wykonane "offline". Podczas przechowywania danych w [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) i używając oddzielnych kont usługowych dla filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) i historii (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Proszę przyznać użytkownikowi filestore dostęp do odczytu do bucketu historii dla blobów `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Usługa filestore będzie od teraz obsługiwać odczyty z usługi kompilatora. {% hint style="warning" %} Zdecydowanie zaleca się najpierw przeprowadzić migrację plików binarnych w środowisku nieprodukcyjnym/sandboxowym. {% endhint %} {% hint style="success" %} Standardowa licencja Server Pro pozwala uruchamiać aplikację w środowisku produkcyjnym oraz jednym w środowisku nieprodukcyjnym/sandboxowym; zdecydowanie zalecamy przygotowanie środowiska nieprodukcyjnego do testów. {% endhint %} {% hint style="info" %} Jeśli uaktualnisz do wersji Server Pro/CE `6.0` a później zdecydujesz, że chcesz cofnąć się do wcześniejszej wersji, powinieneś przywrócić z pełnej kopii zapasowej 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) instancji z spójnym zrzutem **mongo**, **redis** i **sharelatex** katalogów. {% endstep %} {% step %} #### Zaktualizuj **Zestaw narzędzi:** Użyj `$ bin/upgrade` skrypt do uaktualnienia **zestawu narzędzi** do najnowszej wersji. Gdy zostaniesz o to poproszony, nie **nie** potwierdzaj monitu **Aktualizacja** obraz? — zamiast tego ręcznie edytuj **config/version** plik i ustaw wartość na `5.5.7`. **Starszy docker-compose.yml:** Zaktualizuj wersję `sharelatex` usługę na `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 starszego 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" %} ``` Bieżący status: - Łączna liczba projektów: 10 - Łączna liczba usuniętych projektów: 5 Próbkowanie 1000 projektów w celu oszacowania postępu... Statystyki próbki dla projektów: - Projekty w próbce: 9 (90% wszystkich projektów) - Projekty w próbce ze wszystkimi obecnymi hashami: 5 - Procent projektów wymagających uzupełnienia hashy: 44% (szacunkowo) - Projekty w próbce mają 11 plików, które trzeba sprawdzić względem pełnego systemu 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 ze wszystkimi obecnymi hashami: 3 - Procent usuniętych projektów wymagających uzupełnienia hashy: 25% (szacunkowo) - Usunięte projekty w próbce mają 2 pliki, które trzeba sprawdzić względem pełnego systemu 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 starszego 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" %} W przypadku gdy "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 Zestaw narzędzi: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` w `config/variables.env`. Starszy docker-compose.yml: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` w `środowiska` sekcję `sharelatex` usługi. {% endstep %} {% step %} #### Zastosuj zmianę konfiguracji i uruchom instancję Zestaw narzędzi: `bin/up -d` Starszy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zweryfikuj dostęp do plików binarnych Otwórz projekt w edytorze Overleaf w przeglądarce i wybierz plik binarny, np. 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 starszego 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 [utrwalasz pliki dziennika](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) 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 dzienników do /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Rozpoczynanie tworzenia kopii zapasowej plików projektu... Załadowano globalne blob-y: 0 Przetwarzanie projektów nieusuniętych... Przetworzono 1 projekt, czas minął 0 s Zakończono aktualizację aktywnych projektów Przetwarzanie usuniętych projektów... Kolekcja deletedProjects wydaje się pusta. Zakończono aktualizację usuniętych projektów Gotowe. ``` Jeśli migracja zakończy się sukcesem, otrzymasz kod wyjścia `0`, a ostatnie wiersze wskażą brak niepowodzeń: ```bash Gotowe. ``` Plik dziennika będzie wyglądał tak (użyj ścieżki wyświetlonej 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 została rzeczywiście 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ę Zestaw narzędzi: `bin/stop sharelatex` Starszy docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Uczyń stare pliki niedostępnymi dla aplikacji Teraz możesz przenieść stare pliki do pamięci wtórnej. Zalecamy pozostawienie plików przez pewien czas na wypadek późniejszych problemów. {% code overflow="wrap" %} ```bash # Użytkownicy zestawu narzędzi: $ 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 starszego docker-compose.yml: # Zakładamy, że używasz domyślnego bind-mountu 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 bind-mountów, możesz po prostu usunąć bind-mount dla /var/lib/overleaf/data/user_files wewnątrz kontenera. ``` {% endcode %} {% endstep %} {% step %} #### Przejdź do fazy migracji 2 Zestaw narzędzi: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` w `config/variables.env`. Starszy docker-compose.yml: Ustaw `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` w `środowiska` sekcję `sharelatex` usługi. {% endstep %} {% step %} #### Zastosuj zmianę konfiguracji i uruchom instancję Zestaw narzędzi: `bin/up -d` Starszy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Zweryfikuj dostęp do plików binarnych Otwórz projekt w edytorze Overleaf w przeglądarce i wybierz plik binarny, np. obraz. {% endstep %} {% endstepper %} #### Migracja offline Jeśli chcesz uniemożliwić użytkownikom logowanie się podczas działania skryptu migracji plików binarnych, wykonaj następujące kroki: * Zaloguj się do swojej instancji Overleaf przy użyciu konta administratora * Kliknij **Admin** przycisk i wybierz **Zarządzaj witryną** * Kliknij **Otwórz/Zamknij edytor** karta * Kliknij **Zamknij edytor** przycisk * Kliknij **Rozłącz wszystkich użytkowników** przycisk Gdy to zostanie wykonane, jeśli jacyś użytkownicy są zalogowani, zostaną przekierowani na stronę konserwacji, a wszyscy nowi użytkownicy odwiedzający stronę logowania zobaczą stronę konserwacji i **nie będzie** będą mogli się zalogować. Musisz powtórzyć te kroki podczas ponownego uruchamiania instancji. Aby ponownie otworzyć witrynę, po prostu uruchom ponownie instancję. #### Migracja online Możliwe jest uruchomienie 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ć użycie zasobów podczas działania skryptu. * Przy wysokiej współbieżności przetwarzania pętla zdarzeń w `filestore` usługa może doświadczać pewnych blokad, co prowadziłoby do pogorszenia komfortu użytkowania. 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 uruchomić migrację w mniej ruchliwych godzinach (np. w nocy). Naszą rekomendacją jest zamknięcie witryny i uruchomienie migracji 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ć jego działanie online, czy offline, w zależności od konkretnego przypadku. #### Wyczyść starsze 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 pewien czas — możesz sprawić, by były niedostępne dla aplikacji, najpierw zmieniając nazwę folderu. ### Rozwiązywanie problemów Dodamy tutaj porady dotyczące rozwiązywania problemów. Pamiętaj, że chociaż zwykle oferujemy wsparcie tylko klientom Server Pro, ze względu na charakter tej migracji dołożymy również wszelkich starań, aby wspierać klientów 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), zawierając: Temat: Problem z migracją plików binarnych Treść: * Typ instancji: CE lub Server Pro (usuń odpowiednie) * Typ instalacji: Overleaf toolkit lub `docker-compose.yml` lub inne (usuń odpowiednie) * Wersja: 5.5.x (zestaw narzędzi: `$ cat config/version`) * Wynik skryptu migracji (który powinien znajdować się w kontenerze pod `/var/log/overleaf`) * Raport: (uruchom skrypt migracji z `--report`) * Przetworzone projekty: (zgodnie z ostatnim uruchomieniem skryptu) * Czas trwania migracji: * `bin/doctor` wynik (przy użyciu toolkit) * Wersja toolkit: `$ git rev-parse HEAD` (przy użyciu Toolkit) Rozważ dołączenie plików dziennika dla `filestore` usługi do wiadomości e-mail. Znajdziesz go pod adresem `/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 wyświetlonym przez skrypt $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Przed dołączeniem usuń z plików dziennika wszelkie poufne informacje. #### 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 się nie powiodło. Możesz napotkać kilka takich przypadków zgłoszonych jako błędy podczas przetwarzania wszystkich drzew plików. Jeśli liczba brakujących plików jest niewielka, rozważ ręczne przejrzenie tych przypadków i usunięcie ich z edytora w przeglądarce. Jeśli liczba brakujących plików jest wysoka, rozważ skontaktowanie się z pomocą techniczną, zobacz szablon e-maila powyżej. #### Znajdowanie uszkodzonych drzew plików Migracja może nie powieść się dla projektów, które mają nieprawidłowe drzewo plików (na przykład, gdy nazwy plików są puste). Listę tych problemów możesz znaleźć, używając `find_malformed_filetrees` skryptu, 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://ayakaleaf-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.