本项目是一个功能强大的 Emby 代理服务器。它作为中间层部署在您的 Emby 客户端（如浏览器、手机APP）和真实的 Emby 服务器之间。通过智能地拦截和修改客户端与服务器之间的通信数据（API请求），本项目实现了许多 Emby 原生不支持的高级功能，极大地增强了您的媒体库管理和浏览体验。
点击展开/折叠更新日志
- 新功能:
- 增强高级筛选器 (添加日期):
- 新增了对
添加日期 (DateCreated)的原生筛选支持。 - 同样支持动态日期筛选功能。用户现在可以保存“最近 N 天内添加”的规则，系统会自动转换为 Emby 原生的
MinDateCreated参数进行高效处理。
- 新增了对
- 增强高级筛选器 (添加日期):
- 优化:
- Docker 构建优化:
- 优化了
Dockerfile，将npm、apt和pip的软件源全部更换为国内镜像（阿里云/清华源），显著提升了在国内环境下的镜像构建速度。
- 优化了
- 同步更新文档:
- 在高级筛选器管理界面的“性能指南”中，同步更新了“高效筛选规则对照表”，加入了对“添加日期”的支持说明。
- Docker 构建优化:
- 新功能:
- RSS 数据保留机制:
- 新增“开启数据保留”功能。针对 RSS 类型的虚拟库，现在可以选择保留即使已从源中消失的条目。
- 实现了可配置的“保留天数”。用户可以指定条目在本地库中的最长存活时间（默认为 7 天，0 为永久保留），系统会自动清理过期的旧条目。
- 此功能完美解决了因 RSS 源更新过快导致未入库条目被意外“顶出”和移除的问题。
- RSS 数据保留机制:
- 重构与优化:
- Bangumi 匹配逻辑全面升级:
- 移除了对外部匹配 API 的依赖，转为完全本地化的智能匹配。
- 多策略搜索: 引入了 5 种优先级的搜索策略（包括精确名、去后缀名等），显著提高了搜索覆盖率。
- 智能打分系统: 新增了基于“文本相似度 + 动画类型 + 媒体格式 + 年份”的综合打分算法，确保匹配结果的精准度。
- 数据库缓存: 新增
bangumi_cache.db，对 API 响应和匹配结果进行持久化缓存，大幅减少网络请求并提升响应速度。
- Bangumi 匹配逻辑全面升级:
- 重构与优化:
- Bangumi 匹配逻辑全面升级:
- 移除了对外部匹配 API 的依赖，转为完全本地化的智能匹配。
- 多策略搜索: 引入了 5 种优先级的搜索策略（包括精确名、去后缀名等），显著提高了搜索覆盖率。
- 智能打分系统: 新增了基于“文本相似度 + 动画类型 + 媒体格式 + 年份”的综合打分算法，确保匹配结果的精准度。
- 数据库缓存: 新增
bangumi_cache.db，对 API 响应和匹配结果进行持久化缓存，大幅减少网络请求并提升响应速度。
- Bangumi 匹配逻辑全面升级:
- 新功能:
- 增强 RSS 虚拟库:
- 新增“追加 TMDB ID”功能。现在，在编辑 RSS 虚拟库时，您可以额外指定一个 TMDB ID 和媒体类型。
- 该指定的影视项目将会被无条件地追加到从 RSS 源解析出的条目列表中，一同在虚拟库中显示。
- 此功能主要用于确保即使 RSS 源匹配失败或内容为空时，该虚拟库中也至少能显示一个您指定的项目。
- 增强 RSS 虚拟库:
- 修复:
- 修复 RSS 处理器初始化错误: 解决了因
BaseRssProcessor基类构造函数变更后，未同步更新DoubanProcessor和BangumiProcessor子类而导致的TypeError，确保 RSS 库刷新功能可正常使用。
- 修复 RSS 处理器初始化错误: 解决了因
- 新功能:
- 增强高级筛选器 (动态日期):
- 新增了对
首播日期 (PremiereDate)的原生筛选支持。 - 实现了真正的动态日期筛选功能。用户现在可以保存“最近30天内”这样的相对时间规则，筛选器会在每次执行时动态计算日期范围，而不仅仅是在设置时转换一次。
- 新增了对
- 增强高级筛选器 (动态日期):
- 优化:
- 优化:
- 提升用户体验: 优化了“首播日期”筛选器的 UI，允许用户在绝对日期和相对时间之间自由切换，并支持手动输入任意天数（如“最近15天内”），提供了极高的灵活性。
- 同步更新文档: 在高级筛选器管理界面的“性能指南”中，同步更新了“高效筛选规则对照表”，加入了对新功能的支持说明。
- 新功能:
- 增强高级筛选器:
- 大幅扩展了高级筛选器的能力，新增了对多个 Emby API 原生筛选参数的支持，包括
影评人评分、名称以...开头、剧集状态、是否有字幕、是否有官方评级等。 - 这使得用户可以创建更精细、更强大的筛选规则，并且由于更多规则可以直接被 Emby 服务器原生处理，筛选效率也将得到提升。
- 大幅扩展了高级筛选器的能力，新增了对多个 Emby API 原生筛选参数的支持，包括
- 增强高级筛选器:
- 优化:
- 同步更新性能指南: 在高级筛选器管理界面的“性能指南”中，同步更新了“高效筛选规则对照表”，加入了所有新增的高效筛选规则及其用法说明，确保了文档与功能的一致性。
- 优化:
- 实现资源选择无限滚动: 对虚拟库编辑页面的“选择资源”下拉框（包括工作室、人员、类型等）进行了全面优化。现在，列表将随着您的滚动动态加载，极大地提升了拥有大量项目（如数千个工作室或演员）的用户的加载性能和使用流畅性。
- 修复:
- 修复加载闪烁问题: 解决了在滚动加载“人员”列表时，下拉框会短暂消失或闪烁的问题，确保了平滑的滚动加载体验。
- 修复类型切换逻辑: 修复了在对话框内切换资源类型（例如从“工作室”切换到“人员”）时，列表不会自动刷新的问题。
- 修复:
- 增强高级筛选器准确性: 修复了当高级筛选器中包含
IsMovie: 'true'或IsSeries: 'true'规则时，Emby API 请求仍可能返回不符合类型内容的问题。现在，代理服务器会强制将IncludeItemTypes参数分别设置为Movie或Series，确保筛选结果的准确性。
- 增强高级筛选器准确性: 修复了当高级筛选器中包含
- 新功能:
- 新增临时素材上传功能:
- 在虚拟库编辑页面的“封面生成”部分，新增了图片上传功能。
- 用户现在可以临时上传最多9张本地图片，作为生成封面的素材。
- 上传的图片将作为最高优先级的素材源。
- 新增临时素材上传功能:
- 优化:
- 上传素材随机选择: 当上传的图片数量超过封面样式所需时，程序会从中随机抽选，确保每次生成的封面都有所不同。
- 新功能:
- 封面生成功能增强:
- 新增封面中文标题: 在虚拟库编辑页面，现在可以为封面单独设置中文主标题，留空则默认使用虚拟库名称。
- 新增虚拟库级自定义字体: 在虚拟库编辑页面，可以为单个虚拟库指定不同于全局设置的自定义中英文字体。
- 新增虚拟库级自定义图片目录: 在虚拟库编辑页面，可以为单个虚拟库指定一个独立的图片文件夹，封面生成器将从该目录中抓取图片素材。
- 新增全局自定义图片目录:
- 在“系统设置”页面，新增了“全局自定义图片目录”选项。
- 此目录将作为虚拟库未指定自定义图片目录时的“后备”或“默认”图片源。
- 封面生成功能增强:
- 新功能:
- 新增封面生成自定义字体选项:
- 在“系统设置”页面，新增了“自定义中文字体路径”和“自定义英文字体路径”的选项。
- 用户现在可以指定在 Docker 容器内的字体文件绝对路径，用于生成包含自定义字体的封面。
- 如果不填写，系统将自动使用内置的默认字体。
- 新增封面生成自定义字体选项:
- 重构与增强:
- 重构 RSS 处理器:
- 对
rss_processor模块进行了彻底重构，将douban.py和bangumi.py中的通用逻辑（如RSS获取、Emby库匹配、TMDB信息缓存等）提取到一个新的base_processor.py基类中。 - 此举极大地简化了代码，提高了代码复用性，并为未来支持更多类型的 RSS 源奠定了坚实的基础。
- 对
- 新增通用兜底匹配方案:
- 为 RSS 处理器增加了一个强大的兜底匹配机制。现在，当通过源站 ID（如豆瓣 ID）的精确匹配失败时，系统会自动尝试使用项目的标题和年份在 TMDB 上进行搜索匹配。
- 这一改进将显著提高 RSS 虚拟库中项目的 TMDB ID 匹配成功率。
- 重构 RSS 处理器:
- 新功能:
- 新增“全局强制按 TMDB ID 合并”功能:
- 在“系统设置”页面增加了一个全局开关。
- 启用后，此开关将覆盖所有虚拟库的独立设置，强制对所有媒体内容执行 TMDB ID 合并。
- 这为希望在整个媒体库中统一合并策略的用户提供了极大的便利。
- 新增“全局强制按 TMDB ID 合并”功能:
- 新功能:
- 新增“RSS”虚拟库类型 (目前仅支持豆瓣):
- 在创建虚拟库时，新增了“RSS”作为资源类型。此功能允许您将一个 RSSHub 生成的豆瓣订阅源（如“想看”、“在看”、“看过”列表）映射为一个动态更新的媒体库。
- 混合内容展示: 虚拟库会自动区分 RSS 源中的项目哪些已在您的 Emby 库中，哪些尚未入库。
- 占位符生成: 对于尚未入库的项目，代理会利用 TMDB API 获取其元数据（海报、简介、年份等），并动态生成一个“占位符”项目。这使您可以在 Emby 中直观地浏览和管理您的“待看”清单。
- 手动刷新: 您可以在虚拟库管理页面随时手动刷新 RSS 源，以同步最新内容。
- 新增“RSS”虚拟库类型 (目前仅支持豆瓣):
- 重要说明:
- 数据源: 当前版本仅支持解析通过 RSSHub 生成的豆瓣相关订阅链接。
- 依赖: 此功能需要正确配置“TMDB API 密钥”才能为未入库的项目生成占位符。
- 新功能:
- 新增“显示缺失剧集”功能:
- 在“系统设置”中增加了一个“显示缺失的剧集”开关。
- 启用后，当您浏览电视剧的季页面时，代理服务器会自动通过 TMDB API 查询该季的完整剧集列表。
- 将查询结果与您本地库中已有的剧集进行对比，并将缺失的剧集动态注入到显示列表中。
- 这使您可以直观地看到哪些剧集尚未收藏，方便补全。
- 新增 TMDB API Key 设置:
- 为了支持上述功能，在“系统设置”中增加了“TMDB API 密钥”的配置项。您需要填入自己申请的有效密钥。
- 支持为缺失剧集自定义占位图:
- 所有通过此功能动态添加的缺失剧集，都会显示一个统一的占位图。
- 您可以通过替换项目路径
src/assets/images_placeholder/placeholder.jpg下的图片文件，来轻松自定义您喜欢的占位图样式（推荐使用16:9比例的图片）。
- 新增 TMDB HTTP 代理设置:
- 在“系统设置”中增加了“TMDB HTTP 代理”选项。
- 如果您的服务器无法直接访问 The Movie Database，现在可以配置一个 HTTP 代理来确保网络通畅。
- 新增“显示缺失剧集”功能:
- 修复:
- 修复缺失剧集无法显示的问题: 解决了因构造的缺失剧集数据对象缺少
ServerId,Overview,PremiereDate等关键字段，而导致 Emby/Jellyfin 客户端拒绝渲染这些项目的问题。
- 修复缺失剧集无法显示的问题: 解决了因构造的缺失剧集数据对象缺少
- 新功能:
- 新增“全库”虚拟库类型: 在创建虚拟库时，新增了“全库 (All Libraries)”作为资源类型。选择此类型后，虚拟库将包含所有媒体库的内容，可配合高级筛选器实现对整个 Emby 媒体资源的灵活筛选。
- 修复:
- 修复“全库”类型无法保存的问题: 调整了前端验证逻辑，允许在资源类型为“全库”时，无需指定具体的资源 ID 即可保存。
- 修正“全库”类型在首页的“最新”栏目显示:
- 修复了当虚拟库类型为“全库”时，首页“最新”项目请求逻辑不正确的问题，确保能够正确展示所有媒体库的最新内容。
- 通过强制筛选媒体类型，解决了“最新”栏目中错误地显示其他虚拟库（而非实际影视项目）的问题。
- 重构:
- 移除访问控制: 删除了之前版本中添加的密码保护和 API 密钥白名单功能。此功能与项目核心目标（增强媒体库管理）关联不大，且增加了不必要的复杂性。
- 前端: 从系统设置页面移除了相关配置项。
- 后端: 删除了
handler_auth.py认证模块，并更新了proxy_server.py和models.py以移除所有相关逻辑和配置。
- 移除访问控制: 删除了之前版本中添加的密码保护和 API 密钥白名单功能。此功能与项目核心目标（增强媒体库管理）关联不大，且增加了不必要的复杂性。
- 新功能:
- 新增访问控制: 为整个代理服务增加了可选的密码保护和 API 密钥白名单功能。
- 密码保护: 可在配置文件中设置密码，启用后，通过浏览器访问将需要输入密码进行验证。
- API密钥白名单: 可在配置文件中设置一组受信的 Emby API 密钥，只有使用这些密钥的客户端（如 Infuse, Jellyfin APP等）才能访问，增强了安全性。
- IP信任机制: 客户端通过验证后，其 IP 地址将被临时信任24小时，避免了重复验证。
- 新增访问控制: 为整个代理服务增加了可选的密码保护和 API 密钥白名单功能。
- 修复: 彻底解决了因多种原因导致的视频播放和字幕加载失败问题，大幅提升了代理的稳定性和兼容性。
- 健壮性: 移除了实验性的
PlaybackInfo拦截逻辑。该逻辑在处理部分客户端或 Emby 版本时不够稳定，是导致播放失败的潜在原因之一。现在代理将直接、可靠地转发所有播放信令。 - 兼容性: 解决了因 Emby 服务端启用 Brotli 压缩而代理服务器缺少相应解码支持的问题。通过在项目中添加
Brotli依赖库，确保能正确处理各类压缩数据，消除了由此引发的502 Bad Gateway错误。
- 健壮性: 移除了实验性的
- 修复: 解决了更新已有封面的虚拟库（如修改高级筛选器）后，会导致封面信息丢失的问题。现在，在保存虚拟库设置时，程序会正确保留其
ImageTag。 - 修复: 解决了启用“TMDB ID合并”功能时，因错误地在分页后的部分数据上执行合并而导致项目总数计算不正确的问题。现在，程序会先获取所有相关项目，在完整数据集上执行合并后，再进行分页，确保了项目总数的准确性。
- 架构升级:
- 部署模式简化: 将原有的
admin和proxy双容器架构，重构为使用supervisor管理的单容器架构。 - 简化部署: 更新了
docker-compose.yml，现在只需管理单个服务，部署和维护流程更简单。 - 文档同步: 同步更新了
README.md中的快速开始指南，以匹配新的单容器部署模式。
- 部署模式简化: 将原有的
- 新功能:
- 一键清空封面: 在“系统设置”中新增“清空所有本地封面”功能，方便用户一键删除所有已生成的封面并重置状态。
- 新功能:
- 多种封面样式: 手动生成封面时，现在可以在三种不同的内置样式（一种多图、两种单图）中自由选择。
- 全局默认样式: 在“系统设置”中新增了“自动生成封面默认样式”选项，用于控制自动触发的封面生成所使用的样式，并会持久化保存。
- 修复与优化:
- 修复封面生成器: 解决了单图样式因参数不匹配而无法生成的问题，确保所有样式都能正常工作。
- 优化UI/UX:
- 修复了亮色模式下“夜间模式”切换按钮几乎不可见的问题。
- 在封面生成弹窗中增加了必要的操作说明，优化了用户体验。
- 将UI中的“收藏夹”统一修正为“合集”，使其更符合 Emby/Jellyfin 的通用术语。
- 增强兼容性:
- 新增非标准客户端兼容模式: 针对部分行为特殊的第三方播放器（如某些版本的网易爆米花、Infuse 等），增加了后备处理方案。现在，即使客户端不按标准流程请求媒体库，也能正确识别并展示虚拟库。
- 统一认证头转发: 全面审查并统一了所有API处理器的请求头转发逻辑，确保
X-Emby-Token等关键认证信息在所有情况下都能被正确传递，彻底解决401 Unauthorized错误。
- 修复:
- 修正
/Items/Latest响应格式: 修复了“最近添加”接口返回的数据被错误包装在JSON对象中的问题。现在接口会直接返回客户端预期的JSON数组，解决了部分客户端无法加载首页最新项目的错误。
- 修正
- 项目首次发布: 部署 Emby Virtual Proxy 初始版本。
- 核心功能:
- 实现虚拟媒体库、高级内容过滤与聚合。
- 支持为虚拟库自动生成风格化封面。
- 管理后台: 提供基于 Vue.js 的现代化 Web UI 用于全部功能配置。
- 容器化: 支持通过 Docker 和 Docker Compose 进行快速、一键式部署。
-
在您的服务器上创建一个目录，例如
emby-proxy。 -
在该目录下，创建一个名为
docker-compose.yml的文件。 -
将以下内容复制并粘贴到
docker-compose.yml文件中：version: '3.8' services: emby-proxy: image: pipi20xx/emby-virtual-proxy container_name: emby-proxy ports: # 管理后台端口，左边为主机端口，右边为容器端口 - "8011:8001" # 代理核心端口，左边为主机端口，右边为容器端口 - "8999:8999" volumes: # 挂载配置文件和生成的封面目录，确保数据持久化 - ./config:/app/config # 挂载Docker sock，允许后台通过API重启服务 - /var/run/docker.sock:/var/run/docker.sock environment: # 环境变量：告诉管理服务要重启的容器名（即自身） - PROXY_CONTAINER_NAME=emby-proxy # 环境变量：告诉管理服务如何访问同一容器内的代理服务 - PROXY_CORE_URL=http://localhost:8999 restart: unless-stopped
-
在
docker-compose.yml文件所在的目录中，运行以下命令启动服务：docker-compose up -d
-
部署成功后：
- 访问管理后台:
http://<您的服务器IP>:8011 - 在Emby中配置代理: 将Emby客户端（如Infuse, Emby Web）的服务器地址改为
http://<您的服务器IP>:8999
- 访问管理后台:
- 动态创建: 您可以创建任意数量的“虚拟媒体库”，这些库并不在 Emby 服务器上真实存在。
- 内容聚合: 虚拟库的内容可以基于 Emby 中已有的元数据动态生成，支持的源类型包括：
- 合集 (Collections)
- 标签 (Tags)
- 类型 (Genres)
- 工作室 (Studios)
- 演职人员 (Persons)
- 应用场景: 轻松创建如 “漫威电影宇宙”、“周星驰作品集”、“豆瓣Top250” 等完全自定义的媒体库，并让它们像真实库一样展示在主页上。
- TMDB ID 合并: 自动将在不同资料库中但拥有相同
TheMovieDb.org ID的电影或剧集进行聚合。当您在“最近添加”或媒体库视图中浏览时，将只看到一个条目，有效解决版本重复（如 1080p 和 4K 版本）的问题。 - 高级过滤规则: 提供了一个强大的规则引擎，允许您组合多个复杂的条件来过滤媒体内容，实现 Emby 原生无法做到的精确筛选。
- 自动化海报: 可为创建的虚拟媒体库一键生成风格化的海报封面。
- 智能素材抓取: 该功能会自动从虚拟库中随机选取部分影视项目的现有封面作为素材。
- 高度自定义: 将抓取的素材智能拼接成一张精美的海报，并允许您添加自定义的中英文标题。
- 一站式管理: 项目内置一个基于 Vue.js 和 Element Plus 的美观、易用的网页管理界面。
- 功能全面: 您可以在此UI上完成所有配置和管理工作，包括：
- 系统设置（连接 Emby 服务器、API 密钥等）。
- 创建、编辑、删除虚拟库和高级过滤规则。
- 通过拖拽调整虚拟库和真实库在 Emby 主页的显示顺序。
- 手动触发封面生成、清除代理缓存等维护操作。
- 开箱即用: 项目提供完整的
Dockerfile和docker-compose.yml文件，支持使用 Docker 进行一键部署。 - 服务分离: 采用双容器架构（代理核心服务 + 管理后台服务），结构清晰，易于维护。
- API控制: 管理后台可以通过 Docker API 直接控制代理核心，实现如“重启服务以清空缓存”等高级操作。
目前所有客户端都兼容个人只测试了小幻,yamby,EMBY小秘,Forward,senplay如果遇到不兼容请提出并留下客户端名称
- 后端 (Backend):
- 框架: Python
FastAPI - 异步处理:
aiohttp用于与 Emby 服务器进行高性能的异步HTTP通信。 - 缓存:
cachetools用于实现内存缓存，加速API响应。
- 框架: Python
- 前端 (Frontend):
- 框架/构建:
Vue.js 3+Vite - 状态管理:
Pinia - UI 组件库:
Element Plus
- 框架/构建:
本项目的设计和功能受到了以下优秀项目的启发，特此感谢：
总而言之，Emby Virtual Proxy 是一个为 Emby 高级玩家和收藏家设计的强大工具，它通过“代理”这一巧妙的方式，无侵入性地为您的 Emby 带来了前所未有的灵活性和可定制性。