Guardian

给 Plex 装上“门禁”：Guardian 的实时设备准入设计与实现

项目背景与痛点

Plex 的媒体共享机制有个先天缺陷：授权是“一次性”的，而访问是“永久”的。你邀请一位朋友进入库，他从此可以在任意设备、任意时间、任意地点登录，而你能看到的只是一个事后更新的“设备列表”。Plex 自带的手段只有两个——查看当前会话、手动终止播放，本质上都是事后的观测与补救，而不是准入控制。

现实中由此衍生的麻烦几乎每个家庭服务器主人都遇到过：共享账号被二次转发给陌生人、朋友换了台电视却没人知道、凌晨三点有异地 IP 在拉流、孩子的平板绕过了分级限制。Tautulli 能把这些记录下来，但它只负责“看见”，不负责“拦住”。

Guardian 的定位非常明确：它要做的不是又一个监控面板，而是 Plex 前面的一道可编程门禁——实时判定、实时放行或阻断，并且把“给陌生人临时开个口子”这件事变成一次带有效期的授权。

核心技术揭秘

从公开仓库的形态推断，Guardian 是一个典型的单容器自托管服务：Node.js 后端 + React 前端 + SQLite 单文件存储，整体打包成 Docker 镜像。选择 SQLite 而非 Postgres 是有意为之——家庭 NAS 场景下“零外部依赖、一个卷搞定备份”的价值远高于并发能力。

它的数据流可以概括为：事件接入 → 指纹归一化 → 策略求值 → 执行或挂起 → 持久化。

几个值得细看的设计点：

双通道事件源。 Webhook 延迟低，但依赖 Plex Pass 且要求 Plex 服务器能反向访问 Guardian；轮询 /status/sessions 则无此限制，只是有秒级到十几秒的延迟窗口。两者并存意味着 Guardian 必须处理同一会话的重复事件——工单创建要做幂等，否则一次播放能给你刷出五条待审批通知。

设备指纹是真难点。 Plex 会话里的 machineIdentifier 是最可靠的主键，但客户端重装、换端、更新后都可能变化。如果直接拿设备名做匹配，几乎必然误判——谁都能把播放器命名为 “Living Room TV”。合理做法是用 machineIdentifier + 用户 ID 建立强绑定，辅以 IP 网段、平台类型做软指纹匹配；但这仍然是一个有假阳性的启发式，这也是此类系统难以彻底消灭的边界问题。

三态判定而非布尔值。 策略引擎的返回值应当是 allow / deny / pending。前两者可立即执行，pending 才触发审批流。这决定了系统不是“静态黑白名单”，而是带人工介入的准入队列。临时访问在此基础上再加一层 TTL：授权记录带过期时间，到期后状态机自动由 approved 迁移到 expired，无需人工回收。

执行的脆弱性。 终止会话依赖 /status/sessions/terminate，而会话 ID 生命周期很短。策略判定与执行之间若间隔过久，请求可能落空——所以判定结果必须携带最新会话快照，或执行前重取一次。这类竞态是“实时阻断”类工具最常见的线上故障源。

功能亮点与差异

与 Tautulli、Ombi 这类同生态工具相比，Guardian 的差异不在功能数量，而在位置：

• 它是执行器，不是观测器。 判定结果直接落到 Plex API 上——终止会话、拒绝登录、放行播放，形成闭环。监控工具告诉你“有人在看”，Guardian 决定“他能不能看”。
• 双层策略模型。 全局默认策略兜底，用户级策略覆盖，避免了“给每个人单独配一遍”的运维成本。
• 临时授权（time-boxed access） 是它最实用的杀手锏。给临时访客开一个 24 小时窗口，到期自动失效，不用记得回头去删权限——这是 Plex 原生完全没有的能力。
• 部署零负担。 单容器、单文件数据库、Web UI 自带，不需要 Redis、不需要消息队列，插上就能用。对家庭服务器而言，这比任何架构先进性都重要。

应用场景与落地建议

最适合三类场景：家庭 Plex 共享给少量朋友、小型影迷社群/字幕组的内部库、有未成年人使用需求的家庭环境。

上生产前有几条必须注意：

1. Plex Token 等同密码。 Guardian 持有它等于持有你整个服务器的控制权，务必走 HTTPS 反代 + 强口令，绝不要把裸端口暴露到公网。
2. 给自己留后门。 明确把管理员账号、服务器本机、常用设备加入豁免名单。策略写错把自己锁在门外，是这类工具最经典的翻车方式。
3. 想清楚 fail-open 还是 fail-closed。 Guardian 挂了，是放行所有播放，还是阻断一切？对家庭场景，fail-open 几乎总是正确选择——门禁失效不该导致全家看不了电影。
4. 轮询间隔别贪快。 10–30 秒足够，过密会加重 Plex 转码节点的 API 负担。
5. 依赖未公开 API 的风险要认。 Plex 服务端升级导致接口变动时，Guardian 可能需要跟进修复，升级前先看 issue 区。

综合评价

优点：定位极其精准，补的是 Plex 生态里真实存在却长期无人填的坑；判定—执行闭环完整，而非又一个仪表盘；单容器 + SQLite 的克制选型，把部署成本压到了家庭用户能接受的水平；临时授权这一设计有真正的产品直觉。

缺点：设备指纹依赖启发式匹配，误判无法根除；对 Plex 私有 API 的深度耦合意味着版本升级随时可能打断；单写者 SQLite 与单实例架构限制了多服务器集群场景；项目社区规模尚小，边缘 case 的测试覆盖和长期维护承诺仍需观察。

一句话总结：如果你只是想知道谁在看片，Tautulli 够了；如果你想决定谁能看片，Guardian 是目前最省事的答案——前提是你接受它站在一个不算稳固的 API 地基上。