挂载报错排查：唯一约束令牌失效与加载失败

挂载环节的报错集中在四类，逐条对照。

一、添加时直接报错

UNIQUE constraint failed: x_storages.mount_path

挂载路径和已有存储重复了。路径全站唯一；如果管理页里根本没看到重复的那条，强制刷新（Ctrl+F5）再看。

MountPath 校验失败 / required

挂载路径没填。

need img validate code / 设备 ID 不存在需要二次验证（天翼、189 类）

网盘风控或验证码拦截：天翼客户端驱动开「不使用 OCR」或自建 OCR 接口；189 触发风控时改密码后重试。

123 云盘 json 反序列化报错

大概率是这台部署机的 IP 被网盘侧临时限制，停一停，几小时到一天后再挂。

二、保存成功但前台一直加载

页面提示「获取设置失败：请稍后，正在加载存储」＝某个存储失效拖住了启动：

1. 先等几分钟，有时是网盘接口慢。
2. 还不行就进程序目录用命令停掉失效存储：

./alist storage list
./alist storage disable /挂载路径

先 list 列出所有存储（上下键翻页，Ctrl+C 退出），找到失效那条再 disable。Docker 用户在命令前加 docker exec -it 容器名。停掉后重启程序即可进入。

三、能列目录但下载/上传报错

• 阿里云盘 InvalidArgument：没开任何代理时必须用移动端拿的刷新令牌。
• 百度网盘 hit black userlist：接口风控，等 24 小时，多数自动恢复。
• Terabox 挂载成功但空目录：网盘限制非海外 IP 访问，需让程序流量走代理。

四、文件不更新

上传不显示、删除还还在、改根目录不生效——都是半小时目录缓存，等过期或在目录右下角手动刷新；长期不匹配就调小存储的「缓存过期」，见通用项详解。