> 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/full-project-history-migration.md).

# (v3.5.13 마이그레이션) 전체 프로젝트 기록 마이그레이션

## 전체 프로젝트 기록 마이그레이션

해당 `3.5.x` 커뮤니티 에디션 릴리스에는 [전체 프로젝트 기록 기능이](https://www.overleaf.com/learn/latex/Using_the_History_feature) 이미 SaaS 서비스에서 제공되고 있습니다, [overleaf.com](http://overleaf.com/)

Overleaf CE로 인스턴스를 업그레이드한 후 `3.5.13`, 모든 새 프로젝트는 기본적으로 전체 프로젝트 기록을 사용하게 됩니다. 기존 프로젝트는 마이그레이션될 때까지 기존 기록 시스템을 계속 사용합니다.

{% hint style="info" %}
다음으로 업그레이드하는 경우 `3.5.13` 으로 업그레이드한 뒤 더 이전 버전으로 다운그레이드하기로 결정했다면, 전체 시스템 백업에서 복원해야 합니다. 에서 생성된 프로젝트의 기록은 `3.5.13` 이전 버전의 Overleaf CE와 호환되지 않습니다.
{% endhint %}

새로운 전체 프로젝트 기록은 사용자에게 여러 가지 개선 사항을 제공합니다:

* 이전 시스템에서는 지원되지 않던 바이너리 파일의 변경 사항을 추적합니다.
* 레이블이 지정된 버전을 지원합니다.
* 시스템 전반의 안정성이 더 높아지고, 데이터 손실 가능성이 줄어듭니다.

참조 [전체 프로젝트 기록 문서](https://www.overleaf.com/learn/latex/Using_the_History_feature) 에서 전체 프로젝트 기록에 대한 자세한 정보를 확인하세요.

### 기존 프로젝트 마이그레이션

{% stepper %}
{% step %}

#### 백업 생성

전체 [백업](https://docs.overleaf.com/on-premises/maintenance/data-and-backups#performing-a-consistent-backup) 인스턴스의 일관된 스냅샷과 함께 **mongo**, **redis** 그리고 **sharelatex** 디렉터리의.
{% endstep %}

{% step %}

#### 업데이트

sharelatex/sharelatex 이미지 버전을 3.5.13으로 업데이트합니다.

Toolkit: `$ bin/upgrade` 스크립트를 사용해 툴킷을 최신 버전으로 업그레이드하고 **config/version** 을 3.5.13으로 수정하세요.
{% endstep %}

{% step %}

#### 인스턴스 시작

가능하다면, 백업을 복원해야 할 경우의 데이터 손실을 방지하기 위해 마이그레이션이 진행되는 동안 사용자가 인스턴스에 접근하지 못하도록 해야 합니다. 다음을 참조하세요 [오프라인 마이그레이션](https://github.com/overleaf/overleaf/wiki/Full-Project-History-Migration/#offline-migration) 에서 이 작업을 수행하는 방법에 대한 자세한 내용을 확인하세요.
{% endstep %}

{% step %}

#### 모든 서비스가 시작되어 실행 중이 될 때까지 기다리세요

모든 서비스가 시작되어 실행 중이 될 때까지 기다리세요(아래 명령 참조)

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
web sharelatex is alive (api)%
```

{% endcode %}
{% endstep %}

{% step %}

#### 마이그레이션 스크립트를 실행하세요

{% code overflow="wrap" %}

```bash
# Overleaf Toolkit 사용자:
$ 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"

# 기존 docker-compose.yml 사용자:
$ 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"
```

{% endcode %}

`--force-clean` 새 시스템에서 부분적으로 마이그레이션된 프로젝트 기록 데이터를 정리합니다. 이를 통해 이전 시도에서 실패한 개별 프로젝트의 마이그레이션을 다시 시도할 수 있습니다;

`--fix-invalid-characters` 새 기록 시스템에서 지원되지 않는 인쇄 불가능 문자를 대체합니다;

`--convert-large-docs-to-file` 편집 가능한 크기 임계값인 2MB를 초과하는 문서를 편집할 수 없는 파일로 변환합니다)

출력은 다음과 같아야 합니다:

```bash
마이그레이션된 프로젝트  :  1
전체 프로젝트     :  51
남은 프로젝트 :  51
마이그레이션할 전체 기록 레코드: 98
마이그레이션 시작...
프로젝트 마이그레이션 중: 63d29b5772dd80015a81bffe
마이그레이션 결과 { upgraded: true, historyType: 'NoneWithoutConversion' }
프로젝트 마이그레이션 중: 63d29c2e72dd80015a81c0a2
마이그레이션 결과 { upgraded: true, historyType: 'NoneWithoutConversion' }

// …

마이그레이션 완료
==================
마이그레이션된 프로젝트:  51
실패한 프로젝트:  0
완료.
```

마이그레이션이 성공하면 종료 코드 `0`, 그리고 실패가 없음을 나타내는 마지막 줄을 받게 됩니다:

```bash
실패한 프로젝트:  0
완료.
```

사용자에게 다시 접근을 열 수 있습니다(다음 단계를 참조하세요). 실패가 있다면 아래의 문제 해결 섹션을 참조하세요. 문제가 즉시 해결되지 않더라도 사이트를 다시 열 수 있으며, 마이그레이션되지 않은 프로젝트는 기존 기록 시스템에 남아 있습니다.
{% endstep %}

{% step %}

#### 사이트 다시 열기

오프라인 마이그레이션을 수행하도록 선택했다면 사이트를 다시 열어야 합니다. 아직 로그인되어 있다면 다음을 수행해야 합니다:

1. 다음 **관리자** 버튼을 누르고 **사이트 관리**
2. 다음으로, 온프레미스 Server Pro 계정에 로그인합니다 **편집기 열기/닫기** 탭
3. 다음으로, 온프레미스 Server Pro 계정에 로그인합니다 **편집기 다시 열기** 버튼을 클릭합니다

브라우저를 닫았다면 `$ bin/up`.
{% endstep %}
{% endstepper %}

#### 오프라인 마이그레이션

기록 마이그레이션 스크립트가 실행되는 동안 사용자가 로그인하지 못하도록 하려면 다음 단계를 따르세요:

* 관리자 계정으로 Overleaf 인스턴스에 로그인하세요
* 다음 **관리자** 버튼을 누르고 **사이트 관리**
* 다음으로, 온프레미스 Server Pro 계정에 로그인합니다 **편집기 열기/닫기** 탭
* 다음 **편집기 닫기** 버튼을 클릭합니다
* 다음 **모든 사용자 연결 해제** 버튼을 클릭합니다

이 작업이 완료되면, 로그인되어 있는 사용자는 유지보수 페이지로 리디렉션되고, 로그인 페이지를 방문하는 새 사용자는 유지보수 페이지를 보게 되며 **않습니다** 로그인할 수 있습니다.

#### 온라인 마이그레이션

애플리케이션이 계속 실행 중인 상태에서도 마이그레이션 스크립트를 실행할 수 있습니다. 고려해야 할 몇 가지 사항이 있습니다:

* 마이그레이션 과정은 CPU 집약적이므로, 스크립트가 실행되는 동안 리소스 사용량을 모니터링해야 합니다.
* 높은 `--concurrency` 값을 사용하면 일부 서비스의 이벤트 루프(`track-changes` 특히)에서 일부 블로킹이 발생할 수 있으며, 이는 UX 경험을 저하시킵니다. 기본값인 `--concurrency=1` 부터 시작할 것을 권장합니다.
* 언제든지 스크립트를 중지할 수 있습니다. 다시 시작하면 중단했던 지점에서 마이그레이션이 이어집니다. 이는 한가한 시간대(예: 밤)에 마이그레이션을 실행하고 싶을 때 유용합니다.

프로젝트 수가 1000개 미만일 때(`db.projects.count()`) 유지보수 창에 사이트를 닫고 오프라인으로 마이그레이션을 실행하는 것을 권장합니다. 프로젝트 수가 많다면 스크립트를 실행하고 진행 상황을 모니터링한 뒤, 현재 상황에 따라 온라인 또는 오프라인으로 계속 실행할지 결정할 수 있습니다.

#### 기존 기록 데이터 정리

Server Pro에 기존 기록 데이터를 정리하는 스크립트가 추가되었습니다 `3.5.6`, `4.0.6` 그리고 `4.1.0`.

{% code overflow="wrap" %}

```bash
bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/history/clean_sl_history_data.js"
```

{% endcode %}

이 스크립트는 모든 프로젝트가 마이그레이션된 후 실행할 수 있습니다. 온라인 마이그레이션을 수행하는 동안 일부 공간을 확보하는 데에도 사용할 수 있습니다.

{% hint style="info" %}
버전 3.5.13 이전의 Server Pro에서는 이 스크립트가 다음의 내용을 삭제합니다 `docHistory` 그리고 `docHistoryIndex` 컬렉션. MongoDB는 문서를 삭제한 후 디스크 공간을 해제하지 않고, 대신 같은 컬렉션의 향후 문서에 그 공간을 재사용합니다. 기록 마이그레이션 이후에는 이 컬렉션들에 다시 아무 것도 기록되지 않으므로 디스크 공간은 사용되지 않은 상태로 남게 됩니다.

디스크 공간을 다시 사용 가능하게 만들고 싶다면 Server Pro 3.5.13(여전히 3.x 릴리스를 사용하는 경우) 또는 Server Pro 4.2.5(4.x 릴리스를 사용하는 경우)로 업그레이드한 뒤 정리 스크립트를 다시 실행할 수 있습니다.

Server Pro에 포함된 정리 스크립트는 최신 패치 릴리스의 `3.5.x` 및 최신 `4.x.x` 에서 최종 단계로 컬렉션을 삭제합니다.

정리 스크립트를 다시 실행해도 안전합니다.
{% endhint %}

### 문제 해결

여기에 문제 해결 조언을 추가할 예정입니다. 일반적으로는 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)로, 다음 내용을 포함해 주세요:

제목: 전체 프로젝트 기록 마이그레이션 문제

* 인스턴스 유형: CE 또는 Server Pro(해당하지 않는 항목 삭제)
* 설치 유형: Overleaf 툴킷 또는 `docker-compose.yml` 또는 기타(해당하지 않는 항목 삭제)
* 버전: 3.5.x(툴킷: `$ cat config/version`)
* 마이그레이션 스크립트 출력(컨테이너 내부의 다음 위치에 있어야 합니다 `/overleaf/services/web`)
* 마이그레이션된 프로젝트: (마이그레이션 스크립트 출력 기준)
* 전체 프로젝트: (마이그레이션 스크립트 출력 기준)
* 남은 프로젝트: (마이그레이션 스크립트 출력 기준)
* 마이그레이션 기간:
* `bin/doctor` 출력(툴킷 사용 시)
* 툴킷 버전: `$ git rev-parse HEAD` (툴킷 사용 시)

이메일에 `history-v1`, `project-history` 그리고 `track-changes` 서비스의 로그 파일을 첨부하는 것을 고려하세요. 파일은 다음 위치에서 찾을 수 있습니다 `/var/log/sharelatex` 내의 `sharelatex` 컨테이너 안에서 다음과 같이 내보낼 수 있습니다:

```bash
$ 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` 데이터베이스의 모든 프로젝트를 검사하는 스크립트:

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; node scripts/find_malformed_filetrees.js"
잘못된 경로: 123456789012345678901234 rootFolder.0.1.2.3
잘못된 경로: 123456789012345678901234 rootFolder.0.4.5.6
...
```

{% endcode %}

잘못된 경로를 수정하려면 `fix_malformed_filetree` 스크립트를 사용하고, 잘못된 경로마다 한 번씩 명령을 실행하세요:

{% code overflow="wrap" %}

```bash
$ 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"
...
```

{% endcode %}

#### 전체 프로젝트 기록에서 기존 기록으로 프로젝트 다운그레이드

전체 프로젝트 기록으로 마이그레이션된 프로젝트가 있지만 기존 기록으로 되돌리고 싶다면 `downgrade_project` 스크립트를 다음과 같이 사용하세요:

{% code overflow="wrap" %}

```bash
$ bin/docker-compose exec sharelatex /bin/bash -c "cd /overleaf/services/web; PROJECT_ID=YOUR
```

{% 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/full-project-history-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.