immich-drop常见问题FAQ:上传失败、重复判定、链接失效等8大难题快速排查清单
immich-drop常见问题FAQ:上传失败、重复判定、链接失效等8大难题快速排查清单
immich-drop 是一款零登录的 Immich 照片/视频收集 Web 工具:管理员创建邀请链接,任何人打开链接即可上传图片到 Immich 服务器。本文是 immich-drop 常见问题FAQ,覆盖上传失败、重复判定、链接失效、登录异常等 8 大难题,每个问题都给出错误码和最快排查路径,新手也能照单解决。
先了解界面:左侧是上传队列(显示 Queued / Uploading / Done / Duplicate 状态),中间是 Immich 登录页,右侧是创建上传链接面板(含 QR 码分享)。
一、上传失败:大文件卡在 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):
- 本地 SHA-1 缓存:命中直接标记
Duplicate (by checksum - local cache) - 本地设备记录:
deviceAssetId命中则提示"此设备已上传" - 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。
排查三步:
- 点顶栏 Test connection 按钮,它调用 app/app.py 的
/api/ping探测 Immich 健康接口; - 确认
IMMICH_BASE_URL必须带/api后缀,如https://immich.example.com/api(少了/api是最常见的配置错误); - 确认
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),代理若超时断开空闲连接会导致进度"冻结"。
排查:
- 刷新页面看队列最终状态:绿色
done/ 黄色duplicate/ 红色error(见 frontend/app.js 状态条颜色逻辑); - 红色条目可直接点 Retry 按钮重传,无需重新选文件;
- 若在反代后面,给 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% 的问题都能对上号。
