자체 호스팅 Docker 서버에서 ONLYOFFICE 공동 편집 지연 문제 해결

자체 호스팅 Docker 서버에서 ONLYOFFICE 공동 편집 속도가 느리다고 느껴진다면, 문서화되지 않은 편집기 매개변수를 변경하는 것부터 시작하지 마십시오. 먼저 문제를 세 가지 측정 가능한 영역으로 구분하십시오. 서버 리소스 부하, 리버스 프록시/WebSocket 동작, 그리고 스토리지 또는 컨테이너 수준 오류입니다. 공동 편집은 지속적인 실시간 통신에 의존하므로, 문서를 성공적으로 여는 서버라도 여러 사람이 동시에 입력할 때는 속도가 느려질 수 있습니다.

이 가이드 에서는 가상의 예시를 사용합니다 . 소규모 팀이 NGINX 환경의 Docker 컨테이너에서 ONLYOFFICE Docs를 실행하고 있다고 가정합니다. 한두 명의 사용자는 정상적으로 문서를 편집할 수 있지만, 여섯 명이 같은 문서를 열면 커서 업데이트가 지연되고 다른 사용자의 변경 사항이 눈에 띄게 늦은 후에 나타납니다. 이 예시는 교육용 시나리오일 뿐이며, 실제 배포 환경에 대한 벤치마크 또는 보고서가 아닙니다.

2026년 10월 현재, ONLYOFFICE Docs 9.4가 공식 변경 로그에 등록된 최신 릴리스입니다. 버전 9.4에서는 RabbitMQ 및 데이터베이스에 대한 종속성이 제거되어 커뮤니티 에디션 아키텍처가 변경되었으므로, 이전 릴리스를 기준으로 작성된 조언은 최신 커뮤니티 에디션 컨테이너와 더 이상 일치하지 않을 수 있습니다. 이전 포럼 게시물의 튜닝 조언을 복사하기 전에 항상 설치된 에디션과 버전을 확인하십시오.

1. 변경하기 전에 지연 시간을 측정하세요.

가상의 상황에서 가장 먼저 저지르는 실수는 임의의 서비스를 재시작하고 렉이 사라지기를 바라는 것입니다. 대신, 반복 가능한 테스트를 만들어 보세요. 여러 브라우저 세션이나 테스트 계정에서 동일한 문서를 열고 간단한 편집을 수행한 후, 어떤 부분이 지연되는지 기록합니다. 예를 들어 로컬 화면의 키 입력, 원격 커서 이동, 다른 사용자의 텍스트 표시, 저장 상태 또는 문서 초기 로드 등이 지연될 수 있습니다.

이러한 증상들은 서로 다른 병목 현상을 나타냅니다. 로컬 브라우저에서 편집기 자체가 멈추는 경우, 클라이언트 측 CPU 문제이거나 문서가 매우 복잡한 경우일 수 있습니다. 로컬 입력은 즉시 반영되지만 원격 편집 내용이 늦게 반영되는 경우, 네트워크 경로와 WebSocket 세션을 점검하십시오. 여러 문서를 열수록 모든 작업 속도가 느려지는 경우, 서버 CPU, 메모리, 스왑 영역 및 디스크 I/O를 검사하십시오.

ONLYOFFICE는 공식 Docker 설치 가이드 에서 Docker 배포 및 기본 요구 사항을 설명합니다 . Docker Compose의 경우 공식 Docker Compose 지침을 참조하십시오 .

2. 사용자가 편집하는 동안 CPU 및 메모리 사용량을 확인합니다.

Docker 호스트에서 다음 명령을 실행하세요.

docker stats

테스트 그룹이 편집하는 동안 문서 서버 컨테이너를 모니터링하십시오. 또한 다음과 같은 도구를 사용하여 호스트 리소스를 검사하십시오.

free -h
uptime
vmstat 1
df -h

ONLYOFFICE의 공식 Docker 요구 사항에 따르면 문서화된 구성의 경우 최소 4GB의 RAM과 최소 40GB의 여유 디스크 공간(스왑 공간 포함)이 필요합니다. 기업용 지침에서는 용량이 동시 활성 사용자 수와 문서의 수, 유형 및 크기에 따라 달라진다고 명시하고 있습니다. 이러한 수치는 기준치일 뿐이며, 4GB RAM으로 모든 작업 부하에서 원활한 협업이 가능하다는 보장은 아닙니다.

예시에서, docker stats문서 서버 컨테이너가 6명이 동시에 입력할 때마다 사용 가능한 CPU 자원을 대부분 소모하는 현상이 반복적으로 발생한다고 가정해 보겠습니다. 이는 프록시 타임아웃을 추가해도 CPU 사용량이 증가하지 않는다는 중요한 증거입니다. 다음 단계는 지나치게 제한적인 Docker CPU 제한을 해제하거나, 컨테이너를 더 빠른 호스트로 이동하거나, 동시 작업 부하를 줄이는 것입니다. 반대로 CPU 사용량이 여전히 적당한 수준이라면 하드웨어 구매 전에 추가적인 조사를 진행해야 합니다.

게시된 용량 지침에 대한 공식 참조 자료는 ONLYOFFICE Docs Docker 시스템 요구 사항 입니다 .

3. 디스크 공간, 마운트 및 파일 캐시를 확인하십시오.

ONLYOFFICE의 Docker 문서에는 /var/log/onlyoffice로그 및 /var/lib/onlyoffice파일 캐시를 포함한 영구 저장 위치가 명시되어 있습니다. 호스트의 루트 파일 시스템뿐만 아니라 해당 경로를 지원하는 파일 시스템도 확인하십시오.

df -h
docker inspect documentserver --format '{json .Mounts}'

바인드 마운트가 속도가 느린 네트워크 파일 시스템이나 과부하된 디스크를 가리키는 경우 문서 열기, 변환 및 캐시 작업 시 지연이 발생할 수 있습니다. 디스크 공간이 거의 꽉 찬 경우 애플리케이션 튜닝을 수행하기 전에 먼저 디스크 공간을 확보하십시오. ONLYOFFICE의 Linux 문제 해결 문서에서는 디스크 공간 부족이 변환 문제의 원인이 될 수 있다고 명시적으로 언급하고 있습니다.

이 프로젝트는 영구 로그, 캐시 저장소 또는 외부 데이터베이스/Redis/RabbitMQ 서비스가 필요한 경우 관련 데이터를 컨테이너 외부에 저장하는 것을 권장합니다. Docker 볼륨에 대한 공식 지침을 참조하세요 .

4. 리버스 프록시가 실시간 연결을 유지하는지 확인합니다.

많은 자체 호스팅 배포 환경에서는 ONLYOFFICE를 NGINX, Apache, HAProxy 또는 Traefik 뒤에 배치합니다. ONLYOFFICE 공식 프록시 설명서에서는 `--reported` 및 ` X-Forwarded-Proto--reported` 와 같은 전달 헤더를 명시적으로 요구합니다 X-Forwarded-Host. ONLYOFFICE에서 제공하는 구성은 HTTP/1.1 및 WebSocket 업그레이드 처리도 사용합니다.

NGINX의 경우, 다른 제품의 일반적인 WebSocket 코드 조각을 붙여넣기보다는 ONLYOFFICE의 공식 예제와 설정을 비교해 보세요. 대표적인 패턴은 다음과 같습니다.

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Forwarded-Host $the_host;
proxy_set_header X-Forwarded-Proto $the_scheme;

주변 map환경 설정 및 프록시 위치가 중요합니다. 전체 공급업체 예제를 참조하여 토폴로지를 구성하십시오. 지원되는 구성은 프록시 뒤에서 ONLYOFFICE 문서 사용하기 에 게시되어 있습니다 .

가상의 팀에서 Docker 호스트에 CPU와 RAM이 충분하지만 브라우저가 회사 NGINX 계층을 통해 협업 채널에 반복적으로 다시 연결한다고 가정해 보겠습니다. 이는 문서 서버의 컴퓨팅 용량 문제가 아니라 프록시 경로 문제임을 나타냅니다.

5. 브라우저에서 WebSocket 세션을 확인합니다.

브라우저 개발자 도구를 열고 네트워크 패널을 선택한 다음 WebSocket 트래픽을 필터링하고 편집기를 새로 고침하세요. WebSocket 핸드셰이크가 성공하면 일반적으로 HTTP가 표시 101 Switching Protocols되고 연결이 계속 열려 있는 것을 확인할 수 있습니다. "대기 중" 상태로 오래 지속되는 WebSocket 연결을 그 자체로 실패로 간주하지 마세요. 활성 WebSocket 연결은 계속 열려 있는 것이 정상입니다.

중요한 것은 반복적인 연결 끊김/재연결 동작, 핸드셰이크 실패, 프록시 오류 또는 협업 지연과 관련된 긴 간격입니다. 원격 편집이 WebSocket 재연결과 동시에 지연된다면, 해결해야 할 구체적인 네트워크 문제가 있는 것입니다.

TLS 종료, 프록시 유휴 시간 초과, 로드 밸런싱 규칙, WAF 정책 및 WebSocket 트래픽을 보존하지 않을 수 있는 중간 서버를 확인하십시오. 프록시 계층이 두 개 이상인 경우, 공용 NGINX 인스턴스만 관련되어 있다고 가정하지 말고 각 홉을 테스트하십시오.

6. 예상되는 컨테이너와 에디션별 아키텍처를 확인합니다.

달리다:

docker compose ps
# or
docker ps

모든 최신 ONLYOFFICE 배포 환경이 동일한 Redis, PostgreSQL 또는 RabbitMQ 컨테이너 구성을 갖추고 있다고 가정하지 마십시오. 버전이 중요합니다. ONLYOFFICE에 따르면 Docs 9.4부터 오픈 소스 커뮤니티 에디션은 단일 프로세스 아키텍처로 간소화되었으며 RabbitMQ 및 데이터베이스에 대한 종속성이 제거되었습니다. 엔터프라이즈, 개발자, 이전 커뮤니티 배포 환경 및 사용자 지정 Compose 스택은 다를 수 있습니다.

즉, 2023년에 작성된 "RabbitMQ가 병목 현상의 원인일 수 있습니다"라는 문제 해결 문서는 현재 커뮤니티 에디션 인스턴스에는 적용되지 않을 수 있습니다. 실제로 실행 중인 이미지와 버전을 확인하십시오.

docker inspect documentserver --format '{.Config.Image}'
docker image ls onlyoffice/documentserver

ONLYOFFICE Docs의 공식 변경 로그 에는 버전 9.4.0이 2026년 5월 20일 출시 예정으로 기재되어 있습니다. 공급업체의 Docs 9.4 출시 발표에서는 커뮤니티 에디션 아키텍처 변경 사항에 대해 설명합니다.

7. 디버그 로깅을 일시적으로 활성화하고 이를 지연 현상과 연관시켜 분석합니다.

ONLYOFFICE는 디버그 로깅을 위한 Docker 환경 변수를 제공합니다. 문제 해결을 위한 짧은 시간 동안 다음 변수를 추가하세요.

DS_LOG_LEVEL=DEBUG

그런 다음 배포 방법에 따라 해당 컨테이너를 다시 생성하거나 재시작하고 로그를 확인하십시오.

docker logs -f documentserver
# Docker Compose:
docker compose logs -f documentserver

공식 문서에 따르면 Docker 로그는 /var/log/onlyoffice/documentserver컨테이너 내부와 호스트에 마운트된 해당 로그 디렉터리(마운트한 경우)에서 확인할 수 있습니다. 변환기 로그는 파일 열기 또는 변환 속도가 느릴 때 유용하며, 공동 작업 관련 문제는 문서 서버 로그 및 브라우저/네트워크 관찰 결과와 함께 살펴보아야 합니다.

필요한 정보를 수집한 후에는 디버그 모드를 다시 끄십시오. 자세한 로깅은 진단을 위한 것이며, 영구적인 성능 설정이 아닙니다. ONLYOFFICE 문서의 "디버그 로깅 활성화" 에 있는 공급업체 절차를 따르십시오 .

8. 이전 버전의 이미지를 사용 중인 경우 신중하게 업데이트하십시오.

배포 버전이 지원되는 릴리스 라인보다 상당히 뒤쳐진 경우, 업데이트에는 버그 수정 및 아키텍처 개선 사항이 포함될 수 있습니다. 그러나 "최신 버전을 가져와서 재시작"하는 것은 운영 중인 협업 서버에서 성능을 보장하는 안전한 방법이 아닙니다.

먼저 현재 이미지 태그, 구성 파일, JWT 설정, 마운트된 볼륨, 리버스 프록시 구성 및 통합 구성을 기록해 두십시오. 변경 프로세스의 재현성이 필요한 경우 고정된 버전을 사용하십시오. ONLYOFFICE의 Docker 설치 가이드에는 특정 버전을 지정하는 방법이 설명되어 있으며, 공식 변경 로그에서 변경 사항을 확인할 수 있습니다.

사용량이 많은 프로덕션 문서 서버를 의도적으로 중지하기 전에, 사용 중인 에디션 및 배포 환경에 맞는 ONLYOFFICE 종료 지침을 따라 활성 편집 세션을 안전하게 처리하십시오. 저장되지 않은 사용자 작업이 포함된 벤치마크 문서를 업그레이드 테스트에 사용하지 마십시오.

가상 사례가 실제 해결책을 좁혀주는 방법

공동 편집자 6명으로 구성된 예시 팀으로 돌아가십시오. 문제 해결 결과는 관찰 내용에 따라 달라집니다.

Docker 배포를 위한 실용적인 기준

소규모 자체 호스팅 설치의 경우, ONLYOFFICE에서 제시하는 최소 요구 사양을 기준으로 시작하되, 등록된 총 사용자 수가 아닌 실제 동시 접속 사용자 수를 기준으로 크기를 조정하십시오. 영구 로그와 캐시는 지연 시간이 예측 가능한 스토리지에 저장하십시오. 작업 부하를 측정하지 않은 경우 CPU 또는 메모리 사용량을 엄격하게 제한하지 마십시오. 일반적인 편집 작업 부하에서 Docker 호스트 자체의 스왑 현상이 발생하지 않도록 하십시오.

ONLYOFFICE를 공급업체에서 제공하는 예제를 기반으로 하는 리버스 프록시 구성 뒤에 배치하여 WebSocket 업그레이드 및 전달된 호스트/프로토콜 헤더를 유지하십시오. 서버가 유휴 상태일 때뿐만 아니라 실제 공동 편집 중에도 서버를 모니터링하십시오. 더 자세한 증거가 필요한 경우, 디버그 로깅을 일시적으로 활성화하고 로그 타임스탬프를 브라우저의 WebSocket 동작 및 호스트 메트릭과 연관시켜 분석하십시오.

하지 말아야 할 일

• local.json포럼 게시글에서 "성능 최적화"라고 언급했다고 해서 문서화되지 않은 값을 변경하지 마십시오 .
• "대기 중"으로 표시되는 지속적인 WebSocket 연결이 끊어졌다고 단정하지 마십시오. WebSocket 연결은 장시간 유지되는 것이 일반적입니다.
• 단순히 이전 배포 다이어그램에 Redis, RabbitMQ 또는 PostgreSQL이 사용되었다는 이유만으로 추가하지 마십시오. 먼저 사용 중인 에디션 및 버전의 아키텍처를 확인하십시오.
• 지연 시간을 줄이기 위한 지름길로 TLS 검증, JWT 보안 또는 프록시 보호를 비활성화하지 마십시오.
• 서버 유휴 상태 지표를 사용자가 실제로 렉을 보고하는 기간과 비교하지 마십시오.
• 볼륨, 구성 및 롤백 경로를 보존하지 않고는 프로덕션 인스턴스를 업그레이드하지 마십시오.

결론적으로

OnlyOffice 공동 편집 지연 현상은 측정 가능한 시스템 문제로 간주할 때 가장 쉽게 해결할 수 있습니다. 지연 현상을 재현하고, 부하 상태에서 Docker 및 호스트 리소스를 관찰하고, 스토리지를 확인하고, 모든 프록시를 통해 브라우저가 정상적인 WebSocket 연결을 유지하는지 확인하고, 지연이 발생하는 시간대의 로그만 검사하십시오. 병목 현상이 컴퓨팅, 메모리, 디스크, 네트워크/프록시 동작 또는 특정 버전/구성 변경 중 어느 것에 있는지 파악하면 추측에 의존하는 것이 아니라 문제에 집중하여 해결할 수 있습니다.

최신 배포 세부 정보는 ONLYOFFICE Docker 설치 문서 , 공식 리버스 프록시 예제 , 디버그 로깅 가이드 및 공식 문서 변경 로그를 참조하십시오 .