Cloud 使用指南

JavdBviewed Cloud 是运行在你自己的设备或服务器上的数据中枢。扩展和客户端作为设备接入同一个 Cloud 管理员账号，用于同步作品记录、播放进度、媒体源设置等协议实体，并保存密钥库。它不是 JavdBviewed 代管的公共云，也不是替代 Emby、Jellyfin、SMB 或 WebDAV 的视频服务器。

当前稳定版本

截至 2026 年 11 月 7 日，集中发布仓的 stable 清单、公开 Release 和 GHCR 镜像 manifest 均已核实 Cloud 1.2.9 正式发布：

• 镜像：ghcr.io/javdbviewed/javdbviewed-cloud:1.2.9
• 发布提交：4b477f028824b3857a4fe23446db339716f75630
• 镜像 digest：sha256:4cef4e8319426664eaf25960bf794d3c1ed64b254b5d286f6bdeb1fca43ab495
• Cloud 1.2.9 发布说明

stable 清单要求升级前备份，并明确 Cloud 只提示更新，不会自动替换或重启你的容器。部署镜像、版本和回滚判断应以发布清单与发布说明为准，不要把源仓 main 后续提交当作已发布能力。

Cloud 与开发方 Server 的边界

Cloud 是你自己部署、自己保存数据的同步服务；开发方 Server 是另一套面向产品运营或开发基础设施的服务边界。两者不是同一个组件，Server 不是 Cloud 的安装替代品，也不是普通用户连接 Cloud 时需要填写的地址。

使用客户端时，Cloud 地址应指向你自己部署的 Cloud 实例；Emby、Jellyfin 等媒体源仍填写各自的服务器地址。Cloud 可以同步媒体源配置和相关记录，但不因此取得远端视频的播放能力，也不会把视频文件自动搬到 Cloud。

1.2.9 提供什么

• 设备与同步：扩展和客户端绑定到唯一的 admin 管理员账号，设备可在管理台查看；同步会话和实体数据由 Cloud 保存。
• 密钥库与设置：媒体源配置及凭据属于自建实例数据，客户端可从同步结果导入相关设置。能看到配置不代表手机或桌面端当前能访问媒体服务器。
• 数据管理：管理台的数据页可查看实体分布、创建和下载整库快照、恢复快照及清理快照。
• 服务检查：部署后可访问 /health 检查健康状态，访问 /version 核对版本、构建号和协议版本；管理台可查看设备、同步和扫描状态。
• 扫描韧性：延续 1.2.8 的探活失败分型、同因失败退避、线路跟随和暂停提示；1.2.9 的线路白名单增加 javdb580.com 作为候选。扫描暂停或退避不是视频播放服务故障，先按扫描排错路径处理。
• 会话密钥：1.2.9 首次启动在数据目录生成 vault.key，使扫描会话的持久化解密密钥与管理台密码解耦。旧版升级后还需登录管理台一次，才能将已有 v1 会话密文迁移到 v2。
• 出站代理：管理台可关闭出站代理而保留已有地址与凭据，需要时再启用；这是 1.2.9 发布说明中确认的配置行为，不是客户端视频源的代理设置。

数据放在哪里

Cloud 通过 CLOUD_DATA_DIR 指向持久数据目录，裸服务默认是 ./data；本指南的容器部署将宿主机数据目录挂载到容器的 /data，并保持可写。权威数据库是目录下的 cloud.db（SQLite）；管理台快照在 snapshots/，旧版 store.json 首次迁移时会保留迁移备份。1.2.9 还在同一数据目录生成 vault.key（32 字节、权限 0600）。

升级前备份宿主机完整数据目录及部署配置；升级后登录管理台一次迁移旧版 v1 会话，并核查会话和扫描状态。 从 1.2.9 起，数据库与 vault.key 必须一起备份和恢复；丢失密钥后重新生成的文件无法解密旧 v2 会话，回滚旧版二进制也不能读取 v2 密文，需依赖升级前的完整备份或重新推送会话。不要只备份容器本身或镜像标签。

数据目录包含账号、设备、同步实体、设置和密钥库等自建实例数据；快照文件也包含受保护的认证与密钥材料，应放在受控位置，不得将快照、vault.key 或管理密码上传到公开仓库或问题帖。

推荐阅读顺序

1. 部署 Cloud：准备数据目录、配置环境变量、启动容器并完成首次管理员登录。
2. 连接设备：让扩展、桌面端和 Android 连接同一个实例，检查设备接入与同步反馈。
3. 备份、升级与回滚：升级前创建管理台快照，备份完整宿主机数据目录；1.2.9 起数据库与 vault.key 须一起保存。
4. 排查 Cloud：处理健康检查、数据目录不可写、同步失败、扫描暂停和退避提示。

使用前的边界检查

• Cloud 只有一个产品语义上的管理员账号 admin；不要把它当成可注册多个普通用户的公共服务。
• 设备登录 Cloud 与媒体服务器登录是两套凭据；不要把 Cloud 密码填入 Emby 或 WebDAV 表单，也不要把媒体服务器地址当作 Cloud 地址。
• Cloud 同步记录、媒体源配置和播放进度，但不会替你备份或上传远端视频文件；视频仍由客户端连接的实际媒体源提供。
• 生产环境应使用强管理员密码、持久化数据目录和 HTTPS 反向代理；升级前先备份，确认 /health、/version 和客户端同步均正常。

返回Cloud 1.2.9 发布说明，或从上面的部署、连接、备份和排错指南继续。