> 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/id/dukungan/support-guides/v5.5.7-migration-binary-files-migration.md). # (Migrasi v5.5.7) Migrasi berkas biner ## Migrasi file biner Versi utama yang akan datang `6.0` rilis Server Pro dan Community Edition akan mengurangi penggunaan penyimpanan file biner hingga setengahnya. Migrasi online disertakan dalam versi `5.5.7` , sehingga memungkinkan waktu henti minimal sebagai bagian dari peningkatan. Sejak Server Pro `4.x`, file biner disimpan dua kali: di penyimpanan file aktif dalam "filestore" dan di sistem riwayat proyek lengkap. Ke depannya, satu salinan dari setiap file akan disimpan di sistem riwayat proyek lengkap. Migrasi ke sistem penyimpanan yang terkonsolidasi 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` (bawaan), file dibaca dan ditulis ke filestore. File ditulis ke riwayat secara asinkron. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , file dibaca dari riwayat dengan fallback ke filestore dan ditulis ke filestore serta riwayat. Turun versi ke `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` dimungkinkan. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` file dibaca dan ditulis hanya ke riwayat. Turun versi ke `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` tidak dimungkinkan, kecuali dilakukan "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`): Mohon berikan akses baca kepada pengguna filestore ke bucket riwayat untuk blob `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Layanan filestore akan melayani pembacaan dari layanan compiler ke depannya. {% hint style="warning" %} Sangat disarankan untuk melakukan migrasi file biner terlebih dahulu di lingkungan non-produksi/sandbox. {% endhint %} {% hint style="success" %} Lisensi standar Server Pro memungkinkan Anda menjalankan aplikasi di lingkungan produksi maupun di 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 bahwa Anda ingin turun versi ke versi yang lebih lama, maka Anda harus memulihkan dari cadangan sistem penuh. {% endhint %} ### Prosedur migrasi {% stepper %} {% step %} #### Buat cadangan Buat cadangan penuh [cadangan](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) dari 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 **Tingkatkan versi** image? — sebagai gantinya, edit secara manual **config/version** file dan atur nilainya menjadi `5.5.7`. **Legacy docker-compose.yml:** Perbarui versi dari `sharelatex` layanan 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 Legacy 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 %} Contoh keluaran: {% code fullWidth="false" %} ``` Status saat ini: - Jumlah total proyek: 10 - Jumlah total proyek yang dihapus: 5 Mengambil sampel 1000 proyek untuk memperkirakan progres... Statistik sampel untuk proyek: - Proyek sampel: 9 (90% dari seluruh proyek) - Proyek sampel dengan semua hash tersedia: 5 - Persentase proyek yang perlu pengisian ulang hash: 44% (perkiraan) - Proyek sampel memiliki 11 file yang perlu diperiksa terhadap sistem riwayat proyek lengkap. - Proyek sampel memiliki 3 file yang perlu diunggah ke sistem riwayat proyek lengkap (memperkirakan 27% dari seluruh file). Statistik sampel untuk proyek yang dihapus: - Proyek yang dihapus dalam sampel: 4 (80% dari seluruh proyek yang dihapus) - Proyek yang dihapus dalam sampel dengan semua hash tersedia: 3 - Persentase proyek yang dihapus yang perlu pengisian ulang hash: 25% (perkiraan) - Proyek yang dihapus dalam sampel memiliki 2 file yang perlu diperiksa terhadap sistem riwayat proyek lengkap. - Proyek yang dihapus dalam sampel memiliki 1 file yang perlu diunggah ke sistem riwayat proyek lengkap (memperkirakan 50% dari seluruh file). ``` {% 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 Legacy docker-compose.yml: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} Ulangi pengosongan sampai semua proyek telah dikosongkan (`"project_ids":0`). ``` proyek ditemukan {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} total {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} Jika "failedProjects" bukan nol, mohon hubungi dukungan dan jangan lanjutkan migrasi file biner. {% endhint %} {% endstep %} {% step %} #### Majukan fase migrasi ke 1 Toolkit: Atur `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` di `config/variables.env`. Legacy docker-compose.yml: Atur `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` di `lingkungan` bagian `sharelatex` layanan. {% endstep %} {% step %} #### Terapkan perubahan konfigurasi dan mulai instance Toolkit: `bin/up -d` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifikasi akses ke file biner Buka sebuah proyek di editor Overleaf di browser dan pilih file 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 Legacy 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" %} Jika Anda [menyimpan log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) file di luar **sharelatex** kontainer, pastikan pemilik direktori logs disetel ke `www-data` pengguna (uid=33) agar file log yang dihasilkan dapat ditulis. {% endhint %} Keluaran akan terlihat seperti ini: ```bash Atur 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 cadangan file proyek... Blob global dimuat: 0 Memproses proyek yang tidak dihapus... 1 proyek diproses, 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 menunjukkan tidak ada kegagalan: ```bash Selesai. ``` File 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` Legacy docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### Buat file lama tidak dapat diakses oleh aplikasi Sekarang Anda dapat memindahkan file lama ke penyimpanan sekunder. Kami merekomendasikan untuk menyimpan file tersebut untuk sementara waktu jika nantinya muncul masalah. {% 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 Legacy docker-compose.yml: # Kami mengasumsikan bahwa Anda menggunakan bind-mount bawaan 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 kontainer. ``` {% endcode %} {% endstep %} {% step %} #### Majukan fase migrasi ke 2 Toolkit: Atur `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` di `config/variables.env`. Legacy docker-compose.yml: Atur `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` di `lingkungan` bagian `sharelatex` layanan. {% endstep %} {% step %} #### Terapkan perubahan konfigurasi dan mulai instance Toolkit: `bin/up -d` Legacy docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### Verifikasi akses ke file biner Buka sebuah proyek di editor Overleaf di browser dan pilih file biner, seperti gambar. {% endstep %} {% endstepper %} #### Migrasi offline Jika Anda ingin mencegah pengguna dapat masuk saat skrip migrasi file biner sedang berjalan, silakan ikuti langkah-langkah berikut: * 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 koneksi semua pengguna** tombol Setelah ini dilakukan, jika ada pengguna yang sedang masuk mereka akan dialihkan ke halaman pemeliharaan, dan pengguna baru 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 Dimungkinkan menjalankan skrip migrasi saat aplikasi masih berjalan. Ada beberapa hal yang perlu dipertimbangkan: * Proses migrasi sangat intensif pada I/O, Anda harus memantau penggunaan sumber daya saat skrip berjalan. * Dengan konkurensi pemrosesan yang tinggi, event loop di `filestore` layanan mungkin mengalami pemblokiran, yang akan menyebabkan pengalaman pengguna menurun. Kami merekomendasikan memulai dengan nilai bawaan dari `--concurrency=10` dan `--concurrent-batches=1` . * Anda dapat menghentikan skrip kapan saja. Menjalankannya lagi akan memvalidasi proyek sebelumnya dan melewati file yang sudah diproses. Ini berguna jika Anda lebih memilih menjalankan migrasi pada jam-jam yang lebih sepi (mis. pada malam hari). Rekomendasi kami adalah menutup situs dan menjalankan migrasi secara offline dalam jendela pemeliharaan saat 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 progresnya, lalu memutuskan apakah akan terus menjalankannya secara online atau offline berdasarkan kasus Anda. #### Bersihkan data file biner lama Setelah Anda selesai dengan migrasi dan memverifikasi bahwa proyek masih dapat mengakses semua file mereka, Anda dapat menghapus penyimpanan file lama di `/var/lib/overleaf/data/user_files`. Kami sangat merekomendasikan untuk menyimpan file-file ini selama beberapa waktu - Anda dapat membuatnya tidak dapat diakses oleh aplikasi dengan mengganti nama folder terlebih dahulu. ### Pemecahan masalah Kami akan menambahkan saran pemecahan masalah di sini. Harap dicatat bahwa meskipun kami biasanya hanya menawarkan dukungan kepada pelanggan Server Pro, mengingat sifat migrasi ini, kami juga akan berusaha sebaik mungkin untuk mendukung pelanggan CE yang mengalami masalah khusus pada migrasi file biner. Jika skrip migrasi file biner gagal (yaitu keluar dengan error atau mencetak jumlah proyek gagal yang bukan nol), mohon 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 rincian: Subjek: Masalah migrasi file biner Isi: * Jenis Instance: CE atau Server Pro (hapus yang tidak sesuai) * Jenis Instalasi: Overleaf toolkit atau `docker-compose.yml` atau lainnya (hapus yang tidak sesuai) * Versi: 5.5.x (toolkit: `$ cat config/version`) * Keluaran skrip migrasi (yang seharusnya berada di container di bawah `/var/log/overleaf`) * Laporan: (jalankan skrip migrasi dengan `--report`) * Proyek yang diproses: (sesuai dengan run terakhir skrip) * Durasi migrasi: * `bin/doctor` keluaran (saat menggunakan toolkit) * Versi Toolkit: `$ git rev-parse HEAD` (saat menggunakan Toolkit) Pertimbangkan untuk melampirkan file log untuk `filestore` layanan 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 cap waktu seperti yang dicetak oleh skrip $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` Harap sensor informasi sensitif apa pun dari file log sebelum melampirkannya. #### File hilang Versi Server Pro/CE yang lebih lama membuat entri file-tree sebelum unggahan pengguna selesai, yang dapat menyebabkan file tampak hilang ketika unggahan gagal. Anda mungkin menemukan beberapa kasus seperti ini dilaporkan sebagai error saat memproses semua file-tree. Jika jumlah file yang hilang sedikit, pertimbangkan untuk meninjau kasus-kasus ini secara manual dan menghapusnya dari editor di browser. Jika jumlah file yang hilang banyak, pertimbangkan untuk menghubungi dukungan, lihat templat email di atas. #### Menemukan pohon file yang rusak Migrasi mungkin gagal untuk proyek yang memiliki pohon file yang tidak valid (misalnya, ketika nama file kosong). Anda dapat menemukan daftar masalah ini menggunakan `find_malformed_filetrees` skrip yang memeriksa semua proyek di 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 yang bermasalah: {% 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/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.