备份、升级与维护
让数据、密钥、附件和组件版本一起维护。先确认部署身份与恢复路径,再升级服务、分发客户端或切换计算方式。
先记清自己的部署身份
Section titled “先记清自己的部署身份”维护前记录实际使用的项目名、配置文件组合、绑定 IP、端口、镜像版本、数据位置和外部媒体挂载。正式项目默认为 singverse-go-app,实际卷名带项目名前缀。
正式镜像路线使用命名卷,本地源码联调使用 data/docker/ 目录。两种方式的数据位置不同,切换命令不能自动迁移数据。后续操作沿用最初的完整配置组合。
停机备份清单
Section titled “停机备份清单”| 内容 | 为什么要备份 |
|---|---|
| 业务数据库 | 账号、曲库资料、来源、收藏、歌单、历史、反馈、任务与配置 |
| 匹配主密钥 / secrets | 恢复 MFA、WebDAV、AI、音源与连接凭据 |
| 持久资料目录 | 正式封面、歌词、受管上传与共享资料附件 |
| 独立兼容版本与音频成品 | 不是普通临时缓存,按实际需求保留 |
| 下载卷或 NAS 下载目录 | 已发布的真实歌曲及附件 |
| 节点认证、硬件与模型设置 | 计算身份及本机可用配置;compute cache 卷不全是可丢弃文件 |
| 部署配置与版本清单 | 恢复相同镜像、Compose 组合、环境和挂载 |
| 外部媒体与手机作品 | 分别由 NAS/WebDAV 备份和手机导出,不在业务库里 |
如何做一次可恢复的备份
Section titled “如何做一次可恢复的备份”- 使用当前完整 Compose 组合停止业务,等待进程退出;SQLite 不能把正在写入的单个文件直接当完整备份。
- 用 Docker/NAS 卷备份或相应数据库一致性工具备份数据与匹配密钥,保留文件权限。
- 单独保护环境文件和版本记录,不把密钥或真实部署配置提交 Git。
- 在隔离项目与新卷中恢复,核对登录、来源、附件、播放、收藏及计算连接。
- 确认可恢复后再安排正式切换,不能覆盖正在运行的数据库。
停止用 down 可保留卷;down -v 会删除命名卷,不用于常规维护。不要把清理缓存当作清理业务 data 或 compute 整个设置卷。
升级服务与网页
Section titled “升级服务与网页”- 核对目标版本与配套组件,先完成停机备份。
- 源码路线更新完整源码并按原组合构建;镜像路线固定新版本或摘要后拉取。
- 保留项目名、卷、密钥、外部挂载、环境文件和覆盖配置,使用原完整组合启动。
- Go 启动应用未部署的增量迁移,迁移失败先保留日志处理,不能清库“修复”。
- 验证管理登录、来源读取、正式附件、亲友邀请、真实播放和需要的计算任务。
本官网是独立的内容站点。更新 singverse-website 不会替换 Go 内置的管理网页、H5、APK 或已运行的 NAS。
通过 Actions 发布到三个镜像仓库
Section titled “通过 Actions 发布到三个镜像仓库”Go 仓库的 platform-release 发布 singverse;compute 仓库的 singverse-compute-images 发布 singverse-compute 的各运行库。每次正式发布都向 GHCR、Docker Hub、阿里云 ACR 三个目的地推送已验收的同一批 OCI 产物。
发布者在对应仓库的 Actions 页面选择工作流,点击 Run workflow,填写下列参数。release_tag 必须指向该仓库已有的正式 GitHub Release;不能是草稿或预发布,并须等于该标签源码中的 v 加根 VERSION。工作流使用所选标签的代码与已锁定产物。
| Action 参数 | 填写内容 | 留空时 |
|---|---|---|
release_tag |
已有正式 Release,如 v1.2.3(示例) |
Go 发布必填;compute 留空只构建与检查,不推送 |
ghcr_namespace |
小写 GHCR 用户或组织名 | 读取 GHCR_NAMESPACE;仍为空则使用当前仓库 owner |
dockerhub_namespace |
小写 Docker Hub 用户或组织名 | 读取 DOCKERHUB_NAMESPACE |
acr_registry |
ACR 实例的纯 Registry 域名,不含 https:// 或路径 |
读取 ACR_REGISTRY |
acr_namespace |
小写 ACR 命名空间 | 读取 ACR_NAMESPACE |
后四项默认值来自该仓库的 Actions Variables;发布正式 Release 自动触发时也使用这些默认值。参数只选择目的地,不授予权限:所选空间须已授权相应凭据。Docker Hub 使用 DOCKERHUB_USERNAME / DOCKERHUB_TOKEN,阿里云使用 ACR_USERNAME / ACR_PASSWORD,均保存在 Actions Secrets。GHCR 默认使用工作流令牌;跨组织或其他 owner 发布可配置有目标写入权限的 GHCR_USERNAME / GHCR_TOKEN。
三处配置齐全后才进入发布;目标固定标签已有不同内容时会失败,全部固定版本成功后才更新主服务的 latest 或计算端的 latest-<runtime>(例如 latest-base)。手动发布历史 Release 也会把所选空间的这些浮动标签更新到该历史版本。重试复用 Release 保存的组件锁与已验收 OCI 归档,不能删除或替换这些附件来覆盖同版本。手动指定另一空间可以复用同一正式版本,部署端再按实际目的地设置 IMAGE_PREFIX。
发布工作流成功与实际部署是两步操作;仍需拉取镜像并更新 NAS。完整配置、凭据权限与重试说明见 Go 仓库 infra/docker/PUBLISHING.md 和 compute 仓库 infra/docker/README.md。
客户端安装包与配套发布
Section titled “客户端安装包与配套发布”手机和电视更新包来自 NAS 当前镜像内的只读发行文件。发布了新 APK 后,还需把通过校验的发行包重新装入 Go 平台镜像并升级 NAS,设备下载页才会出现新版本。
构建发行组合通常先准备手机、TV、完整前端静态包,再打包 Go。协议上线是另一件事:本轮公平队列与亲友遥控 v2 需要按 Go → TV → H5 顺序启用。两种顺序分别描述产物准备和运行协议升级。
客户端覆盖安装需版本与长期签名兼容;Debug 和 Release 不能互相覆盖。原生 Go 可用 SINGVERSE_CLIENT_RELEASE_DIRECTORY 指向包含 mobile、tv 的发行目录。
升级失败如何回退
Section titled “升级失败如何回退”保留错误日志、数据卷与升级前备份。旧镜像不一定能读取新迁移后的数据库,回退需要恢复匹配版本的数据、密钥和持久附件,再使用相应版本启动。
不要仅把镜像标签调旧就假定安全回退,也不要把失败容器与业务卷一起删除。旧 Java 部署的数据库不能直接当作 Go 业务库复用;历史卷应独立保留并按实际迁移方案处理。
日常检查与问题记录
Section titled “日常检查与问题记录”- 确认服务健康、管理员登录、客户端下载和邀请入口。
- 观察磁盘空闲、缓存预算、下载目录、持久附件和离线成品的实际占用。
- 检查任务中心排队原因、失败批次及来源定时扫描结果。
- 定期用目标电视试播本地、WebDAV、原伴和兼容素材。
- 发生问题记录日期时间、版本、操作、任务编号和错误状态;隐藏令牌、密钥与真实媒体路径。
# 本地源码组合:在 singverse-go-backend 仓库执行make docker-local-statusmake docker-local-logs
# 查看当前部署的既有只读检查入口make docker-check检查命令的认证条件以当前仓库说明为准;不要在共享命令历史直接填写密码。真实 MySQL、GPU、微信和硬件设备检查需在对应环境完成。
升级后快速验收
Section titled “升级后快速验收”- 手机浏览器从 LAN 地址打开下载页,核对可用版本与二维码地址。
- 后台查看来源、歌曲、封面、收藏及历史,确认没有连到空的新数据卷。
- 电视登录并播一首,手机点歌、暂停和切歌,核对执行反馈。
- 使用计算节点时试跑探测与兼容任务,验证双向回源。
- 手机回听原有作品,确认覆盖安装保留本机数据。
- 完成后再结束维护,保留升级前备份和本次版本记录。