Docker 自托管音乐库

把音乐，留在
自己的世界里。

扫描、整理、刮削与播放，在自己的 NAS 或家庭服务器上完成。没有订阅，没有曲库迁移，也没有失去掌控。

立即部署查看产品界面

AMD64 / ARM64
元数据 / 封面 / 歌词刮削
多人私有数据隔离

55种音频扩展

9个在线刮削来源

12项运行能力检测

100%数据在你的设备

一座完整的私人音乐馆

对体验有要求，
对数据有边界。

MusicArk 不只是播放器，也不是一套冰冷的文件管理器。它把日常听歌的愉悦，与长期维护曲库的可靠性放在同一处。

沉浸播放

封面流、动态环境色、逐字歌词与跨页面播放器，让本地收藏拥有完整而克制的流媒体体验。

准确整理

歌曲、专辑、艺术家、分类与文件视图彼此打通，扫描、搜索、批量维护都保持清晰。

真正私有

运行在自己的设备与网络里。多人共享一座曲库，收藏、歌单、历史与访问令牌仍各自独立。

元数据 · 封面 · 歌词

让每首收藏，
重新拥有完整面貌。

从 9 个内置在线来源寻找候选，先比较，再采用。MusicArk 尊重已有标签与本地扫描值，不用一次黑盒操作覆盖整座曲库。

MusicArk 在线刮削页面，展示匹配模式、数据来源以及歌曲信息、封面和歌词分类

Metadata

元数据，逐字段补全

曲名、艺术家、专辑、年份、流派、语言与唯一编号均可预览差异，按字段采用真正需要的值。

Artwork

封面，先看再选择

在线封面先进入候选与预览，确认后再归档；重新扫描也不会覆盖已经采用的结果。

Lyrics

歌词，与歌曲一起保存

普通歌词和逐字歌词独立处理并持久保存，随时可以切换候选或恢复本地扫描值。

多来源匹配三档匹配策略逐项预览差异安全采用与恢复

沉浸式播放

听见音乐，
也看见它的情绪。

当前封面化为克制的环境色，歌词跟随真实音频时间推进。队列、循环、切歌与全屏体验，都留在同一个流畅空间。

MusicArk 沉浸式全屏播放器，左侧为封面和播放控制，右侧为同步歌词 — 全屏播放 · 同步歌词

听歌时纯粹，管理时清晰

一眼看见整座曲库的状态。

从歌曲列表到运行状态，常用操作与风险提示都有明确层级。大曲库也能快速定位、批量整理与安全维护。

本地扫描标签维护重复项分析备份恢复运行审计多用户隔离

自在外观

浅色、深色，
或交给系统。

首次访问自动跟随设备外观，也可以随时固定为浅色或深色。切换只改变视觉，不会中断播放、清空队列或离开当前页面。

下载 MusicArk App 前往 musicark.pro 获取应用

01 · AUTO

跟随系统

读取设备的明暗偏好，并在系统外观变化时实时同步。

02 · LIGHT

明亮（浅色）

清晰通透的浅色界面，适合白天与明亮环境下浏览曲库。

03 · DARK

深色

克制低眩光的深色界面，让封面、歌词与播放器更沉浸。

应用接入 API

让你的播放器，
接入完整 MusicArk 能力。

基于稳定的 /api/core/v1 与 OpenAPI 3.1 契约，第三方播放器可以安全访问曲库、封面、歌词、直放与转码，并同步每个账户自己的队列、收藏、歌单和播放进度。

查看开发者接入指南下载 OpenAPI

接入流程

01
建立连接
使用用户名、密码与稳定的设备 ID 换取独立 Bearer Token。
02
发现曲库
分页读取歌曲、专辑、艺术家、搜索结果、封面与歌词。
03
创建播放会话
按客户端能力选择原始直放、渐进转码或 HLS。
04
同步个人状态
维护队列、收藏、歌单，并按设备上报与恢复播放进度。

PLAYER CONNECTION Bearer · JSON · REST

POST /api/core/v1/player/session
Content-Type: application/json

{
  "username": "alice",
  "password": "••••••••",
  "client_name": "客厅播放器",
  "device_id": "living-room-player"
}

Authorization: Bearer mak_...
GET /api/core/v1/catalog/tracks?limit=50

catalog:read playback:stream playback:control playback:report

曲库与内容

歌曲、专辑、艺术家、文件夹、搜索、推荐、封面和逐字歌词均使用同一鉴权模型。

播放与转码

读取可用 Profile，创建 ListeningSession，并按响应能力使用 Range、渐进流或 HLS。

个人数据同步

队列、音量、循环模式、三类收藏、歌单和设备进度始终按令牌所属用户隔离。

高权限维护

管理员可显式授予 library:write，通过 ETag、幂等键和审计保护维护曲库。

开始使用

选择你的安装方式

Docker Compose 适合长期运行与后续升级；docker run 适合快速体验。两种方式使用同一公开镜像，均支持 AMD64 与 ARM64。

首次启动：打开网页后创建管理员账户。MusicArk 不提供默认用户名或密码，也不需要在配置文件中填写管理员密码。

方式 A · Docker Compose

替换数据与音乐目录，保存配置，然后启动容器。

01修改路径并保存为 compose.yml

下载文件

name: musicark

services:
  musicark:
    image: musicark/musicark:latest
    container_name: musicark
    init: true
    restart: unless-stopped

    # 【可修改】左边的 13038 是网页访问端口，端口被占用时可改成 "23038:13038"。
    ports:
      - "13038:13038"

    # 运行参数：一般保持默认即可。
    environment:
      PUID: auto                         # 自动识别 NAS 用户 ID；特殊权限环境可改为数字
      PGID: auto                         # 自动识别 NAS 用户组 ID；特殊权限环境可改为数字
      UMASK: "022"                       # 新建文件的默认权限
      MUSICARK_AUTO_FIX_PERMISSIONS: "true"            # 自动处理数据目录权限
      MUSICARK_SESSION_COOKIE_SECURE: auto             # 自动选择会话 Cookie 模式
      MUSICARK_LOG_LEVEL: info                         # 日志级别
      MUSICARK_TRANSCODE_CACHE_MAX_BYTES: "5368709120" # 转码缓存上限：5 GiB
      TZ: Asia/Shanghai                  # 【可修改】按所在地修改时区

    volumes:
      # 【必须修改】将 /path/to/data 改成数据保存目录，用于数据库、封面和备份。
      - "/path/to/data:/data"
      # 【必须修改】将 /path/to/music 改成音乐文件所在目录。
      # 结尾的 rw 用于标签写回、整理和回收站；只需扫描与播放时可改为 ro。
      - "/path/to/music:/media/library:rw"

    # 安全配置：限制容器权限，通常不要修改。
    read_only: true
    tmpfs:
      - /tmp:size=128m,mode=1777
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - DAC_OVERRIDE
      - FOWNER
      - SETGID
      - SETUID

    # 健康检查：Docker 可据此判断服务是否正常。
    healthcheck:
      test: ["CMD", "/app/musicark", "healthcheck"]
      interval: 10s
      timeout: 3s
      retries: 12
      start_period: 10s
    stop_grace_period: 30s

    # 日志限制：避免长期运行占满磁盘。
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

02启动 / 查看状态 / 查看日志 / 停止

docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f
docker compose down

访问地址http://设备 IP:13038

/path/to/data 和 /path/to/music 都要替换为设备上的真实绝对路径；只需扫描和播放时可将 :rw 改为 :ro。

方式 B · docker run

将数据目录和音乐目录改成宿主机上的真实绝对路径，然后执行以下命令。

01拉取镜像

docker pull musicark/musicark:latest

02修改路径并运行容器

# 【必须修改】换成设备上的真实绝对路径
DATA_PATH="/path/to/data"       # 数据保存目录
MUSIC_PATH="/path/to/music"    # 音乐文件目录

# 【可修改】网页访问端口，端口被占用时可改成其他数字
MUSICARK_PORT="13038"

docker run -d \
  --name musicark \
  --init \
  --restart unless-stopped \
  -p "${MUSICARK_PORT}:13038" \
  -e PUID=auto \
  -e PGID=auto \
  -e UMASK=022 \
  -e MUSICARK_AUTO_FIX_PERMISSIONS=true \
  -e MUSICARK_SESSION_COOKIE_SECURE=auto \
  -e MUSICARK_LOG_LEVEL=info \
  -e MUSICARK_TRANSCODE_CACHE_MAX_BYTES=5368709120 \
  -e TZ=Asia/Shanghai \
  -v "${DATA_PATH}:/data" \
  -v "${MUSIC_PATH}:/media/library:rw" \
  --read-only \
  --tmpfs /tmp:size=128m,mode=1777 \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --cap-add CHOWN \
  --cap-add DAC_OVERRIDE \
  --cap-add FOWNER \
  --cap-add SETGID \
  --cap-add SETUID \
  --health-cmd '/app/musicark healthcheck' \
  --health-interval 10s \
  --health-timeout 3s \
  --health-retries 12 \
  --health-start-period 10s \
  --stop-timeout 30 \
  --log-driver json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  musicark/musicark:latest

03查看状态 / 查看日志 / 停止

docker ps --filter name=musicark
docker logs --tail 100 musicark
docker stop musicark

访问地址http://设备 IP:13038

只需修改命令顶部的 DATA_PATH、MUSIC_PATH；端口被占用时再修改 MUSICARK_PORT。

MusicArk

为珍藏音乐的人
认真做一座自托管音乐馆

把音乐留在自己的世界里

你的音乐
你的方舟

开始部署下载 App

把音乐，留在自己的世界里。

对体验有要求，对数据有边界。

沉浸播放

准确整理

真正私有

让每首收藏，重新拥有完整面貌。

元数据，逐字段补全

封面，先看再选择

歌词，与歌曲一起保存

听见音乐，也看见它的情绪。

一眼看见整座曲库的状态。

浅色、深色，或交给系统。

跟随系统

明亮（浅色）

深色

让你的播放器，接入完整 MusicArk 能力。

曲库与内容

播放与转码

个人数据同步

高权限维护

选择你的安装方式

你的音乐你的方舟

把音乐，留在
自己的世界里。

对体验有要求，
对数据有边界。

让每首收藏，
重新拥有完整面貌。

听见音乐，
也看见它的情绪。

浅色、深色，
或交给系统。

让你的播放器，
接入完整 MusicArk 能力。

你的音乐
你的方舟