Jellyfin 部署完整教程：从零搭建三大平台跨平台媒体服务器
【免费下载链接】jellyfin The Free Software Media System – Server Backend & API 
项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin
周末想在手机上看 NAS 里存好的电影，文件却隔在网络上、格式还不被手机支持——这正是 Jellyfin 要解决的问题。它是一个自由开源的媒体服务器，装在家里电脑或 NAS 上，能扫描本地视频、音频与图片建立媒体库，并按各设备的播放能力自动转封装或转码。
搭起来之后能得到什么
- 家庭共享：媒体文件留在原处，只需把目录指给 Jellyfin 一次，家人各自用独立账号浏览、播放，观看进度互不干扰。
- 多端访问：浏览器、手机应用、电视端客户端连接的是同一台服务器，同一套媒体库随处可看，无需来回拷贝文件。
- 格式自适应：HEVC、MKV 等本地设备解不动的文件，由服务器端实时转码输出通用流，播放端不需要做任何预处理。
- 数据自控：库元数据、账号体系、播放记录全部落在自己的机器上，没有第三方托管，也不存在隐性费用。
部署路线怎么选：安装包、Docker 与源码对比
| 安装包 | 低 | 不想接触命令行的桌面用户 | 低，升级走安装器 |
| Docker | 中 | Linux / macOS / NAS 用户 | 低，更换镜像即可完成升级 |
| 源码编译 | 高 | 需要改代码、跑测试的开发者 | 高，每次发版需自行重新编译 |
第一次做 Jellyfin 部署，建议按环境直接选：桌面 Windows 用安装包，其余环境优先 Docker，源码编译只留给确实要动代码的场景。
Jellyfin 媒体服务器搭建的硬件参考配置：
| CPU | 双核 2.0 GHz 以上 | 四核 3.0 GHz 以上，支持硬件加速 |
| 内存 | 2 GB | 8 GB |
| 存储 | 50 GB 可用空间 | 500 GB SSD |
Jellyfin 跨平台部署：三大平台实操
Windows：安装与验证 Jellyfin 服务
准备：从 Jellyfin 官方渠道下载最新 Windows 安装包即可，ffmpeg 已随包内置，无需额外依赖。
执行：双击安装包，按向导保持默认选项走完全部步骤。安装结束时会注册一个名为 Jellyfin 的系统服务并立即启动，这一步通常不超过两分钟。
验证：打开 PowerShell，执行下面这条命令：
curl.exe -s -o NUL -w "%{http_code}" http://localhost:8096/health
预期输出为 200。若输出 000，先用 Get-Service jellyfin 看服务是否处于 Running 状态，再回到安装日志排查。
进阶：修改默认端口。当 8096 被占用时，编辑 C:\\ProgramData\\Jellyfin\\config\\system.xml，只需关注端口相关字段：
<Port value="8097" />
<HttpsPort value="8921" />
保存后在 services.msc 中重启服务即可生效。
Linux：Jellyfin 源码编译部署
准备：确认系统已安装 git 与 ffmpeg，并按仓库 global.json 中声明的版本安装对应 .NET SDK，这是编译前唯一需要核对的项。
执行：
git clone https://gitcode.com/GitHub_Trending/je/jellyfin
cd jellyfin && dotnet build
cd Jellyfin.Server/bin/Debug/net9.0
./jellyfin
首次构建会还原大量依赖，耗时稍长；终端打印出监听 0.0.0.0:8096 的地址即表示服务已就绪。
验证：另开一个终端，执行：
curl -s -o /dev/null -w "%{http_code}\\n" http://localhost:8096/health
输出 200 则编译部署成功；若连接被拒绝，回到启动终端查看报错，通常是 .NET 版本与 global.json 要求不符。
进阶：systemd 开机自启。将以下内容写入 /etc/systemd/system/jellyfin.service（二进制与数据目录按实际路径调整）：
[Unit]
Description=Jellyfin Media Server
After=network.target
[Service]
WorkingDirectory=/opt/jellyfin
ExecStart=/opt/jellyfin/jellyfin –datadir /var/jellyfin/data –cachedir /var/jellyfin/cache
Restart=on-failure
[Install]
WantedBy=multi-user.target
随后执行 sudo systemctl daemon-reload && sudo systemctl enable –now jellyfin，用 sudo systemctl status jellyfin 确认状态为 active (running) 即可。
macOS：Jellyfin Docker 部署命令
准备：安装 Docker Desktop（brew install –cask docker）并保持其运行；规划好三类目录——配置、缓存与媒体文件，例如 ~/jellyfin 与 ~/Movies。
执行：
mkdir -p ~/jellyfin/config ~/jellyfin/cache
docker run -d \\
–name jellyfin \\
–user $(id -u):$(id -g) \\
-p 8096:8096 \\
-v ~/jellyfin/config:/config \\
-v ~/jellyfin/cache:/cache \\
-v ~/Movies:/media \\
–restart=unless-stopped \\
jellyfin/jellyfin
–user 把容器内进程映射为当前系统用户的 UID，可以避免容器生成的缩略图、缓存文件出现属主混乱，macOS 上建议保留。
验证：
docker ps | grep jellyfin
curl -s -o /dev/null -w "%{http_code}\\n" http://localhost:8096/health
第一条应显示容器处于 Up 状态，第二条输出 200，至此 Jellyfin 部署完成，浏览器打开 http://localhost:8096 即可进入首跑设置。
媒体库与播放：Jellyfin 媒体库配置
界面操作：建库与转码设置
命令行：硬件加速与安全基线
开启硬件加速前，先用 ffmpeg 确认本机支持哪些硬件编码器：
ffmpeg -hide_banner -encoders | grep -i hw
输出中出现 nvenc、vaapi 或 videotoolbox，才可在界面里勾选对应选项；否则保持软件编码即可。
安全配置记住三条：
- 为每位成员建立独立账号并只授予所需权限，避免共用管理员账号；
- 在「网络」页配置 IP 白名单，服务器默认只监听内网地址，不要裸露端口；
- 需要外网访问时再启用 HTTPS 并将 HTTP 重定向过去，证书可用 Let's Encrypt 签发。
更多模块与目录说明可查阅项目 README.md。
出问题先看这里：Jellyfin 端口冲突与常见排查
| 8096 端口被占用，服务启动失败 | 其他进程占用了端口 | sudo lsof -i :8096 定位进程，改 system.xml 中 <Port value> 后重启服务 |
| 服务起不来或启动即退出 | 依赖缺失、.NET 版本不符、路径错误 | tail -n 50 /var/jellyfin/log/jellyfin.log 看日志；dotnet –info 与 ffmpeg -version 核对依赖 |
| 媒体文件扫描不到、不进库 | 文件命名不规范或服务器读不到目录 | 按「名称 (年份).ext」规范重命名；chmod -R a+r /path/to/media 补齐读权限 |
排障时优先看日志再动手改配置，多数「服务起不来」的问题都能从最后几行日志直接定位。
延伸方向
到这里，Jellyfin 跨平台部署的主体流程就走完了：选对路线、把目录与命名规范处理好，扫描完成后即可正常播放。后续可以沿三个方向继续扩展：
- 移动端客户端：在手机应用商店安装 Jellyfin 客户端并绑定服务器，出门在外也能访问同一套媒体库；
- 远程访问：结合端口转发或反向代理与 HTTPS 证书，把媒体库安全地暴露到外网；
- 插件扩展：在控制台插件页安装 OMdb 元数据等官方插件，补充封面、简介等元信息来源。
【免费下载链接】jellyfin The Free Software Media System – Server Backend & API 项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
