sentriz/gonic

gonic - Subsonic API 音乐流服务器

!https://github.com/sentriz/gonic/blob/master/.github/logo.png?raw=true

镜像概述和主要用途

gonic 是一个免费开源的 Subsonic 服务器 API 实现，兼容 Subsonic 生态的多种客户端。它允许用户通过网络流式传输音乐库，支持按文件夹或标签浏览音乐、实时音频转码、多用户管理、播放记录同步等功能，适用于构建个人或家庭音乐服务器。

核心功能和特性

• 灵活的音乐浏览：支持按文件夹结构（完整保留目录树）或标签（基于 taglib，支持 MP3、Opus、FLAC、APE、M4A、WAV 等格式）浏览音乐库
• 实时音频转码与缓存：需依赖 ffmpeg，支持动态转码并缓存结果，适配不同客户端带宽和设备能力
• Subsonic 点唱机模式：支持服务器端无缝播放（而非流式传输），实现无间隙音乐体验
• 播客支持：可订阅和管理播客内容
• 高效扫描能力：大型音乐库（约 5 万首曲目）首次扫描约 10 分钟，增量扫描仅需约 6 秒
• 多用户管理：支持多用户账户，每个用户可独立设置转码偏好、播放列表、个人收藏等
• 播放记录同步：支持 Last.fm 和 ListenBrainz 播放记录（scrobbling）
• 艺术家相关功能：通过 Last.fm API 获取艺术家相似度和 biography
• 多值标签支持：处理多值流派、艺术家、专辑艺术家等标签，避免列表冗余
• Web 管理界面：用于配置 Last.fm、管理用户、触发扫描等操作
• 轻量高效：基于 Go 语言开发，资源占用低，适合树莓派等嵌入式设备
• 广泛的客户端兼容性：已测试支持 airsonic-refix、Symfonium、DSub、Jamstash、Sublime Music、Strawberry、Ultrasonic 等客户端

使用场景和适用范围

• 个人音乐服务器：搭建私有音乐库，通过网络在多设备上访问
• 家庭共享：支持多用户，家庭成员可独立管理个人播放列表和偏好
• 低资源设备部署：适用于树莓派、NAS 等硬件，轻量化设计降低资源占用
• Subsonic 生态迁移：作为商业 Subsonic 服务的免费替代方案，兼容现有客户端
• 播客管理中心：集中订阅、下载和播放播客内容

使用方法和配置说明

前提条件

• 需安装 ffmpeg（用于音频转码）
• 若启用点唱机模式，需安装 mpv

Docker 部署

1. 快速启动（docker run）

shell
docker run -d \
  --name gonic \
  -p 4747:4747 \
  -v /path/to/music:/music \           # 挂载音乐库目录
  -v /path/to/cache:/cache \           # 挂载转码缓存、封面等数据目录
  -v /path/to/db:/db \                 # 挂载数据库文件目录（可选）
  -e GONIC_MUSIC_PATH=/music \         # 音乐库路径（容器内路径，需与挂载对应）
  -e GONIC_CACHE_PATH=/cache \         # 缓存路径（容器内路径，需与挂载对应）
  -e GONIC_DB_PATH=/db/gonic.db \      # 数据库文件路径（可选）
  sentriz/gonic

2. docker-compose 配置

yaml
version: '3'
services:
  gonic:
    image: sentriz/gonic
    container_name: gonic
    ports:
      - "4747:4747"
    volumes:
      - /path/to/music:/music          # 音乐库目录（宿主机路径:容器内路径）
      - /path/to/podcasts:/podcasts    # 播客目录（可选）
      - /path/to/playlists:/playlists  # 播放列表目录（可选）
      - /path/to/cache:/cache          # 缓存目录
      - /path/to/db:/db                # 数据库目录（可选）
    environment:
      - GONIC_MUSIC_PATH=/music
      - GONIC_PODCAST_PATH=/podcasts   # 启用播客支持（可选）
      - GONIC_PLAYLISTS_PATH=/playlists # 播放列表路径（可选）
      - GONIC_CACHE_PATH=/cache
      - GONIC_DB_PATH=/db/gonic.db
      - GONIC_SCAN_INTERVAL=60         # 自动扫描间隔（分钟，可选）
      - GONIC_SCAN_AT_START_ENABLED=true # 启动时执行初始扫描（可选）
    restart: unless-stopped

初始登录

• 默认登录凭据：用户名 admin，密码 admin
• 首次登录后，建议通过 Web 界面（http://<服务器IP>:4747）修改管理员密码。

配置参数详解

gonic 支持通过环境变量或命令行参数配置，以下为主要参数说明：

高级配置

多文件夹支持

若需配置多个音乐库路径（如分离专辑、合辑、单曲），可通过以下方式实现：

• 环境变量：用逗号分隔路径，如 GONIC_MUSIC_PATH=/music/albums,/music/compilations
• 命令行参数：重复指定 -music-path，如 gonic -music-path /music1 -music-path /music2

多值标签配置

gonic 支持处理多值标签（如同时标记为“摇滚”和“流行”的流派），通过以下模式配置：

示例：启用按分号分隔流派标签

shell
-e GONIC_MULTI_VALUE_GENRE="delim ;"

目录结构要求

按文件夹浏览时，需确保音乐文件组织符合以下规则：

• 同一专辑的文件需放在同一文件夹内
• 一个文件夹内仅包含同一专辑的文件

示例目录结构：

music/
├── drum and bass/
│   └── Photek/
│       └── (1997) Modus Operandi/
│           ├── 01.10 The Hidden Camera.flac
│           ├── 02.10 Smoke Rings.flac
│           └── folder.jpg
└── experimental/
    └── Alan Vega/
        ├── (1980) Alan Vega/
        │   ├── 01.08 Jukebox Babe.flac
        │   └── folder.jpg
        └── (1990) Deuce Avenue/
            ├── 01.13 Body Bop Jive.flac
            └── folder.jpg