(Migracja v3.5.13) Migracja pełnej historii projektów

​

Migracja pełnej historii projektów

Wydanie 3.5.x Community Edition zawiera funkcję pełnej historii projektów, dostępną już w naszej ofercie SaaS, overleaf.com

Po aktualizacji instancji do Overleaf CE 3.5.13 wszystkie nowe projekty będą domyślnie korzystać z pełnej historii projektów (Full Project History). Istniejące projekty będą nadal korzystać ze starszego systemu historii, dopóki nie zostaną zmigrowane.

Jeśli dokonasz aktualizacji do 3.5.13, a następnie zdecydujesz się wrócić do wcześniejszej wersji, przywróć system z pełnej kopii zapasowej. Historia projektów utworzonych w 3.5.13 nie jest zgodna z wcześniejszymi wersjami Overleaf CE.

Nowa pełna historia projektów wprowadza dla użytkowników kilka usprawnień:

• Śledzi zmiany w plikach binarnych, czego starszy system nie obsługuje.
• Obsługuje wersje z etykietami.
• System jest ogólnie bardziej niezawodny, a ryzyko utraty danych jest mniejsze.

Więcej informacji o pełnej historii projektów znajdziesz w dokumentacji Full Project History.

​

Migracja istniejących projektów

1. Utwórz kopię zapasową

   Utwórz pełną kopię zapasową instancji ze spójnym zrzutem katalogów mongo, redis i sharelatex.

2. Zaktualizuj

   Zaktualizuj wersję obrazu sharelatex/sharelatex do 3.5.13.

   Toolkit: użyj skryptu $ bin/upgrade, aby zaktualizować Toolkit do najnowszej wersji, i zmień zawartość config/version na 3.5.13.

3. Uruchom instancję

   Najlepiej uniemożliwić użytkownikom dostęp do instancji podczas migracji, aby uniknąć utraty danych w razie konieczności przywrócenia kopii zapasowej. Więcej informacji o tym, jak to zrobić, znajdziesz w sekcji Migracja offline.

4. Poczekaj, aż wszystkie usługi zostaną uruchomione

   Poczekaj, aż wszystkie usługi zostaną uruchomione i będą działać (patrz polecenie poniżej)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Uruchom skrypt migracji

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   
   # legacy docker-compose.yml users:
   $ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
   

   --force-clean czyści częściowo zmigrowane dane historii projektów w nowym systemie, co pozwala ponowić migrację poszczególnych projektów, które nie powiodły się we wcześniejszych próbach;

   --fix-invalid-characters zastępuje znaki niedrukowalne, które nie są obsługiwane przez nowy system historii;

   --convert-large-docs-to-file konwertuje dokumenty przekraczające próg rozmiaru edytowalnego wynoszący 2MB na nieedytowalne pliki)

   Wynik powinien wyglądać tak:

   Migrated Projects  :  1
   Total Projects     :  51
   Remaining Projects :  51
   Total history records to migrate: 98
   Starting migration...
   Migrating project: 63d29b5772dd80015a81bffe
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   Migrating project: 63d29c2e72dd80015a81c0a2
   migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
   
   // …
   
   Migration complete
   ==================
   Projects migrated:  51
   Projects failed:  0
   Done.
   

   Jeśli migracja zakończy się powodzeniem, otrzymasz kod wyjścia 0, a ostatnie wiersze będą wskazywać brak błędów:

   Projects failed:  0
   Done.
   

   Możesz ponownie udostępnić instancję użytkownikom (patrz następny krok). Jeśli wystąpiły błędy, zapoznaj się z sekcją rozwiązywania problemów poniżej. Nadal możesz ponownie otworzyć witrynę, jeśli problemów nie da się od razu naprawić — niezmigrowane projekty pozostaną w starszym systemie historii.

6. Ponownie otwórz witrynę

   Jeśli wybrano migrację offline, musisz ponownie otworzyć witrynę. Jeśli nadal jesteś zalogowany, musisz:

   1. Kliknąć przycisk Admin i wybrać Manage Site
   2. Kliknąć kartę Open/Close Editor
   3. Kliknąć przycisk Reopen Editor

   Jeśli zamknięto przeglądarkę, musisz ponownie uruchomić witrynę za pomocą $ bin/up.

​

Migracja offline

Aby uniemożliwić użytkownikom logowanie podczas działania skryptu migracji historii, wykonaj następujące kroki:

• Zaloguj się do instancji Overleaf na konto administratora
• Kliknij przycisk Admin i wybierz Manage Site
• Kliknij kartę Open/Close Editor
• Kliknij przycisk Close Editor
• Kliknij przycisk Disconnect all users

Po wykonaniu tych czynności zalogowani użytkownicy zostaną przekierowani na stronę konserwacji, a nowi użytkownicy odwiedzający stronę logowania zobaczą stronę konserwacji i nie będą mogli się zalogować.

​

Migracja online

Skrypty migracji można uruchamiać, gdy aplikacja nadal działa. Należy jednak wziąć pod uwagę kilka kwestii:

• Proces migracji mocno obciąża procesor, dlatego podczas działania skryptu monitoruj wykorzystanie zasobów.
• Przy wysokiej wartości --concurrency pętla zdarzeń w niektórych usługach (w szczególności track-changes) może być blokowana, co pogorszy wrażenia użytkowników. Zalecamy rozpoczęcie od domyślnej wartości --concurrency=1.
• Skrypt można zatrzymać w dowolnym momencie. Po ponownym uruchomieniu migracja zostanie wznowiona od miejsca, w którym została przerwana. Przydaje się to, jeśli wolisz przeprowadzać migrację w godzinach mniejszego obciążenia (np. w nocy).

Zalecamy zamknięcie witryny i przeprowadzenie migracji offline w oknie serwisowym, jeśli liczba projektów jest mniejsza niż 1000 (db.projects.count()). Jeśli projektów jest dużo, możesz uruchomić skrypt, monitorować jego postęp, a następnie zdecydować, czy kontynuować migrację online, czy offline, w zależności od konkretnej sytuacji.

​

Czyszczenie danych starszej historii

Skrypt do czyszczenia danych starszej historii dodano w Server Pro 3.5.6, 4.0.6 i 4.1.0.

bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"

Skrypt można uruchomić po zmigrowaniu wszystkich projektów. Można go też użyć do zwolnienia miejsca podczas migracji online.

W Server Pro przed wersją 3.5.13 skrypt usuwa zawartość kolekcji docHistory i docHistoryIndex. MongoDB nie zwalnia miejsca na dysku po usunięciu dokumentów, lecz wykorzystuje je ponownie dla przyszłych dokumentów w tej samej kolekcji. Po migracji historii nic już nie będzie zapisywać do tych kolekcji, więc to miejsce na dysku pozostanie niewykorzystane.

Jeśli chcesz ponownie udostępnić to miejsce na dysku, możesz zaktualizować system do Server Pro 3.5.13 (jeśli nadal używasz wydania 3.x) lub Server Pro 4.2.5 (jeśli używasz wydania 4.x) i ponownie uruchomić skrypt czyszczący.

Skrypt czyszczący dołączony do najnowszych wydań poprawkowych 3.5.x i najnowszego 4.x.x Server Pro usuwa kolekcje w ostatnim kroku.

Ponowne uruchomienie skryptu czyszczącego jest bezpieczne.

​

Rozwiązywanie problemów

Będziemy tu dodawać porady dotyczące rozwiązywania problemów. Pamiętaj, że choć zwykle oferujemy wsparcie wyłącznie klientom Server Pro, ze względu na charakter tej migracji dołożymy też wszelkich starań, aby pomóc klientom CE, którzy napotkają problemy związane z migracją pełnej historii projektów.

Jeśli skrypt migracji pełnej historii projektów zakończy się niepowodzeniem (tj. zakończy działanie z błędem lub wypisze niezerową liczbę projektów z błędami), wyślij następujące szczegóły do naszego zespołu wsparcia na adres e-mail [e-mail], podając:

Temat: Full project history migration problem

• Typ instancji: CE lub Server Pro (usuń niepotrzebne)
• Typ instalacji: Overleaf toolkit, docker-compose.yml lub inny (usuń niepotrzebne)
• Wersja: 3.5.x (toolkit: $ cat config/version)
• Wynik skryptu migracji (który powinien znajdować się w kontenerze w katalogu /overleaf/services/web)
• Zmigrowane projekty: (według wyniku skryptu migracji)
• Łączna liczba projektów: (według wyniku skryptu migracji)
• Pozostałe projekty: (według wyniku skryptu migracji)
• Czas trwania migracji:
• Wynik bin/doctor (w przypadku korzystania z Toolkitu)
• Wersja Toolkitu: $ git rev-parse HEAD (w przypadku korzystania z Toolkitu)

Rozważ dołączenie do wiadomości plików dziennika usług history-v1, project-history i track-changes. Znajdziesz je w katalogu /var/log/sharelatex wewnątrz kontenera sharelatex i możesz je wyeksportować w następujący sposób:

$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log

Przed dołączeniem plików dziennika usuń z nich wszelkie poufne informacje.

​

Wyszukiwanie uszkodzonych drzew plików

Migracja może się nie powieść w przypadku projektów z nieprawidłowym drzewem plików (na przykład z pustymi nazwami plików). Listę takich problemów możesz uzyskać za pomocą skryptu find_malformed_filetrees, który sprawdza wszystkie projekty w bazie danych:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...

Aby naprawić nieprawidłowe ścieżki, użyj skryptu fix_malformed_filetree, uruchamiając polecenie raz dla każdej błędnej ścieżki:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...

​

Przywracanie projektów z pełnej historii projektów do starszej historii

Jeśli projekt został zmigrowany do pełnej historii projektów, ale chcesz wrócić do starszej historii, użyj skryptu downgrade_project w następujący sposób:

$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR