Docker 搭建 Lidarr 这件事我前后折腾过几轮真正费时间的从来不是把容器跑起来而是让音乐库里的文件被正确识别、重命名、刮削并且在重启、升级、迁移之后还能稳定工作。Lidarr 是一个面向个人音乐库的整理与元数据管理工具它能把散乱的文件按艺术家、专辑、曲目归类补齐封面和曲目信息持续监控库内变化。它适合手里已经有合法音乐文件、希望把库整理得井井有条的人也适合想用容器方式做长期维护的读者。下面按我实际落地的顺序拆开讲重点放在路径、权限、元数据和排错上代码和参数都能直接照着改。1. 先想清楚Docker 搭建 Lidarr 到底解决什么问题1.1 它和普通音乐播放器不是一回事很多人第一次接触 Lidarr会把它当成“能在网页里听歌的工具”实际不是。它更像一个音乐库管家你告诉它音乐放在哪个根目录它去扫描文件读取内嵌标签拿艺术家、专辑、曲目信息去匹配元数据然后按照你定的命名规则整理文件、补封面、记录库内状态。播放这件事通常交给别的客户端Lidarr 负责的是“库是否整齐、信息是否完整、后续变化能不能被跟踪”。这个定位决定了部署时的重点。播放器更关心解码和输出Lidarr 更关心文件路径、读写权限、标签准确度和数据库一致性。你如果只把容器跑起来页面能打开但根目录填错、容器内路径和宿主机路径对不上后面扫描会一脸茫然明明文件在库就是不动或者重命名报错日志里全是 permission denied。我的建议是先把“库管家”的职责想明白再动手写 compose。它解决的问题也很具体手工整理几百上千张专辑命名风格很难统一封面和曲目信息容易缺重复文件靠人眼找很累Lidarr 把这些重复劳动收拢到一套规则里扫描一次、复核一轮后面新增文件按同一套逻辑处理。前提是文件本身有基本标签且你对命名规则有明确预期。标签乱、文件名乱、目录层级乱工具只能帮你一部分剩下还得先做清洗。1.2 为什么用容器而不是直接装直接装在宿主机上也能跑但依赖、运行时、升级回滚会慢慢变成负担。Lidarr 这类服务通常要长期挂着偶尔升级版本配置和数据库都在本地。容器化的好处是把运行环境和宿主机隔开配置、音乐库、备份分别挂载到明确的目录迁移时把目录一拷、compose 一改就能走。升级出问题也能回退到旧镜像标签不至于把宿主机环境搅乱。容器不是万能药。它把权限问题放大了容器内进程用哪个用户跑挂载目录属于谁写文件时 umask 是多少这些在直接安装时可能被忽略在容器里会直接表现为“页面能开、扫描失败”。另外容器内的路径是独立命名空间Lidarr 数据库里记的是容器内绝对路径你宿主机路径变了、挂载点变了数据库里的记录就对不上。所以用容器之前目录规划要比直接安装更认真。我选择容器的理由很朴素配置集中、备份简单、升级可控。配置全在/config音乐库单独挂载备份目录单独挂载出问题先看容器日志再进容器看权限。对比直接安装少了很多“这个依赖装在哪、升级会不会影响系统库”的纠缠。对个人音乐库这种长期维护场景容器化的收益是明显的但前提是你愿意先把路径和权限设计好。1.3 合规边界与适用场景判断Lidarr 本身是库管理工具怎么用取决于文件来源和使用场景。我的做法很明确只处理自己有合法权利的音乐文件自动获取相关功能保持关闭把它当成本地库整理器。个人收藏、家庭共享的自己购买或合法获得的音乐、自己创作或录制的素材库这些场景都适合。来源不明的文件不要往里塞也不要为了“库看起来全”去接一些不该接的环节。从功能上看Lidarr 的扫描、匹配、重命名、封面管理、库监控都是围绕已有文件展开的。你完全可以在不配置任何外部获取环节的情况下使用它建根目录、扫描、人工复核匹配、批量重命名、补元数据。这样既能把库整理好也避免把工具用偏。某开发者一开始图省事把一堆标签混乱的文件直接全库扫描结果专辑被拆得七零八落后来改成先拿二十张样本做规则验证再分批导入问题少了很多。适用人群也要分清。手里文件不多、命名已经很整齐的人用不用工具差别不大文件多、跨多个硬盘、标签风格不统一的人收益明显。还有一类是做素材管理的工作室音乐不是用来发行的而是项目素材需要按情绪、节奏、专辑归类Lidarr 的元数据和目录规则也能帮上忙但这类场景要额外注意文件命名不要和项目编号冲突。先判断自己属于哪一类再决定投入多少时间做规则设计。2. 部署前的目录与权限设计2.1 目录规划配置、音乐库、备份分离我习惯把 Lidarr 相关目录收在一个父目录下例如/srv/lidarr下面分config、music、backup需要的话再加一个incoming作为待整理区。config放数据库、日志、封面缓存和设置music是最终音乐库backup放配置备份和数据库导出incoming只作为临时落地区整理完再进music。分开的好处是备份时不会把几 TB 音乐全打包权限也能按目录区分。配置目录和音乐库的权限要求不一样。config是 Lidarr 自己写权限可以紧一点只给运行用户读写music需要 Lidarr 读写可能还需要别的整理工具或播放器读权限要稍宽。备份目录最好只给管理员和 Lidarr 写避免误删。下面这张表是我常用的规划方式路径名你可以按自己环境改但“用途分离”这个原则别省。宿主机路径容器内路径用途权限建议/srv/lidarr/config/config数据库、日志、设置、缓存运行用户读写700 或 750/srv/lidarr/music/music最终音乐库运行用户读写组用户可读2775/srv/lidarr/backup/backup配置和数据库备份管理员与运行用户读写/srv/lidarr/incoming/incoming待整理临时区运行用户读写定期清理路径命名尽量用英文、短横线或下划线避免空格和特殊符号。中文路径不是绝对不行但排错时日志、命令行、数据库记录混在一起很容易看花眼。音乐库内部也别频繁改根目录名Lidarr 数据库记的是绝对路径你改一次宿主机目录名容器内挂载点不变还好挂载点一变就要重新映射历史记录会对不上。2.2 UID/GID 与权限最常见的翻车点容器里跑 Lidarr 的进程不是宿主机上的你而是一个 UID/GID。常见镜像用PUID、PGID环境变量指定运行用户有些镜像则用user:指令。不管哪种目标都是让容器内进程写挂载目录时宿主机上看到的文件属主是你期望的用户而不是 root 或一个陌生 UID。先查当前用户id -u和id -g把结果填进 compose。不要图省事用 root 跑后面文件全变成 root 属主普通用户改不动备份也麻烦。权限计算要落到 umask。UMASK002的含义是普通文件默认 666减去 002 后是 664目录默认 777减去 002 后是 775。这样同组用户能读写其他人只读。配合目录上的 setgid 位新建文件会继承父目录的组。命令不复杂但要在挂载前做sudo mkdir -p /srv/lidarr/{config,music,backup,incoming} sudo chown -R 1000:1000 /srv/lidarr sudo find /srv/lidarr/music -type d -exec chmod 2775 {} \; sudo find /srv/lidarr/music -type f -exec chmod 664 {} \;上面的1000:1000只是示例换成你id -u、id -g的结果。NAS 或网络文件系统上还要注意挂载参数SMB/NFS 可能把 UID 映射成nobody或者不允许 chown。遇到这种情况先在宿主机本地目录跑通再迁移到网络存储或者让网络存储侧固定映射到同一个 UID/GID。不要一上来就把库放网络盘权限和锁问题会把排错难度拉高。还有一个容易忽略的点容器不要挂/var/run/docker.sock也不要给privileged。Lidarr 不需要这些权限给了只会扩大风险。它只需要写自己的配置和音乐库。安全选项里加no-new-privileges:true是低成本的好习惯。权限这件事宁可部署前多花十分钟也别等扫描到一半报错再回头改。2.3 端口、时区与反向代理的取舍Lidarr 默认 Web 端口是 8686。个人使用我建议绑定到回环地址127.0.0.1:8686:8686需要远程访问时再通过反向代理加认证和 TLS不要直接把端口裸奔到公网。容器网络用默认 bridge 就够除非你有明确的局域网访问需求才考虑 host 模式。host 模式省掉端口映射但会把服务暴露在宿主机所有网卡上取舍要看环境。时区用TZEtc/UTC或你实际所在时区。时区影响日志时间、定时任务和扫描记录不影响音乐文件本身。有人用 UTC 统一管理有人用本地时区方便看日志选一个固定下来就行别今天改明天改。反向代理要注意两件事一是加认证二是把上传大小和超时调够。Lidarr 的封面和扫描请求可能比较集中代理层超时太短会出现页面加载一半失败。防火墙层面只放行你真正需要的来源。局域网访问就限制网段远程访问走代理的 443不要把 8686 直接映射出去。容器重启策略用unless-stopped宿主机重启后服务能自己起来但手动停掉的容器不会自己复活。日志驱动默认就行长期跑可以限制日志大小避免磁盘被容器日志吃掉。端口和时区这些参数看起来琐碎出问题时却最容易被忽略。3. 用 Compose 跑起 Lidarr参数逐项拆解3.1 compose 文件模板与注释下面这份模板是我常用的结构镜像名用your-registry/lidarr:latest占位你换成自己环境里可用的 Lidarr 镜像地址。PUID、PGID、UMASK按上一节的计算结果填。健康检查不是必须的有些镜像里没有wget加了会一直显示 unhealthy可以先注释掉等确认容器内有可用命令再开。services: lidarr: image: your-registry/lidarr:latest container_name: lidarr environment: - PUID1000 - PGID1000 - UMASK002 - TZEtc/UTC volumes: - /srv/lidarr/config:/config - /srv/lidarr/music:/music - /srv/lidarr/backup:/backup - /srv/lidarr/incoming:/incoming ports: - 127.0.0.1:8686:8686 restart: unless-stopped stop_grace_period: 30s security_opt: - no-new-privileges:true # healthcheck: # test: [CMD-SHELL, wget --spider -q http://127.0.0.1:8686/ping || exit 1] # interval: 30s # timeout: 5s # retries: 3 # start_period: 60s逐项解释一下。image决定版本长期使用建议固定到具体 tag不要永远latest升级前心里有数。container_name方便敲命令但一个名字只能对应一个容器。environment里PUID/PGID决定文件属主UMASK决定新文件权限TZ决定日志时间。volumes是持久化核心配置、音乐、备份、临时区都要落到宿主机。ports绑定回环地址减少暴露面。restart和stop_grace_period让容器停得稳一点数据库不容易被硬杀。启动命令就两条先docker compose up -d再看日志docker compose logs -f lidarr。日志里出现监听 8686、数据库迁移完成之类的信息再去浏览器打开http://127.0.0.1:8686。如果页面打不开先docker compose ps看容器是不是反复重启再docker compose logs --tail100 lidarr看报错。不要一上来就改端口、改网络先把日志读明白。3.2 卷映射为什么必须“同路径”Lidarr 数据库里记录的音乐路径是容器内绝对路径不是宿主机路径。你挂载/srv/lidarr/music到/music在 Lidarr 里建根目录就要填/music不要填/srv/lidarr/music。填错的结果是页面里能看到目录扫描却没文件或者重命名时提示源文件不存在。这个问题在新手里非常常见因为宿主机命令行里看到的是/srv/lidarr/music很容易顺手填进去。如果后续还要接别的容器做整理或转码挂载点要统一规划。比如所有容器都把音乐库挂到/music这样彼此看到的路径一致数据库记录、任务参数、脚本路径才不会互相打架。不要一个容器挂/music另一个挂/data/music然后靠符号链接硬凑。符号链接在容器边界上容易断尤其是绝对路径的软链宿主机和容器内解释不一样。绑定挂载默认是读写需要只读可以加:ro但 Lidarr 要重命名、写封面、整理目录主音乐库不能只读。临时区可以按需只读或读写。启用 SELinux 的系统可能要在挂载后加:Z或:z否则容器写不进去。网络文件系统要注意锁和大小写Linux 下Album和album是两个目录从其他系统迁移过来的库可能有大小写冲突扫描前先检查一遍。3.3 启动后的首次配置与健康检查首次打开页面先做三件事设置认证、确认根目录、建音乐库。认证不要省哪怕是局域网设一个强密码也比裸奔强。根目录填容器内路径/music如果临时区也纳入管理再建一个/incoming的库或先不建。媒体管理里的命名规则先别急着大改拿样本目录试跑确认重命名结果符合预期再全库应用。健康检查可以用curl或wget请求/ping但不同镜像内置命令不一样。我的做法是先在容器里执行which wget、which curl有哪个用哪个。没有就关掉 healthcheck靠docker compose ps和日志判断。不要为了健康检查专门装工具镜像层越改越乱。日志位置在/config/logs出问题先看最近几十行比在页面上点来点去快。升级流程也要固定先备份/config再docker compose pull然后docker compose up -d最后看日志和页面是否正常。出问题就把镜像 tag 改回旧版本恢复配置备份。不要在不备份的情况下跨大版本升级。数据库迁移有时不可逆备份是唯一的退路。升级后如果库扫描异常先看日志里有没有数据库锁或迁移错误再考虑重建索引。4. 音乐库导入与元数据整理实操4.1 媒体管理设置命名、根目录、导入方式媒体管理是 Lidarr 最值得花时间的地方。命名规则一旦定下来后面所有导入都按它走改来改去会让库风格分裂。我常用的规则是艺术家目录、专辑目录、两位曲目号加曲目名多碟专辑加碟号。示例{Artist Name}/{Album Title}/{track:00} - {Track Title}多碟用{disc:00}-{track:00}。文件名里避免斜杠、冒号、问号这些跨平台不友好的字符工具一般会替换但规则里提前避开更稳。根目录只填容器内路径且一个库对应一个根目录。不要今天用/music明天改成/media/music数据库里的历史记录会对不上。导入方式有复制和移动两种首轮我建议用复制保留原始文件确认命名和匹配都正确后再清理源目录。移动省空间但一旦规则设错原文件被挪走回滚成本高。临时区到正式库的整理也可以先复制再人工抽查。专辑艺术家这个字段要特别注意。合辑、原声、多人合作专辑如果Album Artist标签缺失或不统一Lidarr 可能把同一张专辑拆成好几个艺术家目录。导入前用标签工具把专辑艺术家统一合辑统一写成Various Artists或你固定的合辑名。单曲和 EP 也要想好放哪是独立目录还是归到专辑下。规则没有绝对对错关键是一致后面扫描和重命名才不会反复横跳。4.2 质量配置与文件识别先修标签再扫描质量配置在本地库整理场景里更像一个“文件达标判断”。Lidarr 会根据文件扩展名、码率、采样率等信息给文件打质量标签你可以建一个只包含现有文件质量的 profile避免它把已有文件判成“不达标”而反复提示。如果你不打算做自动升级相关自动升级选项保持关闭减少误操作。质量配置不是越高越好而是和你的文件实际情况匹配。文件识别的基础是标签。Lidarr 读取内嵌的艺术家、专辑、曲目、曲目号、碟号再去匹配元数据。标签缺失或错乱匹配就会偏。我的顺序是先用标签工具批量检查Artist、Album Artist、Album、Title、Track、Disc把明显的空值和错字修掉再拿二十张样本扫描最后人工复核匹配结果。不要指望 Lidarr 把所有脏标签都猜对它猜错后再改工作量更大。匹配错了怎么办在专辑页面里用手动搜索输入艺术家和专辑名选正确的发行版。选完后确认曲目列表和文件顺序再执行重命名。重命名前先看预览尤其是多碟和合辑。封面缺失不一定是文件问题可能是元数据源访问不稳定先看日志里的请求错误再考虑换元数据源或稍后重试。不要为了补封面反复全库刷新容易把数据库和缓存搞乱。4.3 批量导入与人工复核小步走比一把梭稳批量导入最忌讳一把梭。我的做法是分三批第一批二十张覆盖普通专辑、多碟、合辑、单曲各几张第二批一两百张验证命名规则和权限第三批再全量。每批导入后看三件事目录结构是否符合预期、文件数有没有少、日志有没有权限或匹配错误。某 A 同学把三千多首文件一次性扫进去结果合辑全散封面互相覆盖最后只能删库重来时间反而花得更多。人工复核要抓重点。优先看艺术家目录有没有重复、专辑有没有被拆、曲目号有没有错位、多碟有没有并到一张。文件名里的特殊字符、大小写冲突、重复文件也要抽查。重复文件不一定是完全相同的音频可能是同一张专辑的不同版本保留哪个要按你的规则来。我的习惯是保留原始目录一份整理后的库单独放确认稳定后再清理原始目录。导入过程中不要同时跑多个扫描任务也不要在扫描时重启容器。数据库锁一旦出现页面会卡日志里能看到 lock 相关错误。先停任务、等容器稳定再重新扫描。磁盘空间也要提前看重命名和复制都会占空间尤其是首轮用复制模式。导入完成后做一次配置备份记下当前镜像 tag 和命名规则后面新增文件就按这套走。5. 常见故障排查与维护5.1 权限、路径、标签匹配问题速查表出问题先别猜按“容器状态、日志、路径、权限、标签”的顺序查。下面这张表是我实际遇到频率比较高的几类命令可以在宿主机执行也可以在容器里执行注意路径对应关系。症状常见原因排查方式处理建议页面打不开容器没起来、端口没映射、绑定地址错docker compose ps、docker compose logs --tail100 lidarr先看日志再确认127.0.0.1:8686是否被占用扫描不到文件根目录填了宿主机路径、扩展名不支持、挂载没生效进容器ls -l /music页面根目录填/music统一容器内路径确认文件在挂载目录里重命名失败目录没有写权限、目标路径非法字符、磁盘满ls -ld /music、df -h、看日志报错文件修 UID/GID 和目录权限清理非法字符专辑被拆散专辑艺术家标签缺失或不统一抽查文件标签看艺术家目录先统一Album Artist再重新匹配封面补不上元数据源访问不稳定、缓存异常看日志请求错误检查网络连通性稍后重试清理缓存后单张刷新数据库锁同时扫描、容器被硬杀、存储响应慢日志里找 lockdocker compose stop再启动避免并发扫描给足停止宽限期文件属主变成 root容器以 root 运行、PUID/PGID 没生效ls -ln /srv/lidarr/music改用运行用户批量修正属主排查时有一个小技巧先在容器里看路径再在宿主机看同一个路径。容器里ls -l /music能看到文件说明挂载没问题宿主机ls -ln /srv/lidarr/music看 UID/GID能判断权限。两边都正常再去看 Lidarr 的根目录设置和标签。不要一上来就重建容器很多问题重建一次只是把现象藏起来。5.2 备份、升级、日志与资源占用备份的重点是/config数据库、设置、封面缓存都在里面。最稳的备份方式是停容器再打包docker compose stop lidarr然后tar -czf /srv/lidarr/backup/config-$(date %F).tar.gz -C /srv/lidarr config最后docker compose start lidarr。运行中直接拷数据库可能拿到不一致状态尤其是扫描任务正在跑的时候。备份目录不要和配置目录放在同一个磁盘故障域里至少复制一份到别的存储。升级不要追新。固定 tag升级前看日志和备份升级后跑一次小范围扫描。跨大版本时数据库可能迁移回滚旧镜像不一定能读新库所以备份必须在升级前做。日志文件会慢慢变大定期清理/config/logs下的旧日志或者配置日志轮转。资源占用方面扫描时 CPU 和磁盘 IO 会上去给容器限制内存可以防止极端情况下拖垮宿主机但不要限制得太死数据库操作需要余量。迁移到新机器时保持容器内路径不变宿主机路径可以变但挂载点最好还是/config、/music。把配置备份解压到新机器的配置目录改 compose 里的宿主机路径和 UID/GID启动后检查根目录和库状态。音乐文件本身的内嵌标签才是长期资产数据库只是索引别把全部希望押在数据库上。文件名和标签整理好即使换工具也能快速重建。5.3 独家避坑心得路径先定、标签先修、权限先验我踩过最亏的一次坑是先把几百张专辑扫进去再回头改根目录。数据库里全是旧路径重命名全部失败最后只能删库重扫。后来我的顺序固定成先定宿主机目录和容器内挂载点再写 compose再验权限最后才导入。路径这件事部署前多想十分钟后面少折腾一晚上。另一个坑是标签封面和曲目信息再漂亮专辑艺术家不统一库还是会散。权限验证不要只看页面。页面能打开不代表能写文件。部署完先建一个测试专辑目录放两首带完整标签的文件跑一次扫描和重命名确认宿主机上文件属主、权限、文件名都符合预期。测试通过再批量导入。还有自动获取相关功能如果不打算用就保持关闭减少误触发和无关日志。只处理自己有合法权利的文件这个底线要放在最前面。我自己的习惯是先把路径、UID/GID、命名规则写在一张便签上贴在放 compose 文件的目录旁边每次加新容器先对一遍。音乐库首轮用复制确认稳定后再清理源目录配置每周备份一次升级前额外备份一次日志只保留最近一段排错时再看详细级别。这套做法不花哨但能让你在几个月后回来改东西时不用靠记忆猜当时为什么这么配。