Jellyfin Server 源码开发指南从源码构建、运行到测试媒体服务器【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfinJellyfin 是一个自由软件媒体系统允许用户将媒体从专用服务器推送到各类终端设备。本仓库是 Jellyfin 的后端服务端代码本文基于仓库 README 与对应源码系统讲解如何搭建本地开发环境、从源码构建并运行 Jellyfin Server、理解其命令行参数体系以及执行单元测试读完即可独立跑通一次从 clone 到浏览器访问http://localhost:8096的完整开发闭环。一、仓库定位这是 Jellyfin 的哪一部分README 明确指出本仓库包含 Jellyfin 后端服务器backend server的代码它只是 Jellyfin 组织下众多子项目之一其中最重要的配套项目是独立维护的 Web 客户端jellyfin-web 仓库——Web 客户端源码并不包含在本仓库中这一点对运行和调试都有直接影响。从源码结构看整个解决方案由 Jellyfin.sln 组织核心启动项目是 Jellyfin.Server它依赖以下主要模块Jellyfin.ApiREST API 控制器、认证策略、中间件等Jellyfin.Server.Implementations数据库访问层Entity Framework Core、用户管理、事件系统、备份服务等MediaBrowser.Controller 与 Emby.Server.Implementations媒体库、会话、设备、插件等核心领域逻辑Emby.*前缀是项目继承自 Emby 3.5.2 并移植到 .NET 平台的历史命名Emby.Naming文件命名解析器负责把媒体文件名解析为剧集、专辑等结构化信息src/Jellyfin.DatabaseEF Core 实体模型。版本方面SharedVersion.cs 声明当前程序集版本为12.0.0AssemblyVersion(12.0.0)。二、开发环境准备PrerequisitesREADME 列出的前置依赖有三项均有仓库内文件佐证依赖说明仓库证据.NET 10 SDK构建项目的必需条件global.json 锁定version: 10.0.0且rollForward: latestMinor即允许使用同主版本内较新的 minor 版本IDE可选支持 .NET 开发的 Visual Studio至少 2022或 Visual Studio Codejellyfin.code-workspace 提供工作区配置ffmpeg媒体探测、转码所需README 要求单独安装 jellyfin-ffmpeg 构建MediaBrowser.MediaEncoding 封装了对 ffmpeg 的调用关于操作系统README 声明项目支持除 FreeBSD 之外的所有主流操作系统FreeBSD 尚不兼容。三、克隆仓库并准备 Web 客户端3.1 克隆仓库安装好依赖后克隆一份本地副本。README 给出的基本命令是 HTTPS 方式克隆使用你惯用的仓库镜像地址即可注意默认目录名为jellyfin后文命令依赖该命名git clone 仓库地址 jellyfinREADME 提示如果只是想从源码运行服务器直接克隆即可如果计划向项目提交代码应先 fork 出属于自己命名的仓库再克隆。3.2 获取 Web 客户端文件服务器默认会同时托管 Web 客户端静态文件并服务后端 API。由于本仓库不含客户端源码运行前必须先准备一份 Web 客户端README 给出两个选项从源码构建按照 jellyfin-web 仓库的说明自行构建从已有安装中复制预构建文件例如 Windows 服务器安装的客户端文件位于C:\Program Files\Jellyfin\Server\jellyfin-web。也可以跳过此步——README 推荐前端开发者采用「Web 客户端独立托管」模式见第六节在独立 webpack 开发服务器中运行客户端以获得更紧的开发循环。四、运行服务器4.1 使用 Visual Studio打开解决方案文件.sln按F5即可运行服务器。4.2 使用 Visual Studio Code通过Open Folder...打开仓库目录安装该工作区推荐的扩展README 强调扩展推荐分为「Workspace Recommendations」和「Other Recommendations」两类仅 Workspace Recommendations 为必需按F5启动。4.3 从命令行运行跨平台方式一使用dotnet run直接运行启动项目。假设仓库克隆在名为jellyfin的目录中README 原示例适用于所有操作系统cd jellyfin # 进入仓库目录 dotnet run --project Jellyfin.Server --webdir /absolute/path/to/jellyfin-web/dist # 运行服务器启动项目其中--webdir指向 Web 客户端资源的绝对路径。方式二先构建再直接运行可执行文件。这样便于追加命令行选项加--help可查看全部支持的选项dotnet build # 构建项目 cd Jellyfin.Server/bin/Debug/net10.0 # 进入构建输出目录然后执行构建产物Linux / macOS 上运行./jellyfinWindows 上运行jellyfin.exe。4.4 验证服务服务器默认监听http://localhost:8096与 launchSettings.json 中的applicationUrl一致若托管了 Web 客户端则直接访问该地址REST API 的 Swagger 文档位于http://localhost:8096/api-docs/swagger/index.html五、命令行参数体系README 背后的源码实现README 提到「加--help查看所有支持的命令行选项」这些选项的完整定义在 StartupOptions.cs 中由 CommandLine 库在 Program.cs 的Main入口统一解析Parser.Default.ParseArgumentsStartupOptions(args)。完整参数如下选项短格式作用--datadir-d数据目录数据库文件等--nowebclient—指示 Web 服务器不托管 Web 客户端--webdir-wJellyfin Web UI 资源路径--cachedir-C缓存目录--configdir-c配置数据目录用户设置与图片--logdir-l日志文件目录--ffmpeg—指定外部 FFmpeg 可执行文件路径替代从 PATH 中发现的默认版本--service—以无头服务方式运行--package-name—打包 Jellyfin 时使用的名称如 synology--published-server-url—通过自动发现过程发布的服务器 URL--nonetchange—指示服务器不检测网络状态变化--restore-archive—用于恢复的 Jellyfin 备份归档路径--mode—服务器启动时的操作模式几个值得深入的源码细节1.--nowebclient的生效链路。StartupOptions.ConvertToConfig() 会把NoWebClient翻译成配置键hostwebclientfalse写入 .NET 配置系统该键的常量定义在 ConfigurationExtensions.csHostWebClientKey hostwebclient默认值为true见 ConfigurationOptions.cs。Program.cs 启动时若判定需要托管客户端但--webdir指向的目录不存在或为空会记录错误日志并直接退出退出码 1日志中会提示改用--nowebclient或在配置中设置hostwebclientfalse——这与 README 中「运行前必须先获取 Web 客户端」的要求相互印证。2. 环境变量等价物。服务器以JELLYFIN_前缀读取环境变量Program.cs 中AddEnvironmentVariables(JELLYFIN_)因此 README 中「--nowebclient等价于环境变量JELLYFIN_NOWEBCONTENTtrue」的说法本质就是该前缀约定。从 StartupHelpers.cs 还可以看到各目录项的命令行选项优先于对应环境变量例如--datadir优先于JELLYFIN_DATA_DIR--configdir优先于JELLYFIN_CONFIG_DIR--cachedir优先于JELLYFIN_CACHE_DIR--webdir优先于JELLYFIN_WEB_DIR--logdir优先于JELLYFIN_LOG_DIR。六、高级配置独立托管 Web 客户端README 指出前后端可以分离部署这对前端开发者尤其有用。要让服务器停止托管 Web 内容需设置nowebclient配置两种途径命令行开关--nowebclient环境变量JELLYFIN_NOWEBCONTENTtrue。由于这是常见场景Visual Studio 中预置了一个名为Jellyfin.Server (nowebcontent)的启动配置可在工具栏「Start Debugging」下拉框中选择。launchSettings.json 中还定义了另外两个配置默认的Jellyfin.Server启动后自动打开浏览器访问http://localhost:8096以及Jellyfin.Server (API Docs)自动打开 Swagger 页面三者均设置ASPNETCORE_ENVIRONMENTDevelopment。注意README 特别提示当 Web 客户端被独立托管时设置向导setup wizard无法运行——首次初始化只能通过服务器托管的 Web 客户端完成。七、从 GitHub Codespaces 运行Jellyfin 也可以在 GitHub 托管的 Codespaces 容器内开发调试README 对此给出了两条注意事项和两种配置注意事项取决于所选配置直接点「create codespace」会创建默认配置VS Code 打开后可能需要 2030 秒加载扩展并准备环境请等待输出面板中出现 .NET 版本下载完成的提示若要从外部访问例如另一台 PC 上的 Web 客户端需在 VS Code 底部面板的「ports」中将端口设为 public首次通过任意 WebUI 打开服务器实例时会被带到登录页而非设置页刷新一次登录页即会重定向到 Setup。两种配置Default - Development Jellyfin Server可运行和调试 Jellyfin 服务器的容器但不预装 ffmpeg、Web 客户端和媒体且每次新建容器都要重新走完整设置流程。由于没有 Web 客户端需通过外部客户端连接可以是另一个运行 WebUI 的 Codespaces 容器vuejs 客户端开箱即用场景下不支持 setup 步骤不能直接使用。启动时使用.NET Launch (nowebclient)启动配置。Development Jellyfin Server ffmpeg在上者基础上按 Linux 安装文档预装了 ffmpeg6。如需特定 ffmpeg 版本按.devcontainer/Dev - Server Ffmpeg/install.ffmpeg.sh文件内嵌注释操作运行时使用ghcs .NET Launch (nowebclient, ffmpeg)启动配置。八、运行单元测试本仓库包含在 CI 管线中用于验证功能的单元测试测试工程集中在 tests/ 目录下按模块拆分例如 Jellyfin.Naming.Tests、Jellyfin.MediaEncoding.Tests、Jellyfin.Server.Implementations.Tests、Jellyfin.Model.Tests 等十余个测试工程。README 给出三种运行方式dotnet test # 命令行运行全部测试命令行dotnet testVisual Studio使用 Test ExplorerVisual Studio Code通过 Omnisharp 扩展提供的 CodeLens 注解运行单个测试。九、进一步深入关键入口文件索引完成上述流程后可沿以下源码继续深入Jellyfin.Server/Program.cs应用入口命令行解析、启动配置构建、Kestrel 主机创建含JELLYFIN_ENABLE_IIS这一不受支持的 IIS 托管选项Jellyfin.Server/CoreAppHost.cs 与 Jellyfin.Server/Startup.csDI 服务注册与 ASP.NET Core 管道配置Jellyfin.Server/Migrations/启动前迁移例程数据库结构、配置升级等Emby.Server.Implementations/Library/LibraryManager.cs媒体库扫描与入库的核心Jellyfin.Server.Implementations/Item/BaseItemRepository.cs基于 EF Core 的媒体库持久化。掌握以上内容后你已具备在本仓库中构建、启动、调试和测试 Jellyfin 服务器完整能力并理解了--nowebclient、--webdir、--datadir等选项从命令行到配置系统、再到启动校验逻辑的完整链路。【免费下载链接】jellyfinThe Free Software Media System - Server Backend API项目地址: https://gitcode.com/GitHub_Trending/je/jellyfin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考