> 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/ko/support/support-guides/v5.5.7-migration-binary-files-migration.md). # (v5.5.7 마이그레이션) 바이너리 파일 마이그레이션 ## 바이너리 파일 마이그레이션 다가오는 주요 버전 `6.0` Server Pro 및 Community Edition의 릴리스는 바이너리 파일의 저장 공간 사용량을 절반으로 줄일 것입니다. 온라인 마이그레이션이 버전에 포함되어 있습니다 `5.5.7` 으로, 업그레이드의 일부로 최소한의 다운타임만 허용합니다. Server Pro 이후 `4.x`에서는 바이너리 파일이 두 번 저장됩니다: "filestore"의 활성 파일 저장소와 전체 프로젝트 기록 시스템에 저장됩니다. 앞으로는 각 파일의 단일 복사본이 전체 프로젝트 기록 시스템에 저장됩니다. 통합 저장소 시스템으로의 마이그레이션은 두 부분으로 구성됩니다: 마이그레이션 단계를 제어하는 새 플래그와 모든 활성 및 소프트 삭제된 프로젝트를 처리하는 스크립트입니다. 단계: * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` (기본값), 파일은 filestore에서 읽고 쓰입니다. 파일은 비동기적으로 기록 시스템에 기록됩니다. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` , 파일은 기록 시스템에서 읽되 filestore로 대체(fallback)하며, filestore와 기록 시스템 둘 다에 기록됩니다. 다음 버전으로 다운그레이드하는 것은 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=0` 가능합니다. * `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` 파일은 기록 시스템에서만 읽고 쓰입니다. 다음 버전으로 다운그레이드하는 것은 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` 불가능합니다. 단, "오프라인"으로 수행한 경우는 예외입니다. 데이터를 [S3](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/s3) 에 저장하고 filestore(`OVERLEAF_FILESTORE_S3_ACCESS_KEY_ID`)와 기록(`OVERLEAF_HISTORY_S3_ACCESS_KEY_ID`)에 대해 별도의 서비스 계정을 사용하는 경우: blob에 대해 기록 버킷에 대한 읽기 액세스 권한을 filestore 사용자에게 부여해 주세요 `OVERLEAF_HISTORY_PROJECT_BLOBS_BUCKET` . 앞으로 filestore 서비스가 컴파일러 서비스의 읽기 요청을 처리하게 됩니다. {% hint style="warning" %} 바이너리 파일 마이그레이션은 먼저 비운영/샌드박스 환경에서 수행하는 것을 강력히 권장합니다. {% endhint %} {% hint style="success" %} 표준 Server Pro 라이선스는 운영 환경과 비운영/샌드박스 환경 하나에서 애플리케이션을 실행할 수 있도록 허용합니다. 테스트를 위해 비운영 환경을 마련하는 것을 강력히 권장합니다. {% endhint %} {% hint style="info" %} Server Pro/CE 버전으로 업그레이드한 후 `6.0` 나중에 이전 버전으로 다운그레이드하려는 경우, 전체 시스템 백업에서 복원해야 합니다. {% endhint %} ### 마이그레이션 절차 {% stepper %} {% step %} #### 백업 생성 전체 [백업](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) 인스턴스의 일관된 스냅샷과 함께 **mongo**, **redis** 그리고 **sharelatex** 디렉터리의. {% endstep %} {% step %} #### 업데이트 **도구 모음:** 다음을 사용하세요. `$ bin/upgrade` 업그레이드 스크립트 **도구 모음** 을 최신 버전으로 업데이트합니다. 요청이 표시되면 **아니** 프롬프트를 확인하지 마세요 **업그레이드** 이미지? — 대신 수동으로 편집하세요 **config/version** 파일을 열고 값을 다음으로 설정하세요 `5.5.7`. **레거시 docker-compose.yml:** 이미지 태그의 버전을 업데이트합니다, `sharelatex` 서비스를 `5.5.7`. {% endstep %} {% step %} #### 영향받는 프로젝트 수 추정 {% code overflow="wrap" %} ```bash # 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" # 레거시 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 %} 예시 출력: {% code fullWidth="false" %} ``` 현재 상태: - 총 프로젝트 수: 10 - 총 삭제된 프로젝트 수: 5 진행 상황을 추정하기 위해 프로젝트 1000개를 샘플링하는 중... 프로젝트에 대한 샘플 통계: - 샘플링된 프로젝트: 9개(전체 프로젝트의 90%) - 해시가 모두 존재하는 샘플링된 프로젝트: 5개 - 백필링 해시가 필요한 프로젝트 비율: 44%(추정) - 샘플링된 프로젝트에는 전체 프로젝트 기록 시스템과 대조해야 하는 파일이 11개 있습니다. - 샘플링된 프로젝트에는 전체 프로젝트 기록 시스템에 업로드해야 하는 파일이 3개 있습니다(전체 파일의 27%로 추정). 삭제된 프로젝트에 대한 샘플 통계: - 샘플링된 삭제된 프로젝트: 4개(전체 삭제된 프로젝트의 80%) - 해시가 모두 존재하는 샘플링된 삭제된 프로젝트: 3개 - 백필링 해시가 필요한 삭제된 프로젝트 비율: 25%(추정) - 샘플링된 삭제된 프로젝트에는 전체 프로젝트 기록 시스템과 대조해야 하는 파일이 2개 있습니다. - 샘플링된 삭제된 프로젝트에는 전체 프로젝트 기록 시스템에 업로드해야 하는 파일이 1개 있습니다(전체 파일의 50%로 추정). ``` {% endcode %} {% endstep %} {% step %} #### 프로젝트 기록 대기열 비우기 {% code overflow="wrap" %} ```bash # Overleaf Toolkit 사용자: $ bin/docker-compose exec sharelatex /overleaf/bin/flush-history-queues # 레거시 docker-compose.yml 사용자: $ docker compose exec sharelatex /overleaf/bin/flush-history-queues ``` {% endcode %} 모든 프로젝트가 비워질 때까지 비우기를 반복하세요(`"project_ids":0`). ``` 발견된 프로젝트 {"project_ids":0,"limit":100000,"ts":"2025-09-01T10:35:33.353Z"} 합계 {"succeededProjects":0,"failedProjects":0} ``` {% hint style="danger" %} "failedProjects"가 0이 아닌 경우 지원팀에 연락하고 바이너리 파일 마이그레이션을 계속 진행하지 마세요. {% endhint %} {% endstep %} {% step %} #### 마이그레이션 단계를 1로 진행 도구 모음: 설정 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=1` 를 `config/variables.env`. 레거시 docker-compose.yml: 설정 `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '1'` 를 `환경` 의 섹션에 `sharelatex` 서비스. {% endstep %} {% step %} #### 구성 변경을 적용하고 인스턴스를 시작하세요 도구 모음: `bin/up -d` 레거시 docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### 바이너리 파일 접근 확인 브라우저에서 Overleaf 편집기로 프로젝트를 열고 이미지와 같은 바이너리 파일을 선택하세요. {% endstep %} {% step %} #### 마이그레이션 스크립트를 실행하세요 {% code overflow="wrap" %} ```bash # 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" # 레거시 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" %} 로그를 [지속적으로 저장하는 경우](https://docs.overleaf.com/on-premises/configuration/overleaf-toolkit/logging#persisting-logs) 컨테이너 외부의 **sharelatex** logs 디렉터리 소유자가 다음 사용자로 설정되어 있는지 확인하세요 `www-data` 사용자(uid=33) 그래야 출력된 로그 파일을 쓸 수 있습니다. {% endhint %} 출력은 다음과 같아야 합니다: ```bash UV_THREADPOOL_SIZE=16으로 설정 {"name":"default","hostname":"c25e9faaeb53","pid":971,"level":30,"backend":"fs","msg":"백엔드 로딩 중","time":"2025-07-25T15:00:58.166Z","v":0} /var/log/overleaf/file-migration-2025-07-25T15_00_58_199Z.log에 로그를 기록하는 중 프로젝트 파일 백업을 시작하는 중... 전역 blob 로드됨: 0 삭제되지 않은 프로젝트를 처리하는 중... 프로젝트 1개 처리됨, 경과 시간 0초 실시간 프로젝트 업데이트 완료 삭제된 프로젝트를 처리하는 중... deletedProjects 컬렉션이 비어 있는 것으로 보입니다. 삭제된 프로젝트 업데이트 완료 완료. ``` 마이그레이션이 성공하면 종료 코드 `0`, 그리고 실패가 없음을 나타내는 마지막 줄을 받게 됩니다: ```bash 완료. ``` 로그 파일은 다음과 같이 표시됩니다(스크립트가 출력한 경로를 사용하세요): {% 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":"배치가 실제로 완료됨","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} ``` {% endcode %} {% endstep %} {% step %} #### 인스턴스를 중지하세요 도구 모음: `bin/stop sharelatex` 레거시 docker-compose.yml: `docker compose stop sharelatex` {% endstep %} {% step %} #### 오래된 파일을 애플리케이션에서 접근할 수 없게 만들기 이제 오래된 파일을 보조 저장소로 옮길 수 있습니다. 나중에 문제가 발생할 경우를 대비해 파일을 한동안 보관해 두는 것을 권장합니다. {% code overflow="wrap" %} ```bash # 도구 모음 사용자: $ bin/docker-compose run --rm --entrypoint mv sharelatex --no-clobber --verbose /var/lib/overleaf/data/user_files /var/lib/overleaf/data/old_user_files # 레거시 docker-compose.yml 사용자: # /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 # 선택적 바인드 마운트를 사용 중인 경우, 컨테이너 내부의 /var/lib/overleaf/data/user_files에 대한 바인드 마운트를 단순히 제거하면 됩니다. ``` {% endcode %} {% endstep %} {% step %} #### 마이그레이션 단계를 2로 진행 도구 모음: 설정 `OVERLEAF_FILESTORE_MIGRATION_LEVEL=2` 를 `config/variables.env`. 레거시 docker-compose.yml: 설정 `OVERLEAF_FILESTORE_MIGRATION_LEVEL: '2'` 를 `환경` 의 섹션에 `sharelatex` 서비스. {% endstep %} {% step %} #### 구성 변경을 적용하고 인스턴스를 시작하세요 도구 모음: `bin/up -d` 레거시 docker-compose.yml: `docker compose up -d` {% endstep %} {% step %} #### 바이너리 파일 접근 확인 브라우저에서 Overleaf 편집기로 프로젝트를 열고 이미지와 같은 바이너리 파일을 선택하세요. {% endstep %} {% endstepper %} #### 오프라인 마이그레이션 바이너리 파일 마이그레이션 스크립트가 실행되는 동안 사용자가 로그인하지 못하게 하려면 다음 단계를 따르세요: * 관리자 계정으로 Overleaf 인스턴스에 로그인하세요 * 다음 **관리자** 버튼을 누르고 **사이트 관리** * 다음으로, 온프레미스 Server Pro 계정에 로그인합니다 **편집기 열기/닫기** 탭 * 다음 **편집기 닫기** 버튼을 클릭합니다 * 다음 **모든 사용자 연결 해제** 버튼을 클릭합니다 이 작업이 완료되면, 로그인되어 있는 사용자는 유지보수 페이지로 리디렉션되고, 로그인 페이지를 방문하는 새 사용자는 유지보수 페이지를 보게 되며 **않습니다** 로그인할 수 있습니다. 인스턴스를 다시 시작할 때 이 단계를 반복해야 합니다. 사이트를 다시 열려면 인스턴스를 다시 시작하면 됩니다. #### 온라인 마이그레이션 애플리케이션이 계속 실행 중인 상태에서도 마이그레이션 스크립트를 실행할 수 있습니다. 고려해야 할 몇 가지 사항이 있습니다: * 마이그레이션 과정은 IO 집약적이므로, 스크립트가 실행되는 동안 리소스 사용량을 모니터링해야 합니다. * 높은 처리 동시성에서는 `filestore` 서비스의 이벤트 루프가 일부 블로킹을 겪을 수 있으며, 이는 사용자 경험 저하로 이어질 수 있습니다. 기본값인 `--concurrency=10` 그리고 `--concurrent-batches=1` . * 언제든지 스크립트를 중지할 수 있습니다. 다시 시작하면 이전 프로젝트를 검증하고 이미 처리된 파일은 건너뜁니다. 이는 사용자가 더 한가한 시간대(예: 밤)에 마이그레이션을 실행하고 싶을 때 유용합니다. 프로젝트 수가 1000개 미만인 경우 사이트를 닫고 유지보수 창에서 오프라인으로 마이그레이션을 실행하는 것을 권장합니다(다음 옵션으로 실행할 때 마이그레이션 스크립트 출력 참조 `--report`) 유지보수 창에 사이트를 닫고 오프라인으로 마이그레이션을 실행하는 것을 권장합니다. 프로젝트 수가 많다면 스크립트를 실행하고 진행 상황을 모니터링한 뒤, 현재 상황에 따라 온라인 또는 오프라인으로 계속 실행할지 결정할 수 있습니다. #### 레거시 바이너리 파일 데이터 정리 마이그레이션을 완료하고 프로젝트가 계속해서 모든 파일에 접근할 수 있는 것을 확인했다면, 다음 위치의 이전 파일 저장소를 제거할 수 있습니다 `/var/lib/overleaf/data/user_files`. 이러한 파일은 한동안 보관해 두는 것을 강력히 권장합니다. 먼저 폴더 이름을 변경하여 애플리케이션에서 접근할 수 없게 만들 수 있습니다. ### 문제 해결 여기에 문제 해결 안내를 추가할 예정입니다. 일반적으로는 Server Pro 고객에게만 지원을 제공하지만, 이 마이그레이션의 특성을 고려하여 바이너리 파일 마이그레이션 관련 문제를 겪는 CE 고객에게도 최선을 다해 지원하겠습니다. 바이너리 파일 마이그레이션 스크립트가 실패하면(즉, 오류로 종료되거나 실패한 프로젝트 수가 0이 아닌 수로 출력되면), 다음 세부 정보를 이메일로 지원팀에 보내 주세요 [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)로, 다음 내용을 포함해 주세요: 제목: 바이너리 파일 마이그레이션 문제 본문: * 인스턴스 유형: CE 또는 Server Pro(해당하지 않는 항목 삭제) * 설치 유형: Overleaf 툴킷 또는 `docker-compose.yml` 또는 기타(해당하지 않는 항목 삭제) * 버전: 5.5.x(도구 모음: `$ cat config/version`) * 마이그레이션 스크립트 출력(컨테이너 내부의 다음 위치에 있어야 합니다 `/var/log/overleaf`) * 보고서: (다음 옵션으로 마이그레이션 스크립트를 실행 `--report`) * 처리된 프로젝트: (스크립트의 마지막 실행 기준) * 마이그레이션 기간: * `bin/doctor` 출력(툴킷 사용 시) * 툴킷 버전: `$ git rev-parse HEAD` (툴킷 사용 시) 이메일에 `filestore` 서비스를 이메일에 첨부하세요. 위치는 다음과 같습니다 `/var/log/overleaf/filestore.log` 내의 `sharelatex` 컨테이너 안에서 다음과 같이 내보낼 수 있습니다: ```bash $ docker cp sharelatex:/var/log/overleaf/filestore.log . # 를 스크립트가 출력한 타임스탬프로 바꾸세요 $ docker cp sharelatex:/var/log/overleaf/file-migration-.log . ``` 첨부하기 전에 로그 파일에서 민감한 정보는 모두 삭제해 주세요. #### 누락된 파일 이전 버전의 Server Pro/CE는 사용자 업로드가 완료되기 전에 파일 트리 항목을 생성했기 때문에, 업로드가 실패하면 파일이 누락된 것처럼 보일 수 있었습니다. 모든 파일 트리를 처리할 때 이러한 사례 중 일부가 오류로 보고되는 것을 볼 수 있습니다. 누락된 파일 수가 적다면, 이러한 사례를 수동으로 검토하고 브라우저의 편집기에서 삭제하는 것을 고려하세요. 누락된 파일 수가 많다면, 위의 이메일 템플릿을 참고하여 지원팀에 문의하는 것을 고려하세요. #### 손상된 파일 트리 찾기 예를 들어 파일 이름이 비어 있는 경우처럼 파일 트리가 잘못된 형식을 가진 프로젝트에서는 마이그레이션이 실패할 수 있습니다. 다음을 사용하여 이러한 문제 목록을 찾을 수 있습니다 `find_malformed_filetrees` 데이터베이스의 모든 프로젝트를 검사하는 스크립트: {% 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 %} 잘못된 경로를 수정하려면 `fix_malformed_filetree` 스크립트를 사용하고, 잘못된 경로마다 한 번씩 명령을 실행하세요: {% 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/ko/support/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.