셀프 호스팅 앱은 로컬에서 열리지만 API에 연결할 수 없을 때 무엇을 확인해야 하나요?

에바 왕

IceWhale author

에바 왕 는 기술 작가 그리고 이자 ZimaSpace의 상주 장인입니다. 평생을 기술에 열정을 가진 사람으로서 홈랩과 오픈소스 소프트웨어에 열정을 가지고 있으며,복잡한 기술 개념을 쉽게 이해할 수 있는 실습 가이드로 번역하는 데 전문성을 가지고 있습니다.에바는 셀프 호스팅이 어렵지 않고 재미있어야 한다고 믿습니다. 그녀의 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 신비를 풀도록돕고 있습니다. 첫 NAS 구축부터 Docker 컨테이너 마스터링까지.

What Should You Check When a Self-Hosted App Opens Locally but Its API Cannot Be Reached?

페이지가 로컬에서 열린다는 사실만으로 API 경로가 작동한다고 증명할 수는 없습니다. 브라우저 인터페이스와 백엔드 요청은 서로 다른 호스트, 포트, 프로토콜 또는 인증 정보를 사용할 수 있습니다.

홈 서버에서는 리버스 프록시, 브라우저 캐시 또는 로컬 웹 컨테이너를 통해 HTML과 정적 자산이 로드되는 반면, API 호출은 다른 서비스, 하위 경로, WebSocket 엔드포인트 또는 외부에서 구성된 기본 URL로 전달될 수 있습니다. 먼저 브라우저에서 실패한 요청 하나를 캡처하고, 관련 네트워크 경계에서 해당 요청을 재현한 다음, 눈에 보이는 페이지가 전체 스택에 연결된다는 증거라고 간주하지 말고 라우팅, TLS, 인증, 브라우저 정책, 애플리케이션 구성을 각각 분리해 확인하세요.

페이지와 API가 동일한 네트워크 경로를 사용하는지 확인하기

브라우저 개발자 도구를 열고 실패하는 동작을 다시 실행하세요. 요청 URL, 메서드, 상태 코드, 응답 본문, 원격 주소, 요청 시작 주체(initiator), 그리고 실패가 일반 HTTP 요청, WebSocket, 서버 전송 이벤트 또는 백그라운드 fetch 중 무엇인지 기록하세요.

셀프 호스팅 Baserow 사례에서는 브라우저의 이벤트 채널이 다른 프록시 경로를 따르는 탓에 사용할 수 있는 인터페이스에서 반복적으로 재연결을 보고했습니다. 눈에 보인 증상은 전체 웹 서버 중단이 아니라 실패한 이벤트 연결이었습니다.

성공한 문서 요청과 실패한 API 요청을 문자 단위로 비교하세요. 스킴, 호스트 이름, 포트, 경로 접두사, 쿼리 문자열을 확인합니다. 서로 다르다면 처음 변경된 계층을 조사하세요. 모두 동일하다면 헤더, 쿠키, 응답 처리 및 백엔드 라우팅을 계속 확인하세요.

API 기본 URL, 포트 및 하위 경로 확인하기

애플리케이션의 공개 URL, API URL, WebSocket URL, 기본 경로 및 프런트엔드 빌드 시점 변수를 확인하세요. 로컬에서 제공되는 인터페이스에 오래된 도메인, 사설 IP, 잘못된 포트 또는 서버에서만 존재하는 루트 경로를 가리키는 절대 API 주소가 포함되어 있을 수 있습니다.

하위 경로 배포는 슬래시 처리와 재작성 규칙에 특히 민감합니다. Frigate 리버스 프록시 사례에서는 메인 인터페이스에 접근할 수 있었음에도 리소스 실패의 원인이 하위 경로 재작성 동작으로 밝혀졌습니다.

올바른 경로를 확인하기 위한 목적으로만 구성된 접두사를 포함하거나 제외한 API 엔드포인트를 테스트한 다음, 애플리케이션과 프록시가 하나의 표준 경로에 동의하도록 수정하세요. 일부 메서드만 작동하고 업로드, 콜백 또는 스트리밍 엔드포인트가 의도한 백엔드를 계속 우회하게 만드는 중복 재작성 예외를 유지하지 마세요.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

리버스 프록시 헤더, TLS 및 스트리밍 지원 확인하기

일반 페이지용 프록시 경로와 API, WebSocket 및 스트리밍 요청용 경로를 비교하세요. 업스트림 서비스 이름, 내부 포트, HTTP 버전, 연결 업그레이드 동작, 읽기 시간 제한, 버퍼링 정책, 전달되는 호스트 및 프로토콜 헤더를 확인합니다.

Open WebUI 사용자들은 직접 접근할 때와 프록시를 거칠 때 버퍼링 또는 스트리밍 동작이 달라져, 인터페이스는 정상적으로 보이지만 프록시된 API 출력이 멈추는 문제를 보고했습니다. 진단의 초점은 정적 페이지가 아니라 프록시된 스트리밍 경로입니다.

신뢰할 수 있는 프록시 헤더를 제한적으로 구성해 원래 호스트 이름과 스킴을 백엔드로 전달하세요. 필요한 경로에서만 WebSocket 업그레이드를 활성화하고, 스트리밍 엔드포인트에는 부적절한 버퍼링을 비활성화하세요. 또한 프록시가 실수로 공개 호스트 포트가 아니라 애플리케이션의 내부 리스너를 사용하도록 설정되었는지 확인하세요.

브라우저 정책과 서버 연결 가능성 분리하기

직접 명령은 성공하지만 브라우저에서 실패한다면 브라우저 콘솔에서 CORS, 혼합 콘텐츠, 인증서, 쿠키 및 프리플라이트 오류를 확인하세요. 서버가 올바르게 응답하더라도 브라우저가 요청을 전송하거나 응답을 노출하지 않을 수 있습니다.

리버스 프록시를 사용하는 Open WebUI 논의에서는 WebSocket 및 API 실패를 오리진과 전달된 프로토콜 처리와 연결하며, 프록시를 통과하는 동안 오리진과 프로토콜 신원을 일관되게 유지해야 하는 이유를 보여 줍니다.

HTTPS 페이지가 HTTP API를 호출하지 않는지, API가 필요한 오리진만 허용하는지, 프리플라이트 요청이 동일한 경로에 도달하는지, 세션 쿠키의 도메인·경로·Secure·SameSite 속성이 올바른지 확인하세요. 브라우저 보호 기능을 전역적으로 비활성화하지 말고 서버의 공개 신원과 정책을 수정하세요.

필요한 모든 네트워크에서 전체 API 워크플로 검증하기

첫 번째 실패 요청이 작동한 뒤 LAN과 지원되는 모든 원격 경로에서 로그인, 목록 또는 검색, 생성 또는 업데이트, 업로드, 다운로드, 백그라운드 이벤트 및 토큰 갱신 한 건을 테스트하세요. GET 요청 하나가 성공했다고 해서 인증된 쓰기 작업이나 장시간 연결까지 복구되었다고 볼 수는 없습니다.

주소로 직접 API 호출은 작동하지만 공개 호스트 이름을 통하면 실패할 때는 ZimaSpace의 IP 연결 가능성과 도메인 라우팅을 분리하는 방법을 다음 단계로 활용하세요.

브라우저와 브라우저가 아닌 클라이언트가 의도한 표준 엔드포인트를 사용하고, 프록시가 올바른 백엔드에 연결되며, 리디렉션 과정에서도 인증이 유지되고, 브라우저 정책이 응답을 허용하며, 스트리밍 또는 WebSocket 세션이 안정적으로 유지될 때만 문제가 해결된 것입니다. 캡처한 실패 요청을 향후 업그레이드를 위한 회귀 테스트로 보관하세요.