immich-drop常见问题FAQ:上传失败、重复判定、链接失效等8大难题快速排查清单

原创2026-11-14 11:08:181,990 阅读

immich-drop常见问题FAQ:上传失败、重复判定、链接失效等8大难题快速排查清单

immich-drop 是一款零登录的 Immich 照片/视频收集 Web 工具:管理员创建邀请链接,任何人打开链接即可上传图片到 Immich 服务器。本文是 immich-drop 常见问题FAQ,覆盖上传失败、重复判定、链接失效、登录异常等 8 大难题,每个问题都给出错误码和最快排查路径,新手也能照单解决。

先了解界面:左侧是上传队列(显示 Queued / Uploading / Done / Duplicate 状态),中间是 Immich 登录页,右侧是创建上传链接面板(含 QR 码分享)。

immich-drop 界面截图:上传队列、登录页与创建上传链接面板

一、上传失败:大文件卡在 100MB 限制(413)

现象:文件上传到中途失败,或代理(Nginx、Cloudflare Tunnel 等)直接拦截,返回 Request Entity Too Large。

原因:immich-drop 默认走一次性整包上传,很多反代会限制单请求 100MB 左右。

最快配置方法——启用分块上传(chunked uploads),把大文件切成小块传输:

environment:
  CHUNKED_UPLOADS_ENABLED: true
  CHUNK_SIZE_MB: "95"   # 每块大小,需小于代理限制

参考仓库示例 docker-compose.yml.example。前端只在文件大于分块阈值时才自动切换分块模式,小文件不受影响。分块相关逻辑见 app/app.py。

💡 分块上传同样保留去重检查、EXIF 时间戳、相册归类和逐条进度推送。

二、重复判定:不同照片被误判为 duplicate?

原理:immich-drop 有三级去重(见 app/app.py):

  1. 本地 SHA-1 缓存:命中直接标记 Duplicate (by checksum - local cache)
  2. 本地设备记录:deviceAssetId 命中则提示"此设备已上传"
  3. Immich 服务端:调用 /assets/bulk-upload-check,Immich 报重即跳过

常见问题:

  • Q:换了文件名,但内容完全一样,为什么还是 duplicate? 因为比较的是文件内容哈希(SHA-1),不是文件名,这是正常行为。
  • Q:想重新上传之前被跳过的照片怎么办? 去重缓存存在本地 SQLite state.db(Docker 下挂载在 immich_drop_data 卷的 /data 目录)。删掉这个卷里的 state.db 再重启容器即可清空历史(已入库的 Immich 资产不受影响)。

三、链接失效:邀请链接打不开或提示错误

现象:朋友打开邀请链接后无法上传。后端会返回明确的错误码(见 app/app.py),对照下表排查:

错误码 含义 快速解决
invalid_invite 链接 token 不存在(403) 确认 URL 完整,没漏复制尾部
invite_expired 超过设定的过期天数 在管理页重新编辑过期时间,或重建链接
invite_claimed 一次性链接已被其他人使用(403) 一次性链接只允许第一个会话用,重新创建
invite_exhausted 多次使用链接的次数已用完 调大使用次数或重建
invite_disabled 被管理员手动禁用 在管理页重新启用
invite_password_required 链接设了密码但未通过验证 输入创建时设置的密码解锁

小贴士:v0.5.0 起,管理页(frontend/menu.html)支持直接搜索、启用/禁用、删除和编辑名称/过期时间,过期保存采用"当天结束"策略,避免差一天(off-by-one)问题。

四、公开上传页打不开,总是跳到登录页

现象:访问根路径 / 被重定向到 /login,以为部署坏了。

原因:公开上传页默认关闭(安全优先设计),判断逻辑在 app/app.py。

解决:确实需要无链接直接上传的落地页时,显式开启:

PUBLIC_UPLOAD_PAGE_ENABLED=true

不推荐默认开启——邀请链接模式更安全、可追踪(每次上传会记录 IP、User-Agent、文件名和指纹到 upload_events 表)。

五、顶栏显示 Immich 连接异常

现象:页面顶部 banner 提示无法连接 Immich。

排查三步:

  1. 点顶栏 Test connection 按钮,它调用 app/app.py 的 /api/ping 探测 Immich 健康接口;
  2. 确认 IMMICH_BASE_URL 必须带 /api 后缀,如 https://immich.example.com/api(少了 /api 是最常见的配置错误);
  3. 确认 IMMICH_API_KEY 有效且具备 asset.upload 权限;需要相册功能时还要 album.create、album.read、albumAsset.create。

六、登录失败:unauthorized 或 login_failed

现象:管理员在登录页输入 Immich 邮箱密码后被拒。

排查:登录接口 app/app.py 会透传 Immich 的 /auth/login 结果:

  • unauthorized(401):邮箱或密码与 Immich 账户不一致,注意用的是 Immich 账户凭据,不是 immich-drop 的;
  • login_failed(502):immich-drop 容器根本连不到 Immich,通常是 IMMICH_BASE_URL 写错或网络不通;
  • invalid_response(502):Immich 版本过旧,登录响应里没有 accessToken,升级 Immich 即可。

七、进度条不动了?上传状态一直卡在 uploading

原因:进度通过 WebSocket 推送(app/app.py),代理若超时断开空闲连接会导致进度"冻结"。

排查:

  1. 刷新页面看队列最终状态:绿色 done / 黄色 duplicate / 红色 error(见 frontend/app.js 状态条颜色逻辑);
  2. 红色条目可直接点 Retry 按钮重传,无需重新选文件;
  3. 若在反代后面,给 WebSocket 路径加空闲超时(如 Nginx 的 proxy_read_timeout 大于 30 秒),后端每 30 秒会主动发 ping 保活。

八、上传成功但照片没进相册?

原因:相册归集是可选功能,且邀请链接会覆盖 .env 默认相册。

解决:

  • 公开上传页场景:设置 IMMICH_ALBUM_NAME(不存在会自动创建);
  • 邀请链接场景:建链接时在"Target album"下拉里选相册或输入新名字(会先创建同名相册再归属,逻辑见 app/app.py);
  • 若报 forbidden(403),说明 API key 缺少 album.* 权限,到 Immich 里重新生成带相册权限的 key。

附:常用参数速查表

参数 作用 默认值
IMMICH_BASE_URL Immich 地址,须含 /api http://127.0.0.1:2283/api
IMMICH_API_KEY Immich API 密钥(仅存服务端) —
PUBLIC_UPLOAD_PAGE_ENABLED 公开上传页开关 false
IMMICH_ALBUM_NAME 默认归集相册名 空(不归集)
CHUNKED_UPLOADS_ENABLED 分块上传开关 false
CHUNK_SIZE_MB 分块大小(MB) 95
STATE_DB 去重缓存 SQLite 路径 /data/state.db
MAX_CONCURRENT 并发上传数 3

完整配置说明见 README.md 的 Configuration 章节,参数加载逻辑在 app/config.py。遇到本文未覆盖的问题,可先用顶栏 Test connection + 浏览器开发者工具 Network 面板看具体 HTTP 状态码,90% 的问题都能对上号。

登录后查看全文
immich-drop