Zimbra의 "Nginx 프록시 서비스가 중지되었습니다" 오류를 해결하는 방법

Zimbra에서 "Nginx 프록시 서비스가 중지되었습니다"라는 메시지가 표시되면 프록시 프로세스가 다운되었거나 상태 확인에서 실행 중인지 확인할 수 없는 것입니다. 프록시를 재시작하면 일시적인 중지였던 경우 접속이 복구될 수 있지만, NGINX가 생성된 구성을 로드하지 못하거나, 필요한 포트에 바인딩하지 못하거나, 인증서를 읽지 못하거나, 유효한 업스트림 서버에 연결하지 못하는 경우에도 동일한 메시지가 나타날 수 있습니다. 이상적인 결과는 단순히 상태가 녹색으로 표시되는 것뿐만이 아닙니다. 프록시가 계속 실행되고, Zimbra 웹메일이 의도된 공용 URL을 통해 정상적으로 로드되며, 프록시 로그에 시작 실패 메시지가 더 이상 표시되지 않아야 합니다.

이 가이드는 Zimbra Proxy 서비스를 사용하는 Zimbra 배포 환경에 적용됩니다. 정확한 명령 및 구성 세부 정보는 Zimbra 버전 및 토폴로지에 따라 다를 수 있습니다. 다중 서버 설치 환경에서는 프록시 노드에 대한 점검을 수행하고, 다른 서버에서 프록시가 중지되었다고 보고하더라도 사서함 또는 MTA 노드에서 프록시를 활성화하지 마십시오. Zimbra의 프록시 가이드 및 프록시 CLI 참조 문서 에서 서비스 및 진단 파일에 대한 자세한 내용을 확인할 수 있습니다. 일부 기술 센터 문제 해결 페이지는 아직 개발 중이므로, 설치된 릴리스에 대한 문서와 함께 활용하십시오.

1. 이 서버에서 프록시가 실행되어야 하는지 확인하십시오.

프록시를 호스팅하는 Zimbra 서버에 연결하고 Zimbra 계정으로 전환합니다. 전체 서비스 목록과 프록시별 상태를 모두 확인합니다.

su - zimbra
zmcontrol status
zmproxyctl status
zmprov gs `zmhostname` zimbraServiceEnabled

proxy활성화된 서비스 목록에서 NGINX 프로세스가 실행 중인지, 그리고 상태 출력에서 NGINX 프로세스가 있는지 확인하십시오 . Zimbra 문서 zmproxyctl에는 start, stop, restart, reload, 및 status작업이 표시됩니다. 이 호스트가 사서함 전용 또는 MTA 전용 노드인 경우 프록시가 중지될 수 있습니다. 서버를 활성화하기 전에 배포 환경에서 해당 서버의 역할을 확인하십시오.

프록시가 활성화되어야 하는데 상태가 중지된 경우, 변경하기 전에 현재 상태를 캡처하십시오. 이렇게 하면 재시작 실패와 노드에서 서비스가 애초에 활성화되지 않았던 경우를 구분하는 데 도움이 됩니다.

2. 재시작하기 전에 NGINX 오류 로그를 읽으십시오.

Zimbra의 프록시 문제 해결 가이드 에서는 주요 프록시 로그로 /opt/zimbra/log/nginx.log와 를 식별합니다 /opt/zimbra/log/nginx.access.log. 최근 오류 항목과 기본 구성 파일이 존재하는지 확인하십시오.

tail -n 100 /opt/zimbra/log/nginx.log
tail -n 50 /opt/zimbra/log/nginx.access.log
ls -l /opt/zimbra/conf/nginx.conf

오류 메시지는 일반적으로 다음 확인 사항을 알려줍니다. 누락된 부분이 있으면 nginx.conf생성된 구성에 대한 조사가 필요함을 나타냅니다. 지시문에 "잘못된 포트"라는 listen메시지가 있으면 포트 또는 바인딩 설정에 문제가 있음을 의미합니다. 개인 키 또는 인증서 오류는 SSL 관련 문제를 나타냅니다. 바인딩 실패는 다른 프로세스가 이미 해당 주소와 포트를 사용하고 있음을 나타냅니다.

오류를 없애기 위해 NGINX 구성 파일을 삭제하거나 생성된 파일을 수정하지 마십시오. Zimbra는 구성 디렉터리와 LDAP에 저장된 템플릿과 값을 사용하여 NGINX 구성을 생성합니다. 공급업체의 프록시 구성 및 템플릿 가이드 에서 이러한 생성 모델을 설명합니다. 생성된 파일을 수동으로 수정하면 나중에 재시작 또는 구성 업데이트 중에 내용이 덮어쓰여질 수 있습니다.

3. 지원되는 프록시 재시작 방법을 시도하고 결과를 확인하십시오.

로그에 지속적인 구성 오류 또는 인증서 오류가 표시되지 않으면 Zimbra 사용자 계정으로 Zimbra 컨트롤러를 통해 서비스를 다시 시작하십시오.

zmproxyctl restart
zmproxyctl status

그런 다음 전체 서비스 목록을 다시 확인하십시오.

zmcontrol status

성공적인 결과는 프록시가 실행 중이라고 보고하고 명령이 완료된 후에도 계속 실행 상태를 유지하는 것입니다. Zimbra의 프록시 설명서에는 zmproxyctl restart구성 생성을 호출하는 서비스 작업으로 설명되어 있습니다. 시스템 전체 systemctl restart nginx에 적용되는 대체 작업을 사용하지 마십시오. Zimbra는 자체 프록시 구성 및 서비스를 관리합니다. 재시작이 실패하면 최신 오류 메시지로 돌아가십시오 nginx.log. 오류를 확인하지 않고 반복적으로 재시작하면 일반적으로 원인이 해결되지 않습니다.

4. 오류를 적절한 수정 사항과 연결합니다.

구성 파일이 없거나 생성에 실패한 경우

Zimbra의 문제 해결 안내에서는 /opt/zimbra/conf/nginx.conf상위 속성에 존재하지 않는 서버 또는 사서함 서버가 아닌 서버가 포함되어 있어 프록시 구성 생성이 실패하는 경우를 설명합니다. 먼저 관련 서버 수준 및 전역 값을 확인하십시오.

zmprov -l gs `zmhostname` zimbraReverseProxyAvailableLookupTargets
zmprov -l gs `zmhostname` zimbraReverseProxyUpstreamEwsServers
zmprov -l gs `zmhostname` zimbraReverseProxyUpstreamLoginServers
zmprov -l gcf zimbraReverseProxyAvailableLookupTargets
zmprov -l gcf zimbraReverseProxyUpstreamEwsServers
zmprov -l gcf zimbraReverseProxyUpstreamLoginServers

각 호스트 이름을 실제 서버 인벤토리 및 의도한 라우팅 설계와 비교하십시오. 어떤 서버가 해당 트래픽을 수신해야 하는지 확인한 후에만 오래되었거나 유효하지 않은 항목을 수정하십시오. 벤더 페이지의 샘플 호스트 이름을 프로덕션 환경에 복사하지 마십시오. 공식 "Nginx 시작 실패" 문제 해결 가이드 에는 특정 구성 누락/생성기 오류 패턴에 대한 구성 생성기 명령이 나와 있습니다.

/opt/zimbra/libexec/zmproxyconfgen -s `zmhostname`
zmproxyctl restart

관찰된 오류가 해당 패턴과 일치하고 관련 값을 검토한 후에만 이 기능을 사용하십시오. 생성기가 여전히 예외를 발생시키거나 파일이 누락된 상태로 남아 있는 경우, 반복적으로 다시 실행하기보다는 중지하고 전체 스택 추적 및 서버 속성을 조사하십시오.

로그에 잘못된 포트 또는 바인딩 실패가 보고되는 경우

먼저 어떤 구성된 리스너에서 오류가 발생하는지 확인하십시오. 해당 노드의 Zimbra 서비스 및 프록시 포트 값을 확인하고, 다른 프로세스가 이미 해당 주소에서 수신 대기 중인지 검사하십시오. 예를 들어, 메시지에 포트 443이 언급된 경우, 공용 HTTPS 리스너가 Zimbra NGINX에 속해 있는지, 아니면 별도의 웹 서버 또는 로드 밸런싱 에이전트에 속해 있는지 확인하십시오. 클라이언트가 서비스에 어떻게 접근하는지 파악하기 전까지는 알 수 없는 프로세스를 종료하거나 새 포트를 할당하지 마십시오.

이러한 오류는 invalid port ...:0포트 번호를 추측할 이유가 되지 않습니다. 이는 프록시 설정이나 생성된 구성이 일관되지 않음을 나타낼 수 있습니다. 값을 예상 토폴로지와 비교하고 최근 변경 사항을 검토한 후 Zimbra에서 지원하는 도구를 사용하여 소스 설정을 수정하십시오. 그런 다음 다시 시작하고 zmproxyctl생성된 리스너가 유효한지 확인하십시오.

인증서 또는 개인 키를 로드하는 동안 시작이 실패하는 경우

전체 SSL 오류 메시지를 읽고 오류 메시지에 언급된 인증서 경로를 확인하십시오. 인증서와 개인 키가 동일한 파일인지, 예상되는 서비스 계정에서 읽을 수 있는지, 그리고 만료되지 않았는지 확인하십시오. Zimbra 프록시 문제 해결 문서에는 프록시가 키 자료를 로드할 수 없는 경우가 나와 있습니다. 파일을 임의로 교체하지 말고 사용 중인 Zimbra 버전에 맞는 인증서 배포 절차를 따르십시오. 재부팅이 성공적으로 완료되면 SSL 시작 오류가 사라지고 브라우저에서 공용 웹메일 호스트 이름에 대한 예상 인증서가 표시될 것입니다.

NGINX가 시작되었지만 사용자가 게이트웨이 오류를 보는 경우

프록시가 실행 중이라고 해서 사서함 백엔드가 정상이라는 것을 보장하는 것은 아닙니다. "호스트에 연결할 경로 없음" 오류가 발생하는 경우, Zimbra는 프록시 노드에서 DNS 확인이 제대로 되는지, 그리고 대상 백엔드에 대한 포트 연결 가능 여부를 확인하도록 권장합니다. 502 또는 503 응답이 발생하는 경우, 사서함 서비스와 상위 호스트 및 포트를 확인하십시오. 프록시 가이드에 따르면 사서함 프로세스를 사용할 수 없는 경우 503 오류가 발생할 수 있습니다. 사용 중인 릴리스 및 토폴로지에 맞는 정확한 백엔드와 포트를 사용하고, 프록시 시간 초과 또는 오류 임계값을 변경하기 전에 사서함 서버 로그를 확인하십시오.

5. 서버와 브라우저 모두에서 복구가 완료되었는지 확인합니다.

특정 부위 복구 후 다음 사항을 모두 확인하십시오.

zmproxyctl status프록시가 실행 중임을 보고합니다.
zmcontrol status이 노드에 대해 예상되는 서비스를 보여줍니다.
최신 코드 라인에서는 /opt/zimbra/log/nginx.log동일한 시작 오류가 반복되지 않습니다.
예상되는 리스너가 존재하며 의도한 서비스의 소유입니다. Linux에서 관리자는 다음 ss -ltnp명령으로 리스너를 검사할 수 있습니다. 권한 및 출력 세부 정보는 배포판에 따라 다릅니다.
브라우저는 HTTPS를 통해 일반 Zimbra 웹메일 호스트 이름에 접속하여 로그인하고 메일함을 불러올 수 있습니다. IMAP 또는 POP 클라이언트도 이 프록시를 사용하는 경우 해당 프로토콜을 별도로 테스트하십시오.

이러한 검사는 유용한 복구 단계를 정의합니다. 즉, 서비스가 실행 중이고, 리스너가 존재하며, 브라우저 경로가 제대로 작동하고, 오류가 즉시 재발하지 않은 경우입니다. 서비스 상태가 정상인데도 웹메일이 계속 실패하는 경우, DNS, TLS, 방화벽 규칙, 로드 밸런서 라우팅 또는 메일함 백엔드 상태를 확인해야 합니다. 서비스가 다시 중단되면 새로운 로그 라인과 구성 생성기 출력을 보존하십시오. 이는 무작위로 다시 시작하는 것보다 훨씬 유용합니다.

디버그 로깅은 짧고 통제된 조사에만 사용하십시오.

일반 로그로 지속적인 오류를 설명할 수 없는 경우, Zimbra는 NGINX 프록시 로그 레벨을 일시적으로 높이는 것을 문서화합니다. 디버그 로깅은 인증 토큰을 포함한 민감한 정보를 노출할 수 있으므로, 필요한 경우가 아니면 프로덕션 시스템에서 활성화하지 마십시오. 지원팀에서 디버그 로깅 사용을 지시하는 경우, 로그 접근을 제한하고 필요한 정보만 수집한 후 설정을 이전 값으로 되돌리고 보안 정책에 따라 디버그 로그를 처리하십시오. 해당 릴리스에 맞는 명령어는 Zimbra의 NGINX 디버그 로깅 지침을 참조하십시오 .

구성 생성에 계속 실패하거나, 프록시 인증서를 확인할 수 없거나, 오류가 알 수 없는 리스너와 관련되거나, 노드의 역할이 불분명한 경우 Zimbra 관리자 또는 공급업체 지원팀에 문의하십시오. 서비스 컨트롤러는 정상적인 구성을 다시 시작할 수는 있지만, 올바른 메일 라우팅을 결정하거나, 잘못된 인증서를 복구하거나, 손상된 네트워크 경로를 자체적으로 해결할 수는 없습니다.

공식 참고 자료

본 자료는 2026년 10월 6일에 검토되었습니다. 여기에 참조된 Zimbra Tech Center 페이지에는 이전 예제가 포함되어 있으며 일부는 개발 중인 내용입니다. 프로덕션 구성을 변경하기 전에 서버에 설치된 Zimbra 릴리스 버전에 따라 명령어가 올바른지 확인하십시오.