企业官网建设流程全解析

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 写，避免误删。下面这张表是我常用的规划方式，路径名你可以按自己环境改，但“用途分离”这个原则别省。

路径命名尽量用英文、短横线或下划线，避免空格和特殊符号。中文路径不是绝对不行，但排错时日志、命令行、数据库记录混在一起，很容易看花眼。音乐库内部也别频繁改根目录名，Lidarr 数据库记的是绝对路径，你改一次宿主机目录名，容器内挂载点不变还好，挂载点一变就要重新映射，历史记录会对不上。

2.2 UID/GID 与权限：最常见的翻车点

容器里跑 Lidarr 的进程不是宿主机上的你，而是一个 UID/GID。常见镜像用PUID、PGID环境变量指定运行用户，有些镜像则用user:指令。不管哪种，目标都是让容器内进程写挂载目录时，宿主机上看到的文件属主是你期望的用户，而不是 root 或一个陌生 UID。先查当前用户：id -u和id -g，把结果填进 compose。不要图省事用 root 跑，后面文件全变成 root 属主，普通用户改不动，备份也麻烦。

权限计算要落到 umask。UMASK=002的含义是：普通文件默认 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 模式省掉端口映射，但会把服务暴露在宿主机所有网卡上，取舍要看环境。

时区用TZ=Etc/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: - PUID=1000 - PGID=1000 - UMASK=002 - TZ=Etc/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 --tail=100 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 权限、路径、标签匹配问题速查表

出问题先别猜，按“容器状态、日志、路径、权限、标签”的顺序查。下面这张表是我实际遇到频率比较高的几类，命令可以在宿主机执行，也可以在容器里执行，注意路径对应关系。

排查时有一个小技巧：先在容器里看路径，再在宿主机看同一个路径。容器里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 文件的目录旁边，每次加新容器先对一遍。音乐库首轮用复制，确认稳定后再清理源目录；配置每周备份一次，升级前额外备份一次；日志只保留最近一段，排错时再看详细级别。这套做法不花哨，但能让你在几个月后回来改东西时，不用靠记忆猜当时为什么这么配。