Immich 文档：反向代理

用户可以部署自定义反向代理，将请求转发给 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>;

    # allow large file uploads
    client_max_body_size 50000M;

    # Set headers
    proxy_set_header Host              $http_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;

    # enable websockets: 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;

    # set timeout
    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://: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
   # set timeout in seconds
   ProxyPass / http://127.0.0.1:2283/ timeout=600 upgrade=websocket
   ProxyPassReverse / http://127.0.0.1:2283/
   ProxyPreserveHost On
</VirtualHost>

Traefik Proxy 配置示例

下面的示例适用于 Traefik version 3。

最重要的是增加 immich 所用入口点的 respondingTimeouts。在本例中，入口点 websecure 为 443 端口。默认设置为 60s，这导致视频在 1 分钟后停止上传（错误代码 499）。在此配置下，10 分钟后上传失败，这在大多数情况下已经足够。如有需要，可适当提高。

# traefik.yaml

[...]
entryPoints:
  websecure:
    address: :443
    # this section needs to be added
    transport:
      respondingTimeouts:
        readTimeout: 600s
        idleTimeout: 600s
        writeTimeout: 600s

第二部分是在 docker-compose.yml 文件中的 immich 部分。在示例中添加 Traefik 专用标签。

# docker-compose.yml

services:
  immich-server:
    [...]
    labels:
      traefik.enable: true
      # increase readingTimeouts for the entrypoint used here
      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 所在的网络通信，通常是通过在 immich 服务器中添加 Traefik network 来实现。