키, 검색 및 URL을 확인하여 WOPI 증명 오류를 수정하세요.
Collabora WOPI 증명 실패 원인을 키 불일치, 오래된 검색 데이터, 시간 오차 또는 프록시 URL 변경으로 추적할 수 있으며, 이 과정에서 유효성 검사를 약화시키지 않습니다.
키, 검색 및 URL을 확인하여 WOPI 증명 오류를 수정하세요.
WOPI 호스트에서 "인증서 유효성 검사 실패" 또는 "유효하지 않은 WOPI 인증서" 오류가 보고되면 먼저 어떤 시스템에서 거부 기록이 발생했는지 확인하십시오. 스토리지 호스트가 Collabora의 서명된 요청을 거부하는 경우, WOPI 호스트 허용 목록을 변경하거나 인증서 검사를 비활성화하기 전에 인증 키 쌍과 검색 응답을 확인하십시오. 패키지 설치의 경우 Collabora에서 일반적으로 키 쌍을 생성합니다. Docker, Kubernetes 및 다중 복제 배포의 경우 키 쌍을 제공하고 일관되게 유지해야 합니다.
키를 변경하기 전에 오류가 발생한 점검 사항을 확인하십시오.
WOPI 증명 검증은 서명된 요청과 WOPI 클라이언트가 검색 메타데이터에 제공하는 공개 키를 사용합니다. 이는 Collabora의 신뢰할 수 있는 WOPI 호스트 목록, TLS 인증서 검증 및 스토리지 호스트의 액세스 토큰 확인과는 별개입니다. 개인 키가 없거나 제공된 공개 키와 일치하지 않는 경우 키 재생성을 통해 문제를 해결할 수 있지만, 복제본 하나만 변경되거나 호스트에 캐시된 검색 데이터가 남아 있는 경우 새로운 불일치가 발생할 수 있습니다.
| 로그에 나타난 증거 | 점검할 가능성이 높은 지역 |
|---|---|
| 스토리지 호스트가 CheckFileInfo 또는 다른 WOPI 요청을 수신하는 동안 "잘못된 WOPI 증명"이라는 메시지가 표시됩니다. | Collabora의 인증 키, 호스트의 검색 데이터, URL 재구성 또는 타임스탬프 |
| Collabora에서 "승인되지 않은 WOPI 호스트" 또는 "허용 가능한 WOPI 호스트가 없습니다"라는 메시지가 표시됩니다. | WOPI 호스트 허용 목록/도메인 구성이지, 증명 키가 아닙니다. |
| 토큰이 유효하지 않거나, 만료되었거나, 증명 없이 접근이 거부되었습니다. | 호스트가 발급한 액세스 토큰, 권한 또는 토큰 만료 |
Collabora 로그와 스토리지 호스트 로그 모두에서 실패한 요청을 확인하십시오. 브라우저에 로딩 표시만 나타나는 것으로는 인증 키 오류를 식별할 수 없습니다.
배치 상황에 맞는 수리 방법을 선택하십시오.
가장 혼란을 최소화하는 방법부터 시작하세요. 패키지 기반 설치의 경우, 기존 키 파일과 서비스 로그를 먼저 확인하십시오. 현재 Collabora 문서에 따르면 RPM 및 Debian 패키지 설치는 WOPI 인증 키 쌍을 자동으로 생성합니다. 이러한 파일이 존재하고 안정적이라면 일반적으로 키를 교체할 필요가 없습니다.
| 배포 | 권장 조치 | 절충 |
|---|---|---|
| 단일 패키지 관리 서버 | 생성된 키 쌍을 보관하십시오. 권한이 없거나 일치하지 않는 경우에만 권한을 복구하거나 다시 생성하십시오. | 변경 사항은 미미하지만, 패키지 버전과 구성된 경로를 확인하십시오. |
| 단일 Docker 컨테이너 | 한 쌍을 생성하고 컨테이너에 영구적으로 마운트합니다. | coolwsd를 사용하려면 영구 볼륨과 올바른 읽기 권한이 필요합니다. |
| 쿠버네티스 또는 다중 복제 | Collabora 인스턴스마다 공유 비밀 키 쌍 하나를 마운트합니다. | 복제본 간 일관된 서명 유지; 로테이션 시 호스트의 검색 보기 또한 업데이트되어야 합니다. |
| 프록시 서버 뒤에서 호스트 URL이 변경되었습니다. | 서명 유효성 검사에 사용된 공개 스키마, 호스트, 경로 및 쿼리 문자열을 확인합니다. | 키를 돌리는 것보다 복잡하지만 불필요한 자격 증명 변경을 방지할 수 있습니다. |
Collabora 24.04 매뉴얼에 따르면 공개 Docker 이미지에는 증명 키 쌍이 포함되어 있지 않으므로, 직접 생성하여 영구적으로 마운트해야 합니다. 공식 Helm 차트는 증명 키 시크릿을 지원합니다. 각 복제본마다 별도의 증명 키 쌍을 생성하지 마십시오. 로드 밸런싱으로 인해 장애가 간헐적으로 발생할 수 있습니다.
키 쌍을 안전하게 점검하고 수리하세요.
- 구성된 키 경로를 찾으세요. Collabora 호스트 또는 컨테이너 내부에서
coolwsd.xml증명 키 경로 설정을 확인하고 개인 키와 공개 키가 모두 있는지 확인하세요. 일반적인 위치는 아래에 있지만/etc/coolwsd/패키지 및 컨테이너 레이아웃은 다를 수 있습니다. 개인 키를 로그, 티켓 또는 채팅에 절대 붙여넣지 마세요. - 키가 일치하는지 확인하십시오. 일반적인 기본 경로의 경우 개인 키를 표시하지 않고 지문을 비교합니다 . 결과 해시 값이 일치해야 합니다. 경로가 다르면 실제 구성된 경로로 대체하십시오. 개인 키를 읽을 수 없는 경우 서비스
sudo openssl pkey -in /etc/coolwsd/proof_key -pubout -outform DER | sha256sum의openssl pkey -pubin -in /etc/coolwsd/proof_key.pub -outform DER | sha256sum보안 모델에 따라 소유권과 권한을 수정하십시오. 모든 사용자가 읽을 수 있도록 설정하지 마십시오. - 필요한 경우에만 개인 키를 재생성하십시오. 개인 키가 없거나 키 쌍이 일치하지 않으면
sudo coolconfig generate-proof-key해당 유틸리티가 설치된 위치에서 유틸리티를 사용하십시오. Docker 환경에서는 적절한 영구 위치에 키 쌍을 생성한 다음 Collabora에서 예상하는 위치에 두 파일을 모두 마운트하고 coolwsd 프로세스가 개인 키를 읽을 수 있도록 설정하십시오. 관리형 플랫폼에서는 실행 중인 Pod를 직접 편집하는 대신 해당 플랫폼에서 지원하는 Secret 메커니즘을 사용하십시오. - 모든 인스턴스의 일관성을 유지하십시오. 복제본의 경우, 각 인스턴스에 동일한 키 쌍을 배포하고 Collabora를 재시작하거나 배포하여 파일을 읽도록 하십시오. 그런 다음 스토리지 호스트에서 지원하는 메커니즘을 사용하여 WOPI 검색을 새로 고치거나 다시 가져오십시오. 키 순환은 공개 키를 변경합니다. 이전 키를 계속 사용하는 캐시 또는 다른 복제본을 통해 장애 발생 시에도 서비스를 유지할 수 있습니다.
키는 일치하지만 증명 검증이 여전히 실패하는 경우
양 시스템의 시간 동기화를 확인하십시오. WOPI 증명 요청에는 타임스탬프가 포함되어 있으며, 호스트는 오래되었거나 허용 범위를 벗어난 타임스탬프를 거부할 수 있습니다. NTP 또는 플랫폼의 시간 서비스가 정상적으로 작동하고 서버가 적절한 UTC 시간을 보고하는지 확인하십시오. 시간 동기화 문제를 해결하기 위해 타임스탬프 검사를 완화하지 마십시오.
다음으로, 호스트가 서명된 요청을 재구성하는 데 사용하는 공개 URL을 검사하십시오. 증명은 관련 쿼리 매개변수를 포함한 요청 URL과 연결되어 있으며, WOPI 사양은 유효성 검사에 사용되는 URL 표현이 서명된 형식과 일치해야 한다고 규정합니다. HTTPS를 종료하는 리버스 프록시는 Collabora가 공개 HTTPS URL에 서명했더라도 애플리케이션이 내부 HTTP URL을 보게 할 수 있습니다. WOPI 호스트의 공식 지침에 따라 신뢰할 수 있는 프록시 헤더와 애플리케이션의 외부 URL 설정을 구성하십시오. 증명 로직을 변경하거나 쿼리 매개변수를 제거하지 마십시오.
키 순환 후에만 증명이 실패하는 경우, 검색을 새로 고치고 모든 Collabora 복제본이 동일한 공개 키를 노출하는지 확인하십시오. 특정 프록시 또는 특정 복제본을 통해 라우팅된 요청만 실패하는 경우, 키를 다시 순환하는 대신 해당 경로의 로그와 구성을 비교하십시오. 증명 유효성 검사를 비활성화하면 보안 검사가 약화될 수 있으므로 프로덕션 환경에서의 해결책으로 사용해서는 안 됩니다.
수리를 확인하세요
- 스토리지 호스트의 네트워크에서 Collabora 검색 엔드포인트를 가져와서 최신 증명 키 메타데이터가 반환되는지 확인합니다.
- 테스트 문서를 열고 스토리지 호스트가 CheckFileInfo 요청 및 이후 문서 요청을 오류 없이 수락하는지 확인하십시오.
- 각 프록시 경로 또는 복제본을 통해 이 과정을 반복한 다음 컨테이너 재시작 또는 Pod 교체 후에도 키 쌍이 마운트된 상태로 유지되는지 확인하십시오.
문서 열기가 성공적으로 완료되면 해당 경로만 확인됩니다. 운영하는 각 WOPI 호스트 및 프록시 경로에 대해 이 검사를 반복하십시오.
공식 참조
Collabora 온라인 글꼴 크기 드롭다운 메뉴의 잘못된 렌더링 문제를 해결하세요
브라우저 확대/축소 설정을 초기화하고, 깨끗한 세션을 테스트하고, 잘못된 크기 메뉴에 Collabora 서버 업데이트가 필요한 시점을 파악합니다.
Nextcloud를 자체 호스팅 Collabora CODE 컨테이너에 연결하기
Docker를 사용하여 Collabora CODE를 배포하고, Nextcloud Office에 안전하게 연결하고, 실용적인 WOPI 및 프록시 검사를 통해 문서 편집을 검증하세요.
coolwsd 로그를 사용하여 Collabora 연결 실패를 추적하세요
일시적으로 coolwsd를 디버깅 모드로 전환하고, 실패한 열기 요청을 하나 캡처한 다음, 로그 시퀀스를 사용하여 WebSocket, WOPI, 프록시 및 컨테이너 문제를 구분합니다.
Collabora 관리 콘솔에 안전한 비밀번호를 설정하세요
Docker 또는 Linux용 Collabora Online 관리자 로그인을 구성하고, 해당 서비스를 재시작한 다음, 암호를 노출하지 않고 새 암호를 확인합니다.
Collabora의 coolwsd 또는 loolwsd를 사용하여 CPU 사용량이 높은 문제를 진단하세요.
Collabora 설정을 변경하거나 서비스를 다시 시작하기 전에 CPU 부하가 활성 문서, 유휴 작업자 프로세스 또는 서버 용량 중 어느 쪽에서 발생하는지 확인하십시오.
추측 없이 CODE 컨테이너의 메모리 제한을 높이는 방법
Docker가 Collabora CODE에 메모리 제한을 걸고 있는지 확인하고, Compose 메모리 제한을 안전하게 높인 다음, 실행 중인 컨테이너가 새로운 제한을 적용받았는지 확인합니다.
소스 코드를 수정하지 않고 Collabora CODE 툴바를 사용자 지정하는 방법
Collabora CODE를 간소화하려면 컴팩트 모드 또는 탭 모드와 WOPI PostMessage 컨트롤을 사용하여 선택한 버튼, 명령 및 탭을 안전하게 숨길 수 있습니다.
Collabora 코드를 TLS 종료를 사용하여 Nginx 뒤에서 실행
Collabora CODE 컨테이너의 HTTPS 처리를 Nginx에 맡기고, 웹소켓을 통해 편집 내용을 올바르게 전달하며, 9980번 포트를 노출하지 않고 공개 엔드포인트를 검증합니다.
Collabora 모바일 키보드가 열릴 때 텍스트가 계속 표시되도록 설정
Collabora Online에서 모바일 브라우저 키보드가 텍스트를 가리는 문제를 해결하는 방법을 안내합니다. 브라우저, 내장 WebView, 호스트 페이지에 대한 개별 점검을 포함하여 빠른 해결 방법을 제공합니다.