> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

Випуск Community Edition `3.5.x` містить [функцію повної історії проєктів (Full Project History)](https://www.overleaf.com/learn/latex/Using_the_History_feature), яка вже доступна в нашій SaaS-пропозиції, [overleaf.com](http://overleaf.com/)

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

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

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

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

Докладніше про повну історію проєктів див. у [документації Full Project History](https://www.overleaf.com/learn/latex/Using_the_History_feature).

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

<Steps>
  <Step title="Створіть резервну копію">
    Створіть повну [резервну копію](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) вашого екземпляра з узгодженим знімком каталогів **mongo**, **redis** і **sharelatex**.
  </Step>

  <Step title="Оновіть">
    Оновіть версію образу sharelatex/sharelatex до 3.5.13.

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

  <Step title="Запустіть екземпляр">
    В ідеалі слід заборонити користувачам доступ до вашого екземпляра під час міграції, щоб уникнути втрати даних у разі, якщо знадобиться відновлення з резервної копії. Докладніше про те, як це зробити, див. [Офлайн-міграція](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration).
  </Step>

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

    ```bash wrap theme={null}
    $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
    web sharelatex is alive (api)%
    ```
  </Step>

  <Step title="Запустіть скрипт міграції">
    ```bash wrap theme={null}
    # 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, на нередагований файл)

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

    ```bash theme={null}
    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`, а останні рядки вказуватимуть на відсутність невдач:

    ```bash theme={null}
    Projects failed:  0
    Done.
    ```

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

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

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

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

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

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

* Увійдіть до свого екземпляра 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`.

```bash wrap theme={null}
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```

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

<Info>
  У 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`, на завершальному кроці видаляє ці колекції.

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

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

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

Якщо скрипт міграції повної історії проєктів завершується з помилкою (тобто виходить із помилкою або виводить ненульову кількість невдалих проєктів), надішліть нашій команді підтримки електронною поштою на [support+historymigration@overleaf.com](mailto:support+historymigration@overleaf.com?subject=Full%20project%20history%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) такі відомості:

Тема: 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` та експортувати так:

```bash theme={null}
$ 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`, який перевіряє всі проєкти в базі даних:

```bash wrap theme={null}
$ 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`, запускаючи команду один раз для кожного некоректного шляху:

```bash wrap theme={null}
$ 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` так:

```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.