리버스 프록시

사용자는 요청을 Immich로 전달하는 맞춤형 리버스 프록시를 배포할 수 있습니다. 이를 통해 리버스 프록시는 TLS 종료, 로드 밸런싱 또는 기타 고급 기능을 처리할 수 있습니다. Immich와 사용자 사이의 모든 리버스 프록시는 모든 헤더를 전달하고 Host, X-Real-IP, X-Forwarded-Proto, X-Forwarded-For 헤더를 적절한 값으로 설정해야 합니다. 추가적으로, 리버스 프록시가 충분히 큰 업로드를 허용해야 합니다. 이러한 관행을 따르면 모든 맞춤형 리버스 프록시가 Immich와 완벽히 호환될 수 있습니다.

참고

복구 페이지 로드에 시간이 오래 걸릴 수 있습니다. 서버 타임아웃 또는 오류를 방지하려면 프록시 서버에서 최소 10분의 타임아웃을 지정하는 것을 권장합니다.

주의

Immich는 location /immich {과 같은 하위 경로에서 제공되는 것을 지원하지 않습니다. 도메인 또는 서브도메인의 루트 경로에서 제공되어야 합니다.

Nginx 예제 설정

아래는 nginx의 예제 설정입니다. public_url을 인스턴스의 외부 URL로 설정하고, backend_url을 Immich 서버 경로로 설정하세요.

server {
    server_name <public_url>;

    # 큰 파일 업로드 허용
    client_max_body_size 50000M;

    # 헤더 설정
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 웹소켓 활성화: http://nginx.org/en/docs/http/websocket.html
    proxy_http_version 1.1;
    proxy_set_header   Upgrade    $http_upgrade;
    proxy_set_header   Connection "upgrade";
    proxy_redirect     off;

    # 타임아웃 설정
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout       600s;

    location / {
        proxy_pass http://<backend_url>:2283;
    }
}

Let's Encrypt와의 호환성

nginx 설정에 Let's Encrypt 섹션이 포함된 경우, 다음과 유사한 세그먼트를 포함하고 있을 가능성이 높습니다:

location ~ /.well-known {
    ...
}

이 특정 location 지시문은 발견 과정에서 중요한 /.well-known/immich 경로에 대한 모바일 클라이언트의 접근을 방지할 수 있습니다. 이 경우의 일반적인 오류 메시지는 다음과 같습니다: "앱 주요 버전이 서버와 호환되지 않습니다." 이를 해결하려면 Immich 서버로 요청이 올바르게 전달되도록 이 경로에 대해 추가적인 location 블록을 도입해야 합니다:

location = /.well-known/immich {
    proxy_pass http://<backend_url>:2283;
}

이를 통해 Let's Encrypt의 기능을 유지하면서 모바일 클라이언트가 필요한 Immich 경로에 접근하는 데 문제가 없도록 할 수 있습니다.

Caddy 예제 설정

nginx의 대안으로 Caddy를 리버스 프록시(자동 HTTPS 설정 포함)로 사용할 수도 있습니다. 아래는 예제 설정입니다.

immich.example.org {
    reverse_proxy http://<snip>:2283
}

Apache 예제 설정

아래는 Apache2 사이트 설정 예제입니다.

<VirtualHost *:80>
   ServerName <snip>
   ProxyRequests Off
   # 초 단위의 타임아웃
   ProxyPass / http://127.0.0.1:2283/ timeout=600 upgrade=websocket
   ProxyPassReverse / http://127.0.0.1:2283/
   ProxyPreserveHost On
</VirtualHost>

Traefik 프록시 예제 설정

아래 예제는 Traefik 버전 3용입니다.

가장 중요한 것은 Immich에서 사용하는 엔트리포인트의 respondingTimeouts를 늘리는 것입니다. 이 예제에서 포트 443을 사용하는 엔트리포인트 websecure에 대해 설명합니다. 기본값은 60초로 설정되어 있으며, 이로 인해 1분 후에 비디오 업로드가 멈출 수 있습니다(Error Code 499). 이 구성을 사용하면 대부분의 경우 충분한 10분 후에 실패합니다. 필요에 따라 시간을 늘리세요.

traefik.yaml

[...]
entryPoints:
  websecure:
    address: :443
    # 이 섹션을 추가해야 함
    transport:
      respondingTimeouts:
        readTimeout: 600s
        idleTimeout: 600s
        writeTimeout: 600s

두 번째 부분은 Immich이 포함된 docker-compose.yml 파일에 있습니다. Traefik 특정 레이블을 예제와 같이 추가하세요.

docker-compose.yml

services:
  immich-server:
    [...]
    labels:
      traefik.enable: true
      # 여기에서 사용된 엔트리포인트의 읽기 타임아웃 증가
      traefik.http.routers.immich.entrypoints: websecure
      traefik.http.routers.immich.rule: Host(`immich.your-domain.com`)
      traefik.http.services.immich.loadbalancer.server.port: 2283

Traefik은 일반적으로 immich-server에 Traefik 네트워크를 추가하여 Immich가 있는 네트워크와 통신해야 한다는 점을 명심하세요.