jellyfin/jellyfin：自由软件媒体系统服务器后端与 API

自由软件媒体系统

---

---

Jellyfin 是一套自由软件媒体系统，让你能够自行掌控媒体内容的管理和流式播放。它是专有软件 Emby 和 Plex 的替代方案，可通过多个应用程序将专用服务器中的媒体内容提供至终端用户设备。Jellyfin 源自 Emby 3.5.2 版本，并已迁移至 .NET 平台，以实现完整的跨平台支持。

没有附加条件、没有高级许可证或高级功能，也没有隐藏目的：只有一支希望构建更好产品、并共同实现这一目标的团队。我们欢迎所有有兴趣加入这一征程的人！

如需进一步了解详情，请参阅我们的文档页面。如需接收最新动态、获取 Jellyfin 帮助并加入社区，请访问我们的任一沟通渠道。如需了解项目更多信息，请参阅我们的关于页面。

想要开始使用？
请查看我们的下载页面或安装指南，然后阅读快速入门指南。你也可以从源代码构建。

遇到异常问题？
请在 GitHub 上提交一个 Issue。

想要贡献？
请查看我们的贡献选择冒险指南，了解你可以在哪些方面提供帮助；随后请阅读贡献指南和社区标准。

有新想法或改进建议？
请访问我们的功能请求中心。

没有看到你的语言版本的 Jellyfin？
请访问我们的 Weblate 实例，协助翻译 Jellyfin 及其子项目。

---

本仓库包含 Jellyfin 后端服务器的代码。请注意，这只是 Jellyfin GitHub 组织旗下众多项目之一。如果你希望贡献代码，可先查看我们的文档，了解可参与的工作。

以下说明将帮助你搭建本地开发环境，以便为本仓库作出贡献。开始之前，请务必完整阅读我们的开发贡献指南。请注意，除目前仍不兼容的 FreeBSD 外，本项目支持所有主流操作系统。

在构建项目之前，你必须先在系统中安装 .NET 10 SDK。

本文包含从命令行运行本项目的说明；如果你希望在服务器运行时进行调试，还需要安装 IDE。任何支持 .NET 6 开发的 IDE 都可以使用，其中两个选择是较新版本的 Visual Studio（至少为 2022 版）和 Visual Studio Code。

还需要安装 ffmpeg。

安装完依赖项后，你需要克隆本仓库的本地副本。如果只想从源代码运行服务器，可以直接克隆本仓库；但如果打算向项目贡献代码变更，则应设置自己的仓库 Fork。以下示例展示了如何通过 HTTPS 直接克隆仓库。

git clone https://github.com/jellyfin/jellyfin.git

安装 Web Client

默认情况下，服务器除提供后端服务外，还配置为托管 Web Client 所需的静态文件。由于本仓库并未直接包含 Web Client，因此在运行服务器前，你需要获取一份 Web Client 副本。

请注意，对于开发工作，建议通过额外配置将 Web Client 与 Web 服务器分开托管；在这种情况下，你可以跳过此步骤。

获取 Web Client 文件有两种方式。

1. 按照 jellyfin-web 仓库中的说明，从源代码构建。
2. 从已有服务器安装中获取预构建文件。例如，在 Windows 服务器安装中，客户端文件位于 C:\Program Files\Jellyfin\Server\jellyfin-web。

以下说明将帮助你通过命令行或首选 IDE 启动并运行项目。

使用 Visual Studio 运行

要使用 Visual Studio 运行项目，可打开解决方案（.sln）文件，然后按 F5 运行服务器。

使用 Visual Studio Code 运行

要使用 Visual Studio Code 运行项目，首先需要通过 Open Folder... 选项在 Visual Studio Code 中打开仓库目录。

其次，需要安装工作区推荐的扩展。请注意，扩展推荐分为“工作区推荐（Workspace Recommendations）”和“其他推荐（Other Recommendations）”，但只有“工作区推荐”是必需的。

安装必要扩展后，可以按 F5 运行服务器。

从命令行运行

要从命令行运行服务器，可以使用 dotnet run 命令。以下示例展示了在将仓库克隆到名为 jellyfin 的目录（默认目录名）后如何操作，适用于所有操作系统。

cd jellyfin                          # Move into the repository directory
dotnet run --project Jellyfin.Server --webdir /absolute/path/to/jellyfin-web/dist # Run the server startup project

第二种方式是先构建项目，再直接运行生成的可执行文件。直接运行可执行文件时，可以方便地添加命令行选项。添加 --help 标志可列出所有受支持命令行选项的详细信息。

1. 构建项目

dotnet build                       # Build the project
cd Jellyfin.Server/bin/Debug/net10.0 # Change into the build output directory

2. 执行构建输出。在 Linux、Mac 等系统中使用 ./jellyfin，在 Windows 中使用 jellyfin.exe。

访问托管的 Web Client

如果服务器配置为托管 Web Client，且服务器正在运行，则默认可通过 http://localhost:8096 访问 Web Client。

可通过 http://localhost:8096/api-docs/swagger/index.html 查看 API 文档。

从 GitHub Codespaces 运行

由于 Jellyfin 将在 GitHub 托管服务器上的容器中运行，JF 需要以不同方式处理一些事项。

注意： 根据所选配置的不同（如果只点击“create codespace”，将创建默认配置），即使 VS Code 已经打开，加载全部扩展并准备环境也可能需要 20 至 30 秒。请耐心等待，直到在输出标签页中看到 Downloading .NET version(s) 7.0.15~x64 ...... Done!。

注意： 如果希望从外部访问 JF 实例，例如在另一台 PC 上通过 WebClient 访问，请记得将 VS Code 下方窗口中的“ports”设为 public。

注意： 首次通过任意 WebUI 打开服务器实例时，你会被带到登录页面而不是设置页面。刷新登录页面一次后，应会被重定向至设置页面。

你可以选择两种配置。

默认配置——开发版 Jellyfin Server

此配置会创建一个容器，其中包含运行和调试 Jellyfin Media Server 所需的一切，但不会设置其他内容。每次创建新容器时，都必须重新完成整个设置过程。此外，其中不会预装 ffmpeg、Web Client 或媒体文件。请使用 .NET Launch (nowebclient) 启动配置来启动服务器。

请注意，由于此配置没有 Web Client，你必须通过外部客户端连接。该客户端可以是另一个运行 WebUI 的 Codespace 容器。vuejs 无法开箱即用，因为它不支持设置步骤。

开发版 Jellyfin Server ffmpeg

此配置在默认服务器基础上，通过此处描述的方式扩展了 ffmpeg6 的默认安装：https://jellyfin.org/docs/general/installation/linux#repository-manual。如果希望安装特定的 ffmpeg 版本，请按照 .devcontainer/Dev - Server Ffmpeg/install.ffmpeg.sh 文件中嵌入的注释操作。

请使用 ghcs .NET Launch (nowebclient, ffmpeg) 启动配置，以在启用 jellyfin-ffmpeg 的情况下运行。

本仓库还包含单元测试，用于在 Azure 上的 CI 流水线中验证功能。这些测试有多种运行方式。

1. 使用 dotnet test 从命令行运行测试。
2. 在 Visual Studio 中使用 Test Explorer 运行测试。
3. 在 Visual Studio Code 中使用关联的 CodeLens 注释运行单个测试。

以下章节介绍了从源代码运行服务器的一些更高级场景，它们基于上述标准说明。

单独托管 Web Client

不必将前端 Web Client 作为后端服务器的一部分托管。将这两个组件分开托管，对于希望在独立 webpack 开发服务器中托管客户端、以获得更紧密开发循环的前端开发者可能很有用。有关操作说明，请参阅 jellyfin-web 仓库。

若要让服务器不托管 Web 内容，必须设置 nowebclient 配置标志。可通过命令行开关 --nowebclient 或环境变量 JELLYFIN_NOWEBCONTENT=true 指定该标志。

由于这是常见场景，Visual Studio 还定义了单独的启动配置 Jellyfin.Server (nowebcontent)，可从主工具栏的“Start Debugging”下拉菜单中选择。

注意：

The Free Software Media System

---

---

Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media. It is an alternative to the proprietary Emby and Plex, to provide media from a dedicated server to end-user devices via multiple apps. Jellyfin is descended from Emby's 3.5.2 release and ported to the .NET platform to enable full cross-platform support.

There are no strings attached, no premium licenses or features, and no hidden agendas: just a team that wants to build something better and work together to achieve it. We welcome anyone who is interested in joining us in our quest!

For further details, please see our documentation page. To receive the latest updates, get help with Jellyfin, and join the community, please visit one of our communication channels. For more information about the project, please see our about page.

Want to get started?
Check out our downloads page or our installation guide, then see our quick start guide. You can also build from source.

Something not working right?
Open an Issue on GitHub.

Want to contribute?
Check out our contributing choose-your-own-adventure to see where you can help, then see our contributing guide and our community standards.

New idea or improvement?
Check out our feature request hub.

Don't see Jellyfin in your language?
Check out our Weblate instance to help translate Jellyfin and its subprojects.

---

This repository contains the code for Jellyfin's backend server. Note that this is only one of many projects under the Jellyfin GitHub organization on GitHub. If you want to contribute, you can start by checking out our documentation to see what to work on.

These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our guidelines on development contributions. Note that this project is supported on all major operating systems except FreeBSD, which is still incompatible.

Before the project can be built, you must first install the .NET 10 SDK on your system.

Instructions to run this project from the command line are included here, but you will also need to install an IDE if you want to debug the server while it is running. Any IDE that supports .NET 6 development will work, but two options are recent versions of Visual Studio (at least 2022) and Visual Studio Code.

ffmpeg will also need to be installed.

After dependencies have been installed you will need to clone a local copy of this repository. If you just want to run the server from source you can clone this repository directly, but if you are intending to contribute code changes to the project, you should set up your own fork of the repository. The following example shows how you can clone the repository directly over HTTPS.

git clone https://github.com/jellyfin/jellyfin.git

Installing the Web Client

The server is configured to host the static files required for the web client in addition to serving the backend by default. Before you can run the server, you will need to get a copy of the web client since they are not included in this repository directly.

Note that it is recommended for development to host the web client separately from the web server with some additional configuration, in which case you can skip this step.

There are two options to get the files for the web client.

1. Build them from source following the instructions on the jellyfin-web repository
2. Get the pre-built files from an existing installation of the server. For example, with a Windows server installation the client files are located at C:\Program Files\Jellyfin\Server\jellyfin-web

The following instructions will help you get the project up and running via the command line, or your preferred IDE.

Running With Visual Studio

To run the project with Visual Studio you can open the Solution (.sln) file and then press F5 to run the server.

Running With Visual Studio Code

To run the project with Visual Studio Code you will first need to open the repository directory with Visual Studio Code using the Open Folder... option.

Second, you need to install the recommended extensions for the workspace. Note that extension recommendations are classified as either "Workspace Recommendations" or "Other Recommendations", but only the "Workspace Recommendations" are required.

After the required extensions are installed, you can run the server by pressing F5.

Running From the Command Line

To run the server from the command line you can use the dotnet run command. The example below shows how to do this if you have cloned the repository into a directory named jellyfin (the default directory name) and should work on all operating systems.

cd jellyfin                          # Move into the repository directory
dotnet run --project Jellyfin.Server --webdir /absolute/path/to/jellyfin-web/dist # Run the server startup project

A second option is to build the project and then run the resulting executable file directly. When running the executable directly you can easily add command line options. Add the --help flag to list details on all the supported command line options.

1. Build the project

dotnet build                       # Build the project
cd Jellyfin.Server/bin/Debug/net10.0 # Change into the build output directory

2. Execute the build output. On Linux, Mac, etc. use ./jellyfin and on Windows use jellyfin.exe.

Accessing the Hosted Web Client

If the Server is configured to host the Web Client, and the Server is running, the Web Client can be accessed at http://localhost:8096 by default.

API documentation can be viewed at http://localhost:8096/api-docs/swagger/index.html

Running from GitHub Codespaces

As Jellyfin will run on a container on a GitHub hosted server, JF needs to handle some things differently.

NOTE: Depending on the selected configuration (if you just click 'create codespace' it will create a default configuration one) it might take 20-30 seconds to load all extensions and prepare the environment while VS Code is already open. Just give it some time and wait until you see Downloading .NET version(s) 7.0.15~x64 ...... Done! in the output tab.

NOTE: If you want to access the JF instance from outside, like with a WebClient on another PC, remember to set the "ports" in the lower VS Code window to public.

NOTE: When first opening the server instance with any WebUI, you will be sent to the login instead of the setup page. Refresh the login page once and you should be redirected to the Setup.

There are two configurations for you to choose from.

Default - Development Jellyfin Server

This creates a container that has everything to run and debug the Jellyfin Media server but does not setup anything else. Each time you create a new container you have to run through the whole setup again. There is also no ffmpeg, webclient or media preloaded. Use the .NET Launch (nowebclient) launch config to start the server.

Keep in mind that as this has no web client you have to connect to it via an external client. This can be just another codespace container running the WebUI. vuejs does not work from the get-go as it does not support the setup steps.

Development Jellyfin Server ffmpeg

this extends the default server with a default installation of ffmpeg6 though the means described here: https://jellyfin.org/docs/general/installation/linux#repository-manual If you want to install a specific ffmpeg version, follow the comments embedded in the .devcontainer/Dev - Server Ffmpeg/install.ffmpeg.sh file.

Use the ghcs .NET Launch (nowebclient, ffmpeg) launch config to run with the jellyfin-ffmpeg enabled.

This repository also includes unit tests that are used to validate functionality as part of a CI pipeline on Azure. There are several ways to run these tests.

1. Run tests from the command line using dotnet test
2. Run tests in Visual Studio using the Test Explorer
3. Run individual tests in Visual Studio Code using the associated CodeLens annotation

The following sections describe some more advanced scenarios for running the server from source that build upon the standard instructions above.

Hosting The Web Client Separately

It is not necessary to host the frontend web client as part of the backend server. Hosting these two components separately may be useful for frontend developers who would prefer to host the client in a separate webpack development server for a tighter development loop. See the jellyfin-web repo for instructions on how to do this.

To instruct the server not to host the web content, there is a nowebclient configuration flag that must be set. This can be specified using the command line switch --nowebclient or the environment variable JELLYFIN_NOWEBCONTENT=true.

Since this is a common scenario, there is also a separate launch profile defined for Visual Studio called Jellyfin.Server (nowebcontent) that can be selected from the 'Start Debugging' dropdown in the main toolbar.

NOTE: The setup wizard cannot be run if the web client is hosted separately.

---

This project is supported by: