> For the complete documentation index, see [llms.txt](https://overleaf-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://overleaf-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 доступ на читання до bucket історії для 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 %} #### Оновіть **Інструментарій:** Використайте `$ bin/upgrade` скрипт для оновлення **інструментарію** до останньої версії. Коли буде запитано, не **не** підтверджуйте підказку **Оновіть** образ? — натомість вручну відредагуйте **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 Інструментарій: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` у `config/variables.env`. Старий docker-compose.yml: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` у `середовища` розділ `sharelatex` сервіс. {% endstep %} {% step %} #### Застосуйте зміну конфігурації та запустіть інстанс Інструментарій: `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** контейнером, переконайтеся, що власником каталогу logs є `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 %} #### Зупиніть інстанс Інструментарій: `bin/stop sharelatex` Старий docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Зробити старі файли недоступними для застосунку Тепер ви можете перенести старі файли до вторинного сховища. Рекомендуємо зберігати файли ще деякий час на випадок, якщо пізніше виникнуть проблеми. {% code overflow="wrap" %} ```bash # Користувачі інструментарію: $ 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 Інструментарій: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` у `config/variables.env`. Старий docker-compose.yml: Встановіть `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` у `середовища` розділ `sharelatex` сервіс. {% endstep %} {% step %} #### Застосуйте зміну конфігурації та запустіть інстанс Інструментарій: `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 (інструментарій: `$ 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 записи file-tree створювалися до завершення завантаження файлів користувачем, через що файли могли виглядати відсутніми, якщо завантаження не вдавалося. Під час обробки всіх file-tree ви можете знайти кілька таких випадків, позначених як помилки. Якщо кількість відсутніх файлів невелика, розгляньте можливість вручну переглянути ці випадки та видалити їх у редакторі в браузері. Якщо кількість відсутніх файлів велика, зверніться до служби підтримки, див. шаблон листа вище. #### Пошук пошкоджених дерев файлів Міграція може завершитися помилкою для проєктів, які мають неправильно сформоване дерево файлів (наприклад, де імена файлів порожні). Список цих проблем можна знайти за допомогою `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://overleaf-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.