VPS에서 ONLYOFFICE 문서 서버의 메모리 부족 오류 해결 방법

먼저 Linux 호스트 또는 ONLYOFFICE 컨테이너가 메모리 제한에 도달했는지 확인하십시오. 현재 ONLYOFFICE Docs Community Edition 가이드라인에서는 기본 요구 사항으로 4GB RAM과 최소 4GB의 스왑 공간을 권장합니다. Docker 문제 해결 페이지에서는 열려 있는 문서와 동시 사용자 수가 증가함에 따라 메모리 사용량이 늘어나므로 수십 명의 활성 사용자 환경에서는 2~4GB의 RAM 사용량이 정상일 수 있다고 설명합니다. 하드웨어 표에서는 동시 활성 사용자가 400명 이상인 배포 환경에는 Kubernetes 사용을 권장합니다. 이러한 수치는 참고용일 뿐이며 모든 VPS가 동일한 부하를 처리할 수 있다는 보장은 아닙니다. 호스트 운영 체제, 다른 컨테이너, 문서 크기, VPS 제공업체의 제한 사항 등도 영향을 미칩니다.

이 가이드는 Linux VPS에 Docker를 설치하는 일반적인 과정을 다룹니다. 다음 네 단계를 순서대로 진행하세요. 호스트 및 컨테이너 부하 측정, 로그 및 캐시된 파일 확인, 불필요한 부하 감소 또는 컨테이너 용량 제한 수정, 필요한 경우에만 재시작 후 정상적인 사용 환경에서 검증. 명령어 예시 <CONTAINER_ID>에서 사용된 ID 또는 이름은 실제 컨테이너 ID 또는 이름으로 대체해야 합니다 docker ps. 활성 사용자가 있는 에디터를 중지하기 전에 백업을 생성하고 유지보수 일정을 예약하세요.

1. 메모리 압력이 발생하는 위치를 확인합니다.

ONLYOFFICE 컨테이너 내부가 아닌 VPS 호스트에서 첫 번째 명령어를 실행하세요.

free -h
swapon --show
docker stats --no-stream

free -h호스트의 사용 가능한 메모리와 스왑 영역을 보여줍니다. swapon --show스왑이 활성화되어 있는지 확인할 수 있습니다. 에서 docker statsONLYOFFICE의 메모리 사용량을 표시된 제한과 비교하십시오. 호스트에 사용 가능한 메모리가 거의 없고 여러 서비스가 RAM을 사용하고 있다면 VPS 용량이 부족할 수 있습니다. 호스트에 여유 공간이 있지만 ONLYOFFICE 컨테이너가 훨씬 작은 제한에 근접해 있다면 컨테이너 용량 제한이 직접적인 원인일 수 있습니다. 스왑 영역이 거의 가득 찼거나, 지속적인 스왑 사용 또는 과도한 디스크 활동은 호스트가 프로세스를 종료하기 전에도 편집 속도를 저하시킬 수 있습니다.

구성된 Docker 제한 사항도 확인하십시오.

docker inspect --format '{{.HostConfig.Memory}} {{.HostConfig.MemorySwap}}' <CONTAINER_ID>
docker inspect --format '{{.State.OOMKilled}} {{.State.ExitCode}}' <CONTAINER_ID>

첫 번째 명령어는 메모리 및 메모리+스왑 설정을 바이트 단위로 출력합니다. 메모리 제한이 0이라는 것은 일반적으로 컨테이너 메모리에 대한 명시적인 제한이 설정되지 않았음을 의미하며, VPS에 무제한 RAM이 있다는 것을 의미하는 것은 아닙니다. Docker의 메모리-스왑 설정은 메모리와 스왑을 합산한 최대 용량이므로 스왑 용량만을 의미하는 것으로 해석해서는 안 됩니다. 두 번째 명령어는 컨테이너에 대해 Docker가 OOM(메모리 부족)으로 인한 종료를 기록했는지 여부와 마지막 종료 코드를 보고합니다. Docker는 이러한 제한을 Linux 호스트에서 적용되는 제어 사항으로 설명하며, 호스트 전체의 OOM 압력은 하나 이상의 컨테이너에 영향을 미칠 수 있습니다.

2. 컨테이너 로그와 ONLYOFFICE의 알려진 고빈도 사용 사례를 확인하세요.

설정을 변경하거나 파일을 삭제하기 전에 최근 로그를 확인하세요.

docker logs --since 1h <CONTAINER_ID>

반복적인 재시작, 데이터베이스 시작 오류, 편집기 사용 불가 시점 부근의 메시지 등을 확인하십시오. 또한 권한이 있는 경우 호스트 커널 로그에서 메모리 부족 이벤트도 확인하십시오.

sudo dmesg -T | grep -Ei 'out of memory|killed process|oom' | tail -n 30

ONLYOFFICE의 Docker 문제 해결 페이지에서는 메모리 사용량이 예기치 않게 높을 경우, 갇히거나 잊혀진 문서가 있는지 확인하라고 권장합니다 /var/lib/onlyoffice/documentserver/App_Data/cache/files/forgotten/. 먼저 디렉터리의 크기와 내용을 검사하고, 파일을 무턱대고 삭제하지 마십시오. 해당 파일은 복구 또는 문제 해결에 중요할 수 있습니다. 디렉터리 크기가 크거나 계속 증가하는 경우, 파일과 로그를 보존한 후 공식 문제 해결 지침을 따르거나 ONLYOFFICE 지원팀에 문의하여 사용 중인 버전에 맞는 안전한 정리 방법을 확인하십시오.

3. 불필요한 수요를 줄이고 지나치게 작은 도커 용량 제한을 시정합니다.

ONLYOFFICE의 크기 조정 지침에서 "활성 사용자"란 편집기에서 문서를 열어 놓은 사용자를 의미하며, 보기만 하는 사용자도 포함됩니다. 문서를 열어 놓지 않고 통합 플랫폼에 로그인만 한 사용자는 같은 방식으로 계산되지 않습니다. 사용자에게 사용하지 않는 문서 탭을 닫도록 요청하고, 용량이 작은 VPS에서 대규모 편집 작업이 집중적으로 발생하는 것을 방지하십시오. 여러 개의 대용량 스프레드시트나 복잡한 파일을 동시에 열어 부하가 발생하는 경우, 계정 수만으로 추정하기보다는 활동이 적을 때와 실제 최대 부하 시의 메모리 사용량을 비교하십시오.

VPS에서 스왑이 비활성화된 경우 스왑을 추가하면 갑작스러운 트래픽 급증에 대한 단기적인 완충 효과를 얻을 수 있습니다. ONLYOFFICE의 최신 Docker 설치 가이드에서는 최소 4GB의 스왑 공간을 권장하며, 필요한 스왑 공간의 양은 호스트 운영 체제에 따라 달라질 수 있다고 명시하고 있습니다. 스왑은 디스크 기반이며 RAM보다 훨씬 느리기 때문에 충분한 물리적 메모리를 대체할 수는 없습니다. 스왑 파일을 생성하기 전에 이미 스왑 파일이 있는지 확인하고, 사용 가능한 디스크 공간을 확인하고, 파일 시스템과 VPS 제공업체가 스왑 파일 생성 방식을 지원하는지 확인해야 합니다. 스왑 파일을 지원하는 일반적인 Linux 파일 시스템의 예는 다음과 같습니다.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
swapon --show

기존 스왑 파일에 이러한 명령을 실행하지 마십시오 /swapfile. 재부팅 후에도 새로 생성된 스왑 파일을 유지하려면 /etc/fstab기존 항목을 확인한 후 일치하는 항목을 하나만 추가하십시오.

/swapfile none swap sw 0 0

Docker에서 컨테이너 메모리 제한이 낮게 표시되는 경우, 컨테이너를 생성한 Compose 파일 또는 배포 패널을 확인하십시오. VPS의 전체 RAM 용량과 운영 체제, 데이터베이스, 통합 플랫폼 및 기타 서비스에서 사용 중인 메모리를 확인한 후에만 제한을 늘리거나 제거하십시오. 호스트의 모든 RAM을 ONLYOFFICE에 할당하지 마십시오. 호스트 자체의 메모리 용량이 부족한 경우 Docker의 메모리 제한을 변경해도 물리적 메모리가 추가되지 않습니다. VPS 크기를 조정하거나 다른 서비스를 다른 호스트로 이동하십시오. Compose는 메모리 제한을 지원하지만, 구성된 제한은 실제 배포 모드 및 사용 가능한 호스트 메모리와 일치해야 합니다.

Nextcloud 또는 다른 서비스와 함께 ONLYOFFICE를 실행하는 2GB VPS는 공급업체에서 명시한 4GB RAM 기준에 미치지 못합니다. 4GB VPS조차도 호스트 OS와 통합 스택이 메모리를 공유하는 경우 메모리 부족 현상이 발생할 수 있습니다. 이러한 경우 컨테이너를 반복적으로 재시작하는 것보다 더 큰 VPS를 사용하거나 전용 문서 서버 호스트를 사용하는 것이 더 안정적입니다. 현재 ONLYOFFICE 표에서는 400명 이상의 동시 활성 사용자의 경우 Kubernetes 배포를 권장하며 ONLYOFFICE에 문의하여 적절한 규모를 조정하도록 안내하고 있습니다. 이는 단순히 VPS 하나에 작은 스왑 파일을 추가하는 것으로 해결할 수 있는 워크로드가 아닙니다.

4. 안전하게 재시작한 후 결과를 확인하십시오.

불가피한 경우가 아니라면 사용자가 문서를 편집하는 동안에는 문서 서버를 재시작하지 마십시오. ONLYOFFICE에 따르면 문서는 편집 중인 모든 사용자가 문서를 닫은 후에 저장됩니다. 계획된 컨테이너 중지 전에 문제 해결 가이드에서는 아래와 같은 준비 스크립트를 실행할 것을 권장합니다. 이 스크립트는 사용자의 연결이 끊어지는 동안 최대 5분 정도 소요될 수 있습니다. 사용자에게 먼저 경고하고, 백업을 보존하고, 평소 유지 관리 절차를 따르십시오.

sudo docker exec <CONTAINER_ID> documentserver-prepare4shutdown.sh
sudo docker restart <CONTAINER_ID>

Docker Compose를 사용하는 경우, Compose 구성 또는 제어판에서 변경 사항을 영구적으로 적용하고 프로젝트의 일반적인 재시작 워크플로를 사용하십시오. 실행 중인 컨테이너에 대한 일회성 변경 사항은 컨테이너가 다시 생성될 때 사라질 수 있습니다. --oom-kill-disableONLYOFFICE를 계속 실행 상태로 유지하기 위해 OOM(메모리 부족) 우선순위를 극단적으로 설정하지 마십시오. Docker는 호스트 메모리 부족으로 인해 VPS 및 기타 서비스가 위험에 처할 수 있다고 경고합니다.

VPS 또는 컨테이너가 다시 시작된 후, 컨테이너가 정상적으로 작동하는지, 에디터가 테스트 문서를 열고 저장하는 데 문제가 없는지, 호스트 메모리가 사용 가능한 상태로 유지되는지, 컨테이너가 반복적으로 재시작되지 않는지 확인하십시오. 사용량이 많은 시간대에 호스트와 컨테이너의 메모리 사용량을 관찰하십시오. 문서가 닫힌 후에도 메모리 사용량이 계속 증가하거나, '잊혀진 파일' 디렉터리가 커지거나, OOM(메모리 부족) 이벤트가 다시 발생하는 경우 free -h, swapon --show, , docker stats, docker inspect, 최근 로그의 출력을 수집하여 지원팀에 제출하십시오. 한 번의 성공적인 재시작만으로 용량 문제가 해결되었다고 단정짓지 마십시오.

빠른 결정 가이드

공식 참고 자료

• ONLYOFFICE Docs 커뮤니티 에디션 Docker 시스템 요구 사항 및 동시 사용자 안내
• ONLYOFFICE Docs Docker 문제 해결: 메모리 사용량, 누락된 문서, 로그 및 안전한 종료
• ONLYOFFICE Docs 커뮤니티 에디션 Docker 설치 가이드
• Docker 문서: 컨테이너 메모리 및 스왑 제한
• Docker Compose 서비스 리소스 설정