Jellyfin 媒体服务器部署教程 | 极客的赛博空间

1. 系统要求与准备

1.1 硬件要求

CPU：建议至少 2 核，用于媒体转码时可能需要更强的性能。
内存：建议至少 2 GB。
存储：根据媒体库大小而定，同时需要预留空间用于元数据和转码缓存。

1.2 软件前提

.NET 10 SDK（用于源码运行）或 .NET 运行时（仅运行）。
FFmpeg：Jellyfin 依赖 FFmpeg 进行媒体转码和处理。
Git（如果从源码部署）。
支持的平台：Windows、Linux、macOS（不支持 FreeBSD）。

2. 安装与部署方法

Jellyfin 提供了多种安装途径，推荐大多数用户使用官方安装包或Docker。

2.1 使用官方安装包（推荐）

这是最简单、最常用的方式。

下载：访问 Jellyfin 下载页面，选择您的操作系统。
Windows：
- 下载 .exe 安装程序并运行。
- 安装后，Jellyfin 会作为 Windows 服务运行。
- 启动后，通过 http://localhost:8096 访问 Web 界面。

Linux：

Debian/Ubuntu：使用 APT 仓库。

sudo apt install curl gnupg
curl -fsSL https://repo.jellyfin.org/ubuntu/jellyfin_team.gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/jellyfin.gpg
echo "deb [arch=$( dpkg --print-architecture )] https://repo.jellyfin.org/$( awk -F'=' '/^ID=/{ print $NF }' /etc/os-release ) $( awk -F'=' '/^VERSION_CODENAME=/{ print $NF }' /etc/os-release ) main" | sudo tee /etc/apt/sources.list.d/jellyfin.list
sudo apt update
sudo apt install jellyfin

启动：sudo systemctl start jellyfin 并设置开机自启 sudo systemctl enable jellyfin。

macOS：
- 下载 .dmg 文件并安装。
- 将 Jellyfin.app 拖入 Applications 文件夹并运行。

2.2 使用 Docker（适合容器化环境）

Docker 部署非常便捷，适合隔离运行和快速迁移。

# 拉取并运行官方镜像
docker run -d \
  --name jellyfin \
  --user 1000:1000 \
  --net=host \
  -v /path/to/config:/config \
  -v /path/to/cache:/cache \
  -v /path/to/media:/media:ro \
  -v /path/to/transcodes:/transcodes \
  --restart=unless-stopped \
  jellyfin/jellyfin

端口：--net=host 直接使用宿主机网络，Web UI 默认端口 8096。
卷挂载：将配置文件、缓存、媒体库和转码目录挂载到宿主机，便于持久化。
用户ID：--user 1000:1000 需匹配宿主机用户权限，以避免文件权限问题。

2.3 从源码构建和运行（面向开发者）

如果您想运行开发版本或贡献代码，可以按以下步骤操作。

前提条件

安装 .NET 10 SDK。
安装 FFmpeg。
安装 Git。

步骤

克隆仓库：

1 2	git clone https://github.com/jellyfin/jellyfin.git cd jellyfin

获取 Web 客户端（重要）：
服务器需要 Web 界面文件。您需要从 jellyfin-web 仓库构建或获取已编译的文件。
- 选项A：从已有的 Jellyfin 安装中复制 jellyfin-web 文件夹（例如 Windows 下位于 C:\Program Files\Jellyfin\Server\jellyfin-web）。
- 选项B：从源码构建 Web 客户端（参考 jellyfin-web 仓库的 README）。

运行服务器：

1 2	# 指定 web 客户端目录路径运行 dotnet run --project Jellyfin.Server --webdir /path/to/jellyfin-web/dist

访问：浏览器打开 http://localhost:8096 进入初始设置向导。

3. 初始配置与使用

3.1 首次启动向导

通过浏览器访问 http://localhost:8096。
跟随向导设置管理员账户（用户名和密码）。
添加您的媒体库：选择包含电影、电视节目、音乐等媒体的文件夹。Jellyfin 会自动扫描并获取元数据。
设置元数据语言和首选项。

3.2 后续管理

管理员控制台：登录后点击右上角头像 > “管理”进入后台。
用户管理：创建和管理多个用户，设置访问权限。
插件：通过“插件”菜单安装和启用各种功能扩展（如刮削器、字幕插件等）。
转码设置：在“播放”设置中配置硬件加速（如果支持）和转码参数。

4. 高级配置（开发者/进阶用户）

4.1 独立托管 Web 客户端（分离前后端）

对于前端开发或特殊部署，可以分开托管 Web 客户端：

设置环境变量 JELLYFIN_NOWEBCONTENT=true 或启动参数 --nowebclient 来禁用服务器托管 Web 内容。
然后单独运行开发中的 Web 客户端指向后端 API。

4.2 使用 Visual Studio / VS Code 调试

打开解决方案文件 Jellyfin.sln。
在 Visual Studio 中按 F5 运行并调试。
在 VS Code 中安装推荐的 C# 扩展，然后按 F5 选择调试配置启动。

4.3 运行单元测试

在仓库根目录执行：

1	dotnet test

5. 常见问题排查

问题	可能原因	解决方案
无法访问 Web 界面	服务未启动或防火墙阻止	检查服务状态（`systemctl status jellyfin`），确认端口 `8096` 是否开放。
媒体文件不显示	文件夹权限不足或未正确添加媒体库	确保运行 Jellyfin 的用户（或 Docker 用户）有读取媒体文件的权限。
播放时卡顿/转码失败	FFmpeg 未安装或路径不正确	确保 FFmpeg 已安装且 `ffmpeg` 命令在系统 PATH 中。在 Jellyfin 管理后台可指定 FFmpeg 路径。
安装后初始化设置页面无法加载	Web 客户端文件缺失或未正确指定	确认启动命令中 `--webdir` 参数指向了包含 Web 客户端文件的正确文件夹。
Docker 容器中文件权限错误	映射卷的用户 ID 与宿主机不匹配	使用 `--user $(id -u):$(id -g)` 将容器用户映射到当前宿主机用户。