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

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

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

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

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

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

셀프 호스팅 Baserow 사례에서는 인터페이스를 사용할 수 있었지만, 브라우저의 이벤트 채널이 다른 프록시 경로를 거쳐 반복적으로 재연결을 알렸습니다. 눈에 보인 증상은 웹 서버 전체의 장애가 아니라 이벤트 연결 실패였습니다.

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

각 관련 경계에서 정확히 같은 요청을 다시 실행하기

실패한 요청 하나를 명령어로 복사해 클라이언트, 리버스 프록시 호스트, 애플리케이션 네트워크에 연결된 임시 컨테이너에서 각각 다시 실행하세요. 메서드, 인증 헤더, 콘텐츠 유형, 본문, 예상 호스트 이름을 그대로 유지하세요.

API는 TCP 및 HTTP 계층에서 연결 가능하더라도 토큰이나 헤더가 누락되면 실제 요청을 거부할 수 있습니다. FreshRSS API 관련 논의에서는 외부 연결 실패의 원인이 일반적인 컨테이너 연결 문제가 아니라 인증 컨텍스트 누락으로 좁혀졌습니다.

가장 먼저 실패한 지점을 파악하세요. DNS 오류는 이름 확인 문제를, 연결 거부는 리스너·포트 또는 네트워크 문제를, TLS 오류는 신원 또는 신뢰 문제를 나타냅니다. 401 또는 403은 인증이나 정책 문제를, 404는 대개 라우팅 또는 하위 경로 재작성 문제를 나타냅니다. 직접 호출은 성공하지만 브라우저 호출이 실패한다면 진단의 초점을 프록시나 브라우저 규칙으로 옮기세요.

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

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

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

올바른 경로를 식별하기 위해서만 설정된 접두사가 있는 경우와 없는 경우 모두 API 엔드포인트를 테스트한 다음, 애플리케이션과 프록시가 하나의 표준 경로를 사용하도록 수정하세요. 일부 메서드는 작동하지만 업로드, 콜백 또는 스트리밍 엔드포인트는 의도한 백엔드를 우회하게 만드는 중복 재작성 예외를 남겨두지 마세요.

리버스 프록시 헤더, 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 세션이 안정적으로 유지될 때만 문제가 해결된 것입니다. 향후 업그레이드에서 회귀 테스트로 사용할 수 있도록 실패한 요청을 캡처해 보관하세요.

지원 및 팁

더 읽어보기

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.