Nextcloud에서 ONLYOFFICE "문서를 저장할 수 없습니다" 오류 해결 방법

Nextcloud에서 DOCX 파일을 열면 ONLYOFFICE가 정상적으로 로드되고, 변경 작업을 수행한 후 편집기에서 "문서를 저장할 수 없습니다." 라는 메시지가 표시됩니다. 이때 브라우저가 파일을 찾지 못했거나 ONLYOFFICE 자체가 디스크에 쓰기 작업을 할 수 없다고 생각하기 쉽습니다. 하지만 Nextcloud 통합 환경에서는 이러한 추측이 잘못된 출발점이 될 수 있습니다.

중요한 점은 저장 방식입니다. Nextcloud는 ONLYOFFICE Docs에 문서 URL과 .NET Framework를 제공합니다 callbackUrl. ONLYOFFICE는 파일을 다운로드하고 편집 세션을 호스팅한 후, Nextcloud에 콜백을 요청하여 Nextcloud가 업데이트된 파일을 가져와 저장된 버전을 덮어씁니다. ONLYOFFICE 통합 공식 문서에는 이 콜백 과정이 명확하게 설명되어 있습니다. 즉, 편집기는 정상적으로 열리지만 저장에 사용되는 반환 경로에 문제가 있을 수 있습니다. 조치: 열기와 저장을 두 개의 별도 네트워크 테스트로 처리하십시오.

오류 메시지가 아니라 검증된 동작부터 시작하세요.

현재 공식 통합 문서에 따르면 ONLYOFFICE의 Nextcloud 커넥터는 서버 간 워크플로를 사용합니다. 즉, 문서 서버에서 문서 서버에 접근할 수 있어야 하고, 문서 서버에서 Nextcloud에 접근할 수 있어야 합니다. 편집이 완료되면 ONLYOFFICE는 콜백 URL로 POST 요청을 보냅니다. 그러면 Nextcloud는 편집된 문서를 다운로드하여 이전 버전을 덮어씁니다. 자세한 내용은 ONLYOFFICE Nextcloud 통합 가이드 와 ONLYOFFICE API의 Nextcloud 통합 설명을 참조하십시오 .

확인됨: 잘못된 콜백 경로 또는 연결할 수 없는 콜백 경로로 인해 편집기가 열려 있어도 저장 실패가 발생할 수 있습니다. ONLYOFFICE의 문제 해결 문서에서는 관리자에게 저장 오류가 발생할 때 DocService 로그를 확인하고 콜백 URL에 연결할 수 있는지 확인하도록 명시적으로 안내하고 있습니다. 조치: 편집기를 다시 설치하거나 브라우저 캐시를 지우는 것부터 시작하지 마십시오. 먼저 서버 간 경로를 테스트하십시오.

1. 커넥터에 내장된 연결 검사 기능을 실행합니다.

Nextcloud 호스트에서 웹 서버 사용자 권한으로 ONLYOFFICE 커넥터 검사를 실행합니다. 일반적인 Debian 또는 Ubuntu 설치 환경에서는 다음과 같습니다.

cd /var/www/nextcloud
sudo -E -u www-data php occ onlyoffice:documentserver --check

Nextcloud의 정확한 경로와 HTTP 사용자는 배포판 또는 컨테이너 레이아웃에 따라 다를 수 있습니다. Nextcloud 관리 설명서에서는 occ파일 소유권을 일관되게 유지하기 위해 HTTP 사용자로 실행할 것을 권장합니다. ONLYOFFICE 문서는 occ onlyoffice:documentserver --check커넥터 연결 테스트에 사용됩니다.

이것이 증명하는 것: 문서 서버 구성 또는 연결 오류가 명백하게 드러날 수 있습니다. 이것이 증명하지 못하는 것: 실제 편집 세션 중에 발생하는 모든 콜백이 모든 프록시, DNS 경로 및 인증 계층을 통해 성공적으로 처리된다는 것을 의미하지는 않습니다. 조치: 검사는 통과했지만 저장이 여전히 실패하는 경우, 통합이 정상이라고 선언하는 대신 콜백 및 로그를 계속 확인하십시오.

2. 공용 서버 주소와 내부 서버 주소를 모두 확인하십시오.

Nextcloud에서 설정 → 관리 → ONLYOFFICE를 엽니다 . ONLYOFFICE Docs의 기본 주소는 관련 클라이언트 및 서비스에서 사용 가능해야 합니다. Docker 네트워킹, NAT, 스플릿 호라이즌 DNS 또는 방화벽 정책으로 인해 공개 URL을 내부적으로 라우팅할 수 없는 경우 고급 서버 설정을 확장하십시오.

공식 커넥터는 바로 이러한 상황을 위해 별도의 내부 주소를 제공합니다.

• ONLYOFFICE Docs 서버에서 내부 요청을 보낼 때 사용하는 주소입니다 . Nextcloud가 ONLYOFFICE에 접속하는 데 사용하는 주소입니다.
• ONLYOFFICE Docs의 내부 요청용 서버 주소 : ONLYOFFICE가 콜백 및 관련 서버 간 트래픽을 위해 Nextcloud에 연결하는 데 사용하는 주소입니다.

예를 들어, 동일한 Compose 네트워크에 있는 두 컨테이너는 내부적으로 서비스 이름을 사용할 수 있지만 브라우저는 여전히 공용 HTTPS 호스트 이름을 사용할 수 있습니다. 하지만 이 패턴을 맹목적으로 따라 하지 마십시오. 해당 이름이 네트워크에서 실제로 제대로 해석되는지 확인해야 합니다. 조치: 요청을 시작하는 머신 또는 컨테이너에서 각 방향으로 테스트를 수행하십시오.

흔히 발생하는 오해: "편집기가 열리니 DNS와 라우팅에는 문제가 없다."

그러한 결론은 신뢰할 수 없습니다. 브라우저, Nextcloud 및 ONLYOFFICE Docs는 서로 다른 네트워크 참여자입니다. 브라우저는 ONLYOFFICE office.example.com에 접속할 수 있지만, 문서 서버 컨테이너는 해당 주소를 확인하거나 연결할 수 없습니다 cloud.example.com. 마찬가지로, Nextcloud는 내부 호스트 이름을 통해 ONLYOFFICE에 접속할 수 있지만, 콜백은 연결할 수 없는 공용 주소를 가리킬 수 있습니다.

조치: ONLYOFFICE 컨테이너 또는 호스트에 접속하여 예상되는 Nextcloud 주소를 테스트하십시오. Nextcloud 호스트에 대한 기본 HTTPS 요청을 통해 DNS/TCP/TLS 연결 가능성을 확인할 수 있지만, status.php요청이 성공했다고 해서 실제 콜백 인증이나 POST 처리가 유효한 것은 아니라는 점에 유의하십시오.

3. 프록시 규칙을 변경하기 전에 JWT를 확인하세요.

JWT는 흔히 혼란을 야기하는 또 다른 요소입니다. ONLYOFFICE Docs 7.2 버전부터 JWT는 기본적으로 활성화되어 있으며 비밀 키가 자동으로 생성됩니다. 공식 지침에서는 문서 서버와 Nextcloud ONLYOFFICE 커넥터에 동일한 비밀 키를 사용하도록 요구합니다. 또한 최신 커넥터 설명서에는 기본 헤더를 사용하지 않는 설치 환경을 위한 authorization-header 설정 방법도 안내되어 있습니다.

확인됨: 공유 비밀 키가 일치해야 합니다. 배포 환경에 따라 다름: 관리 위치는 ONLYOFFICE가 패키지에서 설치되었는지, Windows에 설치되었는지, Docker에 설치되었는지에 따라 다릅니다. Docker 배포 환경에서는 JWT_SECRET일반적으로 환경 변수가 사용됩니다. 실제 서버 구성은 .에서 확인할 수도 있습니다 /etc/onlyoffice/documentserver/local.json.

조치: 양쪽의 유효한 비밀 키와 헤더 설정을 비교한 다음, 서버 측 변경 후 ONLYOFFICE 서비스 또는 컨테이너를 다시 시작하십시오. JWT를 영구적으로 비활성화하여 문제를 해결하지 마십시오. 이는 구성을 수정하는 대신 보안 제어를 제거하는 것입니다. 자세한 내용은 ONLYOFFICE의 JWT 구성 가이드를 참조하십시오 .

4. 저장 실패 시점의 ONLYOFFICE 및 Nextcloud 로그를 확인하십시오.

ONLYOFFICE는 저장 오류 발생 시 DocService 로그를 확인하는 것을 권장합니다. Linux 및 Docker 설치 환경에서는 Document Server 로그가 다음 경로에 있습니다 /var/log/onlyoffice/documentserver. Docker 사용자는 `docs.document.log` 명령어를 사용하여 컨테이너 출력을 확인할 수도 있습니다 docker logs -f <container>. 더 자세한 정보가 필요한 경우, ONLYOFFICE는 `docs.log` DS_LOG_LEVEL=DEBUG또는 `log4js` 구성을 통해 임시 디버그 모드를 사용하는 방법을 안내합니다. 자세한 내용은 공식 디버그 로깅 가이드를 참조하십시오 .

Nextcloud에서 기본 파일 기반 로그는 일반적으로 nextcloud.log구성된 데이터 디렉터리에 있습니다. 다음 명령어를 사용하여 활성 경로를 확인할 수 있습니다.

sudo -E -u www-data php occ log:file

Nextcloud는 로그 리더 앱을 사용할 수 있을 때 로그를 기록합니다. log:tail조치 : 저장 실패를 한 번 재현하고 타임스탬프를 기록한 다음 양쪽 결과를 비교합니다. 네트워크 거부, TLS 오류, 401/403 응답, 5xx 응답 또는 스토리지 예외는 각각 매우 다른 해결 방법을 나타냅니다.log:watch

5. 프로덕션 보안을 약화시키지 않고 TLS 및 리버스 프록시 문제를 해결합니다.

자체 서명 또는 개인적으로 발급된 인증서는 해당 CA가 신뢰할 수 없는 경우 서버 간 HTTPS 연결을 손상시킬 수 있습니다. 커넥터에는 "인증서 확인 비활성화(안전하지 않음)" 옵션이 있지만, ONLYOFFICE는 이 옵션을 안전하지 않다고 명시적으로 설명하며 신뢰할 수 있는 CA에서 발급한 인증서로 교체할 것을 권장합니다. 조치: 인증서 확인 우회는 통제된 환경에서 간단한 진단 단계로만 사용하십시오. 영구적인 해결책은 양쪽 서버 모두에서 신뢰할 수 있는 유효한 인증서 체인을 사용하는 것입니다.

ONLYOFFICE 앞에 리버스 프록시가 있는 경우, 예상되는 스키마, 호스트 및 업그레이드 동작이 유지되는지 확인하십시오. ONLYOFFICE는 전달 헤더 및 WebSocket 관련 설정을 포함한 리버스 프록시 관련 지침을 별도로 제공합니다. ONLYOFFICE 의 Nextcloud 리버스 프록시 구성 가이드를 참조하십시오 .

배포 환경에 따라 다릅니다. 저장 오류만으로는 정확한 Nginx, Apache, Traefik, HAProxy, ingress-controller 또는 CDN 구성을 추론할 수 없습니다. 조치: 임의로 타임아웃이나 헤더를 변경하기 전에 프록시 구성을 해당 토폴로지에 대한 공급업체 예제와 비교하고 콜백 중에 기록된 HTTP 상태를 확인하십시오.

6. 콜백이 Nextcloud에 도달하면 스토리지 및 쓰기 오류를 확인하십시오.

콜백이 Nextcloud에 성공적으로 도달했음을 로그를 통해 확인했으면 다음 단계로 넘어갑니다. Nextcloud는 새 문서를 가져와 저장된 버전을 덮어쓸 수 있어야 합니다. 로컬 파일 시스템 권한, 읽기 전용 마운트, 디스크 공간 부족, 할당량 제한, 외부 저장 장치 사용 불가 또는 애플리케이션/저장 장치 예외 등으로 인해 최종 쓰기 작업이 실패할 수 있습니다.

알려진 사실: ONLYOFFICE의 콜백 상태 값은 저장 준비가 완료된 문서와 저장 오류를 구분하며, 콜백에는 저장 서비스에서 검색할 수 있도록 편집된 문서의 URL이 포함됩니다. 공식 콜백 핸들러 문서에서는 상태 2를 저장 준비 완료, 상태 3을 저장 오류로 정의합니다.

브라우저 메시지만으로는 알 수 없는 정보가 있습니다. 오류가 ONLYOFFICE에서 발생했는지, 네트워크 경로에서 발생했는지, Nextcloud에서 발생했는지, 아니면 기본 스토리지에서 발생했는지 여부입니다. 조치: 편집기에서 저장할 수 없다는 메시지가 표시된다고 해서 Nextcloud 데이터 디렉터리의 파일 소유권을 재귀적으로 변경하지 마십시오. 먼저 Nextcloud 로그에서 스토리지 측 오류를 확인하십시오.

7. 저장 버튼과 강제 저장 동작을 이해하세요

또 다른 오해는 ' 저장 ' 버튼을 누를 때마다 Nextcloud에 저장된 파일이 즉시 덮어쓰여진다는 것입니다. 커넥터는 중간 저장 또는 강제 저장 옵션을 사용할 수 있습니다. 공식 통합 가이드에 따르면 ' 편집 중 중간 버전 유지(강제 저장)' 옵션이 활성화된 경우 '저장' 버튼을 클릭하면 변경 사항이 저장소에 직접 전송됩니다. 그렇지 않은 경우 변경 사항은 편집기 캐시에 유지되고 나중에 일반적인 최종 저장 워크플로가 진행됩니다.

이는 문제 해결에 중요합니다. 강제 저장만 실패하고 일반적인 닫기 후 저장은 성공하거나, 그 반대의 경우, 타임스탬프와 콜백 상태는 중요한 증거가 됩니다. 조치: 수동 저장, 브라우저 닫기, 여러 개의 동시 편집기 탭을 혼합하여 사용하는 대신, 명확하게 정의된 하나의 워크플로에서 실패를 재현하고 해당 시도의 로그를 수집하십시오.

빠른 진단표

수정 사항을 확인하는 방법

중요하지 않은 폴더에 작은 테스트용 DOCX 파일을 준비합니다. ONLYOFFICE에서 파일을 열고 타임스탬프와 같은 고유한 내용을 입력합니다. 편집기에서 변경 사항이 저장되었다는 메시지가 표시될 때까지 기다린 후 편집기를 정상적으로 닫습니다. Nextcloud에서 파일을 다시 열고 텍스트가 제대로 입력되었는지 확인합니다. 그런 다음, 배포 환경에서 버전 기록을 사용하는 경우 버전 기록을 확인하고, 동일한 시간대의 서버 로그도 확인합니다.

그런 다음 커넥터 검사를 다시 실행하십시오.

sudo -E -u www-data php occ onlyoffice:documentserver --check

단순히 "편집기가 열리는 것"만이 좋은 결과가 아닙니다. 완전한 테스트는 다음과 같습니다. Nextcloud가 ONLYOFFICE에 연결할 수 있고, ONLYOFFICE가 Nextcloud의 콜백 주소에 연결할 수 있으며, 인증에 성공하고, Nextcloud가 업데이트된 파일을 가져올 수 있고, 스토리지 백엔드가 교체를 수락해야 합니다.

원인이 아직 불분명할 때

로그에서 명확한 오류가 발견되지 않으면, 재현을 시도하는 동안 ONLYOFFICE 및 Nextcloud 로깅 수준을 일시적으로 높인 다음, 오류를 수정하여 로그 수준을 원래대로 되돌리십시오. Nextcloud는 DEBUG 로깅이 매우 상세하며 성능에 영향을 줄 수 있으므로, 영구적인 운영 환경 설정이 아닌 진단 목적으로만 사용해야 한다고 경고합니다. 로그 수준을 변경하기 전에 Nextcloud의 로깅 관련 문서를 검토하십시오 .

이 시점에서 정확한 타임스탬프, HTTP 상태 코드, 커넥터 버전, Nextcloud 버전, ONLYOFFICE Docs 버전, 토폴로지 및 관련 로그 라인을 삭제된 상태로 보존하십시오. 이러한 정보는 브라우저의 일반적인 "문서를 저장할 수 없습니다"라는 메시지보다 훨씬 더 유용합니다.

공식 참고 자료

• ONLYOFFICE: Nextcloud 통합 가이드
• ONLYOFFICE Docs API 문제 해결
• ONLYOFFICE 콜백 핸들러 API
• ONLYOFFICE JWT 구성
• Nextcloud 로깅 구성