常见问题与故障排查
从安装、连接、解锁到同步和恢复，按症状定位问题
先保留现场
先记下客户端版本、平台、存储类型、发生时间和错误提示。如果还能解锁，先创建 JSON 备份。不要把“清空缓存、删除目录、重装应用”当作通用第一步
安装或白屏
| 现象 | 优先检查 |
|---|---|
| 安装包打不开 | 文件完整性、SHA-256、CPU 架构、系统安全提示 |
| Linux AppImage 无法运行 | 执行权限、FUSE/动态库、图形环境与架构 |
| Android 解析/签名错误 | APK 完整性、系统兼容性、是否混装不同类型 |
| 自托管页面白屏 | index.html 与 assets 是否同一版本，资源是否 404 |
| 深层页面刷新 404 | Nginx 的 SPA try_files 回退 |
连接存储失败
CORS：检查实际 Origin 的协议、域名、端口，以及允许方法/请求头、暴露的 ETag。CORS 和 Bucket 访问权限是两个问题
403 / AccessDenied：核对密钥所属账号、资源范围、对象前缀和读写权限。不要为了测试把密码桶改成公共读写
Mixed Content：HTTPS 页面调用 HTTP 服务可能被浏览器阻止。使用整合服务自带页面或配置 HTTPS
私有服务登录失败：核对服务地址、TOML 用户名/密码、修改配置后的重启结果。手机的 localhost 指向手机自身
能登录但解锁失败
登录密码只用于连接存储，主密码才解密密码库。确认是否连接了正确账号/桶、是否使用该库原来的主密码。忘记主密码没有服务端重置解密通道
保存失败或同步冲突
先检查网络、PutObject/服务写入权限、磁盘空间和目录权限。多设备同时写可能触发 ETag 冲突；先停止连续保存，保留当前信息，再读取远端最新状态并决定合并方式
看起来数据不见了
- 清除搜索、标签和收藏筛选，检查隐私模式与回收站
- 确认仍连接原存储、原服务用户名、原 Bucket
- Docker 检查 Mounts；Jar 检查
--work-path；桌面端检查是否换了系统用户 - 保留现有目录，从备份中验证数据，不直接用空库覆盖
JSON 恢复失败
确认文件来自“备份密码”功能，未损坏或截断。输入备份生成时的主密码。恢复成功但数量变化时，检查合并规则与筛选条件。设置未跟随恢复属于备份范围差异，见备份说明
Docker 反复重启
docker ps -a --filter name=password-xl-service
docker logs --tail 100 password-xl-service根据日志判断是配置错误、目录权限、端口冲突还是 CPU 指令集不兼容。原生镜像不兼容时检查 JVM 镜像清单后再切换
AI 报错
核对 API Key、供应商地址、模型名、额度与网络。先用短小虚构文本测试，不把真实密码库整份提交排障。AI 详细排障
如何提供有效反馈
描述“做了什么、期待什么、实际发生什么”，附平台、版本、存储类型和脱敏错误。不要公开密码、云密钥、TOML 明文凭据、自动登录链接或完整日志。联系作者