ONLYOFFICE의 Nginx 502 오류를 해결하기 위해 상위 원인을 추적하세요

먼저 Nginx와 ONLYOFFICE Docs 간의 연결을 확인한 다음 502 응답에 해당하는 오류 로그를 읽어보세요. 502 Bad Gateway 오류는 게이트웨이가 상위 서버에서 유효한 응답을 받지 못했음을 의미하며, 이 오류 자체만으로는 Nginx의 공용 구성이 원인임을 입증하는 것은 아닙니다. Docker 환경에서는 일반적으로 Nginx가 내부 포트 80에서 문서 서버 서비스 이름으로 접속하도록 설정하고 두 컨테이너가 네트워크를 공유하도록 하는 것이 해결 방법입니다.

Nginx를 수정하기 전에 무엇을 확인해야 할까요?

리버스 프록시는 클라이언트 요청을 수락하여 다른 서버로 전달하는 서버입니다. 일반적인 배포 환경에서 공용 Nginx 서버는 HTTPS를 처리하고 ONLYOFFICE Docs로의 요청을 HTTP를 통해 전달합니다. ONLYOFFICE Docs는 자체적으로 내부 Nginx 서버를 실행하므로 외부 프록시 서버 또는 문서 서버 컨테이너 자체에서 502 오류 페이지가 생성될 수 있습니다.

먼저 응답을 보낸 서버를 확인합니다. 페이지의 서버 헤더와 타임스탬프를 외부 프록시 로그 및 문서 서버 로그와 비교합니다. Docker 환경의 경우 컨테이너 상태와 최근 시작 메시지를 확인합니다.

docker ps --filter name=onlyoffice-documentserver
docker logs --tail 100 onlyoffice-documentserver

컨테이너가 재시작 중이거나 방금 시작된 경우 프록시 설정을 변경하기 전에 로그를 확인하십시오. ONLYOFFICE는 데이터베이스 초기화로 인해 첫 시작 시 1~2분 정도 소요될 수 있다고 안내합니다. 네이티브 Linux 설치의 경우, ds-docservice및 ds-converter명령어를 사용하여 확인하십시오 systemctl status. 문서 서버 로그는 경로에 있습니다 /var/log/onlyoffice/documentserver/.

서비스가 중지된 경우 해당 ONLYOFFICE Linux 문제 해결 공식 지침을 참조하십시오.

Nginx가 상위 문서 서버에 연결할 수 있습니까?

노트북뿐만 아니라 Nginx 컨테이너 또는 호스트에서도 테스트하십시오. 서로 다른 Docker 네트워크에 있는 컨테이너는 두 컨테이너 모두 실행 중이더라도 서비스 이름으로 서로를 확인할 수 없습니다. Nginx와 ONLYOFFICE가 사용자 정의 Docker 네트워크를 공유하는 경우 Compose 서비스 이름 또는 확인 가능한 컨테이너 이름과 컨테이너의 수신 포트를 사용하십시오. 공식 Docker 설치 가이드에서는 기본 문서 서버 수신 포트로 80번 포트를 지정합니다. 8080:80과 같이 호스트 포트를 공개하더라도 내부 포트는 변경되지 않습니다.

프록시 컨테이너에서 다음 명령을 실행하세요.

curl -I http://onlyoffice-documentserver:80/

`<service name>` 부분을 실제 Compose 서비스 이름으로 바꾸세요 onlyoffice-documentserver. "호스트를 확인할 수 없습니다"라는 메시지가 표시되면 두 컨테이너를 동일한 Docker 네트워크에 연결하거나 업스트림 이름을 수정하세요. "연결 거부됨"은 일반적으로 대상 호스트는 확인되었지만 해당 포트에서 연결을 수락하는 프로세스가 없거나, 컨테이너가 준비되지 않았거나, 잘못된 포트가 사용되었음을 의미합니다. 네이티브 설치인 경우, 로컬 주소와 구성된 포트를 사용하여 테스트해 보세요(예: `/usr/local/bin/`) curl -I http://127.0.0.1/.

ONLYOFFICE의 Docker 가이드에서는 기본 포트, 포트 매핑, 시작 지연 및 컨테이너 로그에 대해 다룹니다: Docker 설치 및 확인 .

Nginx 프록시 대상을 어떻게 수정하나요?

ONLYOFFICE 호스트 이름에 대한 HTTPS 가상 호스트에서 proxy_pass접근 가능한 업스트림을 가리키도록 설정합니다. 이 예에서는 공유 Docker 네트워크와 위에 표시된 서비스 이름을 가정합니다. 실제 배포 환경에 맞게 변경하십시오.

location / {
    proxy_pass http://onlyoffice-documentserver:80;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

컨테이너화된 프록시를 특정 호스트 주소로 지정하지 마십시오. 127.0.0.1:8080단, 문서 서버가 실제로 동일한 컨테이너 내에서 수신 대기 중이거나 호스트 주소가 의도적으로 구성되어 접근 가능한 경우는 예외입니다. 여기서 "컨테이너 내부"란 127.0.0.1해당 컨테이너 자체를 의미합니다. 또한 문서 서버 엔드포인트가 일반 HTTP인 경우 업스트림으로 HTTPS를 전송하지 마십시오.

전달된 프로토콜과 호스트는 ONLYOFFICE에 클라이언트가 사용한 공개 URL을 알려주고, 업그레이드 헤더는 실시간 에디터 통신에 사용되는 WebSocket 연결을 허용합니다. ONLYOFFICE는 프록시 뒤에서 문서를 실행하는 방법 에 대한 예제를 제공하며 , 여기에는 Nginx HTTPS-HTTP 변환 구성이 포함됩니다 . 환경에 프록시 홉이 여러 개 있거나 URL 경로 접두사를 사용하는 경우, 해당 전체 예제와 비교해 보세요.

변경 사항을 적용하기 전에 `nginx reload` 명령어를 사용하여 구성을 검증한 nginx -t다음, 호스트 또는 컨테이너에 맞는 재로드 방법을 사용하여 Nginx를 다시 시작하십시오. 모든 서비스를 한 번에 다시 시작하지 마십시오. 단계적으로 재로드하면 상위 버전 수정 사항이 결과에 어떤 영향을 미쳤는지 쉽게 확인할 수 있습니다.

ONLYOFFICE에서 여전히 502 오류가 반환되면 어떻게 해야 하나요?

외부 프록시가 문서 서버 시작 페이지에는 접속할 수 있지만 /healthcheck502 오류를 반환하는 경우, 문제는 공용 Nginx 서버가 아닌 문서 서버 내부에 있을 수 있습니다. 문서 서버 컨테이너 로그와 내부 서비스 로그를 확인하십시오. 네이티브 Linux 설치의 경우, 위에서 언급한 서비스 상태 명령과 로그 디렉터리를 검토하십시오. /welcome/응답은 있지만 상태 확인이 실패하는 경우, 이 두 가지를 별개의 신호로 간주하십시오. 정적 시작 페이지가 표시된다고 해서 문서 서비스와 그 종속 서비스가 정상이라는 것을 보장하는 것은 아닙니다.

JWT를 비활성화하여 이 문제를 "해결"하지 마십시오. JSON Web Token(JWT) 유효성 검사는 통합 요청을 인증하는 데 사용됩니다. JWT 불일치는 일반적으로 권한 부여 오류를 발생시키며, 상위 서버에 연결할 수 없는 네트워크 수준의 문제는 아닙니다. 프록시가 응답하지만 통합에서 권한 부여 또는 토큰 오류가 발생하는 경우에만 JWT 설정을 확인하십시오.

마지막으로 Nginx가 올바른 호스트 이름을 올바른 가상 호스트로 라우팅하는지 확인하십시오. 업스트림 DNS 이름이나 포트에 오타가 있으면 트래픽이 다른 곳으로 전송되거나 프록시가 오래된 구성을 사용하게 될 수 있습니다. Nginx 오류 로그에서 , , 또는 server_name와 같은 줄을 확인하십시오 . 각 줄은 서로 다른 계층을 가리킵니다.host not found in upstreamconnect() failedupstream timed out

수정 사항이 제대로 적용되었는지 어떻게 확인할 수 있나요?

프록시 네트워크에서 업스트림을 다시 테스트한 다음, 공용 상태 엔드포인트를 확인하고 연결된 플랫폼을 통해 문서를 엽니다.

curl -I https://docs.example.com/healthcheck

성공적인 상태 점검 응답은 더 이상 502 오류가 아니어야 하며, 실제 문서가 열리고 편집하는 동안 연결 상태가 유지되어야 합니다. 상위 테스트는 성공했지만 공개 요청이 여전히 실패하는 경우, 선택한 Nginx 가상 호스트, 로드된 구성 및 로그에 집중하십시오. 공개 환영 페이지는 정상적으로 표시되지만 상태 점검에서 여전히 502 오류가 발생하는 경우, ONLYOFFICE의 내부 서비스 진단을 진행하십시오.

Nginx 지시문의 동작에 대해서는 Nginx 프록시 모듈 공식 문서를 참조하십시오 . 정확한 명령 및 서비스 이름은 Docker Compose 프로젝트, Linux 배포판 및 ONLYOFFICE 버전에 따라 다를 수 있으므로 실제 이름으로 변경하고 응답을 생성한 구성 요소의 로그를 확인하십시오.