> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# (Di chuyển v5.5.7) Di chuyển tệp nhị phân

## Di chuyển tệp nhị phân

Bản phát hành phiên bản chính `6.0` sắp tới của Server Pro và Community Edition sẽ giảm một nửa dung lượng lưu trữ dành cho tệp nhị phân. Một quá trình di chuyển trực tuyến được bao gồm trong phiên bản `5.5.7`, cho phép giảm thiểu thời gian ngừng hoạt động trong quá trình nâng cấp.

Kể từ Server Pro `4.x`, các tệp nhị phân được lưu hai lần: trong kho lưu trữ tệp đang hoạt động ở "filestore" và trong hệ thống lịch sử dự án đầy đủ. Từ nay trở đi, mỗi tệp sẽ chỉ có một bản sao được lưu trong hệ thống lịch sử dự án đầy đủ.

Việc di chuyển sang hệ thống lưu trữ hợp nhất gồm hai phần: một cờ mới để kiểm soát giai đoạn di chuyển và một script xử lý tất cả các dự án đang hoạt động và các dự án đã bị xóa mềm.

Các giai đoạn:

* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (mặc định), các tệp được đọc và ghi vào filestore. Các tệp được ghi vào history một cách bất đồng bộ.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1`, các tệp được đọc từ history với phương án dự phòng là filestore, và được ghi vào cả filestore lẫn history. Có thể hạ cấp về `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0`.
* `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2`, các tệp chỉ được đọc và ghi vào history. Không thể hạ cấp về `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1`, trừ khi việc di chuyển được thực hiện ở chế độ "ngoại tuyến".

Khi lưu trữ dữ liệu trong [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) và sử dụng các tài khoản dịch vụ riêng biệt cho filestore (`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`) và history (`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`): Vui lòng cấp cho người dùng filestore quyền đọc bucket history dành cho blob `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET`. Từ nay trở đi, dịch vụ filestore sẽ phục vụ các yêu cầu đọc từ dịch vụ biên dịch.

<Warning>
  Chúng tôi đặc biệt khuyến nghị thực hiện việc di chuyển tệp nhị phân trong môi trường không phải production/sandbox trước.
</Warning>

<Check>
  Giấy phép Server Pro tiêu chuẩn cho phép bạn chạy ứng dụng trong một môi trường production cũng như một môi trường không phải production/sandbox; chúng tôi đặc biệt khuyến nghị bạn chuẩn bị một môi trường không phải production để kiểm thử.
</Check>

<Info>
  Nếu bạn nâng cấp lên Server Pro/CE phiên bản `6.0` và sau đó quyết định muốn hạ cấp về phiên bản cũ hơn, bạn nên khôi phục từ một bản sao lưu toàn hệ thống.
</Info>

### Quy trình di chuyển

<Steps>
  <Step title="Tạo bản sao lưu">
    Tạo một [bản sao lưu](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) đầy đủ cho phiên bản của bạn với snapshot nhất quán của các thư mục **mongo**, **redis** và **sharelatex**.
  </Step>

  <Step title="Cập nhật">
    <strong>Toolkit:</strong> Sử dụng script `$ bin/upgrade` để nâng cấp **toolkit** lên phiên bản mới nhất. Khi được hỏi, **không** xác nhận lời nhắc **Upgrade** image? — thay vào đó, hãy chỉnh sửa thủ công tệp **config/version** và đặt giá trị thành `5.5.7`.

    <strong>docker-compose.yml cũ:</strong> Cập nhật phiên bản của dịch vụ `sharelatex` thành `5.5.7`.
  </Step>

  <Step title="Ước tính số lượng dự án bị ảnh hưởng">
    ```bash wrap theme={null}
    # 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"
    ```

    Ví dụ đầu ra:

    ```text theme={null}
    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).
    ```
  </Step>

  <Step title="Flush các hàng đợi lịch sử dự án">
    ```bash wrap theme={null}
    # 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
    ```

    Lặp lại việc flush cho đến khi tất cả các dự án đã được flush (`"project_ids":0`).

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

    <Danger>
      Trong trường hợp "failedProjects" khác không, vui lòng liên hệ bộ phận hỗ trợ và không tiếp tục việc di chuyển tệp nhị phân.
    </Danger>
  </Step>

  <Step title="Chuyển giai đoạn di chuyển lên 1">
    Toolkit: Đặt `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` trong `config/variables.env`.

    docker-compose.yml cũ: Đặt `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` trong phần `environment` của dịch vụ `sharelatex`.
  </Step>

  <Step title="Áp dụng thay đổi cấu hình và khởi động phiên bản">
    Toolkit: `bin/up -d`

    docker-compose.yml cũ: `docker compose up -d`
  </Step>

  <Step title="Xác minh quyền truy cập tệp nhị phân">
    Mở một dự án trong trình soạn thảo Overleaf trên trình duyệt và chọn một tệp nhị phân, chẳng hạn như một hình ảnh.
  </Step>

  <Step title="Chạy script di chuyển">
    ```bash wrap theme={null}
    # 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"
    ```

    <Danger>
      Nếu bạn đang [lưu bền tệp log](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) bên ngoài container **sharelatex**, hãy đảm bảo chủ sở hữu thư mục log được đặt là người dùng `www-data` (uid=33) để tệp log đầu ra có thể được ghi.
    </Danger>

    Đầu ra sẽ trông như sau:

    ```bash theme={null}
    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.

    ```

    Nếu việc di chuyển thành công, bạn sẽ nhận được mã thoát `0`, và các dòng cuối cùng cho thấy không có lỗi:

    ```bash theme={null}
    Done.
    ```

    Tệp log sẽ trông như sau (sử dụng đường dẫn do script in ra):

    ```bash wrap theme={null}
    $ 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}
    ```
  </Step>

  <Step title="Dừng phiên bản">
    Toolkit: `bin/stop sharelatex`

    docker-compose.yml cũ: `docker compose stop sharelatex`
  </Step>

  <Step title="Làm cho các tệp cũ không thể truy cập được từ ứng dụng">
    Bây giờ bạn có thể di chuyển các tệp cũ sang bộ lưu trữ thứ cấp. Chúng tôi khuyên bạn nên giữ lại các tệp này một thời gian phòng khi có vấn đề phát sinh sau này.

    ```bash wrap theme={null}
    # 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.
    ```
  </Step>

  <Step title="Chuyển giai đoạn di chuyển lên 2">
    Toolkit: Đặt `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` trong `config/variables.env`.

    docker-compose.yml cũ: Đặt `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` trong phần `environment` của dịch vụ `sharelatex`.
  </Step>

  <Step title="Áp dụng thay đổi cấu hình và khởi động phiên bản">
    Toolkit: `bin/up -d`

    docker-compose.yml cũ: `docker compose up -d`
  </Step>

  <Step title="Xác minh quyền truy cập tệp nhị phân">
    Mở một dự án trong trình soạn thảo Overleaf trên trình duyệt và chọn một tệp nhị phân, chẳng hạn như một hình ảnh.
  </Step>
</Steps>

#### Di chuyển ngoại tuyến

Nếu bạn muốn ngăn người dùng đăng nhập trong khi script di chuyển tệp nhị phân đang chạy, vui lòng làm theo các bước sau:

* Đăng nhập vào phiên bản Overleaf của bạn bằng tài khoản quản trị viên
* Nhấp vào nút **Admin** và chọn **Manage Site**
* Nhấp vào tab **Open/Close Editor**
* Nhấp vào nút **Close Editor**
* Nhấp vào nút **Disconnect all users**

Sau khi thực hiện xong, nếu có người dùng nào đang đăng nhập, họ sẽ bị chuyển hướng đến trang bảo trì, và bất kỳ người dùng mới nào truy cập trang đăng nhập sẽ thấy trang bảo trì và **không** thể đăng nhập.

Bạn cần lặp lại các bước này khi khởi động lại phiên bản. Để mở lại trang, chỉ cần khởi động lại phiên bản.

#### Di chuyển trực tuyến

Có thể chạy các script di chuyển trong khi ứng dụng vẫn đang chạy. Có một vài điều cần cân nhắc:

* Quá trình di chuyển tiêu tốn nhiều IO, bạn nên theo dõi mức sử dụng tài nguyên trong khi script đang chạy.
* Với mức xử lý đồng thời cao, event loop trong dịch vụ `filestore` có thể bị chặn ở một mức độ nào đó, dẫn đến trải nghiệm người dùng bị suy giảm. Chúng tôi khuyên bạn nên bắt đầu với các giá trị mặc định `--concurrency=10` và `--concurrent-batches=1`.
* Bạn có thể dừng script bất cứ lúc nào. Khi chạy lại, script sẽ xác thực các dự án trước đó và bỏ qua các tệp đã được xử lý. Điều này hữu ích nếu bạn muốn chạy việc di chuyển vào những giờ ít bận rộn hơn (ví dụ: ban đêm).

Khuyến nghị của chúng tôi là đóng trang và chạy việc di chuyển ngoại tuyến trong một khoảng thời gian bảo trì khi số lượng dự án của bạn ít hơn 1000 (xem đầu ra của script di chuyển khi chạy với `--report`). Nếu số lượng dự án lớn, bạn có thể chạy script và theo dõi tiến độ, sau đó quyết định tiếp tục chạy trực tuyến hay ngoại tuyến tùy theo trường hợp cụ thể của mình.

#### Dọn dẹp dữ liệu tệp nhị phân cũ

Khi bạn đã hoàn tất việc di chuyển và xác minh rằng các dự án vẫn có thể truy cập tất cả các tệp của chúng, bạn có thể xóa bộ lưu trữ tệp cũ trong `/var/lib/overleaf/data/user_files`. Chúng tôi đặc biệt khuyến nghị giữ lại các tệp này một thời gian - bạn có thể làm cho chúng không thể truy cập được từ ứng dụng bằng cách đổi tên thư mục trước.

### Khắc phục sự cố

Chúng tôi sẽ bổ sung các lời khuyên khắc phục sự cố tại đây. Xin lưu ý rằng mặc dù thông thường chúng tôi chỉ hỗ trợ khách hàng Server Pro, nhưng do tính chất của lần di chuyển này, chúng tôi cũng sẽ cố gắng hết sức để hỗ trợ khách hàng CE gặp phải các vấn đề cụ thể liên quan đến việc di chuyển tệp nhị phân.

Nếu script di chuyển tệp nhị phân thất bại (tức là thoát với lỗi hoặc in ra số dự án thất bại khác không), vui lòng gửi các thông tin sau đến nhóm hỗ trợ của chúng tôi qua 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), bao gồm chi tiết:

Tiêu đề: Binary file migration problem

Nội dung:

* Loại phiên bản: CE hoặc Server Pro (xóa phần không phù hợp)
* Kiểu cài đặt: Overleaf toolkit hoặc `docker-compose.yml` hoặc khác (xóa phần không phù hợp)
* Phiên bản: 5.5.x (toolkit: `$ cat config/version`)
* Đầu ra của script di chuyển (nằm trong container tại `/var/log/overleaf`)
* Báo cáo: (chạy script di chuyển với `--report`)
* Số dự án đã xử lý: (theo lần chạy script gần nhất)
* Thời gian di chuyển:
* Đầu ra của `bin/doctor` (khi sử dụng toolkit)
* Phiên bản toolkit: `$ git rev-parse HEAD` (khi sử dụng Toolkit)

Hãy cân nhắc đính kèm các tệp log của dịch vụ `filestore` vào email. Bạn có thể tìm thấy chúng tại `/var/log/overleaf/filestore.log` bên trong container `sharelatex` và xuất chúng ra như sau:

```bash theme={null}
$ 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 .
```

Vui lòng loại bỏ mọi thông tin nhạy cảm khỏi các tệp log trước khi đính kèm.

#### Tệp bị thiếu

Các phiên bản Server Pro/CE cũ hơn tạo các mục trong cây tệp trước khi việc tải lên của người dùng hoàn tất, điều này có thể khiến các tệp hiển thị là bị thiếu khi việc tải lên thất bại. Bạn có thể thấy một vài trường hợp như vậy được báo cáo là lỗi khi xử lý tất cả các cây tệp.

Trong trường hợp số lượng tệp bị thiếu ít, hãy cân nhắc xem xét thủ công các trường hợp này và xóa chúng khỏi trình soạn thảo trên trình duyệt.

Trong trường hợp số lượng tệp bị thiếu nhiều, hãy cân nhắc liên hệ bộ phận hỗ trợ, xem mẫu email ở trên.

#### Tìm các cây tệp bị hỏng

Việc di chuyển có thể thất bại đối với các dự án có cây tệp bị sai định dạng (ví dụ: tên tệp bị trống). Bạn có thể tìm danh sách các vấn đề này bằng script `find_malformed_filetrees`, script này kiểm tra tất cả các dự án trong cơ sở dữ liệu:

```bash wrap theme={null}
$ 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"
```

Để sửa các đường dẫn không hợp lệ, hãy dùng script `fix_malformed_filetree`, chạy lệnh một lần cho mỗi đường dẫn bị lỗi:

```bash wrap theme={null}
$ 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"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.