tautulli

核心用法

Tautulli Skill 是一套用于监控 Plex Media Server 的轻量级命令行工具集，通过调用 Tautulli 的 REST API 实现数据查询。用户需预先配置 TAUTULLI_URL 和 TAUTULLI_API_KEY 两个环境变量，即可通过六个独立脚本获取服务器状态：

• activity.sh：实时查看当前播放流，包括用户名、影片标题、播放进度、画质及播放设备
• history.sh：查询观看历史，支持自定义返回条数（默认10条）
• libraries.sh：列出所有媒体库分区及内容数量统计
• recent.sh：查看最近添加的媒体内容
• users.sh：获取用户列表及总观看时长、最后活跃时间
• server.sh：显示 Plex 服务器名称、版本、平台及连接状态

所有脚本均采用统一的 API 调用模式，通过 curl 发送 GET 请求至 $TAUTULLI_URL/api/v2，并使用 jq 解析 JSON 响应。

显著优点

1. 零侵入式监控：纯只读查询，不修改任何服务器配置，风险极低
2. 轻量依赖：仅需系统自带的 curl 和 jq，无需额外运行时或复杂依赖链
3. 脚本化工作流：适合集成到自动化脚本、定时任务或通知系统中
4. 清晰的输出格式：通过 jq 格式化后的数据便于人工阅读或二次处理
5. 配置灵活：通过环境变量管理连接信息，支持多实例切换

潜在缺点与局限性

1. 功能只读：无法执行管理操作（如停止播放、删除记录、管理用户权限）
2. 无内置可视化：输出为纯文本/JSON 格式，需配合其他工具实现图表展示
3. 网络依赖：要求运行环境与 Tautulli 实例网络可达，无法离线使用
4. 参数验证有限：history.sh 和 recent.sh 的 limit 参数仅提供默认值，无严格的正整数校验
5. T3 来源风险：个人开发者维护，长期更新保障相对较弱

适合的目标群体

• 家庭 Plex 管理员：需要快速查看谁在看什么、服务器负载如何
• 媒体库运营者：统计内容增长趋势、用户活跃度分析
• 自动化爱好者：将监控数据接入 Home Assistant、Discord 机器人等通知渠道
• 小型团队 IT：管理内部媒体服务器，无需复杂商业监控方案

使用风险

• API Key 泄露风险：若环境变量配置不当，可能导致 Tautulli 访问凭证暴露
• HTTP 明文传输：默认配置可能使用 HTTP，建议优先启用 HTTPS
• curl/jq 版本差异：老旧系统上的工具版本可能影响 JSON 解析行为
• Tautulli 服务可用性：API 查询依赖 Tautulli 自身运行状态，非 Plex 直连

核心功能

Tautulli 是一款专为 Plex 媒体服务器设计的监控 Skill，通过标准化 API 接口提供六大核心能力：

| 功能模块 | 用途说明 |

|---------|---------|

| **Current Activity** | 实时监控当前播放流，展示用户名、影片标题、播放进度、画质和播放设备 |

| **Watch History** | 查询观看历史记录，支持自定义返回条目数量 |

| **Library Stats** | 统计各媒体库的影片/音乐数量 |

| **Recently Added** | 追踪最新入库的媒体内容 |

| **User Stats** | 分析用户总观看时长和最后活跃时间 |

| **Server Info** | 获取 Plex 服务器版本、平台、连接状态等基础信息 |

显著优点

1. 极简架构，零依赖风险
仅依赖系统原生工具 curl 和 jq，无第三方包管理器引入的供应链攻击风险。六脚本总计约 150 行代码，结构清晰，易于审计。

2. 安全编码实践

• 所有脚本启用 set -euo pipefail 严格模式
• 敏感凭证（API Key）通过环境变量传入，零硬编码
• 纯只读操作，无文件系统写入、无进程调用、无动态代码执行

3. 隐私友好设计
数据仅流向用户自托管的 Tautulli 实例，不接触任何第三方服务，符合 GDPR 最小数据收集原则。

4. 部署灵活
支持 HTTP/HTTPS 协议，适配局域网或公网部署场景，环境变量配置方式兼容各类 CI/CD 和容器化环境。

潜在局限

| 限制项 | 说明 |

|-------|------|

| **T3 来源可信度** | 作者为社区开发者 rjmurillo，非官方/企业背书，信誉积累有待时间验证 |

| **功能边界** | 仅限监控查询，不支持播放控制（暂停/停止/转码调节）等写操作 |

| **网络配置依赖** | 需用户自行确保 TAUTULLI_URL 可访问，证书配置正确 |

| **API 密钥安全** | 环境变量泄露风险由用户侧承担，Skill 本身无加密存储机制 |

适合人群

• 家庭 Plex 管理员：快速查看"谁在看什么"，排查转码性能问题
• 小型团队媒体运维：统计用户活跃度，优化存储采购决策
• 自动化工作流开发者：结合定时任务生成观看报告或库存预警

常规风险与缓解

| 风险场景 | 缓解措施 |

|---------|---------|

| API 密钥泄露 | 使用专用只读 API Key，定期轮换；避免在日志中打印完整 URL |

| HTTP 明文传输 | 优先配置 HTTPS，或在可信内网使用 |

| Tautulli 实例漏洞 | 保持 Tautulli 本体更新，关注 [Tautulli Security Advisories](https://github.com/Tautulli/Tautulli/security) |

安全认证结论

经 CLS-Certify v2.1.0 六维检测（静态分析、动态分析、依赖审计、网络分析、隐私合规、威胁情报），未发现任何安全风险，综合评分 90 分，评级 A 级。