用官方 Helm Chart 将自托管媒体服务器 Kyoo 部署到 Kubernetes 集群

方案简介

Kyoo 是一个聚焦视频内容（电影、剧集与动漫）的自托管媒体服务器，定位为 Jellyfin 或 Plex 的替代品。该项目提供官方 Helm Chart，可直接将整套 Kyoo 部署到 Kubernetes 集群中。由于 Kyoo 在架构上被拆分为多个可以独立工作的服务（如转码器等），天然适合在 Kubernetes 上进行容器化编排。该方案适合已有 Kubernetes 集群、希望以低维护成本自建媒体库的用户：无需整理文件夹结构、无需手动编辑元数据，设置应在 5 分钟内完成。

注意：目前 Chart 的多副本（Multiple replicas）功能仍在开发中（WIP），当前更适合单副本部署。

亮点与能力

• 动态转码：可转码到任意画质，支持 ABR（根据网络自动切换画质），包括原始画质。
• 无需文件夹结构：命名混乱、全部堆在同一目录、奇怪的动漫命名都能开箱即用。
• 视频预览缩略图：悬停进度条即可预览视频。
• 片头/片尾检测：通过音频指纹（或章节标题匹配）自动检测片头与片尾。
• 字幕支持：支持 PGS/VODSUB 与 SSA/ASS，可使用视频内嵌字体，Web 与 Chromecast 上亦可用。
• OIDC 登录：可接入任何符合 OIDC 标准的服务（Google、Discord、Authelia 等）。
• API 文档：提供 Swagger API，方便与其它服务集成。

组成与分工

• Kyoo：自托管媒体服务器本体，负责媒体扫描、元数据管理、播放与转码，由多个可独立工作的服务组成。
• Helm：Kubernetes 的包管理工具，通过官方 Helm Chart 简化 Kyoo 在集群中的安装与配置。
• Kubernetes：容器编排平台，承载 Kyoo 的多个服务，便于统一管理与扩展。

前置要求

• 一个可用的 Kubernetes 集群。
• 集群中安装 Helm（用于安装官方 Chart）。
• 如需启用硬件转码或 OIDC，参考仓库的 INSTALLING.md 安装文档。
• 无需预先整理媒体文件夹结构。

实施步骤

1. 阅读 INSTALLING.md

仓库提供了 INSTALLING.md 安装文档，包含如何启动 Kyoo、启用 OIDC 或硬件转码的基础指南。

2. 使用官方 Helm Chart 部署

通过 Helm 将 Kyoo 部署到你的 Kubernetes 集群（具体命令与 values 配置以官方 Chart 文档为准）。

3. 指向媒体目录

Kyoo 不要求已有组织良好的媒体库，甚至可以直接指向下载目录。

4. 验证部署

启动后访问 Kyoo Web 客户端确认媒体被正确扫描与播放。

使用与配置要点

• 客户端支持：Web、Android、Chromecast 已支持，Android TV 计划中。
• 可通过 https://kyoo.zoriya.dev/swagger 查看 API 文档，用于集成第三方服务。
• 部署后若媒体未被正确扫描（即使命名奇怪），按项目标准应视为 bug。
• 翻译缺失可通过 Weblate 参与补充。

注意事项与常见问题

• Helm Chart 的多副本（Multiple replicas）功能是 WIP，尚未完成。
• Kyoo 没有插件系统，所有功能均为内置。
• 观看列表同步（SIMKL）与离线下载功能在 v5 中尚未重新实现。
• 项目由一人开发，可用客户端数量有限。
• 遇到问题可在 Discord 或 GitHub 提问。

优缺点

• ✓ 官方 Chart 一键部署
• ✓ 多服务架构易编排
• ✕ 多副本尚未完成
• ✕ 仅单人开发维护

出处

本方案挖掘自开源项目 zoriya/Kyoo，方案内容与实施命令均来自其 README 原文。