coolwsd 로그를 사용하여 Collabora 연결 실패를 추적하세요

Collabora Online Development Edition(CODE) 컨테이너의 경우 coolwsd로깅 수준을 높이고, 및 영역이 비활성화되지 않았는지 debug확인한 다음 , 컨테이너 로그를 따라가면서 문서 열기 실패를 재현하십시오. Docker Compose에서는 CODE 이미지의 환경 변수를 통해 설정을 전달하고 서비스를 다시 생성하십시오. 디버그 출력에서 ​​연결이 중단되는 지점이 표시되지 않는 경우에만 사용하고, 완료되면 이전 단계로 돌아가십시오.SocketWebSocketextra_paramstrace

이 방법은 컨테이너 구성을 업데이트할 수 있는 Docker 또는 Compose 배포에 적합합니다. 네이티브 패키지 설치는 /etc/coolwsd/coolwsd.xml대신 서비스 관리자를 사용합니다. 이 설정은 진단 세부 정보를 추가하지만 프록시, WOPI 호스트, 인증서 또는 네트워크 문제를 자체적으로 해결하지는 않습니다.

1. 통제된 환경에서 한 번의 번식을 시작하세요.

문서 하나를 선택하고 해당 문서를 열려고 시도한 시간, 공개 Collabora URL, 컨테이너 또는 Compose 서비스 이름을 기록해 두세요. 여러 파일을 반복적으로 새로 고치지 마세요. 한 번에 모든 파일을 새로 고치면 브라우저 증상, 프록시 로그, 통합 서버 로그 및 coolwsd 항목을 쉽게 일치시킬 수 있습니다.

컨테이너가 실행 중인지 확인하고 컨테이너의 이름을 확인하세요.

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

collabora아래 내용을 호스트에 표시된 컨테이너 이름으로 바꾸십시오 . 문제가 재현되기 직전의 출력을 아래에 표시하십시오.

docker logs --since 2m --follow --timestamps collabora

--follow새로운 출력을 스트리밍하고, --since초기 기록을 제한하며, --timestampsDocker 타임스탬프를 추가합니다. Docker는 컨테이너 로그 참조 에서 이러한 옵션을 설명합니다 . Compose에서는 를 사용할 수 있으며 docker compose logs --since=2m --follow collabora, 여기서 collabora는 서비스 키입니다.

2. 테스트를 디버깅하기 위해 coolwsd를 호출합니다.

Collabora 구성 스키마는 `<required_required_level>`, `< ...을 포함한 명명된 레벨을 지원합니다 warning. notice또한 information` debug<required_level>` trace도 정의되어 있습니다 . 문서화된 기본값은 `<required_level>` 및 `<required_level>`을 비롯한 여러 영역 disabled_areas에서 상세 정보 출력을 비활성화합니다 . 이는 연결 문제 해결에 중요합니다. 레벨만 변경하면 가장 유용한 핸드셰이크 세부 정보가 여전히 표시되지 않을 수 있습니다. 이러한 옵션은 Collabora coolwsd 구성 템플릿 과 Collabora 온라인 SDK 설명서 (Docker 구성 섹션, 2026년 10월 확인)에 설명되어 있습니다.SocketWebSocket

공식 collabora/code이미지의 경우, 서비스의 기존 extra_params값에 두 가지 옵션을 추가하십시오. SSL 종료 또는 서버 이름과 같이 설치에 이미 필요한 옵션은 그대로 유지하십시오.

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

두 번째 옵션은 상세 로깅을 위해 Socket와 를 사용 가능하게 유지하면서 와 는 비활성화합니다. 이 테스트 동안에는 해당 두 영역을 비활성화 목록에 다시 추가하지 마십시오. CODE 이미지 문서에서는 coolwsd에 명령줄 옵션을 전달하는 방법을 설명합니다. 배포 환경에서 마운트된 구성 파일이나 공급업체 관리 이미지를 사용하는 경우 해당 배포 환경의 구성 방법을 따르십시오.WebSocketAdminPixelextra_params

Compose 편집을 적용하려면 서비스를 다시 생성하십시오.

docker compose up -d --force-recreate collabora

실제 Compose 서비스 이름을 사용하십시오. 로 시작된 단기 컨테이너의 경우 docker run실행 구성을 업데이트하고 동일한 볼륨, 네트워크, 포트 및 기타 옵션을 사용하여 다시 생성하십시오. CODE 매뉴얼에 따르면 이미지는 extra_params시작 시 를 허용합니다. 이미 생성된 컨테이너의 환경을 변경한다고 해서 실행 중인 coolwsd 프로세스가 변경되는 것은 아닙니다.

3. 연결을 순서대로 읽으세요

오류를 한 번 재현하고 해당 구간만 검토하세요. 출력에서 WebSocket​​, WOPI, ERR, 와 같은 용어를 검색한 WRN다음 타임스탬프를 비교합니다. 정확한 문구와 로그 영역은 Collabora 버전에 따라 다르므로 이러한 항목들은 문자 그대로의 메시지가 아니라 검토해야 할 범주로 간주해야 합니다.

• 테스트 시점에 새로운 coolwsd 항목이 없습니다. 요청이 해당 컨테이너에 도달하지 못했을 수 있습니다. 구성된 공용 URL, DNS, 로드 밸런서, 리버스 프록시 액세스/오류 로그를 확인하고, 올바른 복제본을 테일링하고 있는지 확인하십시오.
• 브라우저가 서비스에 접속했지만 WebSocket 연결이 유지되지 않는 경우, 프록시에서 WebSocket 업그레이드, 전달된 호스트 및 스키마, TLS 종료, 경로 라우팅 및 유휴 시간 초과 처리를 점검하십시오. 브라우저 개발자 콘솔 및 프록시 로그와 비교해 보십시오. coolwsd는 프록시가 전혀 전달하지 않는 요청을 설명할 수 없습니다.
• WOPI 요청이 발생했으나 실패한 경우, 통합 서버의 WOPI URL, 호스트 허용 목록 또는 별칭 구성, Collabora 컨테이너에서의 연결 가능성, 그리고 통합 서버의 응답을 확인하십시오. WOPI 오류는 브라우저와 Collabora 간의 WebSocket 연결 과정과는 별개의 단계입니다.
• WOPI 연결은 성공했지만 브라우저 연결이 끊어진 경우, 다음으로 WebSocket 경로와 브라우저 측 연결 오류에 집중해야 합니다. 이 과정을 통해 문제 해결 범위를 좁힐 수 있지만, 어떤 프록시 또는 네트워크 설정이 잘못되었는지 정확히 밝혀낼 수는 없습니다.

서비스가 활성화되어 있는데도 Docker에 아무런 출력이 표시되지 않으면 컨테이너 내부의 로깅 구성을 확인하십시오. Docker의 `log` 명령은 컨테이너의 표준 출력 및 오류 스트림을 읽습니다. 파일에 기록하도록 구성된 설치의 경우 /var/log/coolwsd.log구성에 따라 `/etc/docker-log`와 같은 경로를 사용할 수 있습니다. 해당 경로를 가정하지 말고 실제 파일을 검사하십시오.

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

파일 로깅이 활성화된 경우 구성된 경로를 사용하십시오. 예를 들면 다음과 같습니다.

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. 결과를 확인하고 정상적인 로깅을 복원합니다.

테스트 후, 제한된 읽기 작업을 실행하여 의도한 시도가 새로운 항목을 생성했는지 확인합니다.

docker logs --since 5m --timestamps collabora

실패한 열기 요청을 coolwsd 이벤트와 연관시키거나 요청이 해당 컨테이너에 도달하지 않았음을 확인한 후, 어떤 연결 단계에 후속 조치가 필요한지 파악하면 유용한 결과를 얻을 수 있습니다. 출력을 필터링해야 하는 경우, 먼저 짧은 시간 범위를 사용해 보세요.

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

이전 값 logging.level으로 복원한 disabled_areas다음 서비스를 다시 생성하십시오. 디버그 및 추적 수준에서는 훨씬 더 많은 출력이 생성될 수 있으며 민감한 운영 세부 정보가 포함될 수 있습니다. 로그를 공유하기 전에 액세스 토큰, 문서 이름, 사용자 식별자, 호스트 이름 및 내부 주소는 삭제하십시오. 서비스가 공식 CODE 이미지가 아닌 경우 해당 이미지 관리자에게 구성 경로 및 지원되는 매개변수를 확인하십시오.