JellyPlex-Watched

镜像概述

JellyPlex-Watched是一款用于在本地环境中同步Jellyfin和Plex媒体服务器之间用户观看历史记录的工具。它通过文件名和内容提供商ID匹配电影/剧集，支持多服务器配置（通过逗号分隔参数），可自定义同步方向、用户/媒体库映射及筛选规则，适用于需要保持多平台观看记录一致性的场景。

核心功能与特性

• 本地同步机制：无需云端服务，直接在本地网络中实现Jellyfin与Plex间的观看历史同步
• 多服务器支持：通过逗号分隔配置，可同时连接多个Plex和Jellyfin服务器
• 灵活映射规则：支持用户账号映射（解决不同服务器用户名差异）和媒体库映射（解决库名称差异）
• 细粒度同步控制：可配置同步方向（如Plex→Jellyfin、Jellyfin→Plex、服务器间互相同步等）
• 筛选功能：提供媒体库、库类型及用户的黑白名单机制，精确控制同步范围
• 调试与日志：支持干运行模式（仅记录不执行操作）、详细日志输出及调试级别调整
• 安全选项：可跳过SSL证书验证，解决自签名证书导致的连接问题

使用场景

适用于以下场景：

• 同时运行Jellyfin和Plex服务器的家庭媒体中心
• 需要在多台Plex/Jellyfin服务器间保持观看记录一致的用户
• 从Plex迁移到Jellyfin过程中需保留历史观看记录的过渡阶段
• 多用户共享媒体库环境下，确保各平台观看进度同步

配置说明

所有配置通过环境变量或.env文件设置，主要配置项如下：

全局设置

Plex 服务器配置

若不使用令牌，可配置PLEX_USERNAME、PLEX_PASSWORD、PLEX_SERVERNAME（均为逗号分隔多服务器）

Jellyfin 服务器配置

使用方法

前提条件

• 已部署Jellyfin和/或Plex服务器并可网络访问
• 获取Plex令牌（获取方法）
• 获取Jellyfin API令牌（Jellyfin管理界面→控制台→API密钥→新增）

Docker部署步骤

1. 获取镜像

使用预构建镜像（推荐）：

docker pull luigi311/jellyplex-watched:latest

或本地构建：

git clone [***]
cd JellyPlex-Watched
docker build -t jellyplex-watched .

2. 运行容器

方式1：通过环境变量直接配置

适用于简单场景，直接在命令行指定关键参数：

docker run --rm -it \
  -e PLEX_BASEURL="[***]" \
  -e PLEX_TOKEN="your-plex-token-here" \
  -e JELLYFIN_BASEURL="[***]" \
  -e JELLYFIN_TOKEN="your-jellyfin-token-here" \
  -e DRYRUN="False" \
  -e SLEEP_DURATION="1800" \
  luigi311/jellyplex-watched:latest

方式2：通过.env文件配置（推荐）

适用于复杂配置，便于管理多个参数：

1. 创建.env文件（参考项目.env.sample）：

# 全局设置
DRYRUN="False"
DEBUG="False"
SLEEP_DURATION="3600"
USER_MAPPING='{"plex_user":"jellyfin_user"}'
LIBRARY_MAPPING='{"TV Shows":"Series"}'
WHITELIST_USERS="family_user,kid_user"

# Plex设置
PLEX_BASEURL="[***]"
PLEX_TOKEN="token1,token2"
SYNC_FROM_PLEX_TO_JELLYFIN="True"
SYNC_FROM_PLEX_TO_PLEX="True"
SSL_BYPASS="False"

# Jellyfin设置
JELLYFIN_BASEURL="[***]"
JELLYFIN_TOKEN="jellyfin-token-here"
SYNC_FROM_JELLYFIN_TO_PLEX="True"
SYNC_FROM_JELLYFIN_TO_JELLYFIN="False"

2. 运行容器并挂载.env文件：

docker run --rm -it -v "$(pwd)/.env:/app/.env" luigi311/jellyplex-watched:latest

验证与调试

• 首次运行建议先使用DRYRUN="True"测试配置，查看日志确认同步逻辑是否符合预期
• 日志文件默认位于容器内/app/log.log，可通过挂载日志目录持久化日志：

  docker run --rm -it -v "$(pwd)/.env:/app/.env" -v "$(pwd)/logs:/app/logs" -e LOGFILE="logs/sync.log" luigi311/jellyplex-watched:latest
  

• 同步异常时，可开启DEBUG="True"和DEBUG_LEVEL="debug"获取详细调试信息

注意事项

• 多服务器配置时，URL、令牌等参数需按相同顺序用逗号分隔（如第一个URL对应第一个令牌）
• 用户/库映射会影响黑白名单筛选（即映射前后的名称均会被纳入筛选范围）
• 同步依赖内容元数据匹配，特殊命名或元数据缺失的媒体可能无法正确同步
• 建议先在非生产环境测试同步规则，确认无误后再应用到正式环境