Docker 部署与版本升级

Docker 部署与版本升级

Emby 的部署途径主要有两条：官方安装包与 Docker 容器。对大多数自建用户来说，Docker 是更被推荐的那条——环境隔离、升级回滚方便、迁移到新机器只需搬配置目录。这一篇以 emby/embyserver 镜像为主线，讲清楚部署、卷映射、权限与升级四个环节，并说明什么样的情况适合用安装包绕开容器。

为什么选 Docker

在动手之前先确认 Docker 是否真的适合你。对比两种部署方式：

维度	Docker 部署	官方安装包
环境隔离	容器内独立	与系统共享
升级方式	换镜像标签	覆盖安装新版本
回滚能力	切回旧标签即可	需要备份覆盖
迁移成本	搬配置目录	重装并迁移目录
硬件转码支持	需映射设备节点	天然可访问
适用平台	任意支持 Docker 的系统	部分发行版有限制

Docker 的优势集中在长期维护：升级是替换镜像，配置目录在容器外，服务出问题可以整套删掉重建而数据不丢。代价是多一层抽象，硬件转码需要显式把显卡设备映射进容器，初学者容易在这里卡住。群晖用户可以直接用套件中心的容器管理界面，配合《群晖 DSM 系统指南》理解容器与目录映射的操作方式。

如果你只有一台 Windows 机器、只想跑起来试试，官方安装包的体验更直接；一旦你打算把 Emby 作为长期服务运行，Docker 基本是标准答案。官方安装包还覆盖了极少数没有 Docker 环境的平台，比如某些老旧 NAS 直接提供了 Emby 套件，这类平台上套件反而比容器省心。

部署前准备

部署前需要确认三件事：宿主机上的媒体目录路径、配置目录位置、容器运行用户。前两个决定数据落在哪，第三个决定容器能不能正确读写这些目录。

媒体目录通常已经就绪，指向你存放电影、剧集、音乐的顶层目录即可。配置目录建议单独放在一块稳定存储上，它包含数据库、刮削缓存与用户配置，体积会随使用增长，几十 GB 的余量是必要的。运行用户方面，容器默认以 root 运行，这在权限宽松的宿主机上没问题；如果媒体目录属于某个特定用户，需要让容器内进程身份与之匹配，否则会大面积出现扫描不进文件的权限错误。

准备阶段最容易省掉的一步是路径核对。写卷映射时把宿主机的绝对路径敲错一个字母，容器照样能启动，但要么挂载到空目录导致全库扫描为空，要么悄悄创建了新目录而你以为已经挂载成功。命令执行后到宿主机上 ls 一下挂载点、确认媒体文件真的出现在容器里看到的路径下，这十秒钟能省掉后面一整个晚上的排查。同理，初次部署完成后把 /config 的访问权限与宿主机目录所有者一起确认一遍，权限模型在第一次扫描前理顺，后面几乎不会再需要动它。

对应的检查清单：

检查项	通过标准
媒体目录存在且可读	宿主机可列出文件
配置目录规划好独立位置	不与系统盘共用
宿主机 Docker 服务正常	拉取镜像不报错
宿主机显卡节点存在	QuickSync 或 NVENC 可用
端口与宿主机其他服务无冲突	8096 与 8920 空闲

这里出现的端口号后面会反复用到：8096 是 Emby 的 HTTP 端口，8920 是 HTTPS 端口。如果宿主机上同时跑了其他媒体服务，记得先确认这两个端口没被占用。

用 docker run 部署

下面是一条最小可用的部署命令，以 Intel 核显转码场景为例：

docker run -d \
  --name emby \
  --restart unless-stopped \
  -p 8096:8096 \
  -p 8920:8920 \
  -v /srv/emby/config:/config \
  -v /srv/media:/media \
  --device /dev/dri:/dev/dri \
  emby/embyserver:latest

几个参数的解释。端口映射把容器内服务暴露到宿主机，左侧是宿主机端口、右侧是容器内端口。卷映射把宿主机目录挂进容器，/config 是服务端配置与数据库，/media 是媒体库根目录，容器内对这两个路径的读写都直接落在宿主机磁盘上。--device /dev/dri 把核显设备节点映射进容器，这是 Intel QuickSync 能用的前提；NVIDIA 显卡则改为映射 /dev/nvidia0 等节点并安装容器运行时的钩子。镜像标签用 latest 会跟随最新稳定版，升级时它是最省事也最不可控的标签。

部署完成后用浏览器访问 宿主机 IP 加 8096 就能看到初始化向导，按提示完成语言、媒体库与用户设置。首次进入后建议先不要导入全部媒体，建一个小的电影库验证刮削与权限正常，再批量导入。

向导过程中会被问到是否关联在线 Emby 账户。这步可以跳过，服务器在纯局域网模式下同样能完成全部设置；只有需要通过官方中转服务做远程访问、或者要在服务端登记 Premiere 许可时才需要关联。对打算用反向代理自己解决外网访问的读者，跳过账户关联反而更干净，em-0205 会展开。

部署的常见坑

初学部署的高频问题集中在三个地方，这里提前点明。

问题	表现	解决方向
权限不匹配	媒体库为空、扫描无结果	核对容器运行用户与目录所有者
端口被占用	容器启动后立即退出	换宿主机端口或停掉冲突服务
显卡映射缺失	硬件转码开启后不可用	检查设备节点是否传入容器
时区不正确	录制时间错位	启动参数加时区变量
卷映射写错路径	升级后配置丢失	确认映射的是绝对路径

时区是容易被忽略的一项。容器默认沿用镜像内部时区，体现为 DVR 录制计划与实际时间错位、日志时间对不上。在启动参数里设置时区环境变量即可修正，具体变量名以镜像说明文档为准。

另一个常见疑问是多容器并存：Emby 与 Jellyfin 能不能同时跑？完全可以，只要端口与配置目录各自独立。这也是从 Jellyfin 迁移期推荐的做法——两边并行观察一段时间，确认 Emby 侧稳定后再做减法，em-0403 会接续这个话题。

容器日志是排查问题的第一手材料。启动后留意容器输出的前几十行日志，数据库初始化、端口绑定、显卡检测的报错都出现在这里；定期查看日志还能提前发现媒体扫描中断这类静默问题。出问题时先看日志再搜索，比直接提问省时间。

版本升级策略

Emby 的版本分稳定版与预览版两类。稳定版经过官方完整测试，预览版包含新功能但更新频繁、偶有回归。家庭长期服务建议只跟稳定版，预览版留给想提前体验特定功能的用户。

升级操作本身在 Docker 下非常轻量：

docker pull emby/embyserver:latest
docker stop emby
docker rm emby
docker run -d ... emby/embyserver:latest

关键是升级前后的保护动作。升级前停容器，把 /config 目录复制一份到别处；升级后先访问网页端确认媒体库与用户完好，再恢复对外使用。如果升级出问题，删除新容器、用备份的配置目录覆盖回来、重启旧标签镜像即可完整回滚。这就是目录外挂带来的全部收益。

升级频率上，每季度跟随一次稳定版足够。Emby 的维护版本以修复与适配为主，久不升级会遇到新客户端兼容问题，频繁升级则增加无谓的维护动作。如果开了硬件转码，升级后需要重新验证转码可用性——个别版本的驱动适配有回退过，确认方法在 em-0202。

关于镜像标签还有一点建议。生产环境不一定要用 latest 标签：把标签固定到具体的稳定版号，升级由你主动拉动，避免某次例行重启后服务被静默升级到未验证版本。家庭服务器上这个习惯能减少不少惊喜，代价只是升级时多打一条命令。

最后说说数据安全与部署的关系。配置目录里装着整个服务端的状态——媒体库结构、用户、观看记录都在其中。把配置目录放在宿主机的独立存储或至少独立分区上，配合 em-0403 的备份策略，整套系统的容灾能力就建立起来了。部署阶段把这件事放在心上，比服务跑起来后再补功课轻松得多。

Docker 部署与版本升级

Docker 部署与版本升级

为什么选 Docker

部署前准备

用 docker run 部署

部署的常见坑

版本升级策略

延伸阅读