如果你手头有一台闲置云服务器、NAS 或小主机，存了不少电影、动漫或者剧集，肯定不想每次都用文件夹裸翻播放。Jellyfin 是目前最成熟的免费开源自建影音系统，不仅能帮你自动刮削海报、演职员信息和剧情简介，还支持网页、手机、电视 TV 端全平台播放，完全没有 Plex 那套烦人的会员收费和账号绑定，是纯粹属于你自己的家庭影院。

本文基于 Jellyfin Server 12.4.0 官方镜像（jellyfin/jellyfin）在 Linux 环境实测编写（实测时间：2026-11-03）。跟着下面的步骤操作，几分钟内你就能在自己的服务器上拉起私人影视站。

成品长这样

搭建完成后，浏览器访问后台就能看到刮削整齐的海报墙，点开任意影片即可在线流畅串流播放：

Jellyfin 登录后的主页，My Media 区显示 Demo Movies 媒体库 — 图 1：登录后的主页，My Media 区已经出现建好的 Demo Movies 媒体库

准备工作

在开始敲命令前，请确认你的服务器环境满足以下几点要求：

一台 Linux 服务器：轻量纯原画推流 1 核 1G 即可流畅运行；如果后续需要服务端实时转码（如 4K 压制到 1080p），建议至少 2 核 2G 以上配置。
容器运行环境：已安装 Docker 以及 Docker Compose（现代 Docker 已原生集成 docker compose 插件命令）。
放行网络端口：在云服务器控制台安全组及系统防火墙中放行 8096 端口（TCP），这是 Jellyfin 默认的 Web 访问端口。
预留媒体目录：准备好用于存放视频文件的存储路径或挂载磁盘，后续直接映射进容器。

第一步：Docker Compose 部署

创建工作目录并编写 compose 文件：找一个规范的部署路径（例如 ~/jellyfin），新建目录并写入 docker-compose.yml：

mkdir -p ~/jellyfin && cd ~/jellyfin
cat <<'EOF' > docker-compose.yml
services:
  jellyfin:
    image: jellyfin/jellyfin:12.4
    container_name: jellyfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - ./data/config:/config
      - ./data/cache:/cache
      - ./media:/media
    environment:
      - TZ=Asia/Shanghai
EOF

配置中将核心配置文件持久化在当前目录的 ./data/config，媒体库目录挂载到 ./media，并固定指定了上海时区，避免定时任务和刮削时间错乱。

拉取镜像并启动容器：在 docker-compose.yml 所在目录下直接执行后台运行命令：
BASH
```
docker compose up -d
```
Docker 会自动拉取官方 12.4 镜像并创建容器。完成后你可以用 docker compose ps 查看容器运行状态，看到 Up 即代表容器进程已就绪。
验证服务连通性：你可以先在终端用 curl 测试本地端口是否已正常监听，或者直接用浏览器测试远程访问：
BASH
```
curl -I http://127.0.0.1:8096
```
如果接口正常返回 302 重定向到向导地址，说明服务已经顺利起跑。此时用电脑浏览器打开 http://你的服务器IP:8096，屏幕上只要出现欢迎设置向导（Welcome to Jellyfin!），第一阶段的容器部署就成功完成了。

关于数据持久化：你的所有媒体库配置、用户账号和观影进度都保存在映射出来的 ./data/config 目录里（关键是其内部的 jellyfin.db 数据库）。这是你后续所有配置的全部家当，日后即便换机器或升级镜像，只要完整带走 config 目录就能无损恢复。

第二步：走完首次设置向导

容器启动之后，你打开浏览器访问 http://服务器IP:8096，页面会自动跳转进 Jellyfin 的首次安装向导。整个过程非常轻量，跟着界面一步步点即可：

基础语言与服务器命名：第一步先选择显示语言为“Chinese (Simplified) / 简体中文”，接着给你的服务器填一个名字。这里默认会带出主机名，如果你介意暴露机器的真实 hostname，直接改成自己喜欢的名字（比如 HomeMedia），然后点“Next”。
创建管理员账号：为你的 Jellyfin 设置第一个管理员用户名与密码。

安全提示：管理员账户拥有整个影音库与底层系统设置的全部控制权，密码就是全家影音库的大门钥匙。请务必配置强口令，不要用 admin 等弱用户名长期裸奔在内网或公网上。
添加媒体库（先跳过）：向导进行到设置媒体库这一步时，先不要着急在这里加。媒体库在第三步统一进控制台慢慢配更直观，这里直接点击“Next”跳过即可。
元数据语言与远程访问：优先元数据下载语言选“Chinese”，国家选“China / 中国”；远程连接配置保持默认的允许远程访问与端口映射，最后点击“Finish”完成向导。

Jellyfin 首次启动设置向导第一步，填写服务器名并选择显示语言 — 图 2：首次启动的设置向导，先给服务器起个名字并选好显示语言

向导走完后页面会自动重定向到登录页，输入你刚才新建的管理员账号和密码登录，就能正式进入系统。

Jellyfin 登录页，输入管理员账号密码 — 图 3：向导完成后回到登录页，用刚建的管理员账号登录

第三步：建第一个媒体库

登录成功后，主页会提醒你目前还没有任何媒体库。接下来我们手动挂载第一个电影库：

点击左上角菜单栏，进入“控制台（Dashboard）”；在左侧导航栏找到“媒体库（Libraries）”，点击右侧的“添加媒体库（Add Media Library）”。
在弹出的配置面板中：
- 内容类型（Content type）：选择“Movies（电影）”。
- 显示名称（Display name）：输入 Demo Movies。
- 文件夹（Folders）：点击大加号“+”，在弹出的目录选择器顶部直接输入我们在容器内映射的绝对路径 /media/demo（演示用空目录即可）。
提示：刮削语言建议锁定在“Chinese”并勾选你需要的元数据下载器（如 TheMovieDb），刮削选项在建库时顺手配好，后续入库就全自动化了。
配置完成后滑动到最底部点击“确定”。保存后回到控制台的媒体库管理列表，你就能看到刚刚建好的 Demo Movies 媒体库卡片；同时前台主页的“My Media”区域也会同步展示出该入口。

Jellyfin 控制台媒体库管理页，已建好 Demo Movies 电影库 — 图 4：控制台的媒体库管理页，Demo Movies 已经建好

后续使用中，只要你把下载好的影片文件复制到宿主机对应的挂载目录下，在控制台的“媒体库”页面点击“扫描所有媒体库（Scan All Libraries）”，Jellyfin 就会自动触发后台刮削并抓取海报封面。

踩坑实录

1. GitHub Release 里没有安装包
很多人习惯去 GitHub Releases 页直接下 deb/tar 包，但 Jellyfin v12.4 的 Release 资产列表经常是空的。官方的服务端发布包统一放在自有分发站 repo.jellyfin.org 上。特别需要注意的是：该站点的下载链接大多带 302 重定向，如果你用 curl 下载却漏了 -L 参数，最终只会拉到一个 0 字节的空文件导致安装报错。

2. v12 的 API 鉴权头变了
如果你写了自动化初始化或健康探针脚本，老教程里常见的 X-Emby-Authorization 请求头在 v12 登录接口下会触发 request.App is null 的 500 异常。新版本对授权头规范要求更严，旧版的历史脚本不要无脑直接套，需要按 v12 的 API 格式携带 client、device、deviceId 等完整字段。

3. 向导接口有严格的状态依赖
在初始化自动化时需要注意：首次启动向导未完成之前，部分非 Startup 接口会直接返回 404；而一旦向导最后一步点击“Finish”提交，这套向导接口会立刻锁定，后续再调会直接抛 401 Unauthorized。因此如果要做自动化部署编排，严格模拟页面的向导顺序调用才是最稳的方案。

4. 转码功能强依赖 ffmpeg
Jellyfin 官方 Docker 镜像内已经预装了定制优化的 jellyfin-ffmpeg，开箱即用。但如果你是在宿主机直接跑解压版或者自编译部署，必须确保系统全局 PATH 中存在可用的 ffmpeg 与 ffprobe 二进制。否则服务端遇到需要转封装或音视频转码的客户端时，播放会直接报错中断，仅能直接播放原生兼容的码流。

升级与备份

得益于数据和配置全部做了目录映射，日常维护非常省心：

平滑升级：日常升级时，只需要打开 docker-compose.yml 修改镜像版本标签（例如改为最新版本），然后执行两行命令即可完成迁移：
BASH
```
docker compose pull && docker compose up -d
```
Jellyfin 容器在新版本启动时会自动检测现有数据，并在后台完成 SQLite 数据库与元数据结构的自动平滑迁移，无需人工导入 SQL。
数据备份与换机迁移：备份时先优雅停服 docker compose down，然后将挂载出来的 data 目录完整打包保存。你的用户权限、观看进度、海报缓存以及核心的 jellyfin.db 数据库全都在里面；同时记下当时的 media 宿主机映射路径。需要迁移到新服务器时，在新机上按原结构解压恢复该目录并执行 docker compose up -d，整个影音库就会瞬间原地满血复活。