Kyoo 5.2.1 介绍与选型指南

目标：介绍自托管媒体服务器 Kyoo 的定位、微服务架构、功能特性与同类选型对比，帮助读者判断它是否适合自己的影库场景；全部结论来自 Ubuntu 24.04 LTS 上的 Docker Compose 全栈实测（版本 5.2.1，7 个服务组件全部实跑取证）。

一、环境信息

本文所有结论均在以下环境实测取得，读者复现时可对照检查：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 容器运行时：Docker 29.9.2，Docker Compose v5.6.1（插件版）
• Kyoo 版本：5.2.1（官方镜像 ghcr.io/zoriya/kyoo_*:5.2，上游最新稳定版即 v5.2.1，2026-08-27 发布，GitHub Releases 查询日期 2026-10-29）
• 依赖组件：Traefik v3.7（入口网关）、PostgreSQL 18（元数据库）
• 部署形态：单机 Compose 编排，7 个服务容器全部在运行（front、api、auth、scanner、transcoder、traefik、postgres）
• 入口地址：宿主机 http://localhost:8136（Traefik 监听端口映射为 8136，容器内 8901）
• 实测媒体样本：Big Buck Bunny (2008).mp4（H.264 1280×720，约 5 MB，10 秒）

💡 说明：Kyoo 上游采用 大版本.次版本 的镜像 tag（如 5.2），patch 版本通过 GitHub Release（v5.2.1）区分。实测拉取的镜像与 v5.2.1 源码构建产物一致，本文统一以 5.2.1 口径书写。

二、软件概述

Kyoo 是一个聚焦视频内容（电影、剧集、动漫）的开源自托管媒体服务器，定位为 Jellyfin/Plex 的替代品。它由 GitHub 用户 zoriya 主导开发，仓库地址 https://github.com/zoriya/Kyoo，采用 GPL-3.0 许可证，代码与官方 Docker 镜像均公开可审计。

它最有辨识度的两个主张，README 原文明确写出：

1. 零目录结构要求：Kyoo 不要求用户预先整理媒体文件夹，"Bad naming, everything in the same directory, weird anime names, everything works out of the box"——文件名识别（guessing）由扫描器内置算法完成，把识别错误视为 bug 修复。
2. 无插件系统：Kyoo 不提供插件机制，目标把全部功能内置（内置刮削、内置转码、内置多语言字幕管理），换取"低维护"这一核心卖点。

技术栈是四语言微服务组合（这也是理解它部署形态的关键）：

💡 技术拓展：媒体服务器的「元数据刮削」通常依赖外部元数据站。业界常见提供方对比——

提供方	覆盖范围	接入方式	特点
TheTVDB	剧集/动漫为主	v4 API，需 API Key 或内置默认 Key	Kyoo 剧集刮削默认源
TheMovieDB (TMDB)	电影/剧集全覆盖	v3 API + Access Token	Kyoo 电影刮削默认源，可选自带 Token
TVmaze	欧美剧集	免费 REST	轻量替代
AniDB/AniList	动番垂类	REST/XML	动漫命名规整能力弱于 TheTVDB

Kyoo 5.2.1 实际采用 TheTVDB + TheMovieDB 双源组合：扫描器在启动阶段即与 TheTVDB 建立会话（本文第六节有实测证据），这是它作为"零维护"派的一个硬性外部依赖。

版本节奏方面，v5.0.0 完成了 front/api/scanner 的全量重写（官方 Release Notes 原话 "full rewrite of the front, api, scanner"），此后按 v5.1.0 → v5.2.0 → v5.2.1 滚动迭代，v5.2.1 发布于 2026-08-27。对选型者来说，5.x 系列已进入稳定收尾期，大重构风险低。

三、核心架构

理解 Kyoo 的架构，抓住一句话：一个 Traefik 网关把 6 个业务服务串成单入口应用，所有请求先过 Go 认证服务换取 JWT，再到达各自业务服务。以下组件角色与端口全部来自实测的 Compose 配置与容器探查。

3.1 服务组件与端口

Traefik 的路由规则由 Compose label 声明（实测节选自运行中容器的 label）：PathPrefix('/')→front、PathPrefix('/api/')→api、PathPrefix('/swagger')→api、PathPrefix('/auth/') || PathPrefix('/.well-known/')→auth、PathPrefix('/video')→transcoder、PathPrefix('/scanner/')→scanner。/api/ 与 /video 两个路由均挂了 phantom-token 中间件，把请求头的会话凭证先转发到 auth 的 /auth/jwt 换成正式 JWT 再放行。

3.2 认证与请求链路

实测抓取的一条完整播放链路（后文《API 使用详解》篇逐条复现）：

1. 客户端 POST /auth/sessions 用账号密码换会话 token（实测 201，返回 JSON 内含 token 字段）；
2. 携带 Authorization: Bearer <token> 访问 /api/videos/{id}/info，Traefik 的 forwardauth 中间件先调 http://auth:4568/auth/jwt 把会话 token 换成 RS256 签名的 JWT；
3. api 校验 JWT 后返回 302 重定向，Location: /video/L3ZpZGVvL0JpZyBCdWNrIEJ1bm55ICgyMDA4KS5tcDQ/info（base64url 编码的媒体路径）；
4. 浏览器跟随重定向直连 transcoder 拿到 ffprobe 元数据 JSON 或 206 分片的 mp4 视频流。

这个设计的收益是：api/scanner/transcoder 自身不做认证逻辑，鉴权全部收敛在 auth 一处；播放流量（大文件）经 302 直接打到 transcoder，不占用 api。

3.3 存储布局：一库三 schema

实测 psql 查询确认，单个 PostgreSQL 实例内按业务划了三套 schema，职责清晰：

       List of schemas
  Name   |       Owner
---------+-------------------
 gocoder | kyoo
 keibi   | kyoo
 kyoo    | kyoo
 public  | pg_database_owner
(4 rows)

• kyoo（19 张表）：媒体库主数据——shows/seasons/entries/videos/watchlist/history/staff/studios 等；
• keibi（4 张表）：认证域——users、sessions、apikeys、oidc_handle/oidc_login；
• gocoder（7 张表）：转码域——videos、audios、subtitles、chapters、fingerprints、info。

💡 技术拓展：微服务的「共享库分 schema」与「每服务独立库」是两种常见数据隔离策略。对比——

策略	优点	缺点
单库多 schema（Kyoo 采用）	一次备份、跨域 JOIN 简单、部署轻	服务间仍有耦合，扩容到多实例受限
每服务独立库	服务完全自治，可独立扩容	跨服务查询需走 API，备份/事务复杂

Kyoo 目标场景是单机家庭部署，采用单库多 schema 是合理取舍。

四、功能特性

以下特性均有实测依据（对应验证方式标注在每条之后，完整回显见《API 使用详解》篇）：

1. 动态转码与 ABR：transcoder 支持 direct（原画质直连）、master.m3u8（多码率 HLS 自适应）；实测 /api/videos/{id}/direct 携带 Range 头返回 206 Partial Content、Content-Type: video/mp4。
2. 无目录结构约束：扫描器对文件名做识别（guess），识别结果结构化存储在 videos 表的 guess JSONB 字段中；实测通过 seed API 写入 {"title":"Big Buck Bunny","kind":"movie","years":[2008]} 即被系统接受并进入未匹配队列。
3. 视频预览缩略图：transcoder 提供 thumbnails.png/thumbnails.vtt 端点（官方 OpenAPI 实测可见 7 条路由之一），悬浮进度条可预览画面。
4. 多端播放器：Android 端使用 VLC 内核播放（README 原文），桌面/Web 端为内建 HTML5 播放器。
5. 多用户与细粒度权限：权限以 claims JSON 声明，首个注册用户自动获得管理员权限集（users.read/write/delete、apikeys.*、core.*、scanner.* 全量），普通注册用户默认 core.read + core.play，游客可配置只读；实测 .env 三段 claims 环境变量逐一验证。
6. OIDC 单点登录：auth 服务内建 OIDC Provider 对接（Google 等），重定向白名单由环境变量控制，官方应用与 loopback 地址默认放行。
7. API Key 机制：实测 POST /auth/keys 创建 key 后，用 X-Api-Key 请求头调用 /api/shows 返回 200，可对接第三方集成。
8. 硬件加速转码四档：Compose profiles 提供 cpu / vaapi（Intel/AMD）/ qsv / nvidia 四种 transcoder 变体，一行 COMPOSE_PROFILES 切换。
9. 观看进度与播放列表：/api/profiles/me/history、/api/profiles/me/nextup、/api/profiles/me/watchlist 三组"继续观看"接口在官方 OpenAPI 中齐备。

五、快速开始（最小可用示例）

三步拉起一个可用实例（完整参数与排障见部署指南篇）：

第 1 步：准备两份官方文件并启动。 在任意工作目录下载官方 docker-compose.yml 与 .env.example，把后者改名为 .env（必须以点开头、无后缀），按需修改 LIBRARY_ROOT 指向你的媒体目录，然后：

docker compose up -d   # 首次会拉取 7 个服务镜像

实测启动后状态（节选）：

kyoo-5.2.1-postgres   Up 34 minutes (healthy)
kyoo-5.2.1-traefik    Up 34 minutes   0.0.0.0:8136->8901/tcp
kyoo-5.2.1-api        Up 34 minutes   3567/tcp

第 2 步：注册首个管理员账号。 第一个注册的用户自动成为管理员，用 curl 一条命令完成（用户名/密码可自定义，本文演示用 admin）：

curl -s -X POST http://localhost:8136/auth/users \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","email":"admin@example.com","password":"q1w2e3r4"}'

实测返回（节选，含会话 token）：

{"id":"3dcefdeb-254b-40f9-beeb-e1d7dd547241","createdDate":"2026-10-29T10:13:23.469473Z","device":"curl","token":"W5zY5ejXbN56Ugj5goFkNkWjNapfZxfJ6_BnQ77EBzjeFWmWoO-Ygs74MGidjqOfuU8md1n2V-G4m7Rfd25_Rw"}

第 3 步：浏览器打开 http://localhost:8136 登录使用。 实测入口页 HTTP 200，健康检查全部通过：

$ curl -s http://localhost:8136/api/health && echo
{"status":"healthy"}
$ curl -s http://localhost:8136/api/ready && echo
{"status":"healthy","database":"healthy"}

六、适用场景与限制

适合的场景：

• 家庭/小团队影库自托管，媒体文件命名混乱、不想手工刮削的用户（Kyoo 的核心卖点）；
• 动漫收藏重度用户：TheTVDB 对剧集/动漫季集识别能力强，且内置番剧命名规整逻辑；
• 想要"部署完就忘"的低维护诉求：无插件、无额外依赖服务，唯一存储是单 PostgreSQL；
• 有 API 集成诉求的场景：REST + OpenAPI 文档齐全（api 服务 56 条路由、transcoder 7 条路由实测可见），支持 API Key 与细粒度权限。

当前的限制（全部来自实测，非转述）：

1. 扫描器有硬性外网依赖：实测在内网隔离环境部署时，scanner 容器反复重启（RestartCount 持续增长），日志报 aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host api4.thetvdb.com:443，随后 Application startup failed. Exiting.。溯源官方源码 scanner/scanner/providers/thetvdb.py：即使不配置 TVDB_APIKEY，也会用内置默认 Key 在启动时登录 TheTVDB。因此部署 Kyoo 的机器必须能访问 TheTVDB 与 TheMovieDB（或经 HTTP 代理可达），这是与其他媒体服务器最大的部署差异。
2. 无插件系统：功能扩展只能等官方内置或改源码（README 明确说明）。
3. 单机形态：官方仅提供单实例 Compose 部署，无官方集群/多节点方案。
4. 必须依赖 Docker：官方只发布容器镜像与 Compose 文件，无裸机安装包。

七、同类选型对比

面向"自托管视频媒体服务器"这一需求，主流可选方案为 Kyoo、Jellyfin、Emby、Plex 四者（Navidrome 等偏音乐域， Kodi 为播放器客户端，不构成同域竞争，不在对比之列）。

关键差异与选型建议（如果…则…）：

• 如果你的媒体目录命名混乱、想要零整理入库 → Kyoo，它的文件名识别是架构级承诺（识别错误算 bug）；
• 如果需要插件生态（如第三方字幕源、整合 Home Assistant 等）→ Jellyfin，插件数量远超 Kyoo 的"全内置"路线；
• 如果设备端体验优先、愿意付费换省心 → Plex/Emby，客户端覆盖与转码体验是商业产品的强项；
• 如果部署环境无法访问 TheTVDB/TMDB（纯内网影库）→ 避免 Kyoo（scanner 起不来，实测见第六节），选 Jellyfin 并关闭在线刮削；
• 如果想要细粒度 API 权限对接自建系统 → Kyoo 的 claims + API Key 模型对二次开发最友好。

八、参考链接

• 官方仓库：https://github.com/zoriya/Kyoo（含 README、INSTALLING.md、OIDC.md）
• 官方 API 文档：https://kyoo.zoriya.dev/swagger
• GitHub Releases（版本与 docker-compose.yml 下载）：https://github.com/zoriya/Kyoo/releases
• 安装文档（仓库内）：https://github.com/zoriya/Kyoo/blob/master/INSTALLING.md
• 本系列实测篇目：部署实操见《Kyoo 5.2.1 Docker Compose 部署指南》，环境变量逐项含义见《Kyoo 5.2.1 配置参数详解》，接口实测见《Kyoo 5.2.1 API 使用详解》。