> 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/sv/support/support-guides/v5.5.7-migration-binary-files-migration.md).

# (Migrering v5.5.7) Migrering av binärfiler

## Migrering av binära filer

Den kommande huvudversionen `6.0` versionen av Server Pro och Community Edition kommer att halvera lagringsanvändningen för binära filer. En online-migrering ingår i version `5.5.7` , vilket möjliggör minimal driftstoppstid som en del av uppgraderingen.

Sedan Server Pro `4.x`, lagras binära filer två gånger: i den aktiva fillagringen i "filestore" och i det fullständiga projekthistoriksystemet. Framöver kommer en enda kopia av varje fil att lagras i det fullständiga projekthistoriksystemet.

Migreringen till det konsoliderade lagringssystemet består av två delar: en ny flagga för att styra migreringens fas och ett skript som behandlar alla aktiva och mjukt raderade projekt.

Faser:

* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (standard), filer läses och skrivs till filestore. Filer skrivs asynkront till history.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , filer läses från history med fallback till filestore och skrivs till både filestore och history. Nedgradering till `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` är möjlig.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` filer läses och skrivs endast till history. Nedgradering till `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` är inte möjlig, om den inte utfördes "offline".

När data lagras i [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) och använder separata tjänstkonton för filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) och history (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Ge filestore-användaren läsåtkomst till history-bucketen för blobbar `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . Filestore-tjänsten kommer framöver att hantera läsningar från compiler-tjänsten.

{% hint style="warning" %}
Det rekommenderas starkt att först utföra migreringen av binära filer i en icke-produktions-/sandboxmiljö.
{% endhint %}

{% hint style="success" %}
Den vanliga Server Pro-licensen låter dig köra applikationen i en produktionsmiljö samt en i en icke-produktions-/sandboxmiljö; det rekommenderas starkt att du tillhandahåller en icke-produktionsmiljö för testning.
{% endhint %}

{% hint style="info" %}
Om du uppgraderar till Server Pro/CE-version `6.0` och senare bestämmer dig för att nedgradera till en tidigare version, bör du återställa från en fullständig systemsäkerhetskopia.
{% endhint %}

### Migreringsprocedur

{% stepper %}
{% step %}

#### Skapa en säkerhetskopia

Skapa en fullständig [säkerhetskopia](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) av din instans med en konsekvent ögonblicksbild av **mongo**, **redis** och **sharelatex** katalogerna.
{% endstep %}

{% step %}

#### Uppdatera

**Verktygssats:** Använd `$ bin/upgrade` skript för att uppgradera **verktygssatsen** till den senaste versionen. När du tillfrågas, gör **inte** bekräfta prompten **Uppgradera** bild? — redigera i stället manuellt **config/version** filen och sätt värdet till `5.5.7`.

**Äldre docker-compose.yml:** Uppdatera versionen av `sharelatex` tjänsten till `5.5.7`.
{% endstep %}

{% step %}

#### Uppskatta antalet berörda projekt

{% code overflow="wrap" %}

```bash
# Användare av 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"

# Användare av äldre 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 %}

Exempelutdata:

{% code fullWidth="false" %}

```
Aktuell status:
- Totalt antal projekt: 10
- Totalt antal raderade projekt: 5
Samplar 1000 projekt för att uppskatta framstegen...
Statistik för samplade projekt:
- Samplade projekt: 9 (90 % av alla projekt)
- Samplade projekt med alla hashar närvarande: 5
- Andel projekt som behöver hashvärden kompletterade i efterhand: 44 % (uppskattat)
- De samplade projekten har 11 filer som behöver kontrolleras mot det fullständiga projekthistoriksystemet.
- De samplade projekten har 3 filer som behöver laddas upp till det fullständiga projekthistoriksystemet (uppskattar 27 % av alla filer).
Statistik för samplade raderade projekt:
- Samplade raderade projekt: 4 (80 % av alla raderade projekt)
- Samplade raderade projekt med alla hashar närvarande: 3
- Andel raderade projekt som behöver hashvärden kompletterade i efterhand: 25 % (uppskattat)
- De samplade raderade projekten har 2 filer som behöver kontrolleras mot det fullständiga projekthistoriksystemet.
- De samplade raderade projekten har 1 fil som behöver laddas upp till det fullständiga projekthistoriksystemet (uppskattar 50 % av alla filer).
```

{% endcode %}
{% endstep %}

{% step %}

#### Töm projekthistorikens köer

{% code overflow="wrap" %}

```bash
# Användare av Overleaf Toolkit:
$ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues

# Användare av äldre docker-compose.yml:
$ docker compose exec sharelatex /overleaf/bin/flush-history-queues
```

{% endcode %}

Upprepa tömningen tills alla projekt har tömts (`"project_ids":0`).

```
hittade projekt {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"}
totalt {"succeededProjects":0,"failedProjects":0}
```

{% hint style="danger" %}
Om "failedProjects" inte är noll, vänligen kontakta support och fortsätt inte med migreringen av binära filer.
{% endhint %}
{% endstep %}

{% step %}

#### Gå vidare migreringsfasen till 1

Verktygssats: Sätt `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` i `config/variables.env`.

Äldre docker-compose.yml: Sätt `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` i `miljö` avsnittet i `sharelatex` tjänsten.
{% endstep %}

{% step %}

#### Tillämpa konfigurationsändringen och starta instansen

Verktygssats: `bin/up -d`

Äldre docker-compose.yml: `docker compose up -d`
{% endstep %}

{% step %}

#### Verifiera åtkomst till binära filer

Öppna ett projekt i Overleaf-redigeraren i webbläsaren och välj en binär fil, till exempel en bild.
{% endstep %}

{% step %}

#### Kör migreringsskriptet

{% code overflow="wrap" %}

```bash
# Användare av 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"

# Användare av äldre 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" %}
Om du [lagrar logg](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) filer utanför den **sharelatex** containern, se till att ägaren till loggkatalogen är satt till `www-data` användaren (uid=33) så att den utmatade loggfilen kan skrivas.
{% endhint %}

Utdata bör se ut så här:

```bash
Set UV_THREADPOOL_SIZE=16
{"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"Laddar backend","time":"2025-07-25T15:00:58.166Z","v":0}
Skriver loggar till /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log
Startar säkerhetskopiering av projektfiler...
Laddade globala blobbar: 0
Bearbetar ej raderade projekt...
Bearbetade 1 projekt, förfluten tid 0 s
Klar med uppdatering av aktiva projekt
Bearbetar raderade projekt...
Samlingen deletedProjects verkar vara tom.

Klar med uppdatering av raderade projekt
Klart.

```

Om migreringen lyckas får du en avslutningskod på `0`, och de sista raderna visar att inga misslyckanden inträffade:

```bash
Klart.
```

Loggfilen kommer att se ut så här (använd sökvägen som skrivs ut av skriptet):

{% 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":"batchen slutfördes faktiskt","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 för filmigrering","v":0}
```

{% endcode %}
{% endstep %}

{% step %}

#### Stoppa instansen

Verktygssats: `bin/stop sharelatex`

Äldre docker-compose.yml: `docker compose stop sharelatex`
{% endstep %}

{% step %}

#### Gör gamla filer otillgängliga för applikationen

Du kan nu flytta de gamla filerna till sekundär lagring. Vi rekommenderar att behålla filerna ett tag ifall problem uppstår senare.

{% code overflow="wrap" %}

```bash
# Användare av 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

# Användare av äldre docker-compose.yml:
# Vi utgår från att du använder standard bind-mounten i /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
# Om du använder selektiva bind-mounts kan du helt enkelt ta bort bind-mounten för /var/lib/overleaf/data/user_files inne i containern.
```

{% endcode %}
{% endstep %}

{% step %}

#### Gå vidare migreringsfasen till 2

Verktygssats: Sätt `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` i `config/variables.env`.

Äldre docker-compose.yml: Sätt `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` i `miljö` avsnittet i `sharelatex` tjänsten.
{% endstep %}

{% step %}

#### Tillämpa konfigurationsändringen och starta instansen

Verktygssats: `bin/up -d`

Äldre docker-compose.yml: `docker compose up -d`
{% endstep %}

{% step %}

#### Verifiera åtkomst till binära filer

Öppna ett projekt i Overleaf-redigeraren i webbläsaren och välj en binär fil, till exempel en bild.
{% endstep %}
{% endstepper %}

#### Offline-migrering

Om du vill förhindra att användare kan logga in medan skriptet för migrering av binära filer körs, följ dessa steg:

* Logga in på din Overleaf-instans med ett administratörskonto
* Klicka på **Admin** knappen och välj **Hantera webbplats**
* Klicka på **Öppna/Stäng redigeraren** fliken
* Klicka på **Stäng redigeraren** knappen
* Klicka på **Koppla från alla användare** knappen

När detta har gjorts kommer eventuella inloggade användare att omdirigeras till underhållssidan, och nya användare som besöker inloggningssidan kommer att se underhållssidan och **kommer inte att** kunna logga in.

Du behöver upprepa dessa steg när instansen startas om. För att öppna webbplatsen igen, starta helt enkelt om instansen.

#### Online-migrering

Det är möjligt att köra migreringsskripten medan applikationen fortfarande körs. Det finns några saker att ta hänsyn till:

* Migreringsprocessen är IO-intensiv, du bör övervaka resursanvändningen medan skriptet körs.
* Med hög bearbetningskonkurrens kan eventloopen i `filestore` tjänsten uppleva viss blockering, vilket skulle leda till en sämre användarupplevelse. Vi rekommenderar att börja med standardvärdena för `--concurrency=10` och `--concurrent-batches=1` .
* Du kan stoppa skriptet när som helst. Om du startar det igen valideras de tidigare projekten och filer som redan har bearbetats hoppas över. Detta är användbart om du föredrar att köra migreringen under mindre belastade timmar (t.ex. på natten).

Vår rekommendation är att stänga webbplatsen och köra migreringen offline i ett underhållsfönster när ditt projektantal är mindre än 1000 projekt (se utdata från migreringsskriptet när det körs med `--report`). Om antalet projekt är stort kan du köra skriptet och övervaka dess förlopp, och sedan avgöra om du ska fortsätta köra det online eller offline beroende på ditt specifika fall.

#### Städa upp gamla data för binära filer

När du är klar med migreringen och verifierat att projekten fortfarande kan komma åt alla sina filer, kan du ta bort den gamla fillagringen i `/var/lib/overleaf/data/user_files`. Vi rekommenderar starkt att behålla dessa filer ett tag - du kan göra dem otillgängliga för applikationen genom att först byta namn på mappen.

### Felsökning

Vi kommer att lägga till felsökningsråd här. Observera att även om vi normalt endast erbjuder support till Server Pro-kunder, kommer vi, med tanke på denna migrering, också att göra vårt bästa för att stödja CE-kunder som upplever problem specifika för migreringen av binära filer.

Om skriptet för migrering av binära filer misslyckas (dvs. avslutas med ett fel eller skriver ut ett icke-noll antal misslyckade projekt), skicka följande detaljer till vårt supportteam via e-post [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), med uppgifter om:

Ämne: Problem med migrering av binära filer

Meddelande:

* Instanstyp: CE eller Server Pro (ta bort det som inte är lämpligt)
* Installationstyp: Overleaf Toolkit eller `docker-compose.yml` eller annat (ta bort det som inte är lämpligt)
* Version: 5.5.x (verktygssats: `$ cat config/version`)
* Utdata från migreringsskriptet (som bör finnas i containern under `/var/log/overleaf`)
* Rapport: (kör migreringsskriptet med `--report`)
* Bearbetade projekt: (enligt den senaste körningen av skriptet)
* Migreringens varaktighet:
* `bin/doctor` utdata (när toolkit används)
* Toolkit-version: `$ git rev-parse HEAD` (när Toolkit används)

Överväg att bifoga loggfilerna för `filestore` tjänsten till e-postmeddelandet. Du hittar den på `/var/log/overleaf/filestore.log` i `sharelatex` containern och exportera dem så här:

```bash
$ docker cp sharelatex:/var/log/overleaf/filestore.log .
# ersätt <timestamp> med tidsstämpeln som skrivs ut av skriptet
$ docker cp sharelatex:/var/log/overleaf/file-migration-<timestamp>.log .
```

Maskera all känslig information i loggfilerna innan du bifogar dem.

#### Saknade filer

Äldre versioner av Server Pro/CE skapade filträdsposter innan användaruppladdningar var klara, vilket kunde göra att filer verkade saknas när en uppladdning misslyckades. Du kan hitta några av dessa fall rapporterade som fel när alla filträden behandlas.

Om antalet saknade filer är lågt, överväg att manuellt granska dessa fall och ta bort dem från redigeraren i webbläsaren.

Om antalet saknade filer är högt, överväg att kontakta support, se e-postmallen ovan.

#### Hitta trasiga filträd

Migreringen kan misslyckas för projekt som har ett felaktigt filträd (till exempel där filnamnen är tomma). Du kan hitta en lista över dessa problem med `find_malformed_filetrees` skriptet som kontrollerar alla projekt i databasen:

{% 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 %}

För att rätta till de ogiltiga sökvägarna, använd `fix_malformed_filetree` skriptet, och kör kommandot en gång för varje ogiltig sökväg:

{% 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/sv/support/support-guides/v5.5.7-migration-binary-files-migration.md?ask=<question>&goal=<endgoal>
```

`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.