CODE 문서 편집 세션이 10분 후 연결이 끊어지는 문제를 해결합니다.

Collabora Online Development Edition(CODE) 문서가 정상적으로 열리고 편집이 완료된 후 약 10분 후에 편집기 연결이 끊어지는 경우, 브라우저와 CODE 간의 WebSocket 경로부터 점검하십시오. 반복적으로 발생하는 600초 연결 끊김 현상은 CODE의 기본 유휴 타이머보다는 리버스 프록시, 인그레스 컨트롤러, 로드 밸런서 또는 방화벽의 타임아웃 문제일 가능성이 훨씬 높습니다.

이러한 구분이 중요한 이유는 CODE 자체의 유휴 설정을 먼저 변경하면 편집 트래픽을 전달하는 연결을 수정하지 않고 실제 문제를 가릴 수 있기 때문입니다. 현재 Collabora 구성 템플릿에는 보기당 15분, 문서 유휴 시간 제한이 1시간으로 설정되어 있으며, 편집 세션 제한은 10분으로 설정되어 있지 않습니다. 상위 coolwsd.xml 템플릿을 참조하십시오 . 연결이 끊어질 때 사용자가 활발하게 타이핑하고 있다면, CODE의 유휴 설정만으로는 정확한 원인을 설명하기 어렵습니다.

10분간의 연결 끊김은 보통 무엇을 의미할까요?

확인됨:proxy_read_timeout 36000s Collabora에서 공개한 Nginx 예제는 WebSocket 업그레이드 헤더와 메인 WebSocket에 long 타입을 사용합니다 . Nginx 자체 문서에 따르면 프록시된 WebSocket 연결은 구성된 읽기 시간 초과 내에 데이터가 수신되지 않으면 닫히며, 기본값 proxy_read_timeout은 60초입니다. Collabora 온라인 SDK 설명서 및 Nginx WebSocket 프록시 문서를 참조하십시오 .

환경에 따라 다릅니다. CODE 앞에 있는 Nginx 호스트가 올바르게 보이더라도 다른 프록시 계층으로 인해 600초 타임아웃이 발생할 수 있습니다. 일반적인 예로는 Kubernetes Ingress, HAProxy, 클라우드 로드 밸런서, WAF 또는 상위 리버스 프록시가 있습니다. 정확한 타임아웃 및 구성 키는 해당 구성 요소에 따라 다릅니다.

증상만으로는 입증할 수 없습니다. "10분 후 연결이 끊긴다"는 증상만으로는 Nginx가 문제의 원인이라고 단정할 수 없습니다. 여러 계층을 한꺼번에 변경하기 전에 실패한 WebSocket 연결을 캡처하고 해당 타임스탬프를 프록시 및 CODE 로그와 비교 분석하십시오.

조치: 브라우저 개발자 도구를 열어 오류를 재현하고 WebSocket 요청의 정확한 소요 시간을 기록하십시오.

1단계: 웹소켓이 실제로 종료되는 원인인지 확인합니다.

문서를 열고 브라우저의 개발자 도구를 열어 네트워크 패널로 이동합니다. WebSocket 트래픽을 필터링합니다. 코드 편집 트래픽에는 일반적으로 WebSocket 경로가 포함됩니다 /cool/. 오류가 발생하는 지점 이후에도 문서를 열어 둔 상태를 유지하십시오.

세션 연결이 끊어지면 WebSocket 요청을 검사하십시오. 가장 유용한 정보는 연결 지속 시간, 종료 시간, 초기 연결 시 HTTP 상태, 그리고 브라우저에서 네트워크 오류를 보고하는지 여부입니다. 초기 연결이 정상적으로 101 Switching Protocols이루어지고 약 600초 후에 연결이 끊어진다면 연결 수명 또는 비활성 정책에 문제가 있을 가능성이 높습니다.

WebSocket 업그레이드가 전혀 성공하지 못하는 경우, 이는 "10분 타임아웃" 문제가 아닙니다. 먼저 WebSocket 라우팅 및 헤더를 수정하십시오. 편집기에서 저장소 또는 저장 오류가 표시되는 동안 WebSocket 연결은 유지되는 경우, WOPI/저장 경로를 조사하십시오.

조치: 시작 시간과 연결 해제 시간을 기록한 다음, 해당 타임스탬프를 리버스 프록시 액세스/오류 로그 및 CODE 컨테이너 또는 서비스 로그와 비교하십시오.

2단계: CODE 유휴 값을 변경하기 전에 CODE 역방향 프록시 규칙을 확인하십시오.

Nginx의 경우 중요한 점은 WebSocket 위치가 업그레이드 헤더를 전달하고 읽기 시간 제한이 충분히 길어야 한다는 것입니다. Collabora SDK 설명서에는 메인 WebSocket에 대해 이러한 패턴이 나와 있습니다.

location ~ ^/cool/(.*)/ws$ {
    proxy_pass https://127.0.0.1:9980;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 36000s;
}

Nginx에서 TLS가 종료되고 CODE가 의도적으로 일반 HTTP를 제공하는 경우, 업스트림 스키마는 http://다를 수 있습니다. 스키마를 그대로 복사하지 마십시오. CODE 인스턴스의 구성 방식과 일치해야 합니다.

흔히 오해하는 것 중 하나는 `enable` 설정이 이미 설정된 편집 세션의 지속 시간을 제어한다는 것입니다 proxy_connect_timeout. 하지만 이는 사실이 아닙니다. `enable` 설정은 업스트림 연결을 설정하는 동안 적용됩니다. 업스트림 데이터가 없는 기간이 있는 프록시된 WebSocket 연결과 가장 직접적으로 관련된 설정은 `enable`입니다 . Nginx는 HTTP 프록시 모듈 참조 문서proxy_read_timeout 에서 이러한 동작을 설명합니다 .

조치: CODE WebSocket URL과 일치하는 실제 Nginx 블록을 찾아 타임아웃이 설정되어 있는지 확인하십시오. 관련 없는 다른 곳에 설정되어 있지 않은지 확인하십시오 location.

3단계: CODE 26.04 프록시 변경 사항을 반영합니다.

2026년 10월 현재, Collabora의 최신 CODE 26.04 릴리스 노트에는 2026년 9월 24일에 출시된 CODE 26.04.4.2 버전이 포함되어 있습니다. 26.04 시리즈에서는 더욱 간결해진 WebSocket URL이 도입되었습니다. Collabora는 기존 프록시 구성에 업데이트가 필요할 수 있다고 안내하고 있으며, 이후 26.04 빌드에서는 프록시가 업데이트되지 않은 경우 CODE가 기존 URL로 되돌아가고 감사 경고를 표시할 수 있습니다. 특히 Apache2 사용자는 26.04 버전 출시 당시 ProxyPass 규칙을 업데이트해야 한다는 안내를 받았습니다. 자세한 내용은 공식 CODE 26.04 릴리스 노트를 참조하십시오 .

이는 10분마다 발생하는 연결 끊김 현상이 압축 URL 변경 때문이라는 의미는 아닙니다. 26.04 버전에서는 특히 업그레이드 후에 문제가 발생한 경우, 실제로 실행 중인 버전의 설명서를 참조하여 리버스 프록시 규칙을 확인해야 한다는 의미입니다.

조치: 제품의 정보 또는 컨테이너 이미지 태그에서 CODE 버전을 확인한 다음 프록시 구성을 최신 Collabora 프록시 지침과 비교하십시오. 이전 24.04 배포에서 복사한 규칙이 여전히 적합하다고 가정하지 마십시오.

4단계: Kubernetes Ingress, HAProxy, Apache 및 기타 미들박스를 확인합니다.

Nginx가 CODE 바로 앞에 있는 계층 하나만 있는 경우, 타임아웃을 늘리는 것만으로는 충분하지 않을 수 있습니다. ingress-nginx를 사용하는 Kubernetes 환경에서는 Ingress별로 사용할 수 있는 어노테이션인 `ingress-nginx`와 ` ingress-nginx- nginx.ingress.kubernetes.io/proxy-read-timeouttimeout` 이 프로젝트 문서에 나와 있습니다 nginx.ingress.kubernetes.io/proxy-send-timeout. WebSocket 가이드라인에서는 장시간 연결의 경우 1시간보다 큰 값을 권장합니다. 자세한 내용은 공식 Ingress-Nginx 어노테이션 참조 및 WebSocket 노트를 확인하세요 .

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

HAProxy의 경우 Collabora SDK 예제는 WebSocket 스타일 트래픽에 대해 긴 터널 타임아웃을 사용합니다. Apache의 경우 일반 프록시 타임아웃은 mod_proxy로 제어되지만 ProxyTimeout, CODE 26.04에서는 현재 WebSocket ProxyPass 패턴에도 주의를 기울여야 합니다. Apache 자체 mod_proxy 문서에서 어떤 부분이 이를 제어하는지 설명합니다 ProxyTimeout.

조치: 브라우저에서 CODE까지의 연결 경로를 그리고 모든 홉을 검사하십시오. 어느 한 홉에서라도 600초 제한이 발생하면 세션이 종료될 수 있습니다.

5단계: 프록시를 안전하게 검증하고 다시 로드합니다.

Nginx 설정을 수정한 후에는 재부팅하기 전에 테스트하십시오.

sudo nginx -t
sudo systemctl reload nginx

Nginx가 컨테이너에서 실행되는 경우, 기존 systemctl설정이 존재한다고 가정하는 대신 컨테이너 환경에 맞는 유효성 검사 및 재로드 절차를 사용해야 합니다. 중요한 것은 실행 중인 설정을 교체하기 전에 구문을 검증하는 것입니다.

조치: 한 번에 한 레이어씩 변경하고, 이전 값을 기록하고, 구성을 검증한 다음, 동일한 문서 워크플로를 다시 테스트합니다.

6단계: 기존 제한 시간보다 긴 테스트를 통해 수정 사항이 유효한지 확인합니다.

문서가 다시 열리더라도 테스트를 중단하지 마십시오. 이전 오류 발생 시점 이후에도 동일한 편집 세션을 계속 연결해 두십시오. 10분 동안 지속되는 증상의 경우, 2분짜리 스모크 테스트보다는 20~30분 동안의 검증 기간이 더 유용합니다. 네트워크 패널을 열어 두고 간헐적으로 편집 작업을 수행하여 활성 편집 탭과 완전히 유휴 상태인 탭을 구분하십시오.

정상적인 결과는 다음 세 가지 징후로 나타납니다. WebSocket 연결이 10분 이상 유지되고, 편집기가 재연결 메시지 없이 계속해서 편집을 수락하며, 중간 또는 CODE 로그에 해당 시간 초과 오류가 나타나지 않습니다.

가장 가까운 프록시 타임아웃 시간을 늘린 후에도 정확히 10분 후에 연결이 계속 끊어진다면, 이는 다른 홉에 여전히 600초 정책이 적용되어 있다는 유용한 증거가 될 수 있습니다.

조치: 종료 또는 시간 초과를 발생시키는 구성 요소를 찾을 때까지 추적을 계속합니다.

CODE의 유휴 타이머를 10분 네트워크 차단과 혼동하지 마십시오.

상위 CODE 구성 템플릿은 현재 per_view.idle_timeout_secs900초(15분)로 설정되어 있습니다. 설명에 따르면 사용자가 활동하지 않으면 보기가 흐려지고 업데이트가 중지됩니다. 문서 수준의 idle_timeout_secs기본값은 유휴 문서가 언로드되기 전까지 3600초(1시간)입니다.

해당 값들이 사용자의 동작과 일치하는지 확인해 볼 가치는 있지만, 두 기본값 모두 정확히 600초 동안 연결이 끊기는 현상을 설명하지는 못합니다. 이전에 coolwsd.xml환경 변수, Helm 값 또는 컨테이너 매개변수를 사용자 지정한 경우 배포 환경이 기본값과 다를 수 있습니다.

조치: 오류가 네트워크 수준인지 애플리케이션 수준인지 확인한 후에만 유효한 CODE 구성을 검사하십시오. 첫 번째 대응으로 모든 유휴 값을 늘리지 마십시오.

빠른 진단표

결론적으로

CODE 편집 세션이 10분 후 반복적으로 연결이 끊기는 경우 가장 효율적인 순서는 다음과 같습니다. WebSocket 연결 실패를 확인하고, 일치하는 역방향 프록시 규칙을 검증하고, 모든 중간 타임아웃을 검사하고, CODE 26.04의 프록시 경로 변경 사항을 고려하고, 안전하게 다시 로드한 다음, 이전 차단 시간 이후를 테스트합니다. 관찰된 동작과 실제 구성이 가리키는 경우에만 CODE 유휴 설정을 변경하십시오.

오류 발생 시간이 반복되지 않거나, CODE 로그에 크래시, 프로세스 종료, 메모리 부족 또는 WOPI 오류가 동시에 나타나는 경우, 단순한 타임아웃으로 간주하지 마십시오. 이러한 증상은 다른 진단이 필요합니다.