排查 Cloud
本文针对已公开发布的 JavdBviewed Cloud 1.2.9。先分清是服务不可达、管理员登录、设备同步、媒体源访问，还是云侧新作品扫描异常；这些问题不一定共享根因。此版本包含扫描失败分型、同因 10 分钟退避、线路跟随和暂停提示；本页不把源仓后续 main 的行为当作已发布功能。
先确认服务和版本
| 现象 | 核对 | 下一步 |
|---|---|---|
| 部署主机无法打开管理台 | 容器是否运行、/health 是否正常、部署目录中的数据挂载和监听端口是否正确 | 先看部署指南中的健康检查和目录权限，再检查服务日志；不要清空数据目录 |
/health 正常，但客户端无法连接 | 从客户端所在设备访问 Cloud 地址，检查域名、HTTPS 证书、防火墙与网络 | 本指南 Compose 默认绑定宿主机 127.0.0.1:18080，其他设备不可直接访问；需要受限网络入口或 HTTPS 反向代理 |
| 页面显示的版本不符 | 核对 /version 的 version、buildNumber 与部署镜像 tag | 1.2.9 应为 version=1.2.9、buildNumber=git-4b477f028824；更新提示不会自动替换容器，按备份与升级核对实际运行镜像 |
启动失败或提示 disk I/O error、readonly、unable to open database | 宿主机 data/ 是否存在、挂载是否指向预期目录、容器用户能否写入、磁盘是否已满 | 先修正挂载和权限；保留原 cloud.db、快照及 vault.key，不要新建空数据库覆盖旧数据 |
默认管理台在部署主机本机的 http://127.0.0.1:18080/；此处的 127.0.0.1 是部署主机，不是手机或另一台电脑。公网只使用你自己配置的 HTTPS 入口；示例 https://cloud.example.com 不是公共 Cloud 服务。
管理员登录失败
| 现象 | 核对 | 下一步 |
|---|---|---|
| 提示账号或密码错误 | 管理员账号固定为 admin；确认正在登录正确的实例 | 首次未显式设置密码时，从首次启动日志取得临时密码，按页面提示修改；不要把密码贴进公开日志或问题帖 |
| 能登录但同步接口被拒绝 | 管理台是否要求首次修改密码 | 先完成强制改密，再重新使用客户端登录；改密前部分业务接口会返回 403 |
| 修改密码后其他设备掉线 | 管理员改密会撤销关联的设备会话 | 在各设备以新密码重新登录，随后检查同步反馈；不需要重新安装客户端 |
| 反复尝试后收到 429 | 同一远端地址与账号是否短时间连续登录失败 | 停止反复尝试，先核对实例地址及当前凭据，等待临时限制结束 |
已有数据库中的管理员密码不会因修改 .env 的 CLOUD_ADMIN_PASSWORD 自动重置。不要删除 data/ 以重新获取临时密码：该目录包含现有设备、记录和密钥。身份验证仍有问题时，先保存受控备份，再按部署文档核对实际实例与日志。
设备已登录但记录没有同步
- 在客户端确认 Cloud 地址与账号属于同一个自建实例；查看连接状态，并使用该客户端实际提供的同步操作，不要只看是否能打开管理台。
- 在管理台 设备 和 同步会话 页面检查设备是否出现、最近是否有成功活动；再在原设备核对该条记录是否已上传。
- 另一设备的本地路径、下载视频、缓存以及目录授权不随作品记录自动迁移；不要仅凭一项记录未出现就清空原设备或覆盖备份。
- 扩展的 WebDAV 备份与 Cloud 同步是不同通道；Cloud 中没有记录时，先核对 Cloud 的同步状态，而不是改 WebDAV 备份地址。
连接流程见连接设备。如管理台要求批准某台设备的接入申请，先根据该客户端的实际入口完成申请与批准；不是所有客户端都提供免密申请。同步成功不等于每个产品的全部设置字段都双向一致。
媒体源存在却不能播放
| 现象 | 核对 | 下一步 |
|---|---|---|
| Cloud 管理台或客户端列出媒体源，但手机打不开 | 手机当前网络是否能访问真实 Emby/Jellyfin 等服务地址 | 到Android 媒体源检查服务器地址、账号和实际文件；Cloud 不代替手机访问视频服务 |
| 桌面端有作品记录，但本地文件无法打开 | 该电脑的目录是否仍存在、是否有文件读取权限 | 到桌面本地影片检查目录和映射；Cloud 记录不是上传的视频 |
| WebDAV 地址可达，但视频仍不可读 | 该地址是备份目的地还是 Android 的 WebDAV 媒体源 | 按用途检查各自的目录和授权；WebDAV 备份成功不保证播放器能读取远端视频 |
Cloud 管理台不是媒体服务器出站连接测试工具；源地址即使从 Cloud 同步到另一设备，也应由使用视频的设备分别核对可达性。
云侧新作品扫描暂停或失败
打开管理台的 新作品扫描，分别查看 扫描状态 的警示横幅与 后台任务 的最近备注；扫描设置 用于核对启用状态和线路。扫描暂停横幅说明当前扫描不可用并会自动退避重试，不代表整个 Cloud 或客户端播放服务宕机。
| 现象或备注 | 核对 | 下一步 |
|---|---|---|
| 超时、DNS 错误、连接拒绝或代理拨号失败 | Cloud 所在主机到目标站的网络与已配置的出站代理；不要只测试手机网络 | 检查代理可达性和网络后等待下一轮探活；1.2.9 管理台可关闭出站代理并保留配置，关闭后相关请求改走直连 |
| 目标站返回 403 | 当前代理出口或线路是否被目标站限制 | 检查出口和可用线路；不要通过反复点击扫描绕过站点限制 |
| 429、5xx、404 等 HTTP 状态 | 任务备注中的具体状态码，目标站或该线路是否暂时异常 | 确认已配置线路有效，再等待自动重试；不要把所有 HTTP 失败误诊为密码错误 |
（已连续失败 N 轮），数分钟没有新任务行 | 是否同一种原因持续失败、扫描状态是否显示暂停 | 同因失败会就地更新已有行，并进入10 分钟退避窗；窗内不探活也不新增行，不必靠重启容器催促扫描 |
| 提示 JavDB 会话缺失、失效或解密失败 | 扩展是否仍有有效会话、是否推送到当前 Cloud；是否刚升级或改过管理员密码 | 升级到 1.2.9 后先登录管理台一次迁移旧 v1 会话；仍失败则在扩展重新登录并推送会话，再等待退避结束 |
| 启用了新 JavDB 线路，但扫描没有跟随 | 扩展线路设置是否同步到此 Cloud、候选是否为有效 HTTPS 白名单域名 | 核对扩展同步与管理台显示的扫描线路；无有效候选时会回退到默认基址，不能手填任意域名绕过限制 |
1.2.9 将 javdb580.com 纳入云扫描的候选域，不代表扩展旧会话的 cookie 在该域有效；扩展的 cookie 采集白名单仍独立维护。线路切换、会话有效性和 Cloud 本身能否联网分别检查。扫描恢复后再核对后台任务的新结果；此前静默退避不是“服务卡死”。
1.2.9 会话密钥与恢复边界
首次运行 1.2.9 会在数据目录生成 vault.key，升级后须登录管理台一次让已有 v1 会话密文迁移至 v2。cloud.db 与原 vault.key 必须一起备份和恢复；若密钥丢失，新生成的文件不能解密旧 v2 会话。此时需要让扩展重新推送会话并再次登录管理台；回滚旧版镜像也读不了 v2 密文，不能当作密钥修复手段。
不要通过公开日志、截图或云盘分享数据库、快照、vault.key、密码或媒体源凭据。需要回退时先保留现状，再参照备份、升级与回滚使用升级前的完整数据目录备份；仅更换镜像不恢复数据，不能回到升级前会话状态。