Jellyfin 媒体服务实战
本文采用 APT 原生安装,由 systemd 管理 Jellyfin 服务,不需要安装 Docker,也无需先完成 Docker Compose 教程。下文实测结果均来自这一安装方式。
压缩包只包含 prepare-media.sh 和素材说明。第 3 节用它下载、剪辑测试视频并生成封面;视频从 Blender 官方网站下载,不包含在文档仓库中。已有视频也可以直接使用。
1. Jellyfin 简介
Jellyfin 是开源媒体服务软件,可以把开发板上的电影、家庭视频和音乐整理成媒体库,在电脑浏览器、手机或电视客户端中访问。媒体文件、账号和播放记录保存在自己的设备上,适合搭建局域网影音库,也适合学习 Linux 服务管理与视频流媒体处理。
板端负责管理和提供媒体,客户端负责显示画面。客户端能直接播放原文件时,优先使用直放;格式不兼容或网络码率受限时,Jellyfin 调用配套 FFmpeg 转码。Rockchip 平台通过 MPP 调用视频编解码硬件,RGA 负责缩放和像素格式转换,减轻 CPU 的视频处理负担。
| 播放方式 | 板端做什么 | 如何理解 |
|---|---|---|
| 直放(Direct Play) | 发送原文件 | 无需视频转码,通常是首选方式 |
| 重封装或直接串流 | 调整封装,可能只转换音频 | 视频仍可保持原编码 |
| 转码(Transcode) | 重新编码视频,必要时缩放 | 降低质量或遇到不支持的格式时触发,可使用 RKMPP |
如需通过 Docker 部署,可先按第 7 篇 Docker Compose 实战安装 Docker 和 Compose,再使用官方 jellyfin/jellyfin 镜像,持久化 /config、/cache,挂载媒体目录并映射 8096 端口。官方容器指南提供了 Compose 示例;使用 RKMPP 硬件转码还需按 Rockchip 容器配置说明设置设备映射和访问权限。容器部署不在本文实测范围内。
2. 环境与安装
2.1 适用范围与实测环境
本方法面向 ArmSoM 的 Debian / Ubuntu ARM64 系统。RK3576、RK3588 / RK3588S 板型可参考操作,使用硬件转码时需确认镜像已提供 MPP/RGA 驱动及下表所列设备。安装命令会按当前系统选择软件源,适用于 Debian 12 和 Ubuntu 22.04;本文性能数据来自下列 CM5 实测环境。
| 项目 | 实测配置 |
|---|---|
| 板卡 | ArmSoM CM5 + CM5-IO,RK3576,2 GB 内存 |
| 系统 / 内核 | ArmSoM Debian 12 arm64,6.1.118-rk3576 |
| Jellyfin / 配套 FFmpeg | 12.4 / 8.1.3-Jellyfin(8.1.3-2-bookworm) |
| 视频设备 | /dev/mpp_service、/dev/rga、/dev/dma_heap、/dev/dri |
| 客户端 | 同一局域网的 Windows 电脑,Edge 浏览器 |
| 存储 | 安装前剩余约 24 GB;样片准备建议至少留出 2 GB |
需要带 MPP/RGA 驱动的 Rockchip BSP 内核。通用主线内核、第三方镜像和其他板型需单独验证。本文验证 SDR H.264;不据此承诺 4K、多路并发或 HDR 色调映射。RK3576 不启用本文未验证的 HDR 色调映射选项。
2.2 安装官方软件包
以下命令在板端 root 终端执行,普通用户先运行 sudo -i。板卡需联网,电脑和板卡处于同一局域网。先按 APT 软件源指南 核对时间和软件源,再安装依赖:
apt update
apt install -y ca-certificates curl gnupg unzip
添加 Jellyfin 官方源。下面自动读取发行版,ID 应为 debian 或 ubuntu,不要将 Debian 的源写进 Ubuntu 系统。
install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://repo.jellyfin.org/jellyfin_team.gpg.key \
| gpg --dearmor --yes -o /etc/apt/keyrings/jellyfin.gpg
. /etc/os-release
cat > /etc/apt/sources.list.d/jellyfin.sources <<EOF
Types: deb
URIs: https://repo.jellyfin.org/$ID
Suites: $VERSION_CODENAME
Components: main
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/jellyfin.gpg
EOF
Ubuntu 22.04 需启用 universe 以满足依赖;若未启用,先执行 apt install -y software-properties-common,再执行 add-apt-repository universe。其他衍生发行版请参考 Jellyfin 安装说明。
软件源索引报错时先按 APT 指南 处理,再继续:
apt update
apt install -y jellyfin
systemctl enable --now jellyfin
systemctl is-active jellyfin
ip -br address
看到 active 后,记下板卡的局域网 IPv4 地址。电脑浏览器打开 http://板卡IP:8096,例如 http://192.168.1.137:8096。首次启动需要等待初始化完成。
jellyfin 会安装服务、Web 页面及配套 FFmpeg。本文使用 /usr/lib/jellyfin-ffmpeg/ffmpeg,它带有 RKMPP/RGA 支持;不要将后台路径改成系统的 /usr/bin/ffmpeg。已有 Jellyfin 实例应先备份并查看官方升级路径。
3. 添加媒体并播放
3.1 准备一段测试视频
下载文章开头的压缩包,放到板端 ~/jellyfin-demo/ 后解压。也可以直接执行:
mkdir -p ~/jellyfin-demo
cd ~/jellyfin-demo
curl -fL https://docs.armsom.org/downloads/jellyfin/jellyfin-example.tar.gz \
-o jellyfin-example.tar.gz
tar -xzf jellyfin-example.tar.gz
bash prepare-media.sh
脚本下载约 557 MiB 的《Tears of Steel》原片压缩包,截取第 1~2 分钟,生成 60 秒、1920×1080、24 fps 的 H.264 + AAC MP4。原画面为 1920×800,脚本上下补黑边,不拉伸画面。首次下载和处理需要几分钟,准备阶段采用软件编码,不代表 Jellyfin 的硬件转码速度。
| 文件 | 板端路径 |
|---|---|
| 最终视频,约 20.1 MiB | /srv/jellyfin/media/tears-of-steel-1080p.mp4 |
| 封面 | /srv/jellyfin/media/tears-of-steel-1080p-poster.jpg |
| 原片 ZIP 与 MOV | /srv/jellyfin/downloads/ |
素材及截图出自 Tears of Steel(2012),© Blender Foundation,按 CC BY 3.0 使用;本文为截取、补黑边后的测试片段。项目与署名说明。
也可以跳过下载:执行 install -d -m 755 /srv/jellyfin/media,把视频复制到这个目录,并确保 jellyfin 用户可读取。不要直接将 /root 下的目录作为媒体库,普通服务账号通常无法进入。
3.2 完成向导并验证直放
Jellyfin 支持中文、English 等语言,在首次向导中选择即可。已完成设置时,可到“用户菜单 → 设置 → 显示”修改显示语言,保存后刷新页面。界面语言与媒体库的元数据语言是两个设置,不需要修改板端系统语言;英文版教程使用英文界面截图。
- 在浏览器向导中设置名称、语言,创建自己的管理员账号和密码。
- 添加媒体库,内容类型选择“家庭视频和照片”,名称填写
ArmSoM Demo,文件夹填写/srv/jellyfin/media。 - 选择元数据语言和地区;本案例只需局域网访问,可关闭远程访问,然后完成向导并登录。
完成媒体库扫描后,首页的“我的媒体”会显示 ArmSoM Demo,下方可看到最近添加的测试影片。点击媒体库卡片进入视频列表,或直接从影片封面开始播放。

- 等扫描完成,打开
tears-of-steel-1080p,点击播放。若未出现,进入控制台的媒体库页面执行“扫描所有媒体库”,再刷新页面。 - 播放器“设置 → 质量”选择“自动”,再打开“播放信息”。本例在 Edge 中应为直放;若显示转码,先查看其中的转码原因。

本教程面向可信局域网,不需要路由器端口转发。管理员密码由使用者设置,不在示例包中提供通用密码。跨网访问应另行配置 HTTPS 和访问控制。
4. RKMPP 硬件转码
4.1 让服务账号访问硬件
先检查设备是否存在,再把服务账号加入设备所属用户组,重启使其生效:
ls -l /dev/mpp_service /dev/rga /dev/dma_heap /dev/dri
usermod -aG video,render jellyfin
systemctl restart jellyfin
id jellyfin
实测镜像的 MPP、RGA 和系统 DMA heap 节点由 video 组访问,DRM render 节点由 render 组访问。id jellyfin 应包含这两个组。设备缺失或权限不同的镜像,先按 Jellyfin Rockchip 指南 核对驱动和 udev 权限,不要用全局 chmod 777 解决。
4.2 开启加速并触发转码
打开“用户菜单 → 控制台 → 播放 → 转码”,按下表设置并保存:
| 设置 | 本例取值 |
|---|---|
| 硬件加速 | Rockchip MPP(RKMPP) |
| 硬件解码格式 | 勾选 H.264;其余格式按实际验证情况开启 |
| 硬件编码 | 开启 |
| HEVC / AV1 编码、色调映射 | 本例不启用 |
| 转码节流 | 关闭,便于测量整段视频的转码处理速度 |
| FFmpeg 路径 | 保持 /usr/lib/jellyfin-ffmpeg/ffmpeg |
首次保存若出现硬件加速提示,点击“确定”使配置生效。
重新播放样片,将“设置 → 质量”改为 1.5 Mbps。其码率低于原文件,实测会触发 1080p → 720p 转码。播放信息应显示“转码”和 HLS;恢复“自动”即可重新尝试原画直放。
选好 1.5 Mbps 后,退出本次播放,再从片头重新播放样片,保持该质量设置。中途切换质量只会转码剩余部分,日志帧数和耗时会与下方的完整 1440 帧结果不同。
H.264 文件 → MPP 硬解 → RGA 缩放 → MPP H.264 编码
→ HLS 分片 → 局域网浏览器播放
4.3 确认实际使用硬件
播放信息里的“转码”不等于“硬件转码”。在板端取最近的转码日志,检查实际命令与处理结果:
LOG=$(ls -t /var/log/jellyfin/FFmpeg.Transcode-*.log | head -n 1)
grep -E 'hwaccel rkmpp|vpp_rkrga|h264_rkmpp|Lsize=' "$LOG"
本例日志包含 -hwaccel rkmpp、vpp_rkrga=w=1280:h=720,以及:
Stream #0:0 -> #0:0 (h264 (h264_rkmpp) -> h264 (h264_rkmpp))
Stream #0:1 -> #0:1 (copy)
这表示视频硬解、硬编码,音频直接复制。若没有转码日志,先确认当前播放方式不是直放。

| 实测项目 | 结果 |
|---|---|
| 样片扫描 | 识别 H.264 / AAC,1920×1080,24 fps,60 秒 |
| 自动质量 | Edge 原画直放,无视频重新编码 |
| 1.5 Mbps 质量 | RKMPP 硬解 + RGA 缩放 + RKMPP 硬编码,输出 1280×720 H.264,AAC 复制 |
| 转码处理 | 完整 1440 帧,约 506 fps,2.84 秒完成编码 |
| 浏览器播放 | 直放 573 帧 / 23.85 秒;转码播放 696 帧 / 29.01 秒,均约 24.0 fps,两个采样窗口的丢帧增量均为 0 |
| 服务重启 | 账号、媒体库和硬件加速配置保留,仍可访问与播放 |
| 停服备份 | 成功生成包含配置和数据库的压缩包,启动服务后可继续播放;未执行恢复测试 |
506 fps 是短片转码的处理速度;24.0 fps 是客户端帧计数的测量结果,不是显示器刷新率。表中丢帧是采样窗口内的增量,截图显示的是另一轮播放的累计值。测试为单路 SDR、关闭转码节流,不代表并发能力;开启节流后,提前生成足够分片时暂停编码是正常行为。
5. 数据与日常维护
5.1 文件保存在哪里
| 内容 | 默认位置 |
|---|---|
| 视频与封面 | 本文使用 /srv/jellyfin/media/ |
| 配置 | /etc/jellyfin/ |
| 数据库、账号、媒体库信息 | /var/lib/jellyfin/ |
| 转码临时分片 | /var/cache/jellyfin/transcodes/ |
| 服务与 FFmpeg 日志 | /var/log/jellyfin/ |
Jellyfin 转码生成的是临时播放分片,不会覆盖原视频,也不会自动保存一份永久转码 MP4。要制作可长期保存的视频文件,参考 Rockchip 视频编解码案例。大量影片建议放到单独的 SSD / USB 存储,挂载稳定后再添加媒体库路径,并检查服务账号的读取权限。
5.2 查看状态与备份
systemctl status jellyfin --no-pager
journalctl -u jellyfin -n 50 --no-pager
升级前停止服务并备份配置和数据库,完成后启动:
systemctl stop jellyfin
tar -C / -czf "/root/jellyfin-backup-$(date +%F-%H%M%S).tar.gz" \
etc/jellyfin var/lib/jellyfin
systemctl start jellyfin
备份文件位于 /root/,不含媒体原文件;视频需另行备份。Jellyfin 已设置为开机启动。升级应先查看 官方版本升级说明,并按 APT 指南 检查软件源,避免跨越不支持的数据库升级路径。
6. 排障与延伸
| 现象 | 优先检查 |
|---|---|
| APT 提示证书、Release 时间或源连接错误 | 按 APT 排查 校时、检查 DNS 和软件源;不要关闭签名验证 |
| 浏览器打不开 | 核对板卡 IP、systemctl is-active jellyfin、同一局域网连通性和 TCP 8096 防火墙规则 |
| 重刷后提示“服务器不匹配” | 确认 IP 对应刚重刷的板卡后,选择“仍要连接”,重新进入初始化向导;旧账号和旧媒体库不会自动恢复 |
| 文件夹为空或扫描不到视频 | 检查库路径和 jellyfin 用户权限;尝试 sudo -u jellyfin ls /srv/jellyfin/media,然后重新扫描 |
| 已开启 RKMPP,却没有转码日志 | 原画直放不需要编码;降低质量再检查日志 |
| 转码报 Permission denied 或设备初始化失败 | 检查 MPP/RGA 设备、用户组和配套 FFmpeg;添加用户组后须重启服务 |
| 换视频后转码失败或卡顿 | 核对编码格式、位深、HDR、字幕烧录、磁盘和网络负载,先用本文 SDR 样片对照 |
需要理解底层视频管线,可继续阅读 FFmpeg 安装指南和 Rockchip 视频编解码案例。容器部署、HDR、字幕烧录和多用户并发可在单路测试通过后分别验证,避免一次打开所有功能而难以定位问题。
