> 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/id/dukungan/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migrasi v5.5.7) Migrasi berkas biner ## Migrasi berkas biner Rilis versi utama mendatang `6.0` Server Pro dan Community Edition akan mengurangi penggunaan penyimpanan berkas biner hingga setengahnya. Migrasi daring disertakan dalam versi `5.5.7` , sehingga downtime minimal saat proses peningkatan. Sejak Server Pro `4.x`, berkas biner disimpan dua kali: di penyimpanan berkas aktif dalam "filestore" dan di sistem riwayat proyek lengkap. Ke depannya, satu salinan dari setiap berkas akan disimpan di sistem riwayat proyek lengkap. Migrasi ke sistem penyimpanan terpadu terdiri dari dua bagian: sebuah flag baru untuk mengontrol fase migrasi dan sebuah skrip yang memproses semua proyek aktif dan yang dihapus sementara. Fase: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (default), berkas dibaca dan ditulis ke filestore. Berkas ditulis ke riwayat secara asinkron. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , berkas dibaca dari riwayat dengan fallback ke filestore dan ditulis ke filestore serta riwayat. Downgrade ke `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` dimungkinkan. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` berkas dibaca dan ditulis ke riwayat saja. Downgrade ke `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` tidak dimungkinkan, kecuali jika dilakukan secara "offline". Saat menyimpan data di [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) dan menggunakan akun layanan terpisah untuk filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) dan riwayat (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Harap berikan pengguna filestore akses baca ke bucket riwayat untuk blob `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Layanan filestore akan melayani pembacaan dari layanan kompilator ke depannya. {% hint style="warning" %} Sangat disarankan untuk melakukan migrasi berkas biner terlebih dahulu di lingkungan non-produksi/sandbox. {% endhint %} {% hint style="success" %} Lisensi standar Server Pro memungkinkan Anda menjalankan aplikasi di lingkungan produksi serta satu lingkungan non-produksi/sandbox; sangat disarankan agar Anda menyediakan lingkungan non-produksi untuk pengujian. {% endhint %} {% hint style="info" %} Jika Anda meningkatkan ke versi Server Pro/CE `6.0` dan kemudian memutuskan untuk menurunkan versi ke versi yang lebih lama, maka Anda harus memulihkan dari cadangan sistem penuh. {% endhint %} ### Prosedur migrasi {% stepper %} {% step %} #### Buat cadangan Buat cadangan [penuh](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) instance Anda dengan snapshot konsisten dari **mongo**, **redis** dan **sharelatex** direktori. {% endstep %} {% step %} #### Perbarui **Toolkit:** Gunakan `$ bin/upgrade` skrip untuk meningkatkan **toolkit** ke versi terbaru. Saat diminta, jangan **tidak** konfirmasi prompt **Peningkatan** image? — sebagai gantinya, edit secara manual **config/version** file dan setel nilainya ke `5.5.7`. **docker-compose.yml lawas:** Perbarui versi `sharelatex` service ke `5.5.7`. {% endstep %} {% step %} #### Perkirakan jumlah proyek yang terdampak {% code overflow="wrap" %} ```bash # Pengguna 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" # Pengguna docker-compose.yml lawas: $ 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 %} Contoh keluaran: {% code fullWidth="false" %} ``` Status saat ini: - Total jumlah proyek: 10 - Total jumlah proyek yang dihapus: 5 Mengambil sampel 1000 proyek untuk memperkirakan kemajuan... Statistik sampel untuk proyek: - Proyek yang disampel: 9 (90% dari semua proyek) - Proyek sampel dengan semua hash tersedia: 5 - Persentase proyek yang perlu pengisian ulang hash: 44% (perkiraan) - Proyek sampel memiliki 11 berkas yang perlu dicek terhadap sistem riwayat proyek lengkap. - Proyek sampel memiliki 3 berkas yang perlu diunggah ke sistem riwayat proyek lengkap (memperkirakan 27% dari semua berkas). Statistik sampel untuk proyek yang dihapus: - Proyek yang dihapus yang disampel: 4 (80% dari semua proyek yang dihapus) - Proyek yang dihapus yang disampel dengan semua hash tersedia: 3 - Persentase proyek yang dihapus yang perlu pengisian ulang hash: 25% (perkiraan) - Proyek yang dihapus yang disampel memiliki 2 berkas yang perlu dicek terhadap sistem riwayat proyek lengkap. - Proyek yang dihapus yang disampel memiliki 1 berkas yang perlu diunggah ke sistem riwayat proyek lengkap (memperkirakan 50% dari semua berkas). ``` {% endcode %} {% endstep %} {% step %} #### Kosongkan antrean riwayat proyek {% code overflow="wrap" %} ```bash # Pengguna Overleaf Toolkit: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # Pengguna docker-compose.yml lawas: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Ulangi pengosongan hingga semua proyek telah dikosongkan (`"project_ids":0`). ``` found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Jika "failedProjects" tidak nol, harap hubungi dukungan dan jangan lanjutkan migrasi berkas biner. {% endhint %} {% endstep %} {% step %} #### Majukan fase migrasi ke 1 Toolkit: Setel `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` di `config/variables.env`. docker-compose.yml lawas: Setel `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` di dalam `lingkungan` bagian dari `sharelatex` service. {% endstep %} {% step %} #### Terapkan perubahan konfigurasi dan mulai instance Toolkit: `bin/up -d` docker-compose.yml lawas: `docker compose up -d` {% endstep %} {% step %} #### Verifikasi akses ke berkas biner Buka sebuah proyek di editor Overleaf di browser dan pilih berkas biner, seperti gambar. {% endstep %} {% step %} #### Jalankan skrip migrasi {% code overflow="wrap" %} ```bash # Pengguna 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" # Pengguna docker-compose.yml lawas: $ 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" %} Jika Anda [menyimpan log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) berkas di luar **sharelatex** container, pastikan pemilik direktori log disetel ke `www-data` pengguna (uid=33) agar berkas log keluaran dapat ditulis. {% endhint %} Hasilnya akan terlihat seperti ini: ```bash Set UV_THREADPOOL_SIZE=16 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Memuat backend","time":"2025-07-25T15:00:58.166Z","v":0} Menulis log ke /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log Memulai pencadangan berkas proyek... Blob global dimuat: 0 Memproses proyek yang tidak dihapus... Memproses 1 proyek, waktu berlalu 0 dtk Selesai memperbarui proyek aktif Memproses proyek yang dihapus... Koleksi deletedProjects tampaknya kosong. Selesai memperbarui proyek yang dihapus Selesai. ``` Jika migrasi berhasil, Anda akan mendapatkan kode keluar `0`, dan baris terakhir yang menunjukkan tidak ada kegagalan: ```bash Selesai. ``` Berkas log akan terlihat seperti ini (gunakan path seperti yang dicetak oleh skrip): {% 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":"batch benar-benar selesai","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":"statistik file-migration","v":0} ``` {% endcode %} {% endstep %} {% step %} #### Hentikan instance Toolkit: `bin/stop sharelatex` docker-compose.yml lawas: `docker compose stop sharelatex` {% endstep %} {% step %} #### Buat berkas lama tidak dapat diakses oleh aplikasi Sekarang Anda dapat memindahkan berkas lama ke penyimpanan sekunder. Kami merekomendasikan untuk menyimpan berkas-berkas ini untuk sementara jika muncul masalah nanti. {% code overflow="wrap" %} ```bash # Pengguna 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 # Pengguna docker-compose.yml lawas: # Kami mengasumsikan bahwa Anda menggunakan bind-mount default di /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 # Jika Anda menggunakan bind-mount selektif, Anda cukup menghapus bind-mount untuk /var/lib/overleaf/data/user_files di dalam container. ``` {% endcode %} {% endstep %} {% step %} #### Majukan fase migrasi ke 2 Toolkit: Setel `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` di `config/variables.env`. docker-compose.yml lawas: Setel `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` di dalam `lingkungan` bagian dari `sharelatex` service. {% endstep %} {% step %} #### Terapkan perubahan konfigurasi dan mulai instance Toolkit: `bin/up -d` docker-compose.yml lawas: `docker compose up -d` {% endstep %} {% step %} #### Verifikasi akses ke berkas biner Buka sebuah proyek di editor Overleaf di browser dan pilih berkas biner, seperti gambar. {% endstep %} {% endstepper %} #### Migrasi offline Jika Anda ingin mencegah pengguna agar tidak dapat masuk saat skrip migrasi berkas biner berjalan, ikuti langkah-langkah ini: * Masuk ke instance Overleaf Anda dengan akun admin * Klik **Admin** tombol dan pilih **Kelola Situs** * Klik **Buka/Tutup Editor** tab * Klik **Tutup Editor** tombol * Klik **Putuskan sambungan semua pengguna** tombol Setelah ini selesai, jika ada pengguna yang sedang masuk mereka akan dialihkan ke halaman pemeliharaan, dan pengguna baru mana pun yang mengunjungi halaman masuk akan melihat halaman pemeliharaan dan **tidak akan** dapat masuk. Anda perlu mengulangi langkah-langkah ini saat memulai ulang instance. Untuk membuka kembali situs, cukup mulai ulang instance. #### Migrasi online Skrip migrasi dapat dijalankan saat aplikasi masih berjalan. Ada beberapa pertimbangan yang perlu diperhatikan: * Proses migrasi intensif I/O, Anda harus memantau penggunaan sumber daya saat skrip berjalan. * Dengan konkurensi pemrosesan yang tinggi, event loop di `filestore` service mungkin mengalami beberapa pemblokiran, yang akan menyebabkan pengalaman pengguna yang menurun. Kami merekomendasikan untuk memulai dengan nilai default `--concurrency=10` dan `--concurrent-batches=1` . * Anda dapat menghentikan skrip kapan saja. Menjalankannya lagi akan memvalidasi proyek sebelumnya dan melewati berkas yang sudah diproses. Ini berguna jika Anda lebih suka menjalankan migrasi pada jam-jam yang lebih sepi (mis. malam hari). Rekomendasi kami adalah menutup situs dan menjalankan migrasi secara offline dalam jendela pemeliharaan ketika jumlah proyek Anda kurang dari 1000 proyek (lihat output skrip migrasi saat dijalankan dengan `--report`). Jika jumlah proyek besar Anda dapat menjalankan skrip dan memantau kemajuannya, lalu memutuskan apakah akan terus menjalankannya secara online atau offline berdasarkan kasus Anda. #### Bersihkan data berkas biner lawas Ketika Anda selesai dengan migrasi dan telah memverifikasi bahwa proyek masih dapat mengakses semua berkas mereka, Anda dapat menghapus penyimpanan berkas lama di `/var/lib/overleaf/data/user_files`. Kami sangat merekomendasikan untuk menyimpan berkas-berkas ini sementara - Anda dapat membuatnya tidak dapat diakses oleh aplikasi dengan terlebih dahulu mengganti nama folder. ### Pemecahan masalah Kami akan menambahkan saran pemecahan masalah di sini. Harap dicatat bahwa meskipun biasanya kami hanya menawarkan dukungan untuk pelanggan Server Pro, mengingat sifat migrasi ini, kami juga akan berupaya sebaik mungkin untuk mendukung pelanggan CE yang mengalami masalah khusus pada migrasi berkas biner. Jika skrip migrasi berkas biner gagal (yaitu keluar dengan kesalahan atau mencetak jumlah proyek gagal yang bukan nol), harap kirimkan detail berikut ke tim dukungan kami melalui email [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), dengan menyertakan: Subjek: Masalah migrasi berkas biner Isi: * Jenis Instance: CE atau Server Pro (hapus yang sesuai) * Jenis Instalasi: Overleaf toolkit atau `docker-compose.yml` atau lainnya (hapus yang sesuai) * Versi: 5.5.x (toolkit: `$ cat config/version`) * Output skrip migrasi (yang seharusnya berada di dalam container di `/var/log/overleaf`) * Laporan: (jalankan skrip migrasi dengan `--report`) * Proyek yang diproses: (sesuai eksekusi skrip terakhir) * Durasi migrasi: * `bin/doctor` output (saat menggunakan toolkit) * Versi Toolkit: `$ git rev-parse HEAD` (saat menggunakan Toolkit) Pertimbangkan untuk melampirkan file log untuk layanan `filestore` service ke email. Anda dapat menemukannya di `/var/log/overleaf/filestore.log` di dalam `sharelatex` container dan ekspor seperti ini: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # ganti dengan timestamp seperti yang dicetak oleh skrip $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Harap hapus informasi sensitif apa pun dari file log sebelum melampirkannya. #### Berkas hilang Versi Server Pro/CE yang lebih lama membuat entri file-tree sebelum unggahan pengguna selesai, yang dapat menyebabkan berkas tampak hilang ketika unggahan gagal. Anda mungkin menemukan beberapa kasus seperti ini dilaporkan sebagai kesalahan saat memproses semua file-tree. Jika jumlah berkas yang hilang rendah, pertimbangkan untuk meninjau kasus-kasus ini secara manual dan menghapusnya dari editor di browser. Jika jumlah berkas yang hilang tinggi, pertimbangkan untuk menghubungi dukungan, lihat templat email di atas. #### Menemukan pohon file yang rusak Migrasi dapat gagal untuk proyek yang memiliki pohon file yang salah format (misalnya, ketika nama file kosong). Anda dapat menemukan daftar masalah ini menggunakan `find_malformed_filetrees` skrip yang memeriksa semua proyek dalam basis data: {% 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 %} Untuk memperbaiki path yang tidak valid, gunakan `fix_malformed_filetree` skrip, jalankan perintah sekali untuk setiap path buruk: {% 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/id/dukungan/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.