跳转到主要内容

反向代理

用户可以部署一个自定义的反向代理，将请求转发到 Immich。通过这种方式，反向代理可以处理 TLS 终止、负载均衡或其他高级功能。所有位于 Immich 和用户之间的反向代理都必须转发所有头信息，并将 Host、X-Real-IP、X-Forwarded-Proto 和 X-Forwarded-For 头设置为适当的值。此外，您的反向代理应该允许足够大的上传。遵循这些做法可以确保所有自定义反向代理与 Immich 完全兼容。

备注

Repair 页面可能需要较长时间加载。为避免服务器超时或错误，建议在代理服务器上指定至少 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;

    # 启用 WebSocket：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 路径，这对于发现功能至关重要。通常的错误消息为：“您的应用主版本与服务器不兼容”。要解决此问题，应为此路径引入一个额外的 location 块，确保请求正确代理到 Immich 服务器：

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。在这个例子中，入口点 websecure 用于端口 443。默认值为 60s，这会导致视频在上传 1 分钟后停止（错误代码 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 所在的网络通信，通常通过将 Traefik 网络添加到 immich-server 来完成。