Seerr 开源媒体请求与发现管理器:Jellyfin / Plex / Emby 集成实战指南

原创2026-09-14 18:37:581,970 阅读
文章标签:后端前端认证鉴权音视频自托管媒体库请求管理

Seerr 开源媒体请求与发现管理器:Jellyfin / Plex / Emby 集成实战指南

Seerr 是一款免费开源的媒体库请求与发现管理应用,专为自建影音库用户打造,可无缝接入 Jellyfin、Plex、Emby 三种主流媒体服务器,并与 Sonarr、Radarr 等服务联动,自动完成影视剧集的下载编排。本文将基于仓库源码,系统拆解 Seerr 的核心功能、数据库架构、权限体系、通知机制与部署方式,帮助你掌握从安装到日常运维的完整技术方案。

项目定位与核心架构

Seerr 的定位是"媒体库请求管理"(media request management):用户在前端界面上发现并请求想要的电影、剧集,管理员审批后,由 Sonarr/Radarr 等自动化服务完成资源获取,最终在媒体服务器中呈现给用户。项目描述将其概括为 Open-source media request and discovery manager for Jellyfin, Plex, and Emby,即一个同时面向"发现"与"请求"两端的统一入口。

从仓库结构看,Seerr 采用前后端一体的 Next.js + Express 架构:

  • 前端位于 src/(React 19 + Next.js 16 + Tailwind CSS),包含发现页、请求弹窗、设置面板、用户管理等完整界面;
  • 后端位于 server/(Express 5 + TypeORM + TypeScript),承载认证、API 路由、定时任务、通知代理与数据库访问;
  • API 规范集中定义在 seerr-api.yml,运行时通过 express-openapi-validator 做请求/响应校验。

服务默认监听 5055 端口,该端口在 Dockerfile 中通过 EXPOSE 5055 声明,并在 server/index.ts 中通过 process.env.PORT || 5055 读取,可用环境变量覆盖。

核心功能全景

README 中列出的功能清单,每一条都能在源码中找到对应实现,下面逐一展开。

1. Jellyfin / Emby / Plex 全量集成

Seerr 对三家媒体服务器提供"完整集成"(Full integration),包括:

  • 登录认证与用户导入:以 Plex 为例,server/routes/auth.ts 中的 /api/v1/auth/plex 路由接收 Plex 授权码后,通过 PlexTvAPI 换取用户信息(用户名、邮箱、Plex ID),首次登录自动创建本地用户并关联 plexId、plexToken;Jellyfin 侧则由 server/api/jellyfin.ts 提供对应的 Quick Connect 与传统登录流程;
  • 媒体库同步:Seerr 会扫描媒体服务器库,记录哪些标题已可用,从而在请求界面标记"已有"状态,避免重复请求。实现上,server/lib/scanners/ 下分别提供 plex/、jellyfin/、radarr/、sonarr/ 等扫描器目录,由 server/lib/scanners/baseScanner.ts 定义统一的扫描基类;
  • 库类型识别:启动时会自动为旧配置补充媒体库类型(movie / tv / 混合),见 server/index.ts 的库类型迁移逻辑。

2. 双数据库支持:PostgreSQL 与 SQLite

README 明确声明支持 PostgreSQL 和 SQLite 两种数据库,这也是 Seerr 相对传统同类工具的一大特性。底层由 TypeORM 统一管理,配置集中在 server/datasource.ts:

配置项 说明 默认值
DB_TYPE 数据库引擎,设为 postgres 启用 PostgreSQL,否则为 sqlite sqlite
DB_HOST 数据库主机地址(PostgreSQL) —
DB_PORT 连接端口 5432
DB_USER / DB_PASS 数据库账号与密码 —
DB_NAME 数据库名 seerr
DB_USE_SSL 是否启用 SSL 连接 false
DB_SSL_CA / DB_SSL_KEY / DB_SSL_CERT SSL 证书三件套,也支持对应 _FILE 环境变量直接读取证书文件 —
DB_POOL_SIZE 连接池大小 —
DB_CONNECT_TIMEOUT_MS 连接池获取超时,避免耗尽时静默挂起 30000
DB_LOG_QUERIES 是否输出 SQL 日志用于调试 false

值得注意的实现细节:

  • SQLite 默认库文件路径为 config/db/db.sqlite3(可用 CONFIG_DIRECTORY 环境变量重定向),并开启 enableWAL 提升并发读写性能;
  • PostgreSQL 生产模式会自动执行迁移(migrationsRun: true),SQLite 生产模式则在外键关闭状态下执行迁移后再恢复,见 server/index.ts;
  • 两套迁移脚本分别维护在 server/migration/postgres/ 与 server/migration/sqlite/,已沉淀数十个历史迁移,涵盖黑名单改名、Web Push 更新、权限唯一约束等演进;
  • 环境变量解析使用了 boolFromEnv / intFromEnv / stringOrReadFileFromEnv 三个辅助函数,其中 SSL 证书支持"直接给值或给文件路径"两种注入方式,方便容器化部署。

仓库根目录的 compose.postgres.yaml 给出了完整的 PostgreSQL 部署示例:DB_TYPE: 'postgres' 配合独立的 postgres:18 服务,而 compose.yaml 则展示了默认 SQLite 模式的开发环境编排。

3. 电影 / 剧集 / 混合库支持

Seerr 同时支持 Movies、Shows 与 Mixed Libraries。后端为电影、剧集、合集、人物分别建立模型(server/models/ 下的 Movie.ts、Tv.ts、Collection.ts、Person.ts),请求系统则在媒体实体层将剧集请求细化到"季"级别:MediaRequest 关联 SeasonRequest,SeasonRequest 再关联 Season(见 server/entity/MediaRequest.ts 与 server/entity/SeasonRequest.ts),这正是"按季请求"能力的实体基础。

4. 与 Sonarr / Radarr 的服务集成

README 声明当前支持 Sonarr 与 Radarr,后续还将扩展。集成实现位于 server/api/servarr/,base.ts 定义通用请求逻辑,sonarr.ts 与 radarr.ts 分别封装两家的专属 API,且各自配有测试文件(sonarr.test.ts、radarr.test.ts)。设置页面的服务配置路由见 server/routes/settings/ 下的 sonarr.ts 与 radarr.ts。

5. 可定制的请求系统

请求系统允许普通用户以友好的界面按季或整片发起请求,管理员可批量审批。这一能力由权限体系与实体模型共同支撑:

  • MediaRequest 实体携带 status、is4k、isAutoRequest 等字段,并支持标签(tags);
  • 服务端路由 server/routes/request.ts 提供请求创建、查询、更新、审批的完整 REST 接口;
  • 前端的 RequestModal 组件(7 个文件)实现了按季选择、4K 选项、高级请求等交互。

6. 细粒度权限系统

README 提到 "Granular permission system",这在 server/lib/permissions.ts 中是一个按位掩码实现的 Permission 枚举,粒度极细,例如:

  • 基础管理:ADMIN、MANAGE_SETTINGS、MANAGE_USERS、MANAGE_REQUESTS
  • 请求类:REQUEST、REQUEST_MOVIE、REQUEST_TV、REQUEST_4K、REQUEST_ADVANCED、AUTO_APPROVE(及电影/剧集/4K 细分)
  • 问题类:CREATE_ISSUES、VIEW_ISSUES、MANAGE_ISSUES
  • 名单类:MANAGE_BLOCKLIST、VIEW_BLOCKLIST、WATCHLIST_VIEW
  • 其他:VOTE、RECENT_VIEW、AUTO_REQUEST

权限位通过 2 的幂组合,前端设置页的 PermissionEdit 与 PermissionOption 组件提供了可视化的勾选管理界面,服务端中间件在路由层进行鉴权校验。

7. 多通道通知代理

"Support for various notification agents" 在源码中有非常直观的体现:server/lib/notifications/agents/ 目录下共 11 个代理实现——discord、email、gotify、ntfy、pushbullet、pushover、slack、telegram、webhook、webpush,外加基类 agent.ts。服务启动时统一注册这些代理(见 server/index.ts),由 server/lib/notifications/index.ts 的 notificationManager 统一调度,按用户的订阅偏好分发通知。

8. 移动端友好设计

前端基于响应式布局与 PWA 能力构建:src/components/PWAHeader/ 提供移动端头部,src/components/Layout/MobileMenu/ 提供移动菜单,public/ 下包含全套 PWA 图标、manifest(site.webmanifest)与 sw.js 离线缓存,配合 PullToRefresh 组件实现移动端下拉刷新体验(对应 e2e 测试 pull-to-refresh.cy.ts)。

9. 观看清单与黑名单

README 提到的 "watchlisting & blocklisting" 分别对应实体层 server/entity/Watchlist.ts 与 server/entity/Blocklist.ts:

快速开始

安装与运行

官方安装说明位于仓库内的 docs/getting-started/,覆盖 Docker、Kubernetes(charts/seerr-chart/ Helm Chart)、源码构建(buildfromsource.mdx)、Nix 包等途径。README 指出完整安装文档在 https://docs.seerr.dev/getting-started/,仓库内对应目录即为文档源码。

开发模式下可直接通过根目录 compose.yaml 启动:

services:
  seerr:
    build:
      context: .
      dockerfile: Dockerfile.local
    ports:
      - 5055:5055
    volumes:
      - .:/app:rw,cached
      - /app/node_modules
      - /app/.next

生产镜像基于 node:22-alpine 多阶段构建(Dockerfile):先 pnpm install --prod 裁剪非必要原生模块,再构建 Next.js 前端与 TS 后端,最终以非 root 用户 node:node 运行,符合容器安全最佳实践。

环境变量速查

除上表数据库变量外,以下变量在启动路径中同样关键:

  • PORT:服务监听端口,默认 5055;
  • HOST:绑定主机地址,默认全接口;
  • CONFIG_DIRECTORY:配置与 SQLite 数据库存储目录;
  • NODE_ENV:production 时走生产配置(禁用 synchronize,改用迁移)。

API 文档

Seerr 内置 Swagger UI:本地部署后访问 http://localhost:5055/api-docs 即可查看交互式 API 文档。实现上,server/index.ts 读取根目录 seerr-api.yml 规范文件,同时交给 swagger-ui-express 渲染文档、交给 express-openapi-validator 做请求校验,因此 API 文档与实际路由严格同源。

从 Overseerr / Jellyseerr 迁移

Seerr 是 Overseerr/Jellyseerr 生态的延续(README 说明了其对既有用户的迁移路径)。迁移要点:

支持与社区

  • 提问前优先查阅 docs/ 下的完整文档;
  • 社区行为准则见 CODE_OF_CONDUCT.md,对所有社区频道生效;
  • 贡献者可从 CONTRIBUTING.md 开始,仓库还配置了 commitlint(Conventional Commits)、ESLint、Prettier 与 lint-staged 等工程化约束;
  • 代码质量保障方面,后端基于 Node 内置测试运行器与 supertest(见 server/test/),端到端测试使用 Cypress(cypress/e2e/),覆盖登录、发现页、影视详情、用户管理等主流程。

小结

Seerr 的核心价值在于把"发现—请求—审批—自动化获取—媒体呈现"整条链路收敛到统一的 Web 界面中:三家媒体服务器认证与库扫描保证"已有哪些"一目了然,Sonarr/Radarr 集成让"请求后自动补片"成为现实,细粒度权限与多通道通知让多用户协作井然有序,而 PostgreSQL/SQLite 双数据库选择则兼顾了轻量部署与生产级扩展。无论你是个人家庭影音库用户,还是需要为多人团队搭建媒体请求平台,都可以从本文梳理的功能矩阵与源码路径入手,快速评估并部署这套方案。

Seerr 应用界面预览

登录后查看全文
seerr