部署与首次登录
先选发行镜像、源码联调或原生运行,再让手机和电视访问同一 NAS。部署完成后,用少量真实歌曲走通从扫描到播放的完整流程。
先选对部署方式
Section titled “先选对部署方式”| 方式 | 适合谁 | 你需要准备 |
|---|---|---|
| 已发布镜像 | 长期使用,已有可用发行版 | Docker / Compose、镜像版本、持久卷与网络 |
| 正式源码构建 | 需要自行组装发行镜像 | Go 仓库及固定前端发行包、有效客户端发行包、签名校验工具 |
| 本地源码联调 | 同时修改多个仓库 | 相邻前端与 compute 源码、绝对路径、独立本地运行数据 |
| 原生 Go | 自行管理进程、数据库与反向代理 | 仓库工具链、完整前端产物、显式环境变量 |
- Docker 需要 Engine 与 Compose;本地源码联调还需要支持 BuildKit 命名上下文。CPU 架构、磁盘和内存按所选镜像、曲库与计算能力核对。
- 默认数据库为 SQLite,可显式选择 MySQL;MySQL 失败不会静默回退。
- 计算节点可选,用于媒体探测、转码、音轨分析和伴奏分离。
- 手机和电视需要与 NAS 处于同一可互访的私有网络,或能访问你配置的域名。
| 部署方式 | 默认管理入口 | 说明 |
|---|---|---|
| Docker | http://127.0.0.1:18080/admin/ |
HTTP 端口由 SINGVERSE_HTTP_PORT 控制,默认 18080 |
| 原生 Go | http://127.0.0.1:8080/ |
默认只监听回环,不自动加载 .env |
正式发行包部署
Section titled “正式发行包部署”在 singverse-go-backend 仓库根目录执行。源码构建会先准备并校验手机和电视发行包,因此打包机需要 Android SDK 的 apksigner 和 aapt。如果项目已经发布镜像,可以直接拉取。
cp -n .env.example .env# 按部署需要修改 .env,已有 .env 不会被覆盖make docker-build docker-up
# 或使用已发布镜像make docker-pull docker-image-up
# 停止并保留命名卷make docker-down从 GHCR、Docker Hub 或阿里云拉取镜像
Section titled “从 GHCR、Docker Hub 或阿里云拉取镜像”发布工作流将同一批已验收镜像推送到 GitHub Container Registry(GHCR)、Docker Hub 和阿里云 ACR。实际项目空间由发布者的 GitHub Actions 参数决定;部署前取得这次发布的仓库地址与版本,再设置 IMAGE_PREFIX。以下均为地址格式,尖括号内容需替换。
| 镜像仓库 | IMAGE_PREFIX 格式 | 空间来自发布参数 |
|---|---|---|
| GitHub GHCR | ghcr.io/<用户或组织> |
ghcr_namespace |
| Docker Hub | docker.io/<用户或组织> |
dockerhub_namespace |
| 阿里云 ACR | <ACR Registry 域名>/<命名空间> |
acr_registry 与 acr_namespace |
前缀不含 https://、镜像名、版本标签或末尾斜杠。Go 镜像为 <IMAGE_PREFIX>/singverse:<版本>,计算镜像为 <IMAGE_PREFIX>/singverse-compute:<版本>-<运行库>。GitHub Release 使用 v1.2.3 形式,镜像版本使用 1.2.3,不带开头的 v。
# .env:替换为空间中实际已发布的地址和版本;这里的版本仅作示例IMAGE_PREFIX=ghcr.io/your-orgSINGVERSE_VERSION=1.2.3COMPUTE_VERSION=1.2.3COMPUTE_RUNTIME=base
# 保存 .env 后,在 Go 仓库根目录拉取并启动make docker-pull docker-image-up主服务与计算节点独立发版,SINGVERSE_VERSION 和 COMPUTE_VERSION 不必相同。同一 Compose 组合共用一个 IMAGE_PREFIX;启用计算节点时,该空间必须同时有目标版本的两个镜像。私有仓库先用有拉取权限的账号执行 docker login <仓库域名>。
镜像命名空间决定从哪里拉取;Compose 项目名决定本机容器与命名卷归属。切换镜像源时保留既有项目名(默认 singverse-go-app)和数据卷。发布者的参数与权限配置见三仓库镜像发布。
本地源码联调
Section titled “本地源码联调”适合开发者从相邻仓库源码构建前端、Go 和计算节点。先填写前端与 compute 仓库的绝对路径。
cp -n .env.local.example .env.local# 编辑 .env.local:# SINGVERSE_FRONTEND_PROJECT=/absolute/path/to/singverse-frontend# SINGVERSE_COMPUTE_PROJECT=/absolute/path/to/singverse-computemake docker-local-upmake docker-local-statusmake docker-local-logs
# 停止服务,保留本地数据make docker-local-down运行数据位于仓库的 data/docker/,包括数据库、主密钥、节点认证、模型、媒体和下载目录。本地联调会构建并启动 Go 与 compute,正式发行组合默认只启动 Go;二者不要混用数据位置。
让源码联调也能分发 APK
Section titled “让源码联调也能分发 APK”本地联调不默认依赖已发布客户端。若下载页提示缺包,先在各 Android 仓库生成有效的 APK、release.json 和 SHA256SUMS,再在 Go 仓库执行:
make docker-local-releases \ MOBILE_RELEASE_DIR=/absolute/path/to/mobile/build/mobile-release \ TV_RELEASE_DIR=/absolute/path/to/tv/app/build/tv-releasemake docker-local-up准备命令校验真实签名、包名、版本、ABI、最低系统和摘要;需要可用的 apksigner 与 aapt。完成后重新构建组合,安装包才进入当前 NAS 下载页。临时 Debug 签名不能覆盖已安装的正式包。
原生 Go 适合已经准备好工具链和前端 dist 的环境。生产原生运行默认监听 127.0.0.1:8080,不会自动加载 .env,需要显式导出环境变量。
make go-tools-setup dbmate-setupmake go-backend-buildmake go-backend-run首次拆分尚未发布前端时,可显式传入完整前端 dist:
make go-backend-build FRONTEND_DIST=/absolute/path/to/frontend/dist首次登录与改密
Section titled “首次登录与改密”- 打开管理入口
/或/admin/。 - 使用首次账号
admin/admin登录。 - 登录后立即修改密码,并按需配置 TOTP 二次验证。
- 在“设置 → 账号与安全”管理会话和恢复方式。
让手机和电视访问
Section titled “让手机和电视访问”Docker 默认只绑定 127.0.0.1,其他设备无法访问。局域网使用时,把 .env 或 .env.local 中的 SINGVERSE_HTTP_BIND 改为本机当前局域网 IP,再重新部署。
# .env 或 .env.localSINGVERSE_HTTP_BIND=192.168.1.100SINGVERSE_HTTP_PORT=18080然后在手机或电视浏览器打开 http://192.168.1.100:18080/downloads/。二维码会编码当前 NAS 地址,因此请始终用其他设备可达的 IP 或域名打开下载页。机器切换网络后,需要同步更新绑定 IP。
挂载歌曲目录
Section titled “挂载歌曲目录”Docker 中的本地目录指容器内路径。宿主 NAS 的歌曲目录必须先只读挂载,管理端才能选择。默认 Compose 不挂载任意宿主目录。
# compose.media.yaml(本地文件,不要提交真实路径)services: singverse-go-backend: volumes: - /your/nas/karaoke:/media/karaoke:rodocker compose --project-directory . \ -f infra/docker/compose/compose.yaml \ -f compose.media.yaml up -d --build --wait随后在“加歌 → 歌曲来源”添加本地目录,填写 /media/karaoke。WebDAV-only 部署不需要挂载本地媒体目录。
手机和电视查找 _singverse._tcp mDNS 服务。Docker 端口映射只提供 HTTP 入口,不会自动发布发现记录。
macOS Docker Desktop
Section titled “macOS Docker Desktop”make lan-discovery# 自定义容器名make lan-discovery DISCOVERY_CONTAINER=<Go 容器名>命令需要保持运行,Ctrl-C 停止,Mac 重启后重新运行。它会验证容器实际发布的 HTTP 入口后再广播。
Linux NAS
Section titled “Linux NAS”avahi-publish-service "SingVerse NAS" _singverse._tcp 18080 api=1 scheme=http保持进程运行,或使用宿主机已有的 Avahi 服务配置。原生 Go 可显式设置 SINGVERSE_TV_DISCOVERY_ADDRESS 和 SINGVERSE_TV_DISCOVERY_PORT。没有发布 mDNS 时,手动填写地址始终可用。
- 局域网 HTTP 可用于私有网络;跨网或公网访问建议配置 HTTPS 反向代理,并正确设置
SINGVERSE_PUBLIC_ORIGIN与可信代理。 - 数据库、主密钥和节点认证文件必须配套备份。主密钥缺失或不匹配会导致受保护凭据无法恢复。
- 停止服务后再备份数据卷或
data/docker/,不要只备份数据库而遗漏主密钥。 - 原始媒体保持只读;备份策略由你的 NAS 负责。
地址与端口速查
Section titled “地址与端口速查”| 地址 / 配置 | 含义 | 常见误区 |
|---|---|---|
127.0.0.1:18080 |
Docker 默认宿主业务入口 | 只允许部署主机本身访问 |
NAS-LAN-IP:18080 |
手机、电视和亲友实际访问入口 | 需设置绑定 IP、防火墙与路由 |
127.0.0.1:8080 |
原生 Go 默认入口 | 原生不自动加载 .env |
singverse-compute:8090 |
同一 Compose 网络内的计算服务 | 不是手机或浏览器连接地址 |
127.0.0.1:18090 |
默认宿主侧计算节点检查入口 | 健康不代表模型与双向回源已通过 |
_singverse._tcp |
手机与电视寻找 NAS 的发现记录 | 端口映射不自动发布 mDNS |
部署后完成一次小范围验收
Section titled “部署后完成一次小范围验收”- 管理端能登录,已经修改初始密码,账号与时间状态正常。
- 从另一台设备打开下载页,二维码不是 localhost,安装包按准备情况真实显示。
- 添加一个小目录或 WebDAV 子目录,保存并扫描,确认文件数与歌曲数。
- 核对一首歌的资料和原伴,先在目标客户端直放。
- 需要转码时测试计算节点及回源,再试播放兼容素材。
- 电视邀请亲友,测试点歌、队列与暂停,确认实际执行。
- 确认所有数据落在预期位置,安排数据库、主密钥和持久附件配套备份。
找不到 NAS 先手动输入地址,发现只是便利入口。可用前不要扩大到整库、批量生成或大量下载,以免把网络、挂载与整理问题混在一起。