Immich 오류가 클라이언트에서 발생한 것인지 서버에서 발생한 것인지 확인하는 방법

Eva Wong 는 테크니컬 라이터 이자 상주 메이커 로 ZimaSpace에서 활동합니다. 평생 기술을 사랑해 온 그녀는 홈랩과 오픈 소스 소프트웨어에 열정을 품고 있으며, 복잡한 기술 개념을 누구나 이해하기 쉬운 실습 가이드로 풀어내는 데 전문성을 갖추고 있습니다. Eva는 셀프 호스팅이 어렵고 부담스러운 일이 아니라 즐거워야 한다고 믿습니다. 그녀는 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 어려움을 풀어내고, 첫 NAS를 조립하는 것부터 Docker 컨테이너를 능숙하게 다루는 것까지 도전하도록 돕습니다.

변수 하나만 바꿔 같은 작업을 재현하고 실패한 요청의 경로를 추적해 Immich 오류가 클라이언트 측인지 서버 측인지 판별하세요.

“서버 오류”라고 표시되는 모바일 배너도 클라이언트 상태, TLS, 리버스 프록시 또는 서버가 올바르게 거부한 요청 때문에 발생했을 수 있습니다. 마찬가지로 브라우저에서만 발생하는 오류라고 해서 브라우저에 문제가 있다고 단정할 수는 없습니다. 계정, 파일, 작업은 동일하게 유지하고 클라이언트와 경로를 비교한 다음 상태 코드와 동기화된 로그를 사용해 처음 실패한 계층을 찾으세요.

두 번째 클라이언트에서 같은 작업 재현하기

로그인, 이미 알려진 파일 열기, 같은 소용량 사진 업로드, 같은 검색 실행처럼 결과가 일관적인 작업을 하나 선택하세요. 네트워크 경로를 바꾸지 않은 채 브라우저와 모바일 클라이언트에서 같은 계정으로 반복하세요. 두 시도의 정확한 시간과 결과를 기록하세요.

다른 접속 경로를 테스트하던 중 Android 클라이언트에서 실패한 최근 Immich 사례는 여러 클라이언트를 비교하는 것이 얼마나 유용한지 보여 줍니다. 한 게시물의 원인이 모든 경우에 적용되는 것은 아니지만, 특정 클라이언트에서만 문제가 발생한다는 결과는 다음에 살펴볼 위치를 크게 좁혀 줍니다.

모든 클라이언트에서 같은 작업이 동시에 실패한다면 서버, 데이터베이스, 저장소 또는 공통 네트워크 경로를 먼저 살펴보세요. 같은 엔드포인트를 사용하는 다른 클라이언트는 성공하는데 한 클라이언트에서만 실패한다면 클라이언트 버전, 캐시된 상태, 권한, 로컬 인증서 신뢰 설정, 그리고 서로 다른 정확한 요청을 확인하세요.

계정이나 파일은 그대로 두고 경로만 바꾸세요

다음으로 신뢰할 수 있는 로컬 경로와 일반적인 리버스 프록시, VPN, 터널 또는 원격 경로를 비교하세요. 같은 계정과 작업을 사용하세요. 로컬에서는 성공하지만 원격에서는 실패한다면 미디어 파일 자체보다는 DNS, TLS, 프록시, 방화벽 또는 업스트림 라우팅 계층에 문제가 있을 가능성이 높습니다.

ZimaSpace의 로컬 경로와 원격 경로 진단 가이드에서는 LAN 접속 성공과 인터넷 접속 성공이 서로 다른 사실을 입증하는 이유를 설명합니다. 모바일 앱을 재설치하거나 서버를 다시 구축하기 전에 이 구분을 Immich에 적용해 보세요.

두 경로에서 똑같이 실패한다면 프록시 설정을 더는 바꾸지 말고 애플리케이션 측 요청을 살펴보세요. 프록시 경로에서만 실패한다면 프록시 상태 코드, TLS 결과, 업스트림 응답, 시간 초과를 기록하세요. 이처럼 한 번에 하나의 변수만 비교하면 클라이언트 메시지 때문에 조사가 엉뚱한 계층으로 향하는 것을 막을 수 있습니다.

상태 코드는 최종 판정이 아닌 단서로 활용하세요

HTTP 상태 코드는 어디를 살펴봐야 할지 분류하는 데 도움이 되지만, 문제를 일으킨 구성 요소를 자동으로 밝혀 주지는 않습니다. 4xx는 요청, 인증 또는 권한이 올바르지 않았음을 의미하는 경우가 많고, 5xx는 서버 측 구성 요소가 요청을 처리하지 못했음을 나타냅니다. 프록시는 Immich가 요청을 받기 전에 두 종류의 코드를 모두 생성할 수 있습니다.

액세스 로그 필드 가이드에서는 상태 코드, URL 경로, 요청 시간, 원격 호스트, 요청 식별자를 유용한 문제 해결 필드로 강조합니다. 관련 없는 수천 줄을 훑는 대신 실패한 작업 하나에 대한 해당 값을 수집하세요.

프록시에 502 또는 시간 초과가 기록되었지만 일치하는 Immich 요청이 없다면 업스트림 경로를 추적하세요. Immich 로그에 요청이 기록되고 결정적인 4xx 응답을 반환한다면 인증, 권한 또는 요청 내용을 확인하세요. 클라이언트에는 실패로 표시되지만 모든 서버 측 계층에서 2xx가 확인된다면 클라이언트의 파싱, 로컬 캐시 또는 후속 요청을 점검하세요.

동일한 타임스탬프에서 오류율, 지연 시간, 서버 로그를 대조하세요

요청 하나의 실패는 예외적인 경우일 수 있습니다. 해당 작업을 5~10회 재현하고 관련 서버 및 프록시 로그를 확인하면서 성공률과 지연 시간을 기록하세요. 리소스 압박이나 대기열 급증 중에 오류가 증가한다면 두 번째 시도는 성공하더라도 서버에 간헐적인 장애가 발생할 수 있습니다.

Better Stack의 서비스 신호로서의 오류 및 지연 시간 개요는 오류율을 지연 시간 및 트래픽과 구분합니다. 이러한 관점은 잘못된 클라이언트 요청 하나와 부하가 걸릴 때만 성능이 저하되는 서버 경로를 구별하는 데 도움이 됩니다.

여러 클라이언트에 대해 서버 로그에 동일한 예외가 기록된다면, 반증될 때까지 서버 측 문제로 간주하세요. 서버에 실패한 요청이 전혀 도달하지 않는다면 DNS, TLS, 프록시, 클라이언트 네트워크를 추적하세요. 특정 클라이언트 하나만 다른 형태의 요청을 생성한다면 차이를 확인할 수 있도록 충분한 증거를 보존한 뒤 해당 클라이언트를 업데이트하거나 초기화하세요.

2×2 테스트로 최종 판단하기

클라이언트 두 개와 경로 두 개를 사용하세요. 브라우저-로컬, 브라우저-원격, 모바일-로컬, 모바일-원격입니다. 같은 계정과 테스트용 에셋을 유지하세요. 이 매트릭스를 사용하면 클라이언트별 장애, 경로별 장애, 모든 조합에 영향을 미치는 서버 장애를 구분할 수 있습니다.

한 클라이언트는 두 경로에서 모두 실패하고 다른 클라이언트는 통과한다면 클라이언트 원인이라는 근거가 됩니다. 두 클라이언트가 한 경로에서만 실패한다면 경로 원인이라는 근거가 됩니다. 네 가지 조합 모두 같은 애플리케이션 오류를 재현하고 서버 로그에 동일한 실패 작업이 기록된다면 서버 원인이라는 근거가 됩니다.

확인된 계층을 수정한 후 네 개 셀을 모두 다시 실행하고 영향을 받은 구성 요소를 한 번 재시작하세요. 원래 실패한 셀이 다른 검사 항목을 망가뜨리지 않고 통과하면 중단하세요. 일반적인 스크린샷 대신 매트릭스, 타임스탬프, HTTP 상태 코드, 프록시 및 서버 로그 발췌, 클라이언트 버전, 재현 가능한 요청 하나를 첨부해 에스컬레이션하세요.

지원 및 팁

더 읽어보기

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.