Nginx 환경에서 ONLYOFFICE Document Server 502 Bad Gateway 오류를 해결하는 방법

브라우저에서 ONLYOFFICE Docs URL을 열 때 "502 Bad Gateway" 오류가 표시되거나 Nextcloud/ownCloud 커넥터가 문서 서버에 연결할 수 없는 경우가 있습니다. 두 경우 모두 Nginx가 요청을 수신하지만 상위 서버(ONLYOFFICE의 내부 문서 서비스, Docker 컨테이너 또는 다른 리버스 프록시)로부터 유효한 응답을 받지 못하는 것이 원인입니다. 먼저 어떤 Nginx 서버가 502 오류를 반환했는지 확인한 후, 설정을 변경하기 전에 해당 서버를 직접 테스트하십시오.

ONLYOFFICE의 최신 Linux 문제 해결 가이드에서는 서비스와 문서 서버 로그를 확인하도록 권장합니다 ds-docservice. ds-converter역방향 프록시 가이드에서는 전달된 호스트 및 프로토콜 헤더도 언급합니다. 아래 순서는 서비스 상태를 먼저 확인한 다음 Nginx 라우팅 및 Docker 네트워킹을 확인합니다.

1. 어떤 Nginx 서버에서 502 오류가 발생하는지 확인하세요.

ONLYOFFICE 패키지 설치에는 자체 Nginx 구성이 포함되어 있으며, 배포 환경에는 외부 Nginx 리버스 프록시가 있을 수도 있습니다. Docker를 사용하면 네트워크 홉이 하나 더 추가될 수 있습니다. 502 페이지만으로는 레이어를 정확히 파악하기 어려울 수 있으므로, 공개 URL을 로컬 상태 확인 및 Nginx 오류 로그와 비교해 보세요.

패키지 기반 Linux 설치 환경에서 로컬 문서 서버 엔드포인트를 테스트합니다.

curl -i http://127.0.0.1/healthcheck

서버가 기본 포트가 아닌 다른 로컬 포트에서 ONLYOFFICE를 제공하도록 구성된 경우 해당 포트를 사용하십시오. 정상적인 설치에서는 일반적으로 HTTP 성공 응답이 반환됩니다 true. 로컬 요청이 실패하면 외부 프록시를 수정하기 전에 문서 서버 서비스를 수정하십시오. 로컬에서는 성공하지만 공용 호스트 이름에서 502 오류가 반환되는 경우 외부 Nginx 업스트림, 프로토콜, 헤더 및 방화벽 경로에 집중하십시오.

예상되는 포트를 소유하는 프로세스를 확인하십시오.

sudo ss -ltnp | grep -E ':(80|443|8080|8000)\b'

포트는 토폴로지에 따라 다릅니다. 일반적인 Docker 매핑에서는 호스트 포트(예: 8080)를 컨테이너 포트 80으로 할당합니다. 패키지 설치 시 호스트의 Nginx를 사용할 수도 있습니다. 127.0.0.1:80두 서비스가 같은 머신에 있다고 해서 해당 서비스가 올바른 상위 포트라고 가정해서는 안 됩니다.

2. ONLYOFFICE 서비스 및 로그를 확인하십시오.

리눅스 패키지 설치 시 문서 서비스와 변환기를 검사하십시오.

sudo systemctl status ds-docservice ds-converter
sudo journalctl -u ds-docservice -u ds-converter --since "15 minutes ago" --no-pager

ONLYOFFICE의 문제 해결 가이드에서는 Docs 서비스 시작 실패 시 확인해야 할 사항으로 메모리 부족, 포트 80 충돌, 서비스 로그 등을 나열합니다. 서비스가 중지된 경우 먼저 오류를 확인한 후 해당 서비스만 다시 시작하십시오.

sudo systemctl restart ds-docservice

메인 Linux 로그 디렉터리는 입니다 /var/log/onlyoffice/documentserver/. Nginx 오류 로그와 docservice 로그에서 "연결 거부됨", "상위 스트림 시간 초과" 또는 파일 누락과 같은 메시지를 확인하십시오. 이러한 메시지는 각각 다른 원인을 나타냅니다. 연결 거부는 일반적으로 상위 프로세스 또는 포트를 사용할 수 없음을 의미하며, 시간 초과는 서비스 과부하 또는 중단을 의미할 수 있습니다.

서비스가 반복적으로 종료되는 경우 디스크 및 메모리 사용 가능 여부도 확인하십시오.

df -h
free -h

오류가 발생하는 서비스를 로그를 확인하지 않고 계속해서 재시작하지 마십시오. 재시작은 일시적으로 증상을 숨길 수는 있지만 포트 충돌, 종속성 오류 또는 리소스 문제를 해결하지 못할 수 있습니다.

3. Nginx가 접근 가능한 업스트림을 가리키는지 확인합니다.

활성화된 가상 호스트를 읽고 정확한 주소와 포트를 확인합니다 proxy_pass. 해당 Nginx가 실행되는 머신 또는 컨테이너에서 업스트림에 직접 요청합니다. 예를 들어, 컨테이너가 80번 포트를 호스트 포트 8080으로 게시하는 경우 다음과 같이 합니다.

curl -i http://127.0.0.1:8080/healthcheck

예시 주소를 프록시에서 실제로 접근 가능한 엔드포인트 주소로 바꾸십시오. Nginx가 별도의 Docker 컨테이너에서 실행되는 경우, 127.0.0.1Docker 호스트나 ONLYOFFICE 컨테이너가 아닌 해당 Nginx 컨테이너 자체를 참조해야 합니다. 공유 Docker 네트워크에서 접근 가능한 서비스 이름 또는 올바른 호스트 주소와 공개된 포트를 사용하십시오.

업스트림 스키마가 백엔드와 일치하는지 확인하십시오. http://백엔드 리스너가 일반 HTTP를 사용하고 https://TLS로 구성된 경우에만 사용하십시오. TLS 포트로 HTTP를 보내거나 일반 HTTP 포트로 TLS를 보내면 정상적인 서비스가 Nginx에서 사용 불가능한 것으로 인식될 수 있습니다.

4. 전달된 헤더와 WebSocket 프록싱을 확인하세요.

ONLYOFFICE의 리버스 프록시 가이드에서는 애플리케이션이 원래 프로토콜과 호스트 이름을 알 수 X-Forwarded-Proto있도록 유지하라고 권장합니다 X-Forwarded-Host. 공식 Nginx 예제에서도 업그레이드 헤더를 전달합니다. ONLYOFFICE 앞에 외부 프록시가 있는 경우, 해당 프록시의 구성을 사용자의 네트워크 토폴로지에 맞는 공식 시나리오와 비교하십시오.

Docker 컨테이너를 호스트 포트 8080에 매핑하는 간단한 예시가 아래에 나와 있습니다. 해당 map지시문을 Nginx http컨텍스트 내에 넣고 호스트 이름, TLS 구성 및 업스트림 포트를 사용자의 설정에 맞게 수정하십시오.

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name docs.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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 $connection_upgrade;
    }
}

이것은 참조용 패턴이며, 모든 설치 환경에 바로 적용할 수 있는 대체 설정이 아닙니다. 특히, 패키지에 포함된 ONLYOFFICE Nginx 설정 위에 이 패턴을 붙여넣기 전에 포트 80과 443을 어떤 서버 블록이 소유하고 있는지 반드시 확인해야 합니다. Nginx가 패키지에 포함된 ONLYOFFICE와 동일한 호스트를 사용하는 경우, 먼저 포트 충돌이 없는지 확인하고 외부 프록시를 배포 환경에 맞게 구성된 내부 리스너로 라우팅해야 합니다.

편집 후 Nginx를 다시 로드하기 전에 구성을 테스트하십시오.

sudo nginx -t
sudo systemctl reload nginx

구성 테스트가 실패하면 다시 로드하기 전에 보고된 파일과 줄을 수정하십시오. 구문 오류와 상위 시스템의 502 오류는 별개의 문제입니다. 테스트 성공은 nginx -t구문이 올바르다는 것을 확인하는 것이지 상위 시스템이 응답한다는 것을 의미하지 않습니다.

5. ONLYOFFICE가 Docker에서 실행되는 경우, 상태 및 포트 매핑을 확인하십시오.

컨테이너가 실행 중인지, 그리고 어떤 호스트 포트가 공개되었는지 확인하십시오.

docker ps --filter name=onlyoffice
docker port <container_name_or_id>
docker logs --tail 100 <container_name_or_id>

Docker 공식 설치 가이드에서는 호스트 포트를 컨테이너 포트 80에 매핑하고, 예제에서는 환영 페이지가 로드되지 않으면 컨테이너 로그를 확인합니다. docker port호스트 측 업스트림 포트로는 표시된 포트를 사용하십시오. Nginx와 ONLYOFFICE를 모두 컨테이너로 실행하는 경우, 두 서비스를 공유 네트워크에 배치하고 호스트의 루프백 주소가 아닌 ONLYOFFICE 서비스 이름과 컨테이너 포트로 라우팅해야 합니다.

Compose 파일에 상태 확인이 정의되어 있다면 컨테이너의 상태를 확인하세요. 현재 상위 Compose 예제는 http://localhost:8000/info/info.json컨테이너 내부에서 상태를 확인합니다. "실행 중"인 컨테이너라도 문서 서비스에 문제가 있을 수 있습니다. 문서 서비스가 재시작되거나 비정상적인 상태라면 외부 프록시를 변경하기 전에 로그를 사용하여 데이터베이스 시작, 메모리 및 구성을 조사하세요.

ONLYOFFICE는 로그, 인증서 및 파일 캐시에 대한 영구적인 Docker 경로를 문서화합니다. 문제 해결 중에는 볼륨을 삭제하지 마십시오. 볼륨에는 서비스 복구에 필요한 인증서 또는 기타 데이터가 포함될 수 있습니다.

6. 시스템을 새로고침하고, 상태 엔드포인트를 테스트한 후, 통합을 다시 테스트합니다.

확인된 문제를 수정한 후, 공개 호스트 이름을 테스트하고 로컬 엔드포인트와 비교하십시오.

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

실제 문서 서버 URL을 사용하십시오. 로컬 업스트림과 공용 호스트 이름 모두에서 성공적인 응답이 나오면 Nginx가 백엔드에 연결하여 상태 응답을 반환할 수 있음을 나타냅니다. 그런 다음 문서 서버 시작 페이지를 열고 Nextcloud, ownCloud 또는 다른 커넥터에서 원래 실패했던 작업을 다시 시도하십시오.

상태 점검은 성공했지만 커넥터에서 여전히 오류가 보고되는 경우, 남은 문제는 Nginx 502 오류 경로 외부에 있을 수 있습니다. 예를 들어 커넥터 URL, TLS 신뢰 또는 JWT 설정 등이 원인일 수 있습니다. 프록시 시간 초과 값을 무작정 변경하는 대신, 이러한 값들을 커넥터 및 ONLYOFFICE 구성과 비교해 보십시오.

빠른 진단

공식 참고 자료

• ONLYOFFICE Docs Linux 문제 해결
• 프록시 서버 뒤에서 OnlyOffice 문서를 열 수 있습니다.
• ONLYOFFICE 공식 Nginx HTTPS-to-HTTP 프록시 예제
• ONLYOFFICE 문서 Docker 설치 및 포트 매핑
• ONLYOFFICE 문서 서버 작성 예시