极空间NAS部署道理鱼：音乐/MV/有声书全栈媒体库完整指南

一直在折腾家里的极空间NAS，从最开始的纯文件存储，到后来跑Jellyfin看剧、部署各种自动化工具，慢慢感觉这台机器的功能越挖越深。前两天为了给车上的音乐库和跑步时候听的有声书找一个统一入口，盯上了一个叫『道理鱼』（DaoLiYu）的开源项目。一开始我只是想试一下，结果发现它把音乐、MV、有声书这三种看似不搭的内容全栈集成在了一个服务里，这正好治好了我NAS上“音乐一个App、有声书一个App、MV还得另想办法”的老毛病。

这篇文章就把我在极空间Z4S上从零开始部署『道理鱼』的完整过程写出来，包括为什么选它而不选Navidrome或Jellyfin，Docker配置怎么填，媒体库目录怎么整理最省心，以及我实际踩过的几个坑。无论你的机器是Z2Pro、Z4S还是Z6，只要支持Docker，这套流程基本都能照搬。

1. 为什么在极空间上专门装一个“道理鱼”——项目定位与选型分析

1.1 它和Navidrome、Jellyfin有什么不一样

先聊聊我为什么会在那么多流媒体服务里选中道理鱼。极空间自带的音乐播放器不是不能用，但面对我这种本地音乐存量很大、又有MV资源、还有大量有声书音频文件的用户，它有点顶不住。NAS上已有的方案无非这两条线：一类是Navidrome、Subsonic这种专注音乐播放的，界面干净、歌词封面管理强，但只能管音频；另一类是Jellyfin、Emby这种全媒体库，能管电影剧集，但音乐体验只能说够用，对有声书的进度记忆支持更是约等于零。

道理鱼走的是第三条路。它的后端是Go语言写的，前端是Vue3，部署形态就是一个Docker容器，但内置了音乐、MV、有声书三个平行的媒体库模块。这意味着我不用再像以前那样，音乐在Navidrome里、有声书用第三方App通过WebDAV访问、MV单独放在某个目录靠电视播放器硬解码，所有内容都统一出现在道理鱼一个界面上。对NAS用户来说，少一个App就是少一份维护成本。

而且道理鱼对音频格式的处理比较激进。它内置了解码和转码链路，遇到FLAC、APE这些高码率格式，可以实时转成OPUS或AAC推给浏览器和手机端，避免手机流量被无损格式吃掉。这个能力在极空间上很实用，毕竟很多车机投屏或手机远程播放的场景，带宽并没有你想象的那么充裕。

1.2 极空间上跑媒体服务的优势与痛点

极空间和群晖、威联通这些老牌NAS的区别在于，它的系统本身是面向国内用户的，底层虽然是Linux，但提供了一套完整的图形化管理界面，Docker这部分也被包装成了「容器」功能。好处是想跑服务不需要先折腾SSH登录，网页端就能操作，这对刚接触NAS的人非常友好。但痛点也很明显，极空间自带的Docker管理界面比Portainer要弱一截，很多高级选项被藏起来或间接屏蔽，比如容器的特殊权限、网络模式的选择、部分环境变量的注入，如果不了解背后原理，经常会被卡在“明明镜像拉下来了，容器却起不来”这种莫名其妙的地方。

所以我的建议是，部署道理鱼之前，先把极空间Docker的基本逻辑搞清楚：镜像、容器、数据卷这三个概念必须弄明白。你在极空间上跑任何容器，本质就三步：把镜像拉下来，把宿主机的某个目录映射到容器内部的某个路径，把容器的某个端口映射到宿主机的某个端口。道理鱼也不例外。搞清楚这一点，后面走流程时就不会被界面上那些输入框吓到。

2. 部署前的准备工作：镜像、目录与端口规划

2.1 极空间Docker的两种部署方式

极空间上部署Docker容器有两条路。第一条是直接用系统自带的“容器”应用，打开之后能看到镜像仓库、容器列表、镜像列表这些页签，界面整体比较接近Docker Desktop的简化版。第二条是通过SSH登录后使用docker run命令行部署。两条路我都试过，结论很简单：如果你只是想跑起来，用自带容器界面就够了；如果你需要精细控制，比如指定用户ID、挂载多个目录、调整网络参数，SSH命令行会更趁手。

对道理鱼来说，我更推荐先用容器界面把基础版本跑通，确认媒体库扫描正常、界面能访问之后，再考虑要不要切换到命令行方式做更多自定义。因为道理鱼本身需要的配置不多，核心就三个挂载目录加一个端口，图形界面完全可以覆盖，没必要一上来就搞SSH，那样反而容易因为权限设置不对导致容器里读不到文件。

2.2 媒体库目录怎么整理才省心

这是整套流程里最值得提前规划的一步。道理鱼扫描媒体文件时，是严格按照目录结构来区分音乐、MV和有声书的，所以你不能把一堆乱七八糟的音频堆在一个文件夹里让它自动判断，那样它大概率会归类错误。

我建议在NAS上单独建一个总目录，比如/volume1/媒体库，下面再分三个子目录：音乐、MV、有声书。每个子目录内部再按照媒体类型去组织：

• 音乐目录建议用歌手/专辑/曲目的三级结构，这样道理鱼的专辑聚合和艺术家信息匹配最准确。
• MV目录相对自由，按歌手/曲目或者演出者/活动名组织都可以，但文件名最好包含清晰的作品名，因为道理鱼很多MV封面是从本地文件或网络元数据抓取的，文件命名越规范，刮削匹配率越高。
• 有声书目录建议按书名/分章文件整理，道理鱼对有声书的识别主要靠文件名和目录层级，如果你把一个有声书的所有MP3全部平铺在同一个目录里，排序和进度记忆都会很混乱。

我最早部署时偷懒了，直接把之前下载的几千个MP3一锅端丢进音乐目录里，结果道理鱼扫描了两个多小时，还出现了大量“未知艺术家”条目。后来按目录结构重新整理了一遍，重新扫描不到五分钟就完成了，专辑信息、艺术家头像、曲目排序全部正常。这个教训值得提前说。

2.3 端口与资源预留

道理鱼默认的Web访问端口是18888，这个端口在我看到的一些文档里有提及。你可以在极空间的容器配置里把它映射成任意一个宿主机空闲端口。我习惯映射成18888，因为比较好记，访问地址就是http://极空间IP:18888。需要注意端口不要和极空间系统本身的服务冲突，一般只要不是5055、8096这类常见NAS服务端口，问题都不大。

资源占用方面，道理鱼本身很轻量，Go编译的二进制在空闲时内存占用不到100MB，CPU基本为0，只有在转码或扫描媒体库时才会有明显波动。但注意转码是CPU密集型操作，如果你的NAS是ARM架构的入门机型，比如Z2Pro这类，遇到大量直接转码请求时可能会卡顿。这种情况我更建议在客户端优先使用原码播放，不要强制转码，道理鱼的客户端设置里可以针对不同连接类型单独设置播放策略。

3. 手把手在极空间部署道理鱼

3.1 拉取镜像与创建容器

打开极空间的“容器”应用，在镜像仓库页面搜索daoliyu，应该能找到官方或社区维护的镜像。找到后点击下载，等进度条走完。如果你在极空间内置仓库里搜不到，可以先确认一下网络镜像源配置，或者到项目的GitHub Releases页拿一下镜像名称，再到极空间镜像仓库里手动填写镜像地址拉取。

镜像拉下来之后，点击“创建容器”。这里我建议先不要急着点“一键部署”，因为极空间有些一键配置模板可能版本滞后，还是自己填更可控。容器名称随意，比如daoliyu，镜像选择刚才拉取的那个版本。创建完成后会进入配置页面，重点要设置三个区域：存储卷映射、端口映射、环境变量。

3.2 关键配置说明：存储卷、端口、环境变量

存储卷映射是整个部署里最容易出问题的地方。道理鱼默认的配置路径、媒体库路径都在容器内部固定位置，你必须把宿主机真实目录挂载进去，它才能读到文件和保存配置。我当时的配置如下：

• 媒体库目录：把/volume1/媒体库映射到容器内的/data。
• 配置目录：把/volume1/docker/daoliyu映射到容器内的/config。

这里有个细节要注意，极空间的文件路径并不都是/volume1，不同机型或硬盘组不同，路径可能有差异。你在选择宿主机目录时，不要手打路径，尽量通过界面的“选择文件夹”按钮去选，确保路径真实存在且极空间运行容器的用户有权限读写。

端口映射这里，把容器端口18888映射到宿主机端口18888，类型选TCP。如果你不想直接暴露默认端口，也可以映射成其他端口，比如18080，访问地址跟着变就行。

环境变量方面，道理鱼对配置项很克制，基础使用不需要额外设置任何环境变量，时区默认走系统时区，也能直接用。官方文档里提到的个别高级环境变量主要是为了控制日志级别和自定义数据库路径，普通用户用不上。

3.3 初始化设置与媒体库扫描

所有配置填完后，点击创建容器，稍等几秒，容器状态会从“创建中”变为“运行中”。在浏览器地址栏输入http://极空间IP:18888，就能打开道理鱼的Web界面。第一次打开会进入初始化页面，通常需要设置一个管理员账号和密码，这个账号是道理鱼自己的账号体系，和极空间的系统账号无关，最好用一套独立的强密码。

登录之后，进入后台的媒体库管理页面，会看到音乐、MV、有声书三个分类。你需要把之前规划好的三个目录分别添加进去，并设置每个媒体库对应的类型。添加之后，点击“立即扫描”，道理鱼就会开始遍历文件夹，读取音频文件的元数据并写入自己的数据库。

扫描速度取决于你的文件数量和NAS性能。我大概有3000多首音乐、200多部MV和100多个有声书文件夹，在Z4S上首次全量扫描大约花了10分钟。扫描过程中你可以继续浏览其他页面，道理鱼是后台异步扫描，不会卡界面。扫描完成之后，首页就会出现分类卡片，点进去就能看到专辑墙、艺术家墙和MV列表了。

3.4 外网访问的几种常见方式

部署完成后，局域网内已经可以正常用了。如果你在外面也想访问，极空间本身提供了一套远程访问服务，但那是串流到极空间的网页端，并不等价于让你直接访问18888端口。我更推荐给极空间申请一个IPv6公网地址，然后在路由器上放行对应端口，直接访问http://[IPv6]:18888。没有公网IPv6的话，用轻量云服务器做反向代理也是一种方案，但要注意带宽和流量费用。

道理鱼本身支持挂载为网盘、WebDAV等外部来源，这点也值得提—如果媒体库文件不在极空间本地，而是放在另一台NAS或网盘上，你可以通过WebDAV方式把远程目录挂载进道理鱼，省掉拷贝文件的功夫。

4. 音乐/MV/有声书全栈功能的日常使用与效果打磨

4.1 音乐播放、歌词与封面

音乐这块，道理鱼首页会按专辑、艺术家、流派几个维度进行整理。专辑墙的封面抓取支持从文件内嵌封面读取，也支持通过专辑名去匹配网络图片。我这个过程中体会最深的一点是：平时的文件整理越规范，道理鱼的体验就越接近流媒体App。如果你之前音频文件自带封面、ID3信息完整，道理鱼直接就能呈现一个非常漂亮的播放界面；如果ID3信息乱，它就只能靠文件名去猜，效果差一大截。

音乐播放器底栏支持播放队列、循环模式，也支持歌词展示。歌词默认从内嵌歌词或同名字幕文件读取，如果你有自己的LRC文件，记得放在同名目录下，道理鱼会自动识别。我在歌曲目录放了LRC后，音乐播放页就能正常滚动显示歌词了，这个细节对K歌场景挺有用的。

4.2 MV播放与转码

MV是道理鱼相比普通音乐服务器的亮点。你把它当成一个内置了播放器的视频库用就行。道理鱼的MV模块会扫描MV目录下的视频文件，提取缩略图，并按艺术家分组展示。点进一部MV，播放器直接调用内置播放能力，支持进度栏、倍速、全屏。

我遇到比较多的情况是手机通过4G/5G远程看MV，如果NAS带宽不够，视频会一直缓冲。解决办法是在道理鱼的播放设置里开启转码，让它把高清MV实时转成低码率的720p甚至480p流再推给客户端。实测在Z4S上转码一个1080p H.264 MV到720p，CPU占用约30%~40%，基本不影响其他服务的正常运行。如果你是ARM机型，建议优先使用原码播放，或者提前把MV转成较小的码率版本存储在NAS上，而不是依赖实时转码。

4.3 有声书进度记忆与多端同步

有声书模块是我最看重的部分。以前我一边开车一边听有声书，回家换个设备就要手动找上次听到的时间点，非常痛苦。道理鱼为有声书专门做了进度记忆功能，每本书的封面、作者、总时长、章节列表都会单独展示，点击“继续收听”就能精确回到上次停止的位置。这个进度会保存在道理鱼的数据库中，所以无论你是在手机浏览器、电脑浏览器还是平板Web界面里播放，只要登录同一个道理鱼账号，进度都是同步的。

有声书的排序也有讲究。道理鱼支持按书名、最近收听、更新时间排序，我觉得“最近收听”最贴合实际场景—你同时追两三本书时，首页就能直接点进去继续，不用去翻书架。另外如果是分章节的有声书，务必保证章节文件按数字序号命名，否则道理鱼默认按文件名排序会出现第10章排在第二章前面的情况。

5. 踩坑实录与常见问题排查

5.1 常见问题速查表

部署和使用过程中我前前后后折腾了不少，把最典型的几个问题整理成了表格，方便你按图索骥。

5.2 极空间特有场景的避坑建议

极空间的容器功能有一些和标准Docker不太一样的地方，这点必须单独说。第一，极空间宿主机上的文件权限管理得很严格，如果你在创建容器时发现挂载目录里的文件“存在但读不了”，大概率是容器内运行用户没有访问权限。这种情况下，解决办法是把挂载目录设置为777权限，或者让容器以root用户运行。道理鱼的镜像本身不强制要求root，但为了省事，我直接在极空间容器设置里把权限模式调成了“特权模式”，所有文件读写问题一次解决。

第二，极空间系统重启后，容器的启动顺序不一定和创建顺序一致。如果你还部署了其他依赖型容器（比如数据库、反代服务），建议在极空间的容器设置里把“自动启动”关掉，手动通过批量启停脚本来控制。道理鱼本身不依赖其他容器，所以直接开启自动启动，系统重启后服务会自动恢复。

第三，别忽略系统升级对容器的影响。极空间的系统更新偶尔会重建Docker网络或重置容器配置，造成容器无法自动启动。最稳妥的做法是升级系统前，手动备份道理鱼的配置目录，升级后如果发现容器异常，直接复用备份恢复即可。

5.3 一些小众但实用的操作技巧

• 自定义音频转码格式：道理鱼默认转码输出格式可以通过环境变量调整，比如强制输出AAC或MP3，对老车机的蓝牙播放兼容性更好。
• 定时扫描：道理鱼支持配置定时扫描任务，如果你经常往媒体库目录里丢新文件，可以把扫描间隔设为每小时一次，实时性会好很多。
• 移动端PWA安装：道理鱼的Web界面支持PWA，用手机浏览器打开后“添加到主屏幕”，就能像原生App一样全屏使用，省去在应用商店里找客户端的麻烦。
• 分享链接：道理鱼支持生成对外分享链接，你可以把某张专辑或某本有声书生成一个临时链接发给朋友，对方无需登录账号也能试听。这个功能在同事之间安利歌单时非常好用。

这几年陆陆续续在NAS上部署过不少媒体服务，很多项目都是用一两天就扔一边了，但道理鱼在极空间上稳定跑了两周之后，我反而把手机里原来的几款播放器App都卸载了。原因很简单：音乐、MV、有声书这三类内容统一在一个入口里，进度能同步，歌词封面都齐整，这在之前是得靠两三个App配合才能实现的体验。如果你手头的NAS也支持Docker，找一个周末按上面的流程试一遍，大概率会觉得这次折腾挺值。