ONLYOFFICE 문서 서버의 VPS 메모리 부족 문제를 해결하세요

VPS 메모리 부족으로 ONLYOFFICE Document Server가 충돌하거나 재시작되는 경우, 먼저 메모리 부족 이벤트가 발생했는지 확인하고 Docker 메모리 제한이 부족한지 점검하십시오. 그런 다음 워크로드에 필요한 충분한 물리적 RAM을 확보하고 스왑 공간은 안전 장치로만 추가하십시오. 편집기를 반복적으로 재시작하는 것은 지속적인 용량 부족 문제를 해결하지 못합니다.

1. 메모리 부족 현상이 오류의 원인임을 증명하십시오.

ONLYOFFICE 통합 설정이 아닌 Linux VPS에서 시작하십시오. "문서를 로드할 수 없습니다"와 같은 브라우저 메시지는 네트워크 또는 인증 문제로 인해 발생할 수도 있으므로 Linux 메모리 부족(OOM) 킬러가 실제로 프로세스를 종료했는지 확인하는 것이 중요합니다.

SSH를 통해 다음 명령어를 실행하세요. ` onlyoffice-document-server:`로 표시된 컨테이너 이름으로 바꾸세요 docker ps -a.

free -h
docker ps -a
docker stats --no-stream onlyoffice-document-server
docker inspect --format '{{.State.OOMKilled}} {{.State.ExitCode}} {{.HostConfig.Memory}} {{.HostConfig.MemorySwap}}' onlyoffice-document-server

free -h`docker stats` 명령 은 호스트의 사용 가능한 RAM과 스왑 공간을 표시합니다. `docker stats` docker stats명령은 실행 중인 컨테이너의 메모리 사용량을 측정하는 반면, `spect` 명령은 컨테이너의 OOM(메모리 부족)으로 인한 종료 상태, 마지막 종료 코드, 구성된 리소스 제한(바이트 단위)을 보고합니다. 0이 아닌 HostConfig.Memory값은 명시적인 메모리 제한이 설정되었음을 나타냅니다. Docker의 메모리 통계는 특정 파일 캐시를 제외할 수 있으므로, 전체적인 상황을 보여주는 지표로 간주하기보다는 호스트 측정값과 비교해야 합니다. 자세한 내용은 Docker 통계 참조를 확인하세요 .

컨테이너가 중지된 경우 docker stats이전 최고치를 표시할 수 없습니다. 대신 커널 로그와 최근 애플리케이션 메시지를 확인하십시오.

sudo journalctl -k --since "-2 hours" | grep -Ei 'out of memory|killed process|oom'
docker logs --tail 100 onlyoffice-document-server

"메모리 부족" 또는 "프로세스 종료됨"을 언급하는 커널 메시지는 관련된 프로세스를 식별하는 데 도움이 됩니다. OOMKilled=true이는 컨테이너의 OOM(메모리 부족) 이벤트에 대한 강력한 증거이지만, false컨테이너가 계속 실행되는 동안 호스트 커널이 자식 프로세스를 종료했을 가능성을 배제하는 것은 아닙니다. 마찬가지로 종료 코드 137은 SIGKILL 종료만을 나타낼 뿐, 그 원인을 알려주지는 않습니다. OOM 증거가 없는 경우, RAM을 추가하기 전에 로그 및 연결 실패 원인을 조사하십시오.

2. 다른 설정을 조정하기 전에 VPS에 충분한 RAM을 할당하십시오.

2026년 10월 현재, ONLYOFFICE의 공식 Docker Document Server README 파일 에는 권장 사양으로 4GB 이상의 RAM과 최소 2GB의 스왑 공간이 명시되어 있습니다. 별도의 공식 원클릭 설치 프로그램 설명서에서는 Docker 테스트 환경에 4GB RAM을 권장하고, 프로덕션 환경에는 8GB 이상을 권장하며, 설치 프로그램 요구 사항에 최소 4GB의 스왑 공간을 명시하고 있습니다. 이러한 문서들은 서로 다른 배포 환경을 설명하고 있으므로, 4GB RAM이 프로덕션 환경에서 안정적인 성능을 보장하는 것은 아닙니다.

VPS에 1~2GB의 RAM만 있다면 Docker 기반 설치 환경에서 가장 효과적인 해결책은 요금제를 업그레이드하는 것입니다. 이미 4GB의 RAM이 있다면 운영 체제, 데이터베이스, 리버스 프록시, Nextcloud 및 기타 컨테이너에서 사용되는 메모리 용량을 확인해 보세요. 유휴 상태일 때는 안정적으로 작동하는 서버라도 여러 사용자가 동시에 문서를 열거나 대용량 스프레드시트를 변환하는 경우 메모리 부족 현상이 발생할 수 있습니다.

사용량이 많은 호스트에서는 ps aux --sort=-rss | head메모리 사용량이 많은 프로세스를 식별하는 데 사용하고, docker stats대표적인 편집 세션 동안 이 과정을 반복하십시오. 사용 가능한 모든 RAM을 ONLYOFFICE에 할당하는 대신 시스템의 다른 부분에 여유 공간을 확보하십시오. 지속적인 수요가 호스트 용량을 초과하는 경우, 다른 서비스를 이동하거나 VPS를 업그레이드하십시오. 애플리케이션 수준의 설정 변경으로는 물리적 메모리 부족 문제를 해결할 수 없습니다.

Docker 메모리 제한이 실수로 발생했는지 확인하십시오.

Docker 컨테이너는 기본적으로 메모리 제한이 없지만, 배포 시 Docker 명령어 --memory나 Compose 설정을 통해 제한을 지정할 수 있습니다 mem_limit. 예를 들어, 컨테이너 메모리를 2GB로 제한하면 호스트에 8GB의 여유 RAM이 있더라도 OOM(메모리 부족) 오류가 발생하여 컨테이너가 종료될 수 있습니다. 제한을 변경하기 전에 실제 메모리 사용량을 확인하십시오. 제한이 불필요하게 낮으면 측정값과 호스트의 남은 용량을 고려하여 Docker 명령어 실행 또는 Compose 설정을 적절한 값으로 조정해야 합니다. Docker의 리소스 제약 조건 문서 와 Compose 서비스 사양을 참조하십시오 .

공유 VPS에서 메모리 할당을 무제한으로 설정하지 마십시오. 이렇게 하면 다른 서비스가 호스트 전체의 메모리 부족(OOM) 오류로 인해 종료될 수 있습니다. 또한 --memory-swapCompose의 설정도 확인하십시오 memswap_limit. Docker는 해당 설정에서 RAM과 스왑을 합산하여 계산합니다. RAM과 스왑 합산 제한을 동일하게 설정하면 컨테이너의 스왑 사용이 사실상 비활성화됩니다. Compose를 사용하여 ONLYOFFICE를 관리하는 경우, 컨테이너를 다시 생성해도 설정이 유지되도록 Compose 파일에서 해당 설정을 변경하십시오.

3. VPS에 스왑 버퍼가 없는 경우 스왑 버퍼를 추가하십시오.

스왑은 일시적인 메모리 사용량 급증을 흡수할 수 있지만 디스크에 저장되므로 RAM보다 훨씬 느립니다. 먼저 스왑 파일 생성 여부를 확인하십시오 swapon --show. 다음 예제는 스왑 파일이 존재하지 않고 공급자가 스왑을 허용하는 df -h /경우, ext4와 같은 호환 가능한 로컬 파일 시스템을 사용하여 VPS에 2GiB 스왑 파일을 추가합니다./swapfile

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
swapon --show
free -h

새 스왑 파일은 swapon작업이 성공적으로 완료된 후에만 영구적으로 저장됩니다. 기존 항목이 grep -F '/swapfile' /etc/fstab있는지 확인하려면 `;`를 사용하고, 없으면 한 번만 추가합니다.

echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Btrfs, 네트워크 파일 시스템 및 기타 구성에서 스왑 파일을 생성하는 방법은 다릅니다. 기존 스왑 파일에 이러한 명령을 실행하거나 fallocate모든 환경에서 작동한다고 가정하지 마십시오. Linux swapon 매뉴얼에서 파일 시스템별 제한 사항을 확인할 수 있습니다. 일반적인 편집 작업 부하에서 VPS가 자주 스왑을 사용하는 경우, 스왑 파일 크기를 늘리는 것보다 RAM을 더 확보하는 것이 좋습니다.

4. 실제 편집 작업 부하 환경에서 서버를 다시 확인하십시오.

VPS 플랜을 변경하거나 스왑을 활성화하는 경우 ONLYOFFICE 구성을 수정할 필요가 없는 경우가 많습니다. Docker 배포 설정을 변경한 경우 유지 관리 일정을 예약하고 변경 사항을 적용할 때 기존 마운트, 비밀 키, 인증서 경로 및 통합 설정을 유지하십시오. ONLYOFFICE Docker README 문서에는 documentserver-prepare4shutdown.sh계획된 종료에 대한 내용이 포함되어 있으며, 편집자 연결을 해제하는 데 몇 분이 소요될 수 있음을 경고합니다. 사용 중인 문서 서버를 임의로 다시 생성하거나 재시작하지 마십시오. 저장되지 않은 변경 사항이 영향을 받을 수 있습니다.

서비스가 준비되면 컨테이너가 실행 중인지 확인하고 메모리 상태를 다시 검사하십시오.

docker ps --filter name=onlyoffice-document-server
docker stats --no-stream onlyoffice-document-server
docker inspect --format '{{.State.OOMKilled}}' onlyoffice-document-server
docker exec onlyoffice-document-server curl -fsS http://localhost:8000/info/info.json

마지막 점검은 공식 ONLYOFFICE Docker Compose 상태 점검 에 나와 있는 내부 정보 엔드포인트를 사용합니다 . VPS에서 8000번 포트가 공개되지 않았을 수 있으므로 컨테이너 내부에서 실행해야 합니다. 응답하는 엔드포인트는 서비스 가용성을 나타내는 것이지, 모든 스토리지 통합 또는 저장 콜백이 정상적으로 작동한다는 것을 의미하는 것은 아닙니다.

메모리 문제가 해결되었는지 확인하십시오.

Nextcloud, ownCloud 또는 기타 통합 서비스를 통해 작은 문서를 다시 열고, 대표적인 큰 문서를 하나 열어보세요. 간단한 편집을 저장하고 파일을 다시 열었을 때 편집 내용이 나타나는지 확인하세요. 이전에 오류가 발생했던 사용 기간 동안 free -h, docker stats, 커널 OOM 로그를 계속 모니터링하세요.

문제가 성공적으로 해결되었다면, 정상적인 문서 열기 및 저장이 계속되고, 메모리 사용량이 VPS 및 컨테이너 제한 범위 내에 유지되며, 새로운 OOM(메모리 부족) 오류가 발생하지 않아야 합니다. 활동이 적을 때만 충돌이 멈춘다면, VPS에 최대 사용량을 감당할 여유 공간이 부족한 것이므로, 지속적인 스와핑에 의존하기보다는 최대 사용량에 맞춰 RAM 크기를 조정하십시오. RAM 용량이 충분하고 새로운 OOM 오류가 발생하지 않지만 문서 열기 및 저장이 계속 실패하는 경우, 추가적인 메모리 변경 대신 ONLYOFFICE 로그, 리버스 프록시 또는 스토리지 커넥터를 점검하십시오.