Emby 这套媒体服务器我在不同硬件上来回折腾过十来次从早年裸机编译安装到后来全量容器化踩过的坑基本能凑成一本小册子。Docker 搭建 Emby 这件事听起来就三行命令但真正决定你用起来顺不顺手的是镜像版本怎么选、目录怎么挂、权限怎么给、硬件转码怎么通这几件事。这篇就把我自己的完整落地方案摊开讲从一台干净的系统开始到媒体库正常刮削、手机和电视端流畅播放、后期升级不炸库。适合手里有闲置迷你主机、家用服务器或者就是想在一台普通电脑上先跑起来看看效果的朋友也适合已经装过但卡在转码或者权限问题上的老哥对照着排查一遍。下面所有配置都是我自己在用的参数含义和取舍理由会一并说清楚你照着改改路径就能直接跑。1. 先把整体思路捋清楚为什么值得用容器跑1.1 裸机安装的三个现实痛点早几年我习惯直接下二进制包或者用系统的包管理器装 Emby那时候觉得容器是多余的一层。直到有一次系统滚挂了、重装之后发现 Emby 的数据库和元数据全在/var/lib/emby里跟着根分区一起没了几千部片子的观看记录、手动修正过的封面、自定义的合集全部重来一遍那才叫真的疼。裸机安装的问题集中在这几块一是文件散落程序、配置、缓存、日志分别躺在四五个不同目录备份的时候很容易漏二是依赖冲突Emby 依赖特定的运行库版本某些系统上装完别的软件之后它反而起不来了三是升级不可逆大版本迭代会做数据库结构迁移一旦迁移完想退回旧版基本只能靠备份。这三点加起来就足够让人转向容器了。容器化的核心价值不是轻量而是把运行时和状态彻底分开。镜像里只有程序本身所有会变的东西全部通过挂载点落在宿主机上。这样你要换机器把目录拷过去、compose 文件改个路径就完事要升级拉新镜像重建容器要回滚把备份的目录换回来即可。1.2 容器化之后的数据流向理解数据流向是配好这套东西的前提很多人挂载配错就是因为没想明白谁读写谁。跑起来之后Emby 容器内部大致是这样分工的/config配置文件、SQLite 数据库、元数据、插件、日志全在这里。这是唯一必须持久化且必须可写的目录丢了等于重新开始。/mnt/...媒体文件挂载点。这层建议只读挂载避免 Emby 在刮削或者整理时意外改动你的原始文件。/cache或转码临时目录转码过程中的分片文件。放机械盘会明显拖慢起播速度放内存盘或者 SSD 上体验差别很大。/dev/dri硬件转码用的设备节点只有在需要核显或独显转码时才映射。有一件事必须说清楚Emby 的元数据和图片默认不写在媒体目录里而是存在/config/metadata下。这意味着即使你把媒体库设成只读刮削和封面也完全正常。这一点跟某些媒体管理器不一样别被网上老教程带偏了为了写元数据把媒体库开成读写反而增加了误删风险。1.3 镜像选择官方、稳定版还是测试版Emby 官方在容器仓库里维护了几个标签常见的有latest、beta以及带版本号的固定标签。我的建议很直接生产环境用固定版本号别用 latest。理由很简单latest是浮动的某天你执行一次docker compose pull顺手重建可能就跨了一个大版本。跨版本升级会触发数据库结构迁移而迁移是单向的降级要么重装要么恢复备份。用固定标签比如4.x.x这类具体版本升级变成一个有意识的操作而不是一次意外的惊喜。至于beta我个人的态度是除非你在追某个新特性比如新编解码格式的支持、新的转码策略否则别碰。测试版的问题往往不是崩溃而是某些边缘场景下行为不一致比如某些格式的直通判断出错、扫描卡在某个文件上排查起来很费时间。另外有一种说法是官方镜像体积大所以用第三方精简版我不太推荐。精简版通常砍掉了转码依赖或者字体字幕渲染、图片处理这些功能可能出问题而这些问题在日志里表现得很隐晦。镜像大几百兆硬盘不值这个钱。2. 环境准备硬件、系统与存储怎么规划2.1 硬件门槛和实际体验对照Emby 对硬件的要求是分层的只看能不能跑没意义得看要跑什么。我把常见场景和我的实测感受列一下你可以对照自己的设备使用场景CPU 参考内存转码需求实际体验单路直连播放1080p 本地任意双核2GB无流畅内存占用 300MB 左右多路同时播放局域网四核4GB部分需要无转码时很稳转码看核显4K 原盘直通局域网千兆四核以上4GB无受网络和客户端解码能力限制4K 转码 多用户带核显的六核以上8GB必须硬解硬解下 2 至 3 路可行软解直接跪大量刮削、生成缩略图四核4GB无CPU 短时拉满建议错峰跑内存这块有个容易忽略的点Emby 在扫描媒体库、生成缩略图和章节图时会吃内存和 CPU8GB 起步会比较从容。我见过 2GB 内存的机器在初次扫描几万文件时被 OOM 杀掉容器日志里只有一个Killed很容易误判成镜像问题。2.2 系统与 Docker 环境的准备系统我一般选长期支持版本的 Linux 发行版桌面版和服务器版都行服务器版更省资源。装好系统之后第一件事是更新一遍然后装 Docker 和 compose 插件。以下命令在不同发行版上细节略有差异主流发行版的官方仓库里都能直接装到# 确认内核和 cgroup 状态容器能跑起来的前提 uname -r docker info | grep -i cgroup # 安装后校验版本compose 建议用 v2 插件形式 docker --version docker compose version注意如果你的系统上docker compose带空格报错找不到命令说明装的是老的docker-compose独立二进制。两种写法配置语法基本兼容但 v2 插件在依赖顺序和日志输出上更清晰建议升级。装完之后做两件事一是把日常使用的账号加入docker组省得每条命令都加 sudo二是配置镜像加速或者至少确认拉取速度正常。第二点很实际镜像拉一半卡住再重试容易出现层校验失败。2.3 存储规划三个目录必须分开这是我在多次重装之后总结出来的最重要的一条经验配置、缓存、媒体一定要分开放。配置目录放在系统盘或者一块单独的 SSD 上容量需求不大几百 MB 到几 GB但要求随机读写快因为数据库操作频繁。缓存与转码目录优先 SSD有条件直接挂 tmpfs 到内存。转码会产生大量小文件读写放机械盘会导致起播延迟明显尤其是拖动进度条时那种卡两秒才动的体验。媒体目录容量大、顺序读为主机械盘完全够用多盘可以组阵列或者用合并文件系统。我自己的目录结构长这样你可以照着改路径/opt/emby/ ├── config/ # 配置与数据库必须可写 ├── cache/ # 转码与图片缓存 /data/media/ ├── movies/ ├── tvshows/ └── music/有个细节值得说不要把 config 目录放在网络存储或者某些同步盘的挂载点上。SQLite 在网络文件系统上的锁机制不可靠轻则打开缓慢重则数据库损坏。这个坑我替你们踩过了恢复过程相当折腾。2.4 UID 与 GID权限问题的根源容器里的 Emby 进程是以某个用户身份跑的这个身份由环境变量UID和GID指定。如果它跟宿主机上媒体文件的所有者对不上就会出现媒体库扫描不到文件能看到文件名但播放失败这类问题。查一下当前用户和媒体目录的归属id ls -ldn /data/media /data/media/movies输出的第三列和第四列就是 UID 和 GID通常是1000:1000。如果媒体目录属于另一个用户要么把 Emby 的 UID/GID 改成那个值要么把媒体目录的所有权改过来。我倾向于改 Emby 的 UID/GID 去适配文件因为动媒体目录的权限风险更大一不小心递归改错其他服务也跟着出问题。如果要用硬件转码还需要把渲染设备组加进去。先看设备节点的属组ls -l /dev/dri # 典型输出crw-rw---- 1 root render 226, 0 ... card0 # crw-rw---- 1 root render 226, 128 ... renderD128这里的组是render用getent group render拿到它的 GID常见是 104 或 109然后通过GIDLIST环境变量追加给容器。3. 编排文件逐行拆解一份能直接用的 compose3.1 完整配置与参数说明我习惯用 compose 而不是一长串docker run原因很朴素配置文件在半年后回来改一个参数不用翻历史命令。下面是我当前在用的版本做了简化关键项都保留了services: emby: image: emby/embyserver:4.8.11.0 container_name: emby restart: unless-stopped network_mode: host environment: - UID1000 - GID1000 - GIDLIST1000,104 - TZAsia/Shanghai volumes: - /opt/emby/config:/config - /opt/emby/cache:/cache - /data/media:/mnt/media:ro devices: - /dev/dri:/dev/dri逐项说清楚image固定到具体小版本。升级时我改这一行其他不动。restart: unless-stopped开机自启手动停了不会自动拉起。比always更符合我的习惯维护时停掉不会自己蹦回来。network_mode: host直接使用宿主机网络。好处是客户端自动发现UDP 广播能正常工作省掉端口映射的一堆麻烦。代价是端口独占如果宿主机上已经有服务占了 8096会起不来。GIDLIST逗号分隔的附加组把render组的 GID 加进去硬件转码才认得到设备。TZ时区。不设的话日志时间对不上EPG 类功能也会错乱。媒体目录的:ro只读挂载。前面说过 Emby 的元数据不写这里所以只读完全不影响功能反而是一道保险。3.2 关于网络模式的一个取舍host模式和bridge模式的差别很多人只是照抄没想过为什么。简单讲模式优点缺点适合谁host自动发现可用、少一层 NAT、吞吐略高端口独占、隔离性弱单机专用、要局域网自动发现bridge端口明确、隔离好、便于反代需手动映射、UDP 发现麻烦多服务共存、有反向代理我选 host 是因为这台机器就干这一件事而且客厅电视和手机靠自动发现找服务器确实方便。如果你这台机器上还跑着别的服务或者习惯用反向代理统一入口那就用 bridge把network_mode那行换成ports: - 8096:8096 - 8920:8920 - 7359:7359/udp - 1900:1900/udp四个端口的用途分别是HTTP 主界面、HTTPS、客户端自动发现、DLNA 发现。后面两个不写的话电视端的自动搜索会找不到服务器得手动输地址。3.3 硬件转码的设备映射细节devices那行把整个/dev/dri目录映射进去容器内就能看到card0和renderD128。Intel 核显和 AMD 核显走这条路NVIDIA 独显需要额外装运行时配置会复杂不少我一般建议先用核显跑绝大多数家用场景够用。启动后进容器验证一下驱动是否正常docker exec -it emby ls -l /dev/dri docker exec -it emby vainfo 21 | head -20vainfo能列出支持的 profile 就说明驱动栈通了。如果报Cannot connect to X server或者找不到设备通常是设备没映射或者 GID 没加对。提示镜像里不一定自带vainfo如果命令不存在不用慌可以直接在 Emby 后台的转码设置页看有没有硬件加速选项有就说明识别到了。3.4 启动与第一轮验证cd /opt/emby docker compose up -d docker compose logs -f --tail50日志里看到服务开始监听就差不多了。浏览器打开http://宿主机IP:8096应该能看到初始化向导。如果打不开按这个顺序排查容器是否在运行docker ps→ 端口是否被占ss -lntp | grep 8096→ 防火墙是否放行 → 日志里有没有启动失败的堆栈。4. 首次配置与媒体库组织4.1 初始化向导里几个容易选错的地方向导本身不复杂但有三个地方值得停下来想一想。第一是语言和元数据语言。界面语言选中文没问题但元数据语言建议同时勾上中文和英文。只选中文的话冷门片子的简介和封面会抓不到因为元数据源里中文条目覆盖不全。我的做法是首选中文、备用英文刮削失败时手动改。第二是允许远程访问这个开关。它只影响是否接受非局域网来源的请求跟具体怎么连没关系。家用场景下如果只在内网用关掉更省心如果要从外面连回来再打开。这个开关的措辞容易让人误会成开了就能从外面访问实际上还涉及网络路径的问题后面单独说。第三是自动更新。容器部署的场景下强烈建议关掉自动更新。因为容器里的程序更新之后容器一重启就回到镜像里的版本等于白更还可能留下版本不一致的状态。更新统一走拉新镜像 重建容器这条路。4.2 媒体库命名规范刮削成功率的高低八成取决于命名。Emby 的识别规则其实挺宽容但有几个原则遵守了能省掉大量手动修正电影片名 (年份)/片名 (年份).mkv。年份带括号是强信号能大幅降低同名误判。剧集剧名 (年份)/Season 01/剧名 S01E01.mkv。季目录和SxxExx标记缺一不可只写中文第一集基本抓不到。多版本同一部片子的不同版本放在同一目录文件名加后缀区分Emby 会识别成一个条目的多个版本而不是两个重复项。音乐艺术家/专辑/曲目号 - 曲名.flac标签信息比文件名更重要建议先把 ID3 标签整理干净。我见过最常见的问题是剧集被识别成一堆散装电影基本都是缺季目录或者用了01.mp4这种纯数字命名。改个名重新扫描就好不用重装。4.3 扫描策略与性能控制媒体库添加好之后第一次扫描是最耗资源的环节。几万个文件的情况下CPU 和磁盘 IO 会持续跑很久。几个可以调的开关实时监控开启后文件变动会立刻触发更新很方便。但如果你有下载工具在往媒体目录里持续写文件频繁触发会让服务一直在忙。我的做法是开启监控但限制监控范围只监控已整理完成的目录。缩略图生成这是最耗 CPU 的功能。开启之后每个视频都会抽帧生成预览图好处是拖动进度条时能看到画面。建议设成仅在闲时生成或者干脆关掉需要时再手动对特定库开启。章节图片跟缩略图类似耗 CPU 但体验好。我一般在低峰期跑比如设定在凌晨时段执行扫描任务。实操心得初次扫描建议先在设置里把缩略图关掉等媒体库识别稳定、元数据都抓好了再单独开启缩略图任务。一次性全开的话扫描进度条会慢到让你怀疑是不是卡死了。4.4 客户端连接的实际测试方式配完之后别只在浏览器里看真实体验得用客厅设备测。我通常按这个顺序验证浏览器网页版确认服务正常→ 手机 App 局域网连接确认发现和播放→ 电视端确认解码和遥控操作→ 强制转码确认硬件加速生效。强制转码的方法是播放时进播放设置把码率限制到一个明显低于源文件的数值比如 4K 原片限制到 1080p 8Mbps。然后回后台看正在播放面板如果显示Transcoding并且 CPU 占用不高说明硬解生效了如果 CPU 单核跑满那就是在软解需要回去查设备映射。5. 远程访问与反向代理的正确姿势5.1 先想清楚需求再动手远程访问这块我见过太多人一上来就折腾复杂方案最后连不上还找不到原因。先分清楚三种情况只在家里用同一个局域网什么都不用配开箱即用。偶尔在外面看能接受手动连用点对点的方式连回家里的网络配置最简单。长期在外面用希望像本地一样需要公网入口、域名、证书配置量最大。三种方案的复杂度和维护成本差一个数量级。我的建议是先用最简单的方案跑通确认体验能满足需求再决定要不要上更复杂的。5.2 反向代理的关键配置项如果要做反代Nginx 的配置里有几个点必须写对否则会出现能打开首页但播放卡住上传字幕失败WebSocket 连不上这类奇怪问题server { listen 443 ssl; server_name your-domain.example; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:8096; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_buffering off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }几个参数的用意Upgrade和Connection两行是为了 WebSocketEmby 的实时状态推送和遥控功能依赖它不写的话页面能开但功能不正常。proxy_buffering off是为了让媒体流直接透传开着缓冲会导致起播慢、拖动迟钝。超时设长是因为长视频播放的连接可能持续几个小时默认 60 秒会被掐断。client_max_body_size关系到上传字幕、图片和日志默认 1MB 太小。5.3 一个常被忽略的证书问题反代上 HTTPS 之后Emby 自己的设置里有个安全连接模式的选项。如果反代已经终结了 TLS这里要选对否则会出现重定向死循环或者客户端连不上。判断方法很简单先在局域网用 HTTP 直连确认服务正常再通过反代访问如果只有反代路径出问题基本就是这个设置或者请求头透传的问题。另外混用 HTTP 和 HTTPS 会导致浏览器报混合内容错误表现为页面布局错乱但功能能用。统一走一个协议能省掉这类诡异现象。6. 运维实操备份、升级与故障排查6.1 备份策略只备一个目录就够前面反复强调过所有状态都在/config。所以备份逻辑非常简单粗暴# 最稳妥的做法先停容器再打包避免 SQLite 写入中途被截断 docker compose stop emby tar -czf /backup/emby-config-$(date %F).tar.gz -C /opt/emby config docker compose start emby停容器这一步别省。SQLite 在写入过程中被直接复制有很大概率拿到一个损坏的副本恢复的时候打开就报错那时候再想找旧备份就晚了。整个包一般不大如果需要更频繁的备份可以只备数据库文件同样要先停。媒体文件本身不用纳入这个备份范围那是另一个层面的数据保护问题。真正值钱的是你花时间整理的元数据、观看记录、用户设置。6.2 升级流程与回滚预案我的升级流程固定成四步一步都不跳# 1. 备份 docker compose stop emby tar -czf /backup/emby-pre-upgrade.tar.gz -C /opt/emby config # 2. 改版本号编辑 compose 文件里的 image 标签 # 3. 拉取并重建 docker compose pull docker compose up -d # 4. 观察日志与功能 docker compose logs -f --tail100回滚就是把旧镜像标签改回去、把备份的 config 解压覆盖。所以升级前的备份是唯一的安全网尤其跨越次版本号的时候数据库结构迁移不可逆。注意不要在做完备份之后、升级之前又去改配置或者加媒体库。这样备份就过期了回滚会丢掉这些改动。养成备份后立刻升级的习惯。6.3 常见问题速查表下面这些是我这几年实际遇到过、并且被问得最多的问题按现象归类现象可能原因排查与解决媒体库扫描不到文件挂载路径写错 / 权限不足进容器ls /mnt/media看是否可见检查 UID/GID 与文件属主能看到文件但播放报错只读挂载导致元数据写入失败少见/ 文件损坏看日志具体报错确认元数据目录可写转码时 CPU 单核跑满硬件加速未生效检查/dev/dri映射与GIDLIST后台转码设置选对应硬解起播慢、拖动卡顿转码缓存目录在机械盘 / 反代开了缓冲缓存移到 SSD反代加proxy_buffering off页面能打开但遥控失效WebSocket 未透传反代补Upgrade与Connection头日志时间不对时区未设置补TZ环境变量后重建容器容器反复重启端口被占 / 配置目录权限错docker compose logs看首行错误ss -lntp查端口字幕显示为方块字体缺失挂载字体目录或换用图片字幕扫描中途容器被杀内存不足查看系统日志是否有 OOM加大内存或分批扫描数据库打开报错备份时未停容器 / 放在网络存储用停机备份恢复config 迁到本地盘6.4 几个真正省时间的独家习惯说几条不太出现在文档里、但确实能省事的做法。第一给容器加资源限制。尤其是内存。Emby 在扫描高峰期内存会冲高如果不设上限可能把整台机器拖垮。在 compose 里加mem_limit或者在部署层面设 cgroup 限制宁可让它自己重启也别让整机失去响应。第二把日志目录单独看一下。出问题的时候/config/logs里的日志比docker logs详细得多包含转码命令的完整参数。转码失败时把那行命令复制出来手动跑一遍报错信息会非常明确比在后台猜快十倍。第三媒体目录用只读挂载之后别忘了下载工具还在往里写。只读是针对容器的宿主机上的写入不受影响。但如果你用的是实时监控新文件落盘会立刻触发扫描此时文件还没写完可能出现识别成损坏文件的情况。解决办法是让下载工具先写到临时目录整理完成后再移动到媒体库目录。第四定期看一眼数据库大小。/config/data下的数据库文件如果膨胀到几个 GB通常是缩略图或者播放记录累积太多。可以定期清理播放历史、重建索引速度会明显回升。这个操作不可逆做之前记得备份。第五别迷信一次配好永久稳定。系统的内核更新、Docker 版本更新、驱动更新都可能影响硬件转码。我的习惯是每次系统大更新之后,专门跑一遍转码测试确认/dev/dri还在、硬解还生效。这事儿花两分钟能避免某天想看片的时候发现卡成幻灯片。最后分享一个我自己用着很顺的小技巧在 compose 文件旁边放一个README记事本写下这台机器的 UID/GID、render组 GID、镜像版本、备份路径和上次升级日期。半年后回来维护不用重新查一遍系统信息直接照着记事本改就行。这套东西配置本身不难难的是隔了很久之后再回来还能快速上手一份几行的备忘能省掉大量回忆成本。
