(Міграція v3.5.13) Міграція повної історії проєктів

​

Міграція повної історії проєктів

Випуск Community Edition 3.5.x містить функцію повної історії проєктів (Full Project History), яка вже доступна в нашій SaaS-пропозиції, overleaf.com

Після оновлення вашого екземпляра до Overleaf CE 3.5.13 усі нові проєкти за замовчуванням використовуватимуть Full Project History. Наявні проєкти й надалі використовуватимуть застарілу систему історії, доки їх не буде мігровано.

Якщо ви оновилися до 3.5.13 і вирішили повернутися до попередньої версії, вам слід відновити систему з повної резервної копії. Історія проєктів, створених у 3.5.13, несумісна з попередніми версіями Overleaf CE.

Нова повна історія проєктів надає користувачам кілька покращень:

• Вона відстежує зміни у двійкових файлах, що не підтримується в застарілій системі.
• Підтримуються позначені (labelled) версії.
• Система загалом надійніша, ймовірність втрати даних менша.

Докладніше про повну історію проєктів див. у документації Full Project History.

​

Міграція наявних проєктів

1. Створіть резервну копію

   Створіть повну резервну копію вашого екземпляра з узгодженим знімком каталогів mongo, redis і sharelatex.

2. Оновіть

   Оновіть версію образу sharelatex/sharelatex до 3.5.13.

   Toolkit: скористайтеся скриптом $ bin/upgrade, щоб оновити Toolkit до останньої версії, і змініть значення в config/version на 3.5.13.

3. Запустіть екземпляр

   В ідеалі слід заборонити користувачам доступ до вашого екземпляра під час міграції, щоб уникнути втрати даних у разі, якщо знадобиться відновлення з резервної копії. Докладніше про те, як це зробити, див. Офлайн-міграція.

4. Дочекайтеся запуску всіх сервісів

   Дочекайтеся, доки всі сервіси запустяться й працюватимуть (див. команду нижче)

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. Запустіть скрипт міграції

   # 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 очищує частково мігровані дані історії проєктів у новій системі, що дає змогу повторити міграцію для окремих проєктів, які не вдалося мігрувати в попередніх спробах;

   --fix-invalid-characters замінює недруковані символи, які не підтримуються новою системою історії;

   --convert-large-docs-to-file перетворює документи, розмір яких перевищує поріг редагованого розміру 2MB, на нередагований файл)

   Виведення має виглядати так:

   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.
   

   Якщо міграція пройшла успішно, ви отримаєте код виходу 0, а останні рядки вказуватимуть на відсутність невдач:

   Projects failed:  0
   Done.
   

   Ви можете знову відкрити доступ для користувачів (див. наступний крок). Якщо є невдачі, див. розділ усунення несправностей нижче. Ви можете знову відкрити сайт, навіть якщо проблеми не вдалося виправити одразу, — немігровані проєкти залишаться в застарілій системі історії.

6. Знову відкрийте сайт

   Якщо ви обрали офлайн-міграцію, вам потрібно буде знову відкрити сайт. Якщо ви все ще в системі, потрібно:

   1. Натиснути кнопку Admin і вибрати Manage Site
   2. Натиснути вкладку Open/Close Editor
   3. Натиснути кнопку Reopen Editor

   Якщо ви закрили браузер, вам потрібно буде перезапустити сайт за допомогою $ bin/up.

​

Офлайн-міграція

Щоб користувачі не могли увійти в систему під час роботи скрипту міграції історії, виконайте такі кроки:

• Увійдіть до свого екземпляра Overleaf з обліковим записом адміністратора
• Натисніть кнопку Admin і виберіть Manage Site
• Натисніть вкладку Open/Close Editor
• Натисніть кнопку Close Editor
• Натисніть кнопку Disconnect all users

Після цього всіх користувачів, які перебувають у системі, буде перенаправлено на сторінку технічного обслуговування, а нові користувачі, які відкриватимуть сторінку входу, бачитимуть сторінку технічного обслуговування й не зможуть увійти.

​

Онлайн-міграція

Скрипти міграції можна запускати, поки застосунок продовжує працювати. Слід урахувати кілька моментів:

• Процес міграції інтенсивно навантажує CPU, тому під час роботи скрипту слід стежити за використанням ресурсів.
• За високого значення --concurrency цикл подій у деяких сервісах (зокрема track-changes) може блокуватися, що погіршить роботу користувачів. Ми рекомендуємо починати з типового значення --concurrency=1.
• Скрипт можна зупинити будь-коли. Повторний запуск відновить міграцію з того місця, де її було зупинено. Це корисно, якщо ви бажаєте виконувати міграцію в менш завантажені години (наприклад, уночі).

Ми рекомендуємо закрити сайт і виконати міграцію офлайн у вікні технічного обслуговування, якщо кількість ваших проєктів менша за 1000 (db.projects.count()). Якщо проєктів багато, можна запустити скрипт і стежити за його перебігом, а потім вирішити, чи продовжувати онлайн чи офлайн, залежно від вашої ситуації.

​

Очищення даних застарілої історії

Скрипт для очищення даних застарілої історії було додано в Server Pro 3.5.6, 4.0.6 і 4.1.0.

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

Скрипт можна запускати після міграції всіх проєктів. Його також можна використовувати, щоб звільнити частину місця під час онлайн-міграції.

У Server Pro до версії 3.5.13 скрипт видаляє вміст колекцій docHistory і docHistoryIndex. MongoDB не звільняє дисковий простір після видалення документів — натомість він повторно використовує це місце для майбутніх документів у тій самій колекції. Після міграції історії в ці колекції більше нічого не записуватиметься, тож дисковий простір залишатиметься невикористаним.

Якщо ви хочете знову зробити дисковий простір доступним, можна оновитися до Server Pro 3.5.13 (якщо ви все ще використовуєте випуск 3.x) або Server Pro 4.2.5 (якщо використовуєте випуск 4.x) і повторно запустити скрипт очищення.

Скрипт очищення, включений до останніх патч-випусків Server Pro 3.5.x і останніх 4.x.x, на завершальному кроці видаляє ці колекції.

Скрипт очищення можна безпечно запускати повторно.

​

Усунення несправностей

Тут ми додаватимемо поради з усунення несправностей. Зверніть увагу: хоча зазвичай ми надаємо підтримку лише клієнтам Server Pro, з огляду на характер цієї міграції ми також намагатимемося допомогти користувачам CE, які зіткнулися з проблемами, характерними для міграції повної історії проєктів.

Якщо скрипт міграції повної історії проєктів завершується з помилкою (тобто виходить із помилкою або виводить ненульову кількість невдалих проєктів), надішліть нашій команді підтримки електронною поштою на [e-mail] такі відомості:

Тема: Full project history migration problem

• Тип екземпляра: CE або Server Pro (видаліть зайве)
• Тип встановлення: Overleaf toolkit, docker-compose.yml або інше (видаліть зайве)
• Версія: 3.5.x (toolkit: $ cat config/version)
• Виведення скрипту міграції (має розташовуватися в контейнері в /overleaf/services/web)
• Migrated Projects: (згідно з виведенням скрипту міграції)
• Total Projects: (згідно з виведенням скрипту міграції)
• Remaining Projects: (згідно з виведенням скрипту міграції)
• Тривалість міграції:
• Виведення bin/doctor (якщо використовується toolkit)
• Версія Toolkit: $ git rev-parse HEAD (якщо використовується Toolkit)

Бажано також долучити до листа файли журналів сервісів history-v1, project-history і track-changes. Їх можна знайти в /var/log/sharelatex усередині контейнера sharelatex та експортувати так:

$ 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

Перед долученням файлів журналів видаліть із них будь-яку конфіденційну інформацію.

​

Пошук пошкоджених дерев файлів

Міграція може завершитися невдало для проєктів із некоректним деревом файлів (наприклад, де назви файлів порожні). Список таких проблем можна отримати за допомогою скрипту find_malformed_filetrees, який перевіряє всі проєкти в базі даних:

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

Щоб виправити некоректні шляхи, скористайтеся скриптом fix_malformed_filetree, запускаючи команду один раз для кожного некоректного шляху:

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

​

Повернення проєктів із повної історії проєктів до застарілої історії

Якщо проєкт було мігровано до повної історії проєктів, але ви хочете повернутися до застарілої історії, скористайтеся скриптом downgrade_project так:

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