Skip to content

리버스 프록시(URL 경로 접두사)

https://host/app1/ 처럼 리버스 프록시 뒤의 하위 경로에서 Potato를 제공합니다. 배포 URL 접두사를 설정하여 정적 자산, 주석 작업, 라이브 스트림이 마운트 경로 아래에서 올바르게 해석되도록 합니다.

Potato는 https://host/app1/ 같은 URL 하위 경로 아래에서 리버스 프록시 뒤에 실행될 수 있습니다. 이는 여러 내부 서버가 하나의 공개 HTTPS 엔드포인트를 공유할 때 흔히 사용됩니다.

text
https://host/app1/  ->  http://127.0.0.1:8000/
https://host/app2/  ->  http://127.0.0.1:8001/

주석 UI는 루트 상대 URL(/static/..., /updateinstance, /annotate, /media/...)을 통해 정적 자산을 로드하고 작업을 수행합니다. Potato가 /app1 아래에 마운트되면 그렇지 않을 경우 이러한 URL이 공개 루트를 기준으로 해석되며, 이는 CSS와 JS의 404, 숨겨진 인터페이스, 또는 「annotations not saved」로 실패하는 자동 저장으로 나타납니다. 배포 접두사는 사이트별 nginx 편법 없이 이를 해결합니다.

동작 방식

아래 두 옵션 모두 WSGI의 SCRIPT_NAME을 설정하며, Potato는 이를 서버에서 렌더링되는 url_for(...) 출력과 브라우저에 window.config.url_prefix로 노출되는 클라이언트 측 접두사를 위한 단일 진실 공급원으로 읽습니다. 이 접두사는 fetch(), sendBeacon(), EventSource 및 루트 상대 href/action/src 속성을 감쌉니다. 접두사가 설정되지 않으면 SCRIPT_NAME이 비어 있고 아무것도 변경되지 않으므로, 일반적인 potato start 실행에서는 아무 동작도 하지 않습니다.

옵션 A — POTATO_PROXY_FIX(프록시가 전달 헤더를 전송)

프록시를 제어하고 있으며 전달 헤더를 전송할 수 있을 때 사용합니다. Potato는 Werkzeug의 ProxyFix를 활성화하며, 이는 요청별로 X-Forwarded-Prefix(및 -Proto/-Host/-For)를 읽습니다.

bash
export POTATO_PROXY_FIX=1
potato start config.yaml -p 8000

nginx, 접두사를 제거하고 헤더로 전달합니다.

nginx
location /app1/ {
    proxy_pass         http://127.0.0.1:8000/;   # trailing slash strips /app1/
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Prefix /app1;
}

ProxyFix는 전달 헤더를 신뢰합니다. 애플리케이션이 신뢰할 수 있는 프록시를 통해서만 독점적으로 접근 가능한 경우에만 POTATO_PROXY_FIX를 활성화하세요. 내부 포트에도 직접 접근할 수 있다면, 클라이언트가 X-Forwarded-Prefix나 -Host를 위조하여 생성된 URL을 오염시킬 수 있습니다.

옵션 B — POTATO_URL_PREFIX(프록시 구성을 변경할 수 없음)

전달 헤더를 추가할 수 없지만 공개 마운트 경로를 알고 있을 때 사용합니다. Potato가 직접 접두사를 SCRIPT_NAME에 주입합니다.

bash
export POTATO_URL_PREFIX=/app1
potato start config.yaml -p 8000

그래도 프록시는 전달하기 전에 접두사를 제거해야 하며, 그래야 Flask가 /static/styles.css 같은 접두사 없는 경로를 받게 됩니다.

nginx
location /app1/ {
    proxy_pass       http://127.0.0.1:8000/;     # trailing slash strips /app1/
    proxy_set_header Host $host;
}

두 변수가 모두 설정된 경우 요청별 전달 접두사가 우선하며 POTATO_URL_PREFIX는 대체 수단이 됩니다.

라이브 스트리밍(Server-Sent Events)

라이브 에이전트 및 라이브 코딩 뷰어는 SSE를 사용합니다. URL 접두사는 자동으로 적용되지만, SSE는 프록시가 스트림 위치에서 버퍼링을 비활성화하도록 추가로 요구하며, 그렇지 않으면 이벤트가 보류됩니다.

nginx
location /app1/api/ {
    proxy_pass            http://127.0.0.1:8000/api/;
    proxy_set_header      Host $host;
    proxy_buffering       off;
    proxy_read_timeout    3600s;
}

검증

  1. https://host/app1/을 로드하고 CSS와 JS가 404 없이 로드되는지 확인합니다.
  2. 주석을 작성하고 자동 저장되는지 확인합니다.
  3. 다음/이전으로 이동하며 미디어와 데이터가 렌더링되는지 확인합니다.
  4. 라이브 에이전트 평가를 사용하는 경우, 스트림이 연결되고 업데이트되는지 확인합니다.

참고 사항 및 제한

  • 표시되는 주석 콘텐츠 내부의 루트 상대 링크에도 접두사가 붙습니다. 공개 루트를 가리키려는 콘텐츠 작성자는 절대 URL을 사용해야 합니다.
  • pip로 설치된 배포는 패키징된 정적 자산에 의존합니다. 빌드에 중첩된 static/ 디렉터리가 포함되어 있는지 확인하세요.

관련 항목

구현 세부 사항은 소스 문서를 참조하세요.