Jellyfin 媒体服务器部署完全指南Docker 一条主线 3 个高频坑位30 分钟跑通【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin想搭一台免费的私人媒体服务器这篇 Jellyfin 部署教程只走一条主线Docker 容器化外加首次配置与三个高频坑的修复法普通用户 30 分钟可上线。30 秒认识 JellyfinJellyfin 是一个完全免费、开源的媒体服务器把你硬盘里的电影、剧集、音乐、照片整理成可搜索、可多端播放的库数据始终留在自己的机器上。功能全部开放无广告、无会员墙转码、硬件加速都是默认能力多端覆盖Web 管理台 手机/电视客户端多用户各自有进度和偏好播放灵活局域网内尽量直连播放带宽不够时自动转码兜底元数据自动化首扫时自动抓取海报、简介、演员信息可备份可迁移配置、用户、媒体库元数据支持打包成单个归档选对部署姿势先决策再动手。四种路径的差异一眼看完部署方式适合谁上手成本自由度安装包家用电脑、想即装即用的人最低装完即运行低按官方默认布局跑Docker 容器有服务器或 NAS、以后可能迁移的人低4 条命令中挂载卷与镜像版本自己控制源码编译开发者、想读代码或二次开发的人高装 SDK 编译最高可以改到代码层NAS/虚拟机镜像群晖、TrueNAS 或 homelab 玩家中导入镜像中受宿主机生态约束本文主线选Docker隔离干净、迁移就是搬三个目录也是大多数人的最终形态。手把手部署实战 容器化部署四步走第 1 步装好 Docker 并让它自启。sudo apt install docker.io sudo systemctl enable --now docker装完docker --version能出版本号就算就绪。第 2 步建三个目录分别放配置、缓存、媒体文件sudo mkdir -p /opt/jellyfin/config /opt/jellyfin/cache /srv/media/srv/media换成你实际放片子的路径即可。第 3 步启动容器。一行命令逐个看挂载点docker run -d \ --name jellyfin \ --restartunless-stopped \ -p 8096:8096 \ -v /opt/jellyfin/config:/config \ -v /opt/jellyfin/cache:/cache \ -v /srv/media:/media \ jellyfin/jellyfin-p 8096:8096是服务端口Jellyfin 默认 HTTP 端口就是 8096三个-v分别对应容器内固定的/config、/cache、/media第 4 步验证容器活着。docker ps看到jellyfin状态为Up后浏览器打开http://服务器IP:8096能进欢迎页即部署成功。另外三条路各一句要点安装包路线家用机最快sudo apt install jellyfin # Ubuntu/Debian sudo dnf install jellyfin # CentOS/RHEL装完服务即随系统自启用sudo systemctl restart jellyfin重启Windows 上则是net stop jellyfin/net start jellyfin。源码编译路线开发者向global.json 声明项目使用 .NET 10 SDK先装git、dotnet-sdk-10.0和ffmpeg然后git clone https://gitcode.com/GitHub_Trending/je/jellyfin cd jellyfin dotnet build dotnet run --project Jellyfin.Server编译通过后dotnet run直接起服务调试时可以加--configdir等参数把配置指到别处。NAS/虚拟机路线进阶在群晖 Container Manager、TrueNAS 或 PVE 里导入 Jellyfin 官方镜像映射同样的三个卷和 8096 端口后续操作与 Docker 完全一致。常用启动参数速查不管是哪条路线服务都认同一组命令行参数定义见 StartupOptions.cs参数作用--configdir配置目录用户设置、图片、network.xml 都在这里--datadir数据目录数据库文件等--cachedir缓存目录放 SSD 上转码更顺--logdir日志目录--webdirWeb 客户端资源目录--ffmpeg指定自定义 FFmpeg 可执行文件--restore-archive启动时从备份归档恢复见下文备份节第一次点进去该做什么Jellyfin 首次配置按操作顺序走四步全程点鼠标创建管理员账户欢迎页上设置用户名和密码这个账号是后面所有管理操作的入口。过一遍初始设置选择界面语言、元数据语言选中文即可、时区不确定的直接跳过日后再改。添加媒体库控制台 → 媒体库 → 新建选类型电影/电视剧/音乐/照片/书籍/家庭视频然后挑目录。目录结构建议先整理成两种最规范的形态识别率最高Movies/ 星际穿越 (2014).mkv TV/ 熊家餐馆/ 第 01 季/ 熊家餐馆 S01E01.mkv验证播放随便点开一部片子用手机或网页端播放。首扫需要时间封面和简介会陆续补全播放时留意页面显示的直连播放或转码前者说明局域网直出性能最好。 想研究接口时浏览器访问http://服务器IP:8096/api-docs/swagger/index.html可以看完整的 API 文档做二次开发非常有用。踩坑急救 ⚠️以下三个是 Jellyfin 常见问题里出镜率最高的都按现象 → 三步处理 → 验证来写。端口被占用了怎么办现象服务起不来日志里出现类似Kestrel failed to start的报错提示地址或端口绑定失败。三步处理先确认谁占着端口ss -lntp | grep 8096两条路二选一Docker 用户改宿主机映射即可重建容器时写-p 8097:8096本机直装用户则编辑配置目录里的network.xml把InternalHttpPort改成空闲端口重启服务或容器验证curl -I http://localhost:新端口能返回响应头浏览器可打开欢迎页。媒体文件识别不出来怎么办现象媒体库建好了但列表是空的或只有部分文件出现。三步处理检查权限运行用户或容器用户必须对媒体目录有读权限Docker 挂载后docker exec进去ls试一下最直观检查命名电视剧解析依赖 TV 命名解析器 这套规则剧集名 S01E01.mkv这类格式最稳文件被重命名成乱码时解析会直接跳过手动触发重扫控制台 → 媒体库 → 对应库 → 刷新媒体库验证目标文件出现在库里且封面、集数信息正确。播放卡顿、转码吃力怎么办现象手机或网页端播放明显掉帧服务器 CPU 飙高。三步处理确认转码可用Docker 镜像自带 FFmpeg本机直装则确保ffmpeg在 PATH 里或用--ffmpeg指定路径开启硬件加速控制台 → 播放 → 硬件加速按你的芯片选 QSV / VAAPI / NVENC把--cachedir指到 SSD并适当调低转码质量档位验证再次播放时状态显示直连播放或转码时 CPU 占用明显回落。让媒体库更好用养成备份习惯备份覆盖的是用户、配置和媒体库元数据不含媒体文件本身升级或改库前打一份最省心。在控制台的备份页即可创建归档核心逻辑在 备份服务实现需要在新机器上整站还原时一条命令jellyfin --restore-archive /path/to/backup.zip服务会先启动、应用归档再自动重启完成后媒体库原样回来。反向代理 HTTPS 一把过 对外暴露时别裸奔 HTTP。用 nginx 把 443 反代到本机 8096一段最小配置server { listen 443 ssl; server_name your.domain; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; location / { proxy_pass http://127.0.0.1:8096; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; # WebSocket 需要 proxy_set_header Connection upgrade; } }配完nginx -s reload客户端改用https://your.domain连接即可WebSocket 不升级头的话会话推送会断。转码与硬件加速局域网内尽量让它直连播放把转码留给弱网络场景。硬件加速开好后转码压力从 CPU 转移到显卡同一台机器可多路转码。进阶玩家可以把--cachedir、--logdir拆到不同磁盘转码临时文件进 SSD、日志进机械盘互不抢 IO。让封面和简介自己长出来首次扫描时 Jellyfin 会调用元数据插件如 OMDb自动补全海报、简介与演职员信息命名越规范、匹配越准。结语 部署只是开始——把片子按规范命名、把备份和反代配好你的私有影音库就能长期安静地跑下去。现在就去挑一个空目录把第一部电影丢进去试试。安装包Docker 容器源码编译适合家用机、只想马上用起来适合服务器/NAS、未来可能要迁移适合开发者、要读源码或改功能成本装完即用几分钟成本4 条命令约 15 分钟成本SDK 编译半小时起建议家庭场景先装它够用且省心建议生产首选迁移就是搬三个卷建议有二次开发需求再走这条路【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jellyfin 媒体服务器部署完全指南：Docker 一条主线 + 3 个高频坑位，30 分钟跑通
Jellyfin 媒体服务器部署完全指南Docker 一条主线 3 个高频坑位30 分钟跑通【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin想搭一台免费的私人媒体服务器这篇 Jellyfin 部署教程只走一条主线Docker 容器化外加首次配置与三个高频坑的修复法普通用户 30 分钟可上线。30 秒认识 JellyfinJellyfin 是一个完全免费、开源的媒体服务器把你硬盘里的电影、剧集、音乐、照片整理成可搜索、可多端播放的库数据始终留在自己的机器上。功能全部开放无广告、无会员墙转码、硬件加速都是默认能力多端覆盖Web 管理台 手机/电视客户端多用户各自有进度和偏好播放灵活局域网内尽量直连播放带宽不够时自动转码兜底元数据自动化首扫时自动抓取海报、简介、演员信息可备份可迁移配置、用户、媒体库元数据支持打包成单个归档选对部署姿势先决策再动手。四种路径的差异一眼看完部署方式适合谁上手成本自由度安装包家用电脑、想即装即用的人最低装完即运行低按官方默认布局跑Docker 容器有服务器或 NAS、以后可能迁移的人低4 条命令中挂载卷与镜像版本自己控制源码编译开发者、想读代码或二次开发的人高装 SDK 编译最高可以改到代码层NAS/虚拟机镜像群晖、TrueNAS 或 homelab 玩家中导入镜像中受宿主机生态约束本文主线选Docker隔离干净、迁移就是搬三个目录也是大多数人的最终形态。手把手部署实战 容器化部署四步走第 1 步装好 Docker 并让它自启。sudo apt install docker.io sudo systemctl enable --now docker装完docker --version能出版本号就算就绪。第 2 步建三个目录分别放配置、缓存、媒体文件sudo mkdir -p /opt/jellyfin/config /opt/jellyfin/cache /srv/media/srv/media换成你实际放片子的路径即可。第 3 步启动容器。一行命令逐个看挂载点docker run -d \ --name jellyfin \ --restartunless-stopped \ -p 8096:8096 \ -v /opt/jellyfin/config:/config \ -v /opt/jellyfin/cache:/cache \ -v /srv/media:/media \ jellyfin/jellyfin-p 8096:8096是服务端口Jellyfin 默认 HTTP 端口就是 8096三个-v分别对应容器内固定的/config、/cache、/media第 4 步验证容器活着。docker ps看到jellyfin状态为Up后浏览器打开http://服务器IP:8096能进欢迎页即部署成功。另外三条路各一句要点安装包路线家用机最快sudo apt install jellyfin # Ubuntu/Debian sudo dnf install jellyfin # CentOS/RHEL装完服务即随系统自启用sudo systemctl restart jellyfin重启Windows 上则是net stop jellyfin/net start jellyfin。源码编译路线开发者向global.json 声明项目使用 .NET 10 SDK先装git、dotnet-sdk-10.0和ffmpeg然后git clone https://gitcode.com/GitHub_Trending/je/jellyfin cd jellyfin dotnet build dotnet run --project Jellyfin.Server编译通过后dotnet run直接起服务调试时可以加--configdir等参数把配置指到别处。NAS/虚拟机路线进阶在群晖 Container Manager、TrueNAS 或 PVE 里导入 Jellyfin 官方镜像映射同样的三个卷和 8096 端口后续操作与 Docker 完全一致。常用启动参数速查不管是哪条路线服务都认同一组命令行参数定义见 StartupOptions.cs参数作用--configdir配置目录用户设置、图片、network.xml 都在这里--datadir数据目录数据库文件等--cachedir缓存目录放 SSD 上转码更顺--logdir日志目录--webdirWeb 客户端资源目录--ffmpeg指定自定义 FFmpeg 可执行文件--restore-archive启动时从备份归档恢复见下文备份节第一次点进去该做什么Jellyfin 首次配置按操作顺序走四步全程点鼠标创建管理员账户欢迎页上设置用户名和密码这个账号是后面所有管理操作的入口。过一遍初始设置选择界面语言、元数据语言选中文即可、时区不确定的直接跳过日后再改。添加媒体库控制台 → 媒体库 → 新建选类型电影/电视剧/音乐/照片/书籍/家庭视频然后挑目录。目录结构建议先整理成两种最规范的形态识别率最高Movies/ 星际穿越 (2014).mkv TV/ 熊家餐馆/ 第 01 季/ 熊家餐馆 S01E01.mkv验证播放随便点开一部片子用手机或网页端播放。首扫需要时间封面和简介会陆续补全播放时留意页面显示的直连播放或转码前者说明局域网直出性能最好。 想研究接口时浏览器访问http://服务器IP:8096/api-docs/swagger/index.html可以看完整的 API 文档做二次开发非常有用。踩坑急救 ⚠️以下三个是 Jellyfin 常见问题里出镜率最高的都按现象 → 三步处理 → 验证来写。端口被占用了怎么办现象服务起不来日志里出现类似Kestrel failed to start的报错提示地址或端口绑定失败。三步处理先确认谁占着端口ss -lntp | grep 8096两条路二选一Docker 用户改宿主机映射即可重建容器时写-p 8097:8096本机直装用户则编辑配置目录里的network.xml把InternalHttpPort改成空闲端口重启服务或容器验证curl -I http://localhost:新端口能返回响应头浏览器可打开欢迎页。媒体文件识别不出来怎么办现象媒体库建好了但列表是空的或只有部分文件出现。三步处理检查权限运行用户或容器用户必须对媒体目录有读权限Docker 挂载后docker exec进去ls试一下最直观检查命名电视剧解析依赖 TV 命名解析器 这套规则剧集名 S01E01.mkv这类格式最稳文件被重命名成乱码时解析会直接跳过手动触发重扫控制台 → 媒体库 → 对应库 → 刷新媒体库验证目标文件出现在库里且封面、集数信息正确。播放卡顿、转码吃力怎么办现象手机或网页端播放明显掉帧服务器 CPU 飙高。三步处理确认转码可用Docker 镜像自带 FFmpeg本机直装则确保ffmpeg在 PATH 里或用--ffmpeg指定路径开启硬件加速控制台 → 播放 → 硬件加速按你的芯片选 QSV / VAAPI / NVENC把--cachedir指到 SSD并适当调低转码质量档位验证再次播放时状态显示直连播放或转码时 CPU 占用明显回落。让媒体库更好用养成备份习惯备份覆盖的是用户、配置和媒体库元数据不含媒体文件本身升级或改库前打一份最省心。在控制台的备份页即可创建归档核心逻辑在 备份服务实现需要在新机器上整站还原时一条命令jellyfin --restore-archive /path/to/backup.zip服务会先启动、应用归档再自动重启完成后媒体库原样回来。反向代理 HTTPS 一把过 对外暴露时别裸奔 HTTP。用 nginx 把 443 反代到本机 8096一段最小配置server { listen 443 ssl; server_name your.domain; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; location / { proxy_pass http://127.0.0.1:8096; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; # WebSocket 需要 proxy_set_header Connection upgrade; } }配完nginx -s reload客户端改用https://your.domain连接即可WebSocket 不升级头的话会话推送会断。转码与硬件加速局域网内尽量让它直连播放把转码留给弱网络场景。硬件加速开好后转码压力从 CPU 转移到显卡同一台机器可多路转码。进阶玩家可以把--cachedir、--logdir拆到不同磁盘转码临时文件进 SSD、日志进机械盘互不抢 IO。让封面和简介自己长出来首次扫描时 Jellyfin 会调用元数据插件如 OMDb自动补全海报、简介与演职员信息命名越规范、匹配越准。结语 部署只是开始——把片子按规范命名、把备份和反代配好你的私有影音库就能长期安静地跑下去。现在就去挑一个空目录把第一部电影丢进去试试。安装包Docker 容器源码编译适合家用机、只想马上用起来适合服务器/NAS、未来可能要迁移适合开发者、要读源码或改功能成本装完即用几分钟成本4 条命令约 15 分钟成本SDK 编译半小时起建议家庭场景先装它够用且省心建议生产首选迁移就是搬三个卷建议有二次开发需求再走这条路【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考