(Migrace v3.5.13) Migrace na úplnou historii projektů

​

Migrace na úplnou historii projektů

Vydání 3.5.x Community Edition obsahuje funkci úplné historie projektů (Full Project History), která je již k dispozici v naší nabídce SaaS, overleaf.com

Po aktualizaci vaší instance na Overleaf CE 3.5.13 budou všechny nové projekty ve výchozím nastavení používat úplnou historii projektů. Stávající projekty budou nadále používat starší systém historie, dokud nebudou migrovány.

Pokud provedete upgrade na 3.5.13 a rozhodnete se přejít zpět na starší verzi, měli byste obnovit data z úplné zálohy systému. Historie projektů vytvořených ve verzi 3.5.13 není kompatibilní se staršími verzemi Overleaf CE.

Nová úplná historie projektů přináší uživatelům několik vylepšení:

• Sleduje změny v binárních souborech, což starší systém nepodporuje.
• Podporuje pojmenované (označené) verze.
• Systém je obecně robustnější a riziko ztráty dat je menší.

Další informace o úplné historii projektů najdete v dokumentaci k úplné historii projektů.

​

Migrace stávajících projektů

1. Vytvořte zálohu

   Vytvořte úplnou zálohu své instance s konzistentním snímkem adresářů mongo, redis a sharelatex.

2. Aktualizujte

   Aktualizujte verzi obrazu sharelatex/sharelatex na 3.5.13.

   Toolkit: Pomocí skriptu $ bin/upgrade aktualizujte toolkit na nejnovější verzi a upravte config/version na 3.5.13.

3. Spusťte instanci

   V ideálním případě byste měli během migrace zabránit uživatelům v přístupu k instanci, abyste předešli ztrátě dat v případě, že budete muset obnovit zálohu. Více informací o tom, jak to provést, najdete v části Offline migrace.

4. Počkejte, až budou všechny služby spuštěny

   Počkejte, až budou všechny služby spuštěny a v provozu (viz příkaz níže)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Spusťte migrační skript

   # 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 vymaže částečně migrovaná data historie projektů v novém systému, což umožňuje opakovat migraci u jednotlivých projektů, u kterých předchozí pokusy selhaly;

   --fix-invalid-characters nahradí netisknutelné znaky, které nový systém historie nepodporuje;

   --convert-large-docs-to-file převede dokumenty, které překračují limit 2 MB pro upravitelnou velikost, na neupravitelné soubory)

   Výstup by měl vypadat takto:

   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.
   

   Pokud je migrace úspěšná, obdržíte návratový kód 0 a poslední řádky budou uvádět, že nedošlo k žádným selháním:

   Projects failed:  0
   Done.
   

   Poté můžete uživatelům znovu zpřístupnit instanci (viz další krok). Pokud došlo k selháním, podívejte se do části o řešení problémů níže. Web můžete znovu otevřít, i když se problémy nepodaří ihned vyřešit; nemigrované projekty zůstanou ve starším systému historie.

6. Znovu otevřete web

   Pokud jste se rozhodli provést offline migraci, budete muset web znovu otevřít. Pokud jste stále přihlášeni, postupujte takto:

   1. Klikněte na tlačítko Admin a zvolte Manage Site
   2. Klikněte na kartu Open/Close Editor
   3. Klikněte na tlačítko Reopen Editor

   Pokud jste zavřeli prohlížeč, budete muset web restartovat pomocí $ bin/up.

​

Offline migrace

Chcete-li zabránit uživatelům v přihlášení během běhu skriptu pro migraci historie, postupujte takto:

• Přihlaste se do své instance Overleaf administrátorským účtem
• Klikněte na tlačítko Admin a zvolte Manage Site
• Klikněte na kartu Open/Close Editor
• Klikněte na tlačítko Close Editor
• Klikněte na tlačítko Disconnect all users

Jakmile to provedete, všichni přihlášení uživatelé budou přesměrováni na stránku údržby a všichni noví uživatelé, kteří navštíví přihlašovací stránku, uvidí stránku údržby a nebudou se moci přihlásit.

​

Online migrace

Migrační skripty je možné spustit i za běhu aplikace. Je však třeba vzít v úvahu několik věcí:

• Proces migrace je náročný na CPU, proto byste měli během běhu skriptu sledovat využití prostředků.
• Při vysoké hodnotě --concurrency může u některých služeb (zejména track-changes) docházet k blokování smyčky událostí, což by vedlo ke zhoršení uživatelského zážitku. Doporučujeme začít s výchozí hodnotou --concurrency=1.
• Skript můžete kdykoli zastavit. Po opětovném spuštění bude migrace pokračovat tam, kde jste skončili. To se hodí, pokud dáváte přednost spouštění migrace v méně vytížených hodinách (např. v noci).

Doporučujeme uzavřít web a spustit migraci offline v rámci okna údržby, pokud máte méně než 1000 projektů (db.projects.count()). Pokud je projektů hodně, můžete skript spustit a sledovat jeho průběh a poté se podle své konkrétní situace rozhodnout, zda v něm budete pokračovat online, nebo offline.

​

Vyčištění dat starší historie

Skript pro vyčištění dat starší historie byl přidán ve verzích Server Pro 3.5.6, 4.0.6 a 4.1.0.

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

Skript lze spustit poté, co byly migrovány všechny projekty. Lze jej také použít k uvolnění místa během online migrace.

V Server Pro starším než verze 3.5.13 skript maže obsah kolekcí docHistory a docHistoryIndex. MongoDB po smazání dokumentů neuvolňuje místo na disku; místo toho jej znovu použije pro budoucí dokumenty ve stejné kolekci. Po migraci historie už do těchto kolekcí nic zapisovat nebude, takže místo na disku zůstane nevyužité.

Pokud chcete místo na disku znovu zpřístupnit, můžete provést upgrade na Server Pro 3.5.13 (pokud stále používáte řadu 3.x) nebo Server Pro 4.2.5 (pokud používáte řadu 4.x) a skript pro vyčištění spustit znovu.

Skript pro vyčištění obsažený v nejnovějších opravných vydáních Server Pro řady 3.5.x a v nejnovější verzi 4.x.x jako poslední krok kolekce odstraňuje.

Skript pro vyčištění je bezpečné spustit opakovaně.

​

Řešení problémů

Sem budeme přidávat rady k řešení problémů. Upozorňujeme, že ačkoli běžně poskytujeme podporu pouze zákazníkům Server Pro, vzhledem k povaze této migrace se budeme snažit pomoci i zákazníkům CE, kteří narazí na problémy specifické pro migraci na úplnou historii projektů.

Pokud skript pro migraci na úplnou historii projektů selže (tj. skončí s chybou nebo vypíše nenulový počet neúspěšných projektů), pošlete prosím našemu týmu podpory e-mailem na [e-mail] následující podrobnosti:

Předmět: Full project history migration problem

• Typ instance: CE nebo Server Pro (nehodící se škrtněte)
• Typ instalace: Overleaf toolkit, docker-compose.yml nebo jiný (nehodící se škrtněte)
• Verze: 3.5.x (toolkit: $ cat config/version)
• Výstup migračního skriptu (měl by se nacházet v kontejneru pod /overleaf/services/web)
• Migrated Projects: (podle výstupu migračního skriptu)
• Total Projects: (podle výstupu migračního skriptu)
• Remaining Projects: (podle výstupu migračního skriptu)
• Doba trvání migrace:
• Výstup bin/doctor (při použití toolkitu)
• Verze Toolkitu: $ git rev-parse HEAD (při použití Toolkitu)

Zvažte přiložení souborů protokolů služeb history-v1, project-history a track-changes k e-mailu. Najdete je ve složce /var/log/sharelatex uvnitř kontejneru sharelatex a můžete je exportovat takto:

$ 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

Před přiložením souborů protokolů z nich prosím odstraňte veškeré citlivé informace.

​

Hledání poškozených stromů souborů

Migrace může selhat u projektů s chybně vytvořeným stromem souborů (například tam, kde jsou názvy souborů prázdné). Seznam těchto problémů zjistíte pomocí skriptu find_malformed_filetrees, který zkontroluje všechny projekty v databázi:

$ 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
...

Neplatné cesty opravíte pomocí skriptu fix_malformed_filetree, přičemž příkaz spustíte jednou pro každou chybnou cestu:

$ 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"
...

​

Převod projektů z úplné historie projektů zpět na starší historii

Pokud byl některý projekt migrován na úplnou historii projektů, ale chcete se vrátit ke starší historii, použijte skript downgrade_project následovně:

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