메인 콘텐츠로 건너뛰기
이전 버전을 사용 중이라면 경로 이름에서 overleaf 대신 sharelatex를 사용하세요.
Overleaf 컨테이너에 NFS 파일 시스템을 마운트하는 것은 기술적으로 가능하지만 권장하지 않으며, 다양한 유형의 성능 오류가 발생할 수 있습니다.컴파일 시 흔히 발생하는 오류는 다음과 같습니다.
특히 컴파일 데이터에 사용되는 디렉터리처럼 일시적인 데이터에는 NFS 기반 파일 시스템을 사용하지 않을 것을 권장합니다. 다음 디렉터리에는 로컬 스크래치 디스크, 가급적 로컬 SSD를 사용하는 것을 권장합니다.docker-compose 기반 구성의 경우, 애플리케이션의 경로를 변경하지 않도록 NFS에서의 바인드 마운트를 재정의하는 방법을 권장합니다. 다음은 /scratch에 마운트된 스크래치 디스크를 사용하는 docker-compose 구성 발췌 예시입니다.
docker-compose excerpt
업데이트 후 기존 파일을 NFS에서 새 위치로 마이그레이션할 필요는 없습니다. LaTeX 컴파일러가 전체 컴파일을 다시 실행하여 모든 파일을 재생성할 수 있습니다.자세한 내용은 다음을 참고하세요: https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-with-an-nfs-filesystem
Windows 또는 macOS에서 Overleaf를 실행하는 경우, mongo 서비스가 다음 오류와 함께 재시작에 실패할 수 있습니다.
Example error
이 오류는 Windows에 마운트된 디렉터리처럼 MongoDB가 요구하는 시맨틱을 제공하지 않는 파일 시스템에서 MongoDB 데이터를 바인드 마운트할 때 발생할 수 있습니다. WSL 2를 사용하는 Windows에서는 Toolkit을 Ubuntu의 Linux 홈 디렉터리 아래에 두고 기본 바인드 마운트를 사용하세요. 플랫폼 가이드의 MongoDB 확인 사항을 참조하세요.Docker가 관리하는 스토리지가 필요한 새 설치의 경우, 다음 오버라이드는 명명된 볼륨을 사용합니다(MongoDB 이미지 스토리지 안내 참고). 기존 설치에서는 마운트를 변경해도 데이터가 마이그레이션되지 않습니다. 전환하기 전에 데이터베이스/캐시를 백업하고 복원하세요. 그렇지 않으면 서비스에 빈 볼륨이 보이게 됩니다. 기존 구성이 있다면 병합하여 config/docker-compose.override.yml에 다음을 추가하세요.
config/docker-compose.override.yml
자세한 내용은 다음을 참고하세요: https://docs.overleaf.com/on-premises/support/troubleshooting#running-overleaf-on-windows-or-macos-results-in-the-mongoservice-not-starting
docker logs redis 명령을 사용하여 로그 사본을 출력하세요.Fatal: Can't initialize Background Jobs 줄이 보인다면 전체 출력은 다음과 비슷할 것입니다.
Redis log example
이는 현재 사용 중인 Docker 버전과 관련이 있을 수 있습니다. 20.10.10 이상 버전으로 업데이트하면 이 문제가 해결됩니다.자세한 내용은 Redis 업스트림 이슈를 참고하세요: https://github.com/redis/redis/issues/12362참고: https://docs.overleaf.com/on-premises/support/troubleshooting#upgrading-to-redis-6.2-results-in-a-restart-loop
Community Edition에서는 모든 컴파일이 동일한 sharelatex 컨테이너 안에서 이루어지기 때문에 \write18 명령이 기본적으로 비활성화되어 있습니다. 이것이 더 안전한 기본값입니다.pdflatex에서 이를 활성화하려면 프로젝트 루트에 다음 내용으로 latexmkrc 파일을 만드세요.
latexmkrc
그런 다음 다시 컴파일해 보세요.참고: https://docs.overleaf.com/on-premises/support/troubleshooting#please-verify-that-you-have-enabled-system-calls.-for-pdflatex-this-is-pdflatex-shell-escape
이 오류는 mongo 컨테이너가 계속 충돌하고 재시작된다는 의미입니다. bin/up은 MongoDB를 시작한 다음 그 안에서 명령을 실행하는데, 컨테이너가 재시작되는 동안 이 명령이 실패합니다. bin/docker-compose ps에서 mongo 서비스가 Restarting으로 표시됩니다.실제 원인을 찾으려면 MongoDB 로그를 확인하세요.
일반적인 원인은 다음과 같습니다.
  • CPU가 AVX를 지원하지 않습니다. MongoDB 5.0 이상은 x86-64에서 AVX가 필요하며, 로그에 MongoDB 5.0+ requires a CPU with AVX support가 표시됩니다. 가상 머신에서는 AVX가 전달되도록 CPU 유형을 host로 설정하세요.
  • Linux 커널 6.19 ~ 7.0.13. MongoDB는 이 커널에서 시작을 거부합니다. 해결 방법은 소프트웨어 요구 사항을 참조하세요.
  • 데이터가 이전 MongoDB 버전으로 생성되었습니다. MongoDB 8.0은 4.4 또는 5.0의 데이터를 직접 열 수 없습니다. 메이저 버전을 하나씩 업그레이드하세요. MongoDB 업데이트를 참조하세요.
Ayakaleaf Pro에서는 정상적인 동작이므로 무시해도 됩니다. 이 메시지는 OVERLEAF_IS_SERVER_PRO가 true가 아닐 때 출력되며, Ayakaleaf Pro 이미지에서는 이것이 기본 상태입니다. Ayakaleaf Pro에는 이 변수가 필요하지 않으므로 설정하지 않은 상태로 두세요.
Overleaf가 시작되기 전에 컨테이너는 시작 검사를 실행하며, 그중 하나라도 실패하면 종료됩니다. Toolkit은 restart: always로 컨테이너를 실행하므로 Docker가 컨테이너를 다시 시작하고, 같은 검사가 다시 실패합니다. 시작 출력에 실패한 검사의 이름이 표시됩니다.
일반적인 원인은 다음과 같습니다.
  • Missing required secrets: config/variables.env에 OVERLEAF_INVITE_TOKEN_SECRET을 설정하세요. 환경 변수를 참조하세요.
  • ShareLaTeX to Overleaf rebranding: 구성에서 여전히 SHARELATEX_ 변수나 경로를 사용하고 있습니다. 메시지에 안내된 대로 이름을 변경하세요.
  • Checking can connect to mongo and redis 이후의 오류: Overleaf가 MongoDB 또는 Redis에 연결할 수 없습니다. bin/logs mongo와 bin/logs redis를 확인하세요.
원인을 해결한 후 bin/up -d를 실행하세요.
컨테이너는 시작할 때마다 시작 스크립트를 하나씩 차례로 실행하며, 로그에는 각 스크립트가 *** Running /etc/my_init.d/<script>...로 표시됩니다. 910_initiate_doc_version_recovery는 한때 Overleaf 5.0.1을 실행했던 인스턴스에서만 할 일이 있습니다. 다른 인스턴스에서는 No recovery of doc versions needed.를 출력하고 시작이 계속됩니다. 이 출력은 OVERLEAF_DATA_PATH의 data/history/doc-version-recovery.log에도 기록됩니다.종료 코드와 bin/docker-compose logs --tail=100 sharelatex의 마지막 부분을 보면 무슨 일이 일어났는지 알 수 있습니다.
  • 종료 코드 2이고 로그가 *** Init system aborted.로 끝나는 경우: 예를 들어 bin/stop, docker stop 또는 bin/up에서의 Ctrl+C로 컨테이너가 중지된 것입니다. 마지막 Running 줄의 스크립트는 그 순간 실행 중이던 스크립트일 뿐, 실패한 것이 아닙니다. bin/up -d로 컨테이너를 다시 시작하고 시작이 완료될 때까지 기다리세요.
  • 종료 코드 1이고 로그에 *** /etc/my_init.d/<script> failed with status <n>가 표시되는 경우: 해당 스크립트가 실패한 것이며, 오류는 바로 위 줄에 있습니다. 910_initiate_doc_version_recovery가 Detected unflushed changes while recovering doc versions로 실패했다면, 인스턴스가 5.0.1을 실행했고 아직 플러시되지 않은 편집 내용이 있는 것입니다. 공식 Doc version recovery 가이드를 따르세요.
이 페이지는 계정에 로그인되어 있지만 해당 페이지를 열 권한이 없을 때 표시됩니다. 예를 들어 관리자가 아닌 계정으로 관리자 페이지를 열거나, 공유받지 않은 프로젝트를 여는 경우입니다.관리자 페이지를 열려면 관리자 계정으로 로그인하세요. 기존 관리자가 다른 계정을 관리자로 지정하거나, create-user --admin 명령으로 관리자 계정을 만들 수 있습니다. 사용자 관리를 참조하세요. 개발 환경(develop/)에서는 관리자 페이지에 develop/dev.env의 ADMIN_PRIVILEGE_AVAILABLE=true도 필요합니다. Ayakaleaf Pro 이미지에는 이미 설정되어 있습니다.
마지막 수정일 2026년 11월 8일