Tune by Mozaiklabs

技术指南

本页面向高级用户和集成开发者：Tune 的构建方式、它的 API 以及运维细节。日常设置请见配置。

架构

  • 服务器：单个程序 tune-server，使用 Rust 编写。它负责为音乐库建立索引、解码音频、驱动设备，并提供网页界面、API 和音频流，全部通过同一个端口（默认 8888）。
  • 网页界面：由服务器提供的 Svelte 应用（程序旁边的 web/ 文件夹，或 TUNE_WEB_DIR）。
  • 数据库：默认为 SQLite，PostgreSQL 为可选项（见配置）。迁移在启动时运行。
  • 解码：内置解码器（Symphonia，加上 Tune 自己的 WavPack 和 APE 解码器，以及 libopus）。重采样使用 sinc 插值（rubato）。播放不经过 ffmpeg；已发布的版本中附带一个精简的 ffmpeg，仅用于转换器的 AAC 编码。
  • 发现：DLNA/UPnP 使用 SSDP，AirPlay 和 Chromecast 使用 mDNS，Squeezebox 的发现使用 UDP 3483。
  • Tune 还会在网络上把自己呈现为一台 UPnP 媒体服务器（其音乐库对 DLNA 控制应用可见），并按区域呈现为 UPnP 渲染器。

HTTP API

所有路由都位于 /api/v1 之下。路由的 JSON 列表由 GET /api/v1/system/api-docs 提供（即“设置 › 系统 › 关于”中的 API 文档链接）。Tune 不提供 OpenAPI 描述。

路由用途
GET /api/v1/system/health服务器健康状态：ok 或 degraded（HTTP 200），error（HTTP 503）
GET /api/v1/system/version服务器版本
GET /api/v1/system/stats统计信息（Docker 镜像的健康检查使用）
POST /api/v1/system/scan, GET /api/v1/system/scan/status启动扫描，跟踪其进度
GET /api/v1/system/logs?lines=N最新的日志行（默认 1000 行）
GET /api/v1/system/diagnostics/bundle诊断压缩包
GET /api/v1/zones区域列表
GET /api/v1/zones/{id}/status区域的播放状态
POST /api/v1/zones/{id}/play, /pause, /resume, /stop, /next, /previous, /seek, /volume播放命令
GET /api/v1/zones/{id}/queue播放队列
GET /api/v1/search在音乐库和各服务中搜索
GET /api/v1/library/albums, /artists, /tracks音乐库

实时事件（播放、队列、扫描等）通过位于 /ws（或 /api/v1/ws）的 WebSocket 传递。旧的 /api/scan 路由（不带 v1）已不再存在。

身份验证

身份验证默认关闭，这使得 API 对整个本地网络开放。它通过 API（/api/v1/auth/config）开启。账户就是 Tune 的配置文件，密码使用 Argon2 哈希，会话为有效期 24 小时的 JWT。长期有效的 API 令牌由 POST /api/v1/auth/token 签发。接受的请求头有：Authorization: Bearer <token> 和 Authorization: ApiKey <key>。即使开启了身份验证，/system/health 和 /system/version 仍然保持公开。Tune 不提供 HTTPS：如有需要，请在它前面放置一个反向代理。

Squeezebox / LMS 兼容性

  • 内置 SlimProto 服务器，端口 3483（TCP 和 UDP，可用 TUNE_SLIMPROTO_PORT 配置），供 Squeezelite 和 Squeezebox 播放器使用。
  • 与 LMS 兼容的文本命令端口 9090（TUNE_CLI_PORT），如果 9090 被占用，则顺延到下一个空闲端口。

运维

  • .deb 软件包：程序在 /opt/tune/，数据在 /var/lib/tune/，配置在 /etc/default/tune-server（升级时保留），tune-server.service 单元以 tune 用户运行。apt purge 绝不会删除 /var/lib/tune。
  • Docker：renesenses/tune 镜像（amd64、arm64）。它以非 root 的 tune 用户（uid 1000）运行，带有 /data 和 /music 卷。它既不包含本地音频输出，也不包含 PostgreSQL。在 arm64 上无法使用 AirPlay 2，Tune 会使用 AirPlay 1。
  • Tune OS：基于 Fedora。程序在 /opt/tune，服务为 tune，数据在 /opt/tune/data，80 端口转发到 8888，SSH 已启用（拒绝 root 登录）。
  • 日志：RUST_LOG 允许按模块进行细粒度过滤。

另请参阅