ohmzii/immaculaterr

Immaculaterr

镜像概述和主要用途

Immaculaterr 是一款 Plex "自动驾驶" 工具，能够监控用户的观看活动，自动构建精选收藏，并保持媒体库整洁，全程无需人工干预。它通过实时响应 Plex 库活动、调度自动化任务以及提供个性化推荐，为 Plex 用户打造智能化的媒体管理体验。

核心功能和特性

Plex 触发式自动化

• 自动响应 Plex 库活动，实时运行智能工作流

调度器自动化

• 处理非工作时间的内容获取和 Plex 主页刷新工作流

精选电影和电视剧收藏

• 基于用户长期观看偏好的 "Immaculate Taste" 收藏
• 基于最近观看内容的动态收藏（每次观看后刷新）
• "Change of Taste" 收藏（每次观看后刷新）

每用户个性化（电影 + 电视）

• 每个 Plex 观看者获得专属精选行（例如："基于你的最近观看 (用户名)"）
• 推荐数据集按观看者和库隔离，确保一个用户的历史不会影响其他用户的推荐

基于角色的 Plex 固定功能

• 管理员观看者的收藏行固定到 "库推荐" 和 "主页"
• 非管理员观看者的收藏行固定到 "好友主页"（受 Plex 共享用户工作流限制）

推荐引擎

• 基于 TMDB 的推荐
• 可选集成：Google + OpenAI

快照数据库

• 存储推荐数据，以便刷新任务能检测到 Plex 中可用的新内容

Plex 库选择控制

• 可在初始设置和 "命令中心 → Plex 库选择" 中选择要包含的电影/电视剧库
• 新的 Plex 电影/电视剧库默认自动包含，除非手动关闭
• 如果运行目标是已关闭或暂时不可用的库，该部分会安全跳过并在运行报告中明确显示，而非导致整个任务失败

刷新范围行为

• 收藏触发/链式刷新保持在触发观看者/库的范围内
• 独立刷新运行（计划或无范围手动运行）按确定顺序扫描符合条件的用户/库，管理员最后处理

Radarr + Sonarr 集成

• 当 Overseerr 模式关闭时，直接将电影/剧集发送到 ARR 下载器

观察站（Observatory）

• 滑动批准下载请求（可选 "需要批准" 模式），管理推荐
• 向左滑动将建议添加到拒绝列表（不会再次推荐），可通过 "命令中心 → 重置拒绝列表" 清除

Overseerr 集成（可选集中请求流程）

• 将缺失的电影/电视请求路由到 Overseerr，而非直接发送到 ARR
• 可按任务卡启用，每个任务可使用自己的缺失项目流程
• 包含命令中心重置控件，必要时可清除所有 Overseerr 请求

作业报告和日志

• 分步 breakdown、指标表和运行历史

操作可见性和控制

• 支持用户的命令中心重置控件、Plex 用户数据集管理、扩展调试器覆盖范围和更清晰的用户/媒体运行报告

使用场景和适用范围

• Plex 媒体服务器管理员，希望自动化媒体库管理
• 家庭共享 Plex 的用户，需要为不同家庭成员提供个性化推荐
• 希望减少手动整理媒体库时间的用户
• 使用 Radarr/Sonarr/Overseerr 生态系统的媒体爱好者

使用方法和配置说明

安装步骤

HTTP 基础安装（必需）

选项 A（DockerHub）：

bash
docker pull ohmzii/immaculaterr:latest
docker rm -f Immaculaterr 2>/dev/null || true

docker run -d \
  --name Immaculaterr \
  --network host \
  -e HOST=0.0.0.0 \
  -e PORT=5454 \
  -e APP_DATA_DIR=/data \
  -e DATABASE_URL=file:/data/tcp.sqlite \
  -v immaculaterr-data:/data \
  --restart unless-stopped \
  ohmzii/immaculaterr:latest

选项 B（GHCR）：

bash
docker pull ghcr.io/ohmzi/immaculaterr:latest
docker rm -f Immaculaterr 2>/dev/null || true

docker run -d \
  --name Immaculaterr \
  --network host \
  -e HOST=0.0.0.0 \
  -e PORT=5454 \
  -e APP_DATA_DIR=/data \
  -e DATABASE_URL=file:/data/tcp.sqlite \
  -v immaculaterr-data:/data \
  --restart unless-stopped \
  ghcr.io/ohmzi/immaculaterr:latest

可选 HTTPS 配置（可稍后运行）

bash
mkdir -p ~/immaculaterr
curl -fsSL -o ~/immaculaterr/caddy-entrypoint.sh \
  "https://raw.githubusercontent.com/ohmzi/Immaculaterr/v1.6.0/docker/immaculaterr/caddy-entrypoint.sh"
chmod +x ~/immaculaterr/caddy-entrypoint.sh

docker pull caddy:2.8.4-alpine
docker rm -f ImmaculaterrHttps 2>/dev/null || true

docker run -d \
  --name ImmaculaterrHttps \
  --network host \
  -e IMM_ENABLE_HTTP=false \
  -e IMM_ENABLE_HTTPS=true \
  -e IMM_HTTPS_PORT=5464 \
  -e IMM_INCLUDE_LOCALHOST=true \
  -e IMM_ENABLE_LAN_IP=true \
  -e APP_INTERNAL_PORT=5454 \
  -v ~/immaculaterr/caddy-entrypoint.sh:/etc/caddy/caddy-entrypoint.sh:ro \
  -v immaculaterr-caddy-data:/data \
  -v immaculaterr-caddy-config:/config \
  --restart unless-stopped \
  caddy:2.8.4-alpine \
  /bin/sh /etc/caddy/caddy-entrypoint.sh

安装后访问

• HTTP 应用（完成必需安装步骤后可用）：

  • http://localhost:5454/
  • http://<服务器IP>:5454/

• HTTPS 配置（仅运行可选 HTTPS 命令后可用）：

  • https://localhost:5464/
  • https://<服务器IP>:5464/

• 可用端口：

  • 5454/tcp: Immaculaterr HTTP
  • 5464/tcp: Immaculaterr HTTPS（可选）

环境变量说明

文档资源

• 安装指南：https://github.com/ohmzi/Immaculaterr/blob/master/doc/setupguide.md
• 常见问题：https://github.com/ohmzi/Immaculaterr/blob/master/doc/FAQ.md
• 安全策略：https://github.com/ohmzi/Immaculaterr/blob/master/doc/security.md
• 版本历史：https://github.com/ohmzi/Immaculaterr/blob/master/doc/Version_History.md

完整项目 README：https://github.com/ohmzi/Immaculaterr/blob/master/doc/README.md

安全与反馈

• 报告 Bug：https://github.com/ohmzi/Immaculaterr/issues
• 发送建议：Immaculaterr 反馈表单

许可证

Immaculaterr 采用 MIT 许可证 — 详见 https://github.com/ohmzi/Immaculaterr/blob/master/LICENSE%E3%80%82