WatchState

!构建状态 !MIT许可证 !Docker拉取量 !ghcr拉取量

该工具的主要目标是在不依赖第三方服务的情况下同步后端用户的播放状态，开箱即用地支持Jellyfin、Plex和Emby媒体服务器。

更新日志

2025-08-18

我们添加了标记v1.0.0前的最后一个功能：现在可以搜索数据库中的重复文件引用。如果您有多个后端引用同一文件但报告不同元数据，此功能非常有用。

若要跳过多集项目，请进入后端页面，从快速操作列表中选择“从此后端强制导入元数据”，这将重新创建元数据，并包含标记多集项目的标志。

后续更新将主要关注错误修复、性能改进以及文档更新。

2025-08-14

我们计划在2025年第四季度标记v1.0.0，因此如果您依赖已弃用的行为或功能，请开始迁移到我们已实现的新替代方案。在v1.0.0前将移除的内容，我们将在未来几周记录所有即将移除的已弃用功能。最值得注意的是将移除每个用户/后端的webhook端点。

请参阅NEWS获取最新更新和变更。

核心功能

• 通过WebUI管理
• 子用户支持
• 同步后端播放状态（多对多或单向）
• 将后端播放状态备份为可移植格式
• 接收来自媒体后端的webhook事件
• 查找不匹配或错误匹配的项目
• 搜索后端元数据
• 通过一致性检查验证媒体服务器是否报告相同数据
• 通过webhook或计划任务同步观看进度/播放状态
• 检查媒体后端是否存在对旧文件的过时引用

如果您喜欢我的作品，您可能也会喜欢我的另一个项目YTPTube，这是一个简单直接的前端，帮助从支持的所有网站下载内容。

安装方法

如果您更喜欢视频格式，AlienTech42 ***频道有一个关于使用unraid安装WatchState的视频链接。非常感谢。

注意：我不认识该频道所有者，但感谢其付出。视频中关于webhook URL有一个小错误，请直接从后端页面复制URL。此外，该工具支持多用户。

首先，创建一个目录来存储数据，为了遵循此设置，请在工作目录中创建名为data的目录。然后按照您喜欢的方法安装工具。

通过compose文件

在data目录旁创建compose.yaml，并添加以下内容：

services:
    watchstate:
        image: ghcr.io/arabcoders/watchstate:latest
        # 要更改工具关联的用户/组ID，请修改以下行
        user: "${UID:-1000}:${GID:-1000}"
        container_name: watchstate
        restart: unless-stopped
        ports:
            - "8080:8080" # WebUI可用的端口
        volumes:
            - ./data:/config:rw # 将当前目录挂载到容器的/config目录

接下来，使用以下命令运行容器：

$ docker compose up -d

通过docker命令

$ docker run -d --rm --user "${UID:-1000}:${GID:-1000}" --name watchstate --restart unless-stopped -p 8080:8080 -v ./data:/config:rw ghcr.io/arabcoders/watchstate:latest

[!IMPORTANT] 至关重要的是，user:或--user要与data目录的所有者匹配，容器是无root权限的，因此如果无法写入数据目录，容器将崩溃。

不建议以root身份运行容器，但如果运行失败，可尝试设置user: "0:0"或--user '0:0'。如果这能工作，说明存在权限问题。请参考FAQ排查问题。

Unraid用户

对于Unraid用户，您可以安装Community Applications插件，搜索watchstate，它已预先配置。否则，要手动安装，需要在高级选项卡/视图的“额外参数”部分添加值：--user 99:100。

这必须在启动容器之前完成，否则容器将使用旧的用户ID，之后您需要从终端运行以下命令：chown -R 99:100 /mnt/user/appdata/watchstate。

使用Podman而非Docker

要使用Podman运行此容器，将compose.yaml中的user设置为0:0。在容器内看似以root身份运行，但实际上会映射到运行命令的用户。

管理方法

启动容器后，可通过浏览器访问http://localhost:8080打开WebUI。

[!NOTE] 首次使用时，系统会提示创建新的系统用户，这是一次性操作。

要添加后端，请点击右上角的帮助按钮，选择单向或双向同步方法，并按照说明操作。

添加后端并导入数据后，您将看到类似以下的界面：

!WebUI

支持的导入方法

目前，该工具支持三种从后端导入数据的方法：

• 计划任务
  • 按计划从后端拉取数据的定时作业
• 按需导入
  • 手动运行导入任务，按需从后端拉取数据
• Webhooks
  • 接收来自后端的事件并相应更新数据库

[!NOTE] 即使所有后端都支持webhooks，也应保持导入任务启用。这有助于维持健康的数据同步，并捕获任何遗漏的事件。有关webhooks限制的更多信息，请查看webhook指南。

常见问题

请查看常见问题页面或指南，获取有关配置的更多深入说明。

社交渠道

如果您有简短或快速的问题，或只想与其他用户交流，欢迎加入此***服务器。请注意，这是个人项目，因此我可能需要一些时间回复问题，我的工作时区为UTC+3。

***

如果您想并支持我的工作，可以向儿童慈善机构。例如国际许愿基金会。