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

​

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

Community Edition의 3.5.x 릴리스에는 SaaS 서비스인 overleaf.com에서 이미 제공되고 있는 전체 프로젝트 기록 기능이 포함되어 있습니다.

인스턴스를 Overleaf CE 3.5.13으로 업그레이드하면 모든 새 프로젝트는 기본적으로 전체 프로젝트 기록(Full Project History)을 사용합니다. 기존 프로젝트는 마이그레이션될 때까지 레거시 기록 시스템을 계속 사용합니다.

3.5.13으로 업그레이드한 후 이전 버전으로 다운그레이드하기로 결정한 경우, 전체 시스템 백업에서 복원해야 합니다. 3.5.13에서 생성된 프로젝트의 기록은 이전 버전의 Overleaf CE와 호환되지 않습니다.

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

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

전체 프로젝트 기록에 대한 자세한 내용은 전체 프로젝트 기록 문서를 확인하세요.

​

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

1. 백업 생성

   mongo, redis, sharelatex 디렉터리의 일관된 스냅샷으로 인스턴스의 전체 백업을 생성합니다.

2. 업데이트

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

   Toolkit: $ bin/upgrade 스크립트를 사용해 Toolkit을 최신 버전으로 업그레이드하고 config/version을 3.5.13으로 편집합니다.

3. 인스턴스 시작

   이상적으로는 백업을 복원해야 할 경우의 데이터 손실을 피하기 위해 마이그레이션이 진행되는 동안 사용자가 인스턴스에 접근하지 못하도록 하는 것이 좋습니다. 방법에 대한 자세한 내용은 오프라인 마이그레이션을 참조하세요.

4. 모든 서비스가 실행될 때까지 대기

   모든 서비스가 실행될 때까지 기다립니다(아래 명령 참조).

   $ bin/docker-compose exec sharelatex /bin/bash -c "curl http://localhost:3000/status"
   web sharelatex is alive (api)%
   
5. 마이그레이션 스크립트 실행

   # 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를 초과하는 문서를 편집할 수 없는 파일로 변환합니다.

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

   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과 함께 실패가 없음을 나타내는 마지막 줄이 표시됩니다:

   Projects failed:  0
   Done.
   

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

6. 사이트 다시 열기

   오프라인 마이그레이션을 수행하기로 한 경우 사이트를 다시 열어야 합니다. 아직 로그인되어 있다면 다음을 수행하세요:

   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에 추가되었습니다.

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이 아닌 경우), 다음 세부 정보를 이메일 [e-mail]로 지원팀에 보내 주세요:

제목: 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에서 찾을 수 있으며 다음과 같이 내보낼 수 있습니다:

$ 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 스크립트를 사용해 이러한 문제 목록을 찾을 수 있습니다:

$ 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 스크립트를 사용하여 잘못된 경로마다 명령을 한 번씩 실행하세요:

$ 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 스크립트를 사용하세요:

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