> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/uk/pidtrimka/support-guides/v5.5.7-migration-binary-files-migration.md). # (Міграція v5.5.7) Міграція двійкових файлів ## Міграція бінарних файлів Майбутня мажорна версія `6.0` випуск Server Pro та Community Edition зменшить використання сховища бінарних файлів удвічі. Онлайн-міграцію включено у версію `5.5.7` , що забезпечує мінімальний час простою під час оновлення. Оскільки Server Pro `4.x`, бінарні файли зберігаються двічі: в активному файловому сховищі в "filestore" і в системі повної історії проєкту. Надалі в системі повної історії проєкту зберігатиметься одна копія кожного файлу. Міграція до консолідованої системи зберігання складається з двох частин: новий прапорець для керування етапом міграції та сценарій, що обробляє всі активні та позначені як видалені проєкти. Етапи: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (за замовчуванням), файли читаються і записуються до filestore. Файли записуються до історії асинхронно. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , файли читаються з історії з поверненням до filestore і записуються і до filestore, і до історії. Пониження до `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` можливе. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` файли читаються і записуються лише до історії. Пониження до `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` неможливе, якщо тільки це не було виконано "офлайн". Під час зберігання даних у [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) та використання окремих службових облікових записів для filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) і history (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): будь ласка, надайте користувачу filestore доступ на читання до бакета історії для blob-об'єктів `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Служба filestore надалі обслуговуватиме читання від служби компілятора. {% hint style="warning" %} Дуже рекомендується спочатку виконати міграцію бінарних файлів у небойовому/пісочному середовищі. {% endhint %} {% hint style="success" %} Стандартна ліцензія Server Pro дозволяє запускати застосунок у робочому середовищі, а також в одному небойовому/пісочному середовищі; дуже рекомендується підготувати небойове середовище для тестування. {% endhint %} {% hint style="info" %} Якщо ви оновитеся до версії Server Pro/CE `6.0` а потім вирішите повернутися до попередньої версії, слід відновитися з повної резервної копії системи. {% endhint %} ### Процедура міграції {% stepper %} {% step %} #### Створіть резервну копію Створіть повну [резервну копію](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) вашого екземпляра з узгодженим знімком **mongo**, **redis** та **контейнера sharelatex** каталогів. {% endstep %} {% step %} #### Оновіть **Toolkit:** Використайте `$ bin/upgrade` сценарій для оновлення **toolkit** до найновішої версії. Коли буде запропоновано, не **не** підтверджуйте запит **Оновлення** образ? — натомість вручну відредагуйте **config/version** файл і встановіть значення `5.5.7`. **Старий docker-compose.yml:** Оновіть версію `контейнера sharelatex` службу до `5.5.7`. {% endstep %} {% step %} #### Оцініть кількість проєктів, яких це стосується {% code overflow="wrap" %} ```bash # Користувачі Overleaf Toolkit: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" # Для користувачів старого docker-compose.yml: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --report" ``` {% endcode %} Приклад виводу: {% code fullWidth="false" %} ``` Поточний стан: - Загальна кількість проєктів: 10 - Загальна кількість видалених проєктів: 5 Вибірка 1000 проєктів для оцінки прогресу... Статистика вибраних проєктів: - Вибрані проєкти: 9 (90% усіх проєктів) - Вибрані проєкти, у яких наявні всі хеші: 5 - Відсоток проєктів, яким потрібно додати хеші заднім числом: 44% (оцінка) - У вибраних проєктах є 11 файлів, які потрібно перевірити у системі повної історії проєкту. - У вибраних проєктах є 3 файли, які потрібно завантажити до системи повної історії проєкту (оцінка 27% усіх файлів). Статистика вибраних видалених проєктів: - Вибрані видалені проєкти: 4 (80% усіх видалених проєктів) - Вибрані видалені проєкти, у яких наявні всі хеші: 3 - Відсоток видалених проєктів, яким потрібно додати хеші заднім числом: 25% (оцінка) - У вибраних видалених проєктах є 2 файли, які потрібно перевірити у системі повної історії проєкту. - У вибраних видалених проєктах є 1 файл, який потрібно завантажити до системи повної історії проєкту (оцінка 50% усіх файлів). ``` {% endcode %} {% endstep %} {% step %} #### Очистити черги історії проєкту {% code overflow="wrap" %} ```bash # Користувачі Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Для користувачів старого docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Повторюйте очищення, доки всі проєкти не будуть очищені (`"project_ids":0`). ``` знайдені проєкти {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} загалом {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Якщо "failedProjects" не дорівнює нулю, зверніться до служби підтримки та не продовжуйте міграцію бінарних файлів. {% endhint %} {% endstep %} {% step %} #### Переведіть етап міграції на 1 Toolkit: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` у `config/variables.env`. Старий docker-compose.yml: встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` у `середовища` розділ у `контейнера sharelatex` службу. {% endstep %} {% step %} #### Застосуйте зміну конфігурації та запустіть інстанс Toolkit: `bin/up -d` Старий docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Перевірте доступ до бінарних файлів Відкрийте проєкт у редакторі Overleaf у браузері та виберіть бінарний файл, наприклад зображення. {% endstep %} {% step %} #### Запустіть скрипт міграції {% code overflow="wrap" %} ```bash # Користувачі Overleaf Toolkit: $ bin/docker-compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" # Для користувачів старого docker-compose.yml: $ docker compose exec sharelatex /bin/bash -c "source /etc/overleaf/env.sh && source /etc/container_environment.sh && cd /overleaf/services/history-v1 && /sbin/setuser www-data node storage/scripts/back_fill_file_hash.mjs --all" ``` {% endcode %} {% hint style="danger" %} Якщо ви [зберігаєте журнали](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) файли поза межами **контейнера sharelatex** контейнера, переконайтеся, що власником каталогу журналів є `www-data` користувач (uid=33), щоб можна було записати згенерований файл журналу. {% endhint %} Вивід має виглядати так: ```bash Встановіть UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Loading backend","time":"2025-07-25T15:00:58.166Z","v":0} Запис журналів у /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Початок резервного копіювання файлів проєкту... Завантажено глобальних blob-об'єктів: 0 Обробка не видалених проєктів... Оброблено 1 проєкт, минуло 0 с Оновлення активних проєктів завершено Обробка видалених проєктів... Схоже, колекція deletedProjects порожня. Оновлення видалених проєктів завершено Готово. ``` Якщо міграція успішна, ви отримаєте код завершення `0`, а останні рядки вказуватимуть на відсутність помилок: ```bash Готово. ``` Файл журналу матиме такий вигляд (використовуйте шлях, який виводить сценарій): {% code overflow="wrap" %} ```bash $ docker cp sharelatex:/var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log . $ cat file-migration-2025-07-25T15_00_58_199Z.log {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"end":"68839a8f577b9f009d947b27 (2025-07-25T14:54:07.000Z)","msg":"actually completed batch","time":"2025-07-25T15:00:58.379Z","v":0} {"name":"file-migration","hostname":"c25e9faaeb53","pid":971,"level":30,"time":"2025-07-25T15:00:58.383Z","LOGGING_IDENTIFIER":"4effa2000000000000000000","projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063,"eventLoop":{"idle":48.277844,"active":381.53244699971054,"utilization":0.8876763888372498},"diff":{"eventLoop":{"idle":48.223536,"active":134.04030200059555,"utilization":0.7354190687027976},"projects":1,"blobs":6,"filesWithHash":5,"filesWithoutHash":2,"filesDuplicated":0,"filesRetries":0,"filesFailed":0,"fileTreeUpdated":0,"badFileTrees":0,"globalBlobsCount":0,"globalBlobsEgress":0,"projectDeleted":0,"projectHardDeleted":0,"fileHardDeleted":0,"mongoUpdates":1,"readFromGCSCount":7,"readFromGCSIngress":28532,"writeToGCSCount":5,"writeToGCSEgress":300,"readFromGCSThroughputMiBPerSecond":0.14925639825786063},"deferredBatches":[],"msg":"file-migration stats","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Зупиніть інстанс Toolkit: `bin/stop sharelatex` Старий docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Зробіть старі файли недоступними для застосунку Тепер можна перемістити старі файли до вторинного сховища. Рекомендуємо ще деякий час зберігати ці файли на випадок, якщо пізніше виникнуть проблеми. {% code overflow="wrap" %} ```bash # Для користувачів Toolkit: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Для користувачів старого docker-compose.yml: # Ми припускаємо, що ви використовуєте стандартний bind-mount у /var/lib/overleaf $ docker compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # Якщо ви використовуєте вибіркові bind-mount-и, ви можете просто видалити bind-mount для /var/lib/overleaf/data/user_files всередині контейнера. ``` {% endcode %} {% endstep %} {% step %} #### Переведіть етап міграції на 2 Toolkit: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` у `config/variables.env`. Старий docker-compose.yml: встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` у `середовища` розділ у `контейнера sharelatex` службу. {% endstep %} {% step %} #### Застосуйте зміну конфігурації та запустіть інстанс Toolkit: `bin/up -d` Старий docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Перевірте доступ до бінарних файлів Відкрийте проєкт у редакторі Overleaf у браузері та виберіть бінарний файл, наприклад зображення. {% endstep %} {% endstepper %} #### Офлайн-міграція Якщо ви хочете заборонити користувачам входити в систему, поки працює сценарій міграції бінарних файлів, виконайте такі кроки: * Увійдіть до вашого екземпляра Overleaf за допомогою облікового запису адміністратора * Натисніть кнопку **Адмін** кнопку і виберіть **Керувати сайтом** * Натисніть кнопку **Відкрити/закрити редактор** вкладку * Натисніть кнопку **Закрити редактор** кнопку * Натисніть кнопку **Від’єднати всіх користувачів** кнопку Після цього, якщо будь-які користувачі вже увійшли, їх буде перенаправлено на сторінку технічного обслуговування, а будь-які нові користувачі, які відвідають сторінку входу, побачать сторінку технічного обслуговування і **не зможуть** увійти. Потрібно повторити ці кроки під час перезапуску інстанса. Щоб знову відкрити сайт, просто перезапустіть інстанс. #### Онлайн-міграція Можна запускати скрипти міграції, поки застосунок ще працює. Є кілька моментів, які слід врахувати: * Процес міграції інтенсивно використовує введення/виведення, тому під час роботи сценарію слід відстежувати використання ресурсів. * За високої паралельності обробки цикл подій у `filestore` службі може частково блокуватися, що призведе до гіршого досвіду користувача. Рекомендуємо починати зі стандартних значень `--concurrency=10` та `--concurrent-batches=1` . * Ви можете зупинити сценарій будь-коли. Після повторного запуску він перевірить попередні проєкти та пропустить файли, які вже були оброблені. Це корисно, якщо ви віддаєте перевагу запуску міграції в менш завантажені години (наприклад, уночі). Наша рекомендація — закрити сайт і виконати міграцію офлайн у вікно технічного обслуговування, коли кількість ваших проєктів менша за 1000 (див. вивід сценарію міграції під час запуску з `--report`). Якщо кількість проєктів велика, ви можете запустити скрипт і спостерігати за його прогресом, а потім вирішити, чи продовжувати виконання онлайн чи офлайн залежно від вашого конкретного випадку. #### Очистіть застарілі дані бінарних файлів Коли ви завершите міграцію та переконаєтеся, що проєкти все ще мають доступ до всіх своїх файлів, ви можете видалити старе файлове сховище в `/var/lib/overleaf/data/user_files`. Дуже рекомендуємо ще деякий час зберігати ці файли — спочатку можна зробити їх недоступними для застосунку, перейменувавши папку. ### Усунення неполадок Тут ми додамо поради з усунення несправностей. Зверніть увагу: хоча зазвичай ми надаємо підтримку лише клієнтам Server Pro, з огляду на характер цієї міграції ми також зробимо все можливе, щоб підтримати клієнтів CE, які зіткнуться з проблемами, специфічними для міграції бінарних файлів. Якщо сценарій міграції бінарних файлів завершується помилкою (тобто виходить з помилкою або виводить ненульову кількість невдалих проєктів), будь ласка, надішліть такі відомості нашій команді підтримки електронною поштою [support+filestoremigration@overleaf.com](mailto:support+filestoremigration@overleaf.com?subject=Binary%20file%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), вказавши: Тема: Проблема з міграцією бінарних файлів Текст: * Тип екземпляра: CE або Server Pro (видаліть, якщо не підходить) * Тип встановлення: Overleaf toolkit або `docker-compose.yml` або інше (видаліть, якщо не підходить) * Версія: 5.5.x (toolkit: `$ cat config/version`) * Вивід скрипта міграції (який має бути розташований у контейнері в `/var/log/overleaf`) * Звіт: (запустіть сценарій міграції з `--report`) * Оброблені проєкти: (відповідно до останнього запуску сценарію) * Тривалість міграції: * `bin/doctor` вивід (під час використання toolkit) * Версія toolkit: `$ git rev-parse HEAD` (під час використання Toolkit) Розгляньте можливість долучення файлів журналів для `filestore` службу до листа. Його можна знайти в `/var/log/overleaf/filestore.log` всередині `контейнера sharelatex` контейнера та експортувати їх так: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # замініть на часову позначку, яку виводить сценарій $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Будь ласка, замажте будь-яку конфіденційну інформацію у файлах журналів перед їх долученням. #### Відсутні файли У старіших версіях Server Pro/CE записи в дереві файлів створювалися до завершення завантаження користувачем, через що файли могли виглядати як відсутні у разі збою завантаження. Під час обробки всіх дерев файлів ви можете побачити кілька таких випадків, позначених як помилки. Якщо кількість відсутніх файлів невелика, розгляньте можливість вручну перевірити ці випадки та видалити їх у редакторі в браузері. Якщо кількість відсутніх файлів велика, зверніться до служби підтримки; див. шаблон листа вище. #### Пошук пошкоджених дерев файлів Міграція може завершитися невдачею для проєктів із неправильним деревом файлів (наприклад, коли імена файлів порожні). Ви можете знайти перелік цих проблем за допомогою `find_malformed_filetrees` скрипта, який перевіряє всі проєкти в базі даних: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/find_malformed_filetrees.mjs > /tmp/malformed-file-trees.json" ``` {% endcode %} Щоб виправити неправильні шляхи, використайте `fix_malformed_filetree` скрипт, запускаючи команду один раз для кожного поганого шляху: {% code overflow="wrap" %} ```bash $ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web && /sbin/setuser www-data node scripts/fix_malformed_filetree.mjs --logs=/tmp/malformed-file-trees.json" ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ayakaleaf-pro.ayaka.space/on-premises/uk/pidtrimka/support-guides/v5.5.7-migration-binary-files-migration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.