aetaric/checkrr

Checkrr

镜像概述和主要用途

Checkrr 是一款用于扫描媒体库文件完整性的工具，可通过多种检查（ffprobe、魔数、MIME类型、文件哈希等）识别损坏的媒体文件，并在检测到问题时通过 Sonarr、Radarr 或 Lidarr 请求新文件。它使用 bbolt 平面文件数据库记录通过检查的文件哈希，大幅提升后续扫描速度，适用于维护媒体库完整性。

核心功能和特性

• 多维度文件检查：集成 ffprobe、魔数验证、MIME 类型检测及文件哈希校验，全面识别损坏文件
• 高效扫描机制：通过数据库记录已验证文件哈希，大幅提升大型媒体库的后续扫描速度
• Arr 服务集成：支持 Sonarr、Radarr、Lidarr，可自动移除损坏文件并请求新文件
• 灵活运行模式：可作为守护进程持续运行或一次性运行（适用于定时任务）
• 配置扩展性：支持多路径扫描、多 Arr 服务实例配置及路径映射
• 数据持久化：使用 bbolt 数据库存储文件哈希，确保扫描状态不丢失

使用场景和适用范围

适用于拥有电影、电视剧等媒体库，并通过 Sonarr、Radarr 或 Lidarr 管理媒体的用户。尤其适合：

• 长期维护大型媒体库，需定期检查文件完整性
• 经历过服务器迁移、文件系统变更导致潜在文件损坏的场景
• 希望自动化替换损坏媒体文件，减少手动操作的用户

安装与使用方法

前置要求

• 依赖工具：需安装 ffmpeg（含 ffprobe），并确保 ffprobe 在系统 PATH 中
• 配置文件：必须提前创建，可从官方示例获取并编辑
• 数据库文件：必须提前创建空文件（Docker 环境下尤为重要）

CLI 安装与运行

1. 安装依赖：通过包管理器安装 ffmpeg（Linux/macOS）或下载安装程序（Windows）
2. 下载程序：从 https://github.com/aetaric/checkrr/releases 获取对应系统版本
3. 创建配置文件：

   bash
   wget https://raw.githubusercontent.com/aetaric/checkrr/main/checkrr.yaml.example -O checkrr.yaml
   

4. 编辑配置：移除未使用的配置段（如未使用 InfluxDB 则删除 stats 块），参考 https://raw.githubusercontent.com/aetaric/checkrr/main/checkrr.yaml.minimal
5. 运行方式：
   • 作为守护进程：checkrr -c /path/to/checkrr.yaml
   • 一次性运行：checkrr -c /path/to/checkrr.yaml --run-once

Docker 安装与运行

重要：启动前必须创建配置文件和数据库文件，否则 Docker 会将其识别为目录导致错误。

1. 创建必要文件：

   bash
   # 创建空数据库文件
   touch checkrr.db
   # 下载配置文件示例
   wget https://raw.githubusercontent.com/aetaric/checkrr/main/checkrr.yaml.example -O checkrr.yaml
   

2. 编辑配置：根据实际环境修改配置，如需映射路径（当媒体路径在 Checkrr 与 Arr 服务中不一致时）

3. 运行容器：

   • 基础命令：

     bash
     docker run -v /path/to/checkrr.yaml:/etc/checkrr.yaml -v /path/to/media:/media -v /path/to/checkrr.db:/checkrr.db aetaric/checkrr:latest
     

   • Docker Compose 配置：

     yaml
     ---
     version: "3"
     
     services:
       checkrr:
         container_name: checkrr
         image: aetaric/checkrr:latest
         volumes:
           - /path/to/checkrr/config/checkrr.yaml:/etc/checkrr.yaml
           - /path/to/checkrr/config/checkrr.db:/checkrr.db
           - /path/to/media/to/scan:/media
         ports:
           - 8585:8585
         restart: on-failure
     

配置说明

核心配置项

• checkrr.checkpath：指定扫描路径，支持多路径配置：

  yaml
  checkrr:
    checkpath:
      - /media/TV_Shows
      - /media/Movies
  

• arr：配置 Arr 服务，支持多个实例，每个实例需指定 service 类型（sonarr/radarr/lidarr）及路径映射
• path_mappings：当 Checkrr 与 Arr 服务的媒体路径不一致时配置路径转换规则

多 Arr 服务配置示例

yaml
arr:
  - service: sonarr
    url: http://sonarr:8989
    api_key: "your_sonarr_key"
    path_mappings:
      - checkrr_path: /media/TV
        service_path: /data/TV
  - service: radarr
    url: http://radarr:7878
    api_key: "your_radarr_key"

升级至 3.1 或更高版本注意事项

• Arr 服务配置变更：3.1+ 版本支持多个 Arr 服务实例，需在配置中为每个实例添加 service 字段（sonarr/radarr/lidarr）
• 路径映射：Docker 环境下需为每个 Arr 服务配置路径映射，确保 Checkrr 能正确转换 Arr 服务返回的文件路径

界面截图

!https://github.com/aetaric/checkrr/blob/main/screenshots/Idle.png?raw=true !https://github.com/aetaric/checkrr/blob/main/screenshots/Running.png?raw=true