Immich 常见问题排查：登录失败、视频不传、缩略图慢与文件名乱码

这一页把前文散落的高频问题收拢成速查表，每条给「症状 → 最可能原因 → 处理」。官方 FAQ 是本页的事实底本，未覆盖的疑难去官方 FAQ 和社区讨论检索。

登录与连接

手机 App 突然登录不上。第一嫌疑：App 与服务器版本不同线——商店审核常让 App 更新晚几天，升级了服务器就会撞上。处理：等 App 更新到位，或先核对两边版本号；仍不行，查 App 内日志、去网页端验证密码本身。

管理员密码忘了。不需要重装：在服务器上对 immich-server 容器执行官方的 reset-admin-password 命令即可重置；list-users 命令可以列出全部用户核对账号。具体命令格式见官方文档的 server-commands 页。

外网连接不稳定。自签名证书、Basic Auth 属于实验性特性，视频播放和上传经常出问题——官方明确建议改用受信任证书（如 Let's Encrypt）或 VPN 方案，见 首次登录 的外网一节。

上传与备份

只传照片不传视频。几乎总是网络层拦截：反向代理没放开大请求体（视频是大头）；用 Cloudflare Tunnel 的注意——它有 100MB 的官方请求上限（不可调整）。处理：按官方 reverse-proxy 文档调大 client_max_body_size 类参数，或绕开隧道直连。

后台备份长时间不动。手机系统电池策略杀后台，逐项检查 后台备份与电池优化 的清单；安卓机型优先查 dontkillmyapp.com 对应条目。

微信/WhatsApp 图片日期错乱。这类图片本身没有拍摄时间元数据，Immich 无从得知真实日期——不是 Bug。收到图片时的时间是它唯一能用的依据。

照片在硬盘上日期不对。元数据提取当初失败或任务被清过的历史遗留，重跑「存储迁移」任务（任务队列里触发）。

处理性能

缩略图任务数永远大于照片数。设计如此：每张照片 3 种缩略图（模糊占位/预览/缩略图）+ 每张人脸 1 张小图，任务多不是异常。

全库导入后一切都很慢。正常现象——任务队列 在消化积压。技巧：导入时暂停智能搜索/人脸识别/转码，传完再放开，让机器学习在夜里跑。

机器只有 4GB 内存。关闭机器学习保核心功能，见 硬件要求；机器学习模型下载失败/报损坏，删掉模型缓存卷让它重下。

视频播放卡顿、CPU 高。启用 硬件转码；注意 HDR 视频在网页播放器存在已知的色彩偏差（下载回本地看是正常的），官方在持续改进播放器。

文件名与存储

文件管理器里文件名是一串乱码。存储模板默认关闭，服务器按随机字符串存文件防重名——照片本体毫无问题，时间线里显示的都是原始文件名。想让硬盘上也按「拍摄日期/文件名」归档：开启存储模板，再跑一次存储模板迁移任务把存量照片改名。改之前读官方存储模板专页 + 数据库备份。

原图会被 Immich 修改吗。不会——设计原则「原始文件永不改动」。编辑记录、星级、描述全部存进数据库和 XMP 旁路文件；唯一会动原文件的例外：回收站清空时删除对应原文件。

快速自检命令与入口

排查的通用心法：分层定位——先确认哪一层出问题（手机网络 → 服务器容器 → 任务队列 → 机器学习），再用本站对应专页的检查单走一遍。多数问题的答案，其实已经写在 数据库备份 和 后台备份 这些「平时该做对的事」里了。