(Миграция v3.5.13) Миграция полной истории проектов

​

Миграция полной истории проектов

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

После обновления вашего экземпляра до Overleaf CE 3.5.13 все новые проекты по умолчанию будут использовать полную историю проектов. Существующие проекты продолжат использовать устаревшую систему истории, пока не будут перенесены.

Если вы обновитесь до 3.5.13 и решите вернуться к более ранней версии, необходимо восстановить систему из полной резервной копии. История проектов, созданных в 3.5.13, несовместима с более ранними версиями Overleaf CE.

Новая полная история проектов приносит пользователям ряд улучшений:

• Она отслеживает изменения в двоичных файлах, что не поддерживается в устаревшей системе.
• Поддерживаются версии с метками.
• Система в целом надёжнее, вероятность потери данных ниже.

Подробнее о полной истории проектов см. в документации по полной истории проектов.

​

Миграция существующих проектов

1. Создайте резервную копию

   Создайте полную резервную копию вашего экземпляра с согласованным снимком каталогов mongo, redis и sharelatex.

2. Обновите версию

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

   Toolkit: используйте скрипт $ bin/upgrade, чтобы обновить toolkit до последней версии, и укажите 3.5.13 в config/version.

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 преобразует документы, размер которых превышает порог редактируемости в 2 МБ, в нередактируемые файлы)

   Вывод должен выглядеть так:

   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