(v5.5.7 Taşıması) İkili dosya taşıması

​

İkili dosya taşıması

Server Pro ve Community Edition’ın yaklaşan 6.0 ana sürümü, ikili (binary) dosyaların depolama kullanımını yarıya indirecektir. 5.5.7 sürümüne, yükseltmenin bir parçası olarak kesinti süresini en aza indiren çevrimiçi bir taşıma dahil edilmiştir.

Server Pro 4.x’ten bu yana ikili dosyalar iki kez depolanmaktadır: “filestore” içindeki etkin dosya deposunda ve tam proje geçmişi sisteminde. Bundan sonra her dosyanın tek bir kopyası tam proje geçmişi sisteminde depolanacaktır.

Birleştirilmiş depolama sistemine taşıma iki bölümden oluşur: Taşımanın aşamasını denetlemek için yeni bir bayrak ve tüm etkin ve geçici olarak silinmiş (soft-deleted) projeleri işleyen bir betik.

Aşamalar:

• OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 (varsayılan): dosyalar filestore’dan okunur ve filestore’a yazılır. Dosyalar geçmişe eşzamansız olarak yazılır.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 : dosyalar filestore’a geri dönüş (fallback) ile geçmişten okunur ve hem filestore’a hem de geçmişe yazılır. OVERLEAF_FILESTORE_MIGRATION_LEVEL=0 seviyesine geri dönmek mümkündür.
• OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 : dosyalar yalnızca geçmişten okunur ve yalnızca geçmişe yazılır. Taşıma “çevrimdışı” yapılmadıysa OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 seviyesine geri dönmek mümkün değildir.

Verileri S3 üzerinde depoluyor ve filestore (OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID) ile geçmiş (OVERLEAF_HISTORY_S3_ACCESS_KEY_ID) için ayrı servis hesapları kullanıyorsanız: Lütfen filestore kullanıcısına blob’lar için geçmiş bucket’ı olan OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET üzerinde okuma erişimi verin. Bundan sonra derleyici servisinden gelen okumaları filestore servisi karşılayacaktır.

İkili dosya taşımasını önce üretim dışı/sandbox bir ortamda gerçekleştirmeniz önemle tavsiye edilir.

Standart Server Pro lisansı, uygulamayı hem bir üretim ortamında hem de bir üretim dışı/sandbox ortamında çalıştırmanıza izin verir; test için bir üretim dışı ortam hazırlamanız önemle tavsiye edilir.

Server Pro/CE 6.0 sürümüne yükseltir ve daha sonra önceki bir sürüme geri dönmeye karar verirseniz, tam bir sistem yedeğinden geri yükleme yapmalısınız.

​

Taşıma prosedürü

1. Yedek oluşturun

   Örneğinizin mongo, redis ve sharelatex dizinlerinin tutarlı bir anlık görüntüsünü içeren tam bir yedeğini oluşturun.

2. Güncelleyin

   Toolkit: toolkit’i en son sürüme yükseltmek için $ bin/upgrade betiğini kullanın. Sorulduğunda Upgrade image? istemini onaylamayın — bunun yerine config/version dosyasını manuel olarak düzenleyin ve değeri 5.5.7 olarak ayarlayın.

   Eski docker-compose.yml: sharelatex servisinin sürümünü 5.5.7 olarak güncelleyin.

3. Etkilenen projelerin sayısını tahmin edin

   # Overleaf Toolkit users:
   $ 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"
   
   # Legacy docker-compose.yml users:
   $ 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"
   

   Örnek çıktı:

   Current status:
   - Total number of projects: 10
   - Total number of deleted projects: 5
   Sampling 1000 projects to estimate progress...
   Sampled stats for projects:
   - Sampled projects: 9 (90% of all projects)
   - Sampled projects with all hashes present: 5
   - Percentage of projects that need back-filling hashes: 44% (estimated)
   - Sampled projects have 11 files that need to be checked against the full project history system.
   - Sampled projects have 3 files that need to be uploaded to the full project history system (estimating 27% of all files).
   Sampled stats for deleted projects:
   - Sampled deleted projects: 4 (80% of all deleted projects)
   - Sampled deleted projects with all hashes present: 3
   - Percentage of deleted projects that need back-filling hashes: 25% (estimated)
   - Sampled deleted projects have 2 files that need to be checked against the full project history system.
   - Sampled deleted projects have 1 files that need to be uploaded to the full project history system (estimating 50% of all files).
   
4. Proje geçmişi kuyruklarını boşaltın

   # Overleaf Toolkit users:
   $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues
   
   # Legacy docker-compose.yml users:
   $ docker compose exec sharelatex /overleaf/bin/flush-history-queues
   

   Tüm projeler boşaltılana kadar ("project_ids":0) boşaltma işlemini tekrarlayın.

   found projects {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
   total {"succeededProjects":0,"failedProjects":0}
   

   “failedProjects” sıfır değilse, lütfen destek ekibine ulaşın ve ikili dosya taşımasına devam etmeyin.

5. Taşıma aşamasını 1'e ilerletin

   Toolkit: config/variables.env içinde OVERLEAF_FILESTORE_MIGRATION_LEVEL=1 ayarlayın.

   Eski docker-compose.yml: sharelatex servisinin environment bölümünde OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1' ayarlayın.

6. Yapılandırma değişikliğini uygulayın ve örneği başlatın

   Toolkit: bin/up -d

   Eski docker-compose.yml: docker compose up -d

7. İkili dosyalara erişimi doğrulayın

   Tarayıcıda Overleaf düzenleyicisinde bir proje açın ve görsel gibi bir ikili dosya seçin.

8. Taşıma betiğini çalıştırın

   # Overleaf Toolkit users:
   $ 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"
   
   # Legacy docker-compose.yml users:
   $ 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"
   

   Günlük dosyalarını sharelatex konteynerinin dışında kalıcı olarak saklıyorsanız, çıktı günlük dosyasının yazılabilmesi için günlük dizininin sahibinin www-data kullanıcısı (uid=33) olarak ayarlandığından emin olun.

   Çıktı şuna benzer görünmelidir:

   Set 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}
   Writing logs into /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
   Starting project file backup...
   Loaded global blobs: 0
   Processing non-deleted projects...
   Processed 1 projects, elapsed time 0s
   Done updating live projects
   Processing deleted projects...
   The collection deletedProjects appears to be empty.
   
   Done updating deleted projects
   Done.
   
   

   Taşıma başarılı olursa 0 çıkış kodu ve hata olmadığını belirten son satırları alırsınız:

   Done.
   

   Günlük dosyası şuna benzer görünür (betiğin yazdırdığı yolu kullanın):

   $ 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}
   
9. Örneği durdurun

   Toolkit: bin/stop sharelatex

   Eski docker-compose.yml: docker compose stop sharelatex

10. Eski dosyaları uygulama için erişilemez hâle getirin

    Artık eski dosyaları ikincil depolamaya taşıyabilirsiniz. Daha sonra sorun çıkma ihtimaline karşı dosyaları bir süre saklamanızı öneririz.

    # Toolkit users:
    $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files
    
    # Legacy docker-compose.yml users:
    # We are assuming that you are using the default bind-mount in /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
    # In case you are using selective bind-mounts, you can simply remove the bind-mount for /var/lib/overleaf/data/user_files inside the container.
    
11. Taşıma aşamasını 2'ye ilerletin

    Toolkit: config/variables.env içinde OVERLEAF_FILESTORE_MIGRATION_LEVEL=2 ayarlayın.

    Eski docker-compose.yml: sharelatex servisinin environment bölümünde OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2' ayarlayın.

12. Yapılandırma değişikliğini uygulayın ve örneği başlatın

    Toolkit: bin/up -d

    Eski docker-compose.yml: docker compose up -d

13. İkili dosyalara erişimi doğrulayın

    Tarayıcıda Overleaf düzenleyicisinde bir proje açın ve görsel gibi bir ikili dosya seçin.

​

Çevrimdışı taşıma

İkili dosya taşıma betiği çalışırken kullanıcıların oturum açabilmesini engellemek istiyorsanız lütfen şu adımları izleyin:

• Overleaf örneğinize bir yönetici hesabıyla giriş yapın
• Admin düğmesine tıklayın ve Manage Site seçeneğini seçin
• Open/Close Editor sekmesine tıklayın
• Close Editor düğmesine tıklayın
• Disconnect all users düğmesine tıklayın

Bu yapıldıktan sonra, oturum açmış kullanıcılar bakım sayfasına yönlendirilir ve giriş sayfasını ziyaret eden yeni kullanıcılar bakım sayfasını görür ve oturum açamaz.

Örneği yeniden başlatırken bu adımları tekrarlamanız gerekir. Siteyi yeniden açmak için örneği yeniden başlatmanız yeterlidir.

​

Çevrimiçi taşıma

Uygulama çalışmaya devam ederken taşıma betiklerini çalıştırmak mümkündür. Göz önünde bulundurulması gereken birkaç husus vardır:

• Taşıma işlemi yoğun G/Ç (IO) gerektirir; betik çalışırken kaynak kullanımını izlemelisiniz.
• Yüksek işlem eşzamanlılığında filestore servisindeki olay döngüsü (event loop) bir miktar bloklanabilir ve bu da kullanıcı deneyiminin kötüleşmesine yol açar. Varsayılan --concurrency=10 ve --concurrent-batches=1 değerleriyle başlamanızı öneririz.
• Betiği istediğiniz zaman durdurabilirsiniz. Yeniden başlatmak önceki projeleri doğrular ve zaten işlenmiş dosyaları atlar. Bu, taşımayı daha az yoğun saatlerde (ör. gece) çalıştırmayı tercih ettiğiniz durumlarda kullanışlıdır.

Önerimiz, proje sayınız 1000’den az olduğunda (betiği --report ile çalıştırdığınızdaki çıktıya bakın) siteyi kapatıp taşımayı bir bakım penceresinde çevrimdışı çalıştırmanızdır. Proje sayısı fazlaysa, betiği çalıştırıp ilerlemesini izleyebilir, ardından kendi durumunuza göre çevrimiçi mi yoksa çevrimdışı mı devam edeceğinize karar verebilirsiniz.

​

Eski ikili dosya verilerini temizleme

Taşımayı tamamlayıp projelerin tüm dosyalarına hâlâ erişebildiğini doğruladıktan sonra, /var/lib/overleaf/data/user_files içindeki eski dosya depolamasını kaldırabilirsiniz. Bu dosyaları bir süre saklamanızı önemle tavsiye ederiz — önce klasörü yeniden adlandırarak uygulama için erişilemez hâle getirebilirsiniz.

​

Sorun giderme

Sorun giderme önerilerini buraya ekleyeceğiz. Normalde yalnızca Server Pro müşterilerine destek sunsak da, bu taşımanın niteliği gereği ikili dosya taşımasına özgü sorunlar yaşayan CE müşterilerine de destek olmak için elimizden geleni yapacağımızı lütfen unutmayın.

İkili dosya taşıma betiği başarısız olursa (yani bir hatayla çıkarsa veya sıfırdan farklı sayıda başarısız proje yazdırırsa), lütfen aşağıdaki ayrıntıları destek ekibimize [e-mail] adresine e-postayla gönderin:

Konu: Binary file migration problem

Gövde:

• Örnek Türü: CE veya Server Pro (uygun olmayanı silin)
• Kurulum Türü: Overleaf toolkit veya docker-compose.yml ya da diğer (uygun olmayanı silin)
• Sürüm: 5.5.x (toolkit: $ cat config/version)
• Taşıma betiği çıktısı (konteynerde /var/log/overleaf altında bulunmalıdır)
• Rapor: (taşıma betiğini --report ile çalıştırın)
• İşlenen projeler: (betiğin son çalıştırmasına göre)
• Taşımanın süresi:
• bin/doctor çıktısı (toolkit kullanırken)
• Toolkit sürümü: $ git rev-parse HEAD (Toolkit kullanırken)

filestore servisinin günlük dosyalarını e-postaya eklemeyi düşünün. Bunları sharelatex konteyneri içinde /var/log/overleaf/filestore.log konumunda bulabilir ve şu şekilde dışa aktarabilirsiniz:

$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# replace <timestamp> with the timestamp as printed by the script
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .

Lütfen günlük dosyalarını eklemeden önce içlerindeki hassas bilgileri karartın.

​

Eksik dosyalar

Server Pro/CE’nin eski sürümleri, kullanıcı yüklemeleri tamamlanmadan dosya ağacı girdileri oluşturuyordu; bu da bir yükleme başarısız olduğunda dosyaların eksik görünmesine neden olabiliyordu. Tüm dosya ağaçları işlenirken bu durumlardan birkaçının hata olarak raporlandığını görebilirsiniz.

Eksik dosya sayısı azsa, bu durumları manuel olarak gözden geçirip tarayıcıdaki düzenleyiciden silmeyi düşünün.

Eksik dosya sayısı fazlaysa destek ekibine ulaşmayı düşünün; yukarıdaki e-posta şablonuna bakın.

​

Bozuk dosya ağaçlarını bulma

Taşıma, hatalı biçimlendirilmiş bir dosya ağacına sahip projelerde (örneğin dosya adlarının boş olduğu durumlarda) başarısız olabilir. Veritabanındaki tüm projeleri denetleyen find_malformed_filetrees betiğini kullanarak bu sorunların bir listesini bulabilirsiniz:

$ 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"

Geçersiz yolları düzeltmek için fix_malformed_filetree betiğini kullanın ve komutu her hatalı yol için bir kez çalıştırın:

$ 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"