Immich 显示 Server Status Offline 且 Version Unknown 怎么排查

Immich 显示 Server Status Offline 且 Version Unknown 怎么排查【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich当你通过反向代理访问 Immich 时Web 界面左下角的状态栏可能会显示红色圆点配 Server Status Offline版本号位置则显示 Version Unknown即未知。这不是服务器宕机而是 Immich 官方 FAQ 中专门列出的一种现象My server shows Server Status Offline | Version Unknown. What can I do?官方给出的答案只有一条你需要在反向代理上启用 WebSocketsenable WebSockets。本文按照 Reverse Proxy 文档 给出一条可执行的修复路径。先看懂这个状态指示器的含义Web 界面左下角的状态组件 ServerStatus.svelte 显示的内容直接由 WebSocket 连接的connected状态驱动WebSocket 未连接时显示红色圆点和server_offline文案即你看到的 Server Status Offline版本号只在connected version同时成立时才会渲染否则显示unknown。也就是说Offline Version Unknown 两个现象是同一个根因的两面浏览器与 Immich 服务器之间的 WebSocket 通道没有建立成功。如果你的部署位于反向代理之后最可能的原因就是代理配置没有转发 WebSocket 升级请求。前提条件Immich 通过反向代理nginx、Caddy、Apache 或 Traefik对外提供服务代理后端指向 Immich 服务器的2283端口官方示例配置使用的端口。你有权限编辑反向代理的配置文件并使其重新加载生效。修改方法在反向代理中启用 WebSockets官方 Reverse Proxy 文档对不同代理分别给出了示例配置。下面以最常用的 nginx 为主路径其余代理作为可选分支。nginx 主路径将 reverse-proxy.md 中的示例配置用于你的 nginx 站点。其中public_url是你对外的访问地址backend_url是 Immich 服务器的地址需要替换为你自己的实际值server { server_name public_url; # allow large file uploads client_max_body_size 50000M; # disable buffering uploads to prevent OOM on reverse proxy server and make uploads twice as fast (no pause) proxy_request_buffering off; # increase body buffer to avoid limiting upload speed client_body_buffer_size 1024k; # Set headers 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; # enable websockets proxy_http_version 1.1; proxy_redirect off; # set timeout proxy_read_timeout 600s; proxy_send_timeout 600s; send_timeout 600s; location / { proxy_pass http://backend_url:2283; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } # useful when using Lets Encrypt http-01 challenge # location /.well-known/immich { # proxy_pass http://backend_url:2283; # } }其中直接决定 WebSocket 能否建立的是proxy_http_version 1.1;和location /内的Upgrade/Connection upgrade两行头部设置。如果只改这一处问题而原有站点配置其余部分正常保留你现有的其余配置、只补齐 WebSocket 相关部分也可以但官方示例是作为完整站点给出的照抄更稳妥。可选分支其他代理Caddy示例配置immich.example.org { reverse_proxy http://snip:2283 }Apache示例站点配置VirtualHost *:80 ServerName snip ProxyRequests Off # set timeout in seconds ProxyPass / http://127.0.0.1:2283/ timeout600 upgradewebsocket ProxyPassReverse / http://127.0.0.1:2283/ ProxyPreserveHost On /VirtualHostApache 配置中upgradewebsocket参数就是 WebSocket 转发开关。Traefik v3除了常规路由标签外文档特别强调要调大所用 entrypoint 的respondingTimeoutstraefik.yaml[...] entryPoints: websecure: address: :443 # this section needs to be added transport: respondingTimeouts: readTimeout: 600s idleTimeout: 600s并在 Immich 所在的docker-compose.yml中为immich-server加上 Traefik 标签端口指向 2283Host 规则替换为你的域名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.example.com) traefik.http.services.immich.loadbalancer.server.port: 2283文档提醒Traefik 需要能与 Immich 所在网络通信通常做法是把 Traefik 网络加入immich-server。验证修复结果按你所用代理的方式重新加载配置使其生效后刷新 Immich 的 Web 页面观察左下角状态栏修复前红色圆点Server Status Offline版本位置显示 Unknown修复后绿色圆点状态变为在线online并且旁边会显示服务器版本号。这正是 ServerStatus.svelte 中connected由 false 变为 true 后渲染的分支。如果改完配置仍然显示 Offline说明 WebSocket 升级请求仍然没有到达 Immich 服务器需要回到代理配置中检查Upgrade/Connection头部是否完整、后端地址与端口是否指向 2283。边界与注意事项本排查路径适用于经过反向代理的部署FAQ 的官方答案就是在反向代理上启用 WebSockets。Immich 不支持通过子路径sub-path提供服务例如location /immich {这类写法不行必须挂在子域名的根路径上reverse-proxy.md 中的 caution。所有位于 Immich 与用户之间的反向代理都必须转发全部头部并把Host、X-Real-IP、X-Forwarded-Proto、X-Forwarded-For设置为正确值同时允许足够大的上传体积——这些是文档列出的通用兼容性要求WebSocket 修复之外也应满足。如果你使用 Lets Encrypt 的 http-01 challenge确认 well-known 端点/.well-known/immich被正确路由到 Immich否则移动端可能出现连接问题nginx 示例中保留了该 location 的注释块按需启用。完成上述配置后状态栏恢复正常是这次任务的最终验收点若状态恢复但其他功能如上传仍有异常再按 FAQ 中对应条目分别处理。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考