> ## 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.
# (v3.5.13 마이그레이션) 전체 프로젝트 기록 마이그레이션
## 전체 프로젝트 기록 마이그레이션
Community Edition의 `3.5.x` 릴리스에는 SaaS 서비스인 [overleaf.com](http://overleaf.com/)에서 이미 제공되고 있는 [전체 프로젝트 기록 기능](https://www.overleaf.com/learn/latex/Using_the_History_feature)이 포함되어 있습니다.
인스턴스를 Overleaf CE `3.5.13`으로 업그레이드하면 모든 새 프로젝트는 기본적으로 전체 프로젝트 기록(Full Project History)을 사용합니다. 기존 프로젝트는 마이그레이션될 때까지 레거시 기록 시스템을 계속 사용합니다.
`3.5.13`으로 업그레이드한 후 이전 버전으로 다운그레이드하기로 결정한 경우, 전체 시스템 백업에서 복원해야 합니다. `3.5.13`에서 생성된 프로젝트의 기록은 이전 버전의 Overleaf CE와 호환되지 않습니다.
새로운 전체 프로젝트 기록은 사용자에게 다음과 같은 여러 개선 사항을 제공합니다:
* 레거시 시스템에서는 지원되지 않던 바이너리 파일의 변경 사항을 추적합니다.
* 레이블이 지정된 버전을 지원합니다.
* 시스템이 전반적으로 더 견고하며 데이터 손실 가능성이 줄어듭니다.
전체 프로젝트 기록에 대한 자세한 내용은 [전체 프로젝트 기록 문서](https://www.overleaf.com/learn/latex/Using_the_History_feature)를 확인하세요.
### 기존 프로젝트 마이그레이션
**mongo**, **redis**, **sharelatex** 디렉터리의 일관된 스냅샷으로 인스턴스의 전체 [백업](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)을 생성합니다.
sharelatex/sharelatex 이미지 버전을 3.5.13으로 업데이트합니다.
Toolkit: `$ bin/upgrade` 스크립트를 사용해 Toolkit을 최신 버전으로 업그레이드하고 **config/version**을 3.5.13으로 편집합니다.
이상적으로는 백업을 복원해야 할 경우의 데이터 손실을 피하기 위해 마이그레이션이 진행되는 동안 사용자가 인스턴스에 접근하지 못하도록 하는 것이 좋습니다. 방법에 대한 자세한 내용은 [오프라인 마이그레이션](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration)을 참조하세요.
모든 서비스가 실행될 때까지 기다립니다(아래 명령 참조).
```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
web sharelatex is alive (api)%
```
```bash wrap theme={null}
# Overleaf Toolkit users:
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
# legacy docker-compose.yml users:
$ docker exec sharelatex /bin/bash -c "cd /overleaf/services/web; VERBOSE_LOGGING=true node scripts/history/migrate_history.js --force-clean --fix-invalid-characters --convert-large-docs-to-file"
```
`--force-clean`은 새 시스템에서 부분적으로 마이그레이션된 프로젝트 기록 데이터를 지워, 이전 시도에서 실패한 개별 프로젝트의 마이그레이션을 다시 시도할 수 있게 합니다.
`--fix-invalid-characters`는 새 기록 시스템에서 지원되지 않는 인쇄 불가능한 문자를 대체합니다.
`--convert-large-docs-to-file`은 편집 가능한 크기 임계값인 2MB를 초과하는 문서를 편집할 수 없는 파일로 변환합니다.
출력은 다음과 같아야 합니다:
```bash theme={null}
Migrated Projects : 1
Total Projects : 51
Remaining Projects : 51
Total history records to migrate: 98
Starting migration...
Migrating project: 63d29b5772dd80015a81bffe
migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
Migrating project: 63d29c2e72dd80015a81c0a2
migration result { upgraded: true, historyType: 'NoneWithoutConversion' }
// …
Migration complete
==================
Projects migrated: 51
Projects failed: 0
Done.
```
마이그레이션이 성공하면 종료 코드 `0`과 함께 실패가 없음을 나타내는 마지막 줄이 표시됩니다:
```bash theme={null}
Projects failed: 0
Done.
```
이제 사용자의 접근을 다시 열 수 있습니다(다음 단계 참조). 실패가 있는 경우 아래 문제 해결 섹션을 참조하세요. 문제가 즉시 해결되지 않더라도 사이트를 다시 열 수 있으며, 마이그레이션되지 않은 프로젝트는 레거시 기록 시스템에 남아 있습니다.
오프라인 마이그레이션을 수행하기로 한 경우 사이트를 다시 열어야 합니다. 아직 로그인되어 있다면 다음을 수행하세요:
1. **Admin** 버튼을 클릭하고 **Manage Site**를 선택합니다
2. **Open/Close Editor** 탭을 클릭합니다
3. **Reopen Editor** 버튼을 클릭합니다
브라우저를 닫은 경우 `$ bin/up`으로 사이트를 다시 시작해야 합니다.
#### 오프라인 마이그레이션
기록 마이그레이션 스크립트가 실행되는 동안 사용자가 로그인하지 못하도록 하려면 다음 단계를 따르세요:
* 관리자 계정으로 Overleaf 인스턴스에 로그인합니다
* **Admin** 버튼을 클릭하고 **Manage Site**를 선택합니다
* **Open/Close Editor** 탭을 클릭합니다
* **Close Editor** 버튼을 클릭합니다
* **Disconnect all users** 버튼을 클릭합니다
이 작업을 완료하면 로그인되어 있던 사용자는 유지 관리 페이지로 리디렉션되며, 로그인 페이지를 방문하는 새 사용자는 유지 관리 페이지를 보게 되고 로그인할 수 **없습니다**.
#### 온라인 마이그레이션
애플리케이션이 실행 중인 상태에서도 마이그레이션 스크립트를 실행할 수 있습니다. 몇 가지 고려 사항이 있습니다:
* 마이그레이션 과정은 CPU를 많이 사용하므로 스크립트가 실행되는 동안 리소스 사용량을 모니터링해야 합니다.
* `--concurrency` 값이 높으면 일부 서비스(특히 `track-changes`)의 이벤트 루프가 차단될 수 있으며, 이로 인해 사용자 경험이 저하될 수 있습니다. 기본값인 `--concurrency=1`로 시작하는 것을 권장합니다.
* 언제든지 스크립트를 중지할 수 있습니다. 다시 시작하면 중단한 지점부터 마이그레이션이 재개됩니다. 덜 바쁜 시간대(예: 야간)에 마이그레이션을 실행하려는 경우에 유용합니다.
프로젝트 수가 1000개 미만(`db.projects.count()`)인 경우에는 사이트를 닫고 유지 관리 시간에 오프라인으로 마이그레이션을 실행할 것을 권장합니다. 프로젝트 수가 많은 경우 스크립트를 실행하고 진행 상황을 모니터링한 다음, 상황에 따라 온라인으로 계속 실행할지 오프라인으로 실행할지 결정할 수 있습니다.
#### 레거시 기록 데이터 정리
레거시 기록 데이터를 정리하는 스크립트가 Server Pro `3.5.6`, `4.0.6`, `4.1.0`에 추가되었습니다.
```bash wrap theme={null}
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```
이 스크립트는 모든 프로젝트가 마이그레이션된 후에 실행할 수 있습니다. 온라인 마이그레이션을 수행하는 동안 일부 공간을 확보하는 데에도 사용할 수 있습니다.
버전 3.5.13 이전의 Server Pro에서는 이 스크립트가 `docHistory` 및 `docHistoryIndex` 컬렉션의 내용을 삭제합니다. MongoDB는 문서를 삭제한 후에도 디스크 공간을 해제하지 않고, 대신 같은 컬렉션의 향후 문서를 위해 그 공간을 재사용합니다. 기록 마이그레이션 후에는 이 컬렉션에 다시 쓰는 작업이 없으므로 디스크 공간은 사용되지 않은 채로 남습니다.
디스크 공간을 다시 사용할 수 있게 하려면 Server Pro 3.5.13(3.x 릴리스를 계속 사용하는 경우) 또는 Server Pro 4.2.5(4.x 릴리스를 사용하는 경우)로 업그레이드한 후 정리 스크립트를 다시 실행하세요.
`3.5.x`의 최신 패치 릴리스와 최신 `4.x.x`의 Server Pro에 포함된 정리 스크립트는 마지막 단계로 컬렉션을 삭제합니다.
정리 스크립트는 다시 실행해도 안전합니다.
### 문제 해결
여기에 문제 해결 조언을 추가할 예정입니다. 일반적으로는 Server Pro 고객에게만 지원을 제공하지만, 이 마이그레이션의 특성을 고려하여 전체 프로젝트 기록 마이그레이션과 관련된 문제를 겪는 CE 고객도 최선을 다해 지원할 것입니다.
전체 프로젝트 기록 마이그레이션 스크립트가 실패하는 경우(즉, 오류와 함께 종료되거나 실패한 프로젝트 수가 0이 아닌 경우), 다음 세부 정보를 이메일 [support+historymigration@overleaf.com](mailto:support+historymigration@overleaf.com?subject=Full%20project%20history%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)로 지원팀에 보내 주세요:
제목: Full project history migration problem
* Instance Type: CE 또는 Server Pro(해당하지 않는 항목 삭제)
* Installation Type: Overleaf toolkit 또는 `docker-compose.yml` 또는 기타(해당하지 않는 항목 삭제)
* Version: 3.5.x (toolkit: `$ cat config/version`)
* 마이그레이션 스크립트 출력(컨테이너 내 `/overleaf/services/web` 아래에 있어야 함)
* Migrated Projects: (마이그레이션 스크립트 출력 기준)
* Total Projects: (마이그레이션 스크립트 출력 기준)
* Remaining Projects: (마이그레이션 스크립트 출력 기준)
* 마이그레이션 소요 시간:
* `bin/doctor` 출력(Toolkit 사용 시)
* Toolkit 버전: `$ git rev-parse HEAD` (Toolkit 사용 시)
이메일에 `history-v1`, `project-history`, `track-changes` 서비스의 로그 파일을 첨부하는 것을 고려해 주세요. 이 파일은 `sharelatex` 컨테이너 내부의 `/var/log/sharelatex`에서 찾을 수 있으며 다음과 같이 내보낼 수 있습니다:
```bash theme={null}
$ docker cp sharelatex:/var/log/sharelatex/history-v1.log history-v1.log
$ docker cp sharelatex:/var/log/sharelatex/project-history.log project-history.log
$ docker cp sharelatex:/var/log/sharelatex/track-changes.log track-changes.log
```
첨부하기 전에 로그 파일에서 민감한 정보를 삭제해 주세요.
#### 손상된 파일 트리 찾기
파일 트리가 잘못된 형식인 프로젝트(예: 파일 이름이 비어 있는 경우)는 마이그레이션이 실패할 수 있습니다. 데이터베이스의 모든 프로젝트를 검사하는 `find_malformed_filetrees` 스크립트를 사용해 이러한 문제 목록을 찾을 수 있습니다:
```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
BAD PATH: 123456789012345678901234 rootFolder.0.1.2.3
BAD PATH: 123456789012345678901234 rootFolder.0.4.5.6
...
```
잘못된 경로를 수정하려면 `fix_malformed_filetree` 스크립트를 사용하여 잘못된 경로마다 명령을 한 번씩 실행하세요:
```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.1.2.3"
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/fix_malformed_filetree.js 123456789012345678901234 rootFolder.0.4.5.6"
...
```
#### 프로젝트를 전체 프로젝트 기록에서 레거시 기록으로 다운그레이드
전체 프로젝트 기록으로 마이그레이션된 프로젝트를 레거시 기록으로 되돌리려면 다음과 같이 `downgrade_project` 스크립트를 사용하세요:
```bash wrap theme={null}
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.