feramance/qbitrr Docker 镜像 - 轩辕镜像

qBitrr

![PyPI]([] ![Downloads]([] ![Docker Pulls]([] ![CodeQL]([] ![Nightly Build]([] ![pre-commit.ci]([] ![License: MIT]([***]

🧩 qBitrr keeps qBittorrent, Radarr, Sonarr, Lidarr, and your request tools chatting happily so downloads finish, import, and clean up without babysitting.

📚 What's Inside

• Overview
• Core Features
• State of the Project
• Quickstart
  • Install with pip
  • Run with Docker
  • Native Systemd Service
• Configuration
• Feature Deep Dive
  • Torrent Health Monitoring
  • Automated Search & Requests
  • Quality Management
  • Seeding & Tracker Control
  • Disk Space Management
  • Auto-Updates & Restarts
• Built-in Web UI
• Day-to-day Operations
• Troubleshooting
• Contributing
• Support
• License

🧠 Overview

qBitrr is the intelligent glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr). It monitors torrent health, triggers instant imports when downloads complete, automates quality upgrades, manages disk space, integrates with request systems (Overseerr/Ombi), and provides a modern React dashboard for complete visibility and control.

✨ Core Features

🚑 Torrent Health & Import Management

• Instant imports – trigger DownloadedMoviesScan/DownloadedEpisodesScan the moment torrents finish
• Stalled torrent detection – identify and handle stuck/slow downloads with configurable thresholds
• Failed download handling – automatically blacklist failed torrents in Arr instances and trigger re-searches
• FFprobe verification – validate media files are playable before import (auto-downloads FFprobe binary)
• Smart file filtering – exclude samples, extras, trailers via regex and extension allowlists

🔍 Automated Search & Request Integration

• Missing media search – automatically search for missing movies/episodes/albums on schedules
• Quality upgrade search – find better releases for existing media based on quality profiles
• Custom format scoring – search for releases meeting minimum custom format scores
• Overseerr/Ombi integration – auto-pull and prioritize user requests from request management tools
• Smart search modes – series-level or episode-level search for TV shows based on context
• Temporary quality profiles – use lower quality profiles for missing items, upgrade later with flexible mapping

📊 Quality & Metadata Management

• RSS sync automation – schedule periodic RSS feed refreshes across all Arr instances
• Queue management – auto-refresh download queues to keep Arr instances in sync
• Custom format enforcement – automatically remove torrents not meeting minimum CF scores
• Quality profile switching – dynamically change profiles for missing vs. upgrade searches with per-profile mapping
• Interactive profile configuration – test Arr connections and select quality profiles from dropdowns in WebUI
• Auto-reset profiles – force reset temp profiles on startup or after configurable timeouts
• Year-based search ordering – prioritize searches by release date (newest first or reverse)

🌱 Seeding & Tracker Control

• Per-tracker settings – configure MaxETA, ratios, seeding time per tracker
• Global seeding limits – set upload/download rate limits, max ratios, and seeding times
• Automatic removal – remove torrents based on ratio, time, or both
• Dead tracker cleanup – auto-remove trackers with specific error messages
• Tracker injection – add missing trackers or remove existing ones per torrent
• Super seed mode – enable super seeding for specific trackers
• Tag management – auto-tag torrents by tracker or custom rules

💾 Disk Space & Resource Management

• Free space monitoring – pause all torrents when disk space falls below threshold
• Auto pause/resume – intelligently manage torrent activity based on disk availability
• Configurable thresholds – set limits in KB, MB, GB, or TB
• Path-specific monitoring – watch specific directories for space issues

🔄 Auto-Updates & Self-Healing

• GitHub release-based updates – automatically checks for published (non-draft) releases via GitHub API
• Scheduled auto-updates – update qBitrr on a cron schedule (default: weekly Sunday 3 AM)
• Manual update trigger – one-click updates from WebUI
• Installation-aware updates – detects git/pip/binary installs and uses appropriate update method
• Version verification – confirms installed version matches target before restart
• Smart restart mechanism – uses os.execv() for true in-place restarts (no supervisor needed)
• Cross-platform compatibility – works in Docker, systemd, native installs, Windows, Linux, macOS
• Graceful shutdown – cleanly closes databases, flushes logs, terminates child processes
• Process auto-restart – automatically restarts crashed Arr manager processes with crash loop protection
• Crash loop detection – prevents infinite restart loops with configurable max restart limits and time windows
• Configurable restart behavior – control restart delays, maximum attempts, and monitoring windows via WebUI

💻 First-Party Web UI

• Live process monitoring – see all running Arr managers and their current activity
• Log viewer – tail logs in real-time with filtering and search
• Arr insights – view movies, series, albums with filtering by year, quality, status, and quality profiles
• Config editor – edit configuration directly from the UI with validation and helpful tooltips
• Test connections – validate Arr credentials and load quality profiles with one click
• Restart controls – restart individual processes or the entire application
• Dark/light theme – customizable UI appearance
• Token authentication – optional API protection with bearer tokens

📌 State of the Project

The long-term plan is still to ship a C# rewrite, but the Python edition isn't going anywhere—it gets regular fixes and features, and the Web UI is now production-ready. Ideas and PRs are welcome! Head over to the issue templates or the PR checklist to get started.

⚡ Quickstart

qBitrr supports Python 3.12+ on Linux, macOS, and Windows. Run it natively or in Docker—whatever fits your stack.

🐍 Install with pip

bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install qBitrr2

# First run creates ~/config/config.toml
qBitrr2

Update later:

bash
python -m pip install --upgrade qBitrr2

Or enable auto-updates in config.toml:

toml
[Settings]
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0"  # Weekly on Sunday at 3 AM

📝 Note: Auto-updates check GitHub releases for new versions. Only published (non-draft) releases trigger updates. Binary installations receive update notifications but require manual download.

🐳 Run with Docker

Minimal setup:

bash
docker run -d \
  --name qbitrr \
  --tty \
  -e TZ=Europe/London \
  -p 6969:6969 \
  -v /etc/localtime:/etc/localtime:ro \
  -v /path/to/appdata/qbitrr:/config \
  -v /path/to/completed/downloads:/completed_downloads:rw \
  --restart unless-stopped \
  feramance/qbitrr:latest

The container automatically binds its WebUI to 0.0.0.0; exposing 6969 makes the dashboard reachable at http://<host>:6969/ui.

Docker Compose example:

yaml
services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    user: 1000:1000
    restart: unless-stopped
    tty: true
    environment:
      TZ: Europe/London
    ports:
      - "6969:6969"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /path/to/appdata/qbitrr:/config
      - /path/to/completed/downloads:/completed_downloads:rw
    logging:
      driver: json-file
      options:
        max-size: 50m
        max-file: "3"
    depends_on:
      - qbittorrent
      - radarr
      - sonarr

ℹ️ On first boot the container writes config.toml under /config. Update the values to match your mounts and restart the container.

⚙️ Native Systemd Service

For Linux users running qBitrr natively (non-Docker), you can set up automatic startup and restart management using systemd.

Quick setup:

bash
# Install qBitrr
pip install qBitrr2

# Copy systemd service file
sudo cp qbitrr.service /etc/systemd/system/qbitrr.service

# Enable and start
sudo systemctl enable qbitrr
sudo systemctl start qbitrr

# Check status
sudo systemctl status qbitrr

Benefits:

• ✅ Auto-start on boot
• ✅ Automatic restarts after crashes or updates
• ✅ Integrated logging with journalctl
• ✅ Resource limits and security hardening
• ✅ Works seamlessly with qBitrr's auto-update feature

See the full guide: SYSTEMD_SERVICE.md for detailed setup instructions, troubleshooting, and security hardening options.

🛠️ Configuration

📂 Config Location

• Native install: ~/config/config.toml
• Docker: /config/config.toml
• First run: Auto-generates a template config file
• Manual generation: qbitrr --gen-config

🔧 Essential Setup

1. Configure qBittorrent connection in [qBit] section:

   • Set Host, Port, UserName, Password
   • qBittorrent 5.x requires Version5 = true (4.6.7 is the latest validated 4.x build)

2. Configure Arr instances (Radarr/Sonarr/Lidarr):

   • Each instance needs: URI, APIKey, Category
   • Naming format: Instance names must follow pattern (Radarr|Sonarr|Lidarr)-<name> (e.g., Radarr-Movies, Sonarr-TV4K)
   • Important: Use matching categories in Arr's download client settings
   • Tagging: Ensure Arr instances tag their downloads so qBitrr can track them

3. Set completed download folder:

   toml
   [Settings]
   CompletedDownloadFolder = "/path/to/completed"
   

4. Enable logging for troubleshooting:

   toml
   [Settings]
   Logging = true
   ConsoleLevel = "INFO"  # or DEBUG for verbose output
   

📖 Configuration Reference

See config.example.toml for comprehensive documentation of all settings, including:

• Torrent health check thresholds
• Search automation options
• Seeding limits and tracker rules
• Request system integration
• WebUI settings
• File filtering and exclusion rules

🎯 Feature Deep Dive

🚑 Torrent Health Monitoring

qBitrr continuously monitors your torrents and takes intelligent action when problems arise.

Stalled Torrent Detection:

toml
[Radarr-Movies.Torrent]
StalledDelay = 15              # Minutes before considering a torrent stalled
ReSearchStalled = true         # Re-search before removing stalled torrents
MaximumETA = 604800           # Max ETA in seconds (7 days)
IgnoreTorrentsYoungerThan = 600  # Grace period for new torrents (10 min)

Automatic Blacklisting: When torrents fail or stall beyond thresholds, qBitrr:

1. ✅ Marks the release as failed in the Arr instance
2. ✅ Blacklists the release to prevent re-download
3. ✅ Optionally triggers an automatic re-search
4. ✅ Removes the failed torrent from qBittorrent

Smart Completion Rules:

toml
[Radarr-Movies.Torrent]
MaximumDeletablePercentage = 0.99  # Don't delete torrents >99% complete
DoNotRemoveSlow = true             # Protect slow but active torrents

File Verification:

toml
[Settings]
FFprobeAutoUpdate = true  # Auto-download FFprobe binary

• Validates media files are playable before import
• Detects corrupted or fake files
• Prevents broken media from being imported into Arr

Error Code Handling:

toml
[Radarr-Movies]
ArrErrorCodesToBlocklist = [
  "Not an upgrade for existing movie file(s)",
  "Unable to determine if file is a sample"
]

Automatically handle specific Arr error messages by removing failed files and triggering re-searches.

---

🔍 Automated Search & Requests

Missing Media Search:

toml
[Radarr-Movies.EntrySearch]
SearchMissing = true              # Enable automated searching
SearchLimit = 5                   # Max concurrent searches
SearchByYear = true               # Order by release year
SearchInReverse = false           # Newest first (true = oldest first)
SearchRequestsEvery = 300         # Delay between searches (seconds)
SearchAgainOnSearchCompletion = true  # Loop continuously

Quality Upgrade Search:

toml
[Radarr-Movies.EntrySearch]
DoUpgradeSearch = true            # Search for better quality versions
QualityUnmetSearch = true         # Search for unmet quality profiles
CustomFormatUnmetSearch = true    # Search for better custom format scores
ForceMinimumCustomFormat = true   # Auto-remove torrents below CF threshold

Overseerr Integration:

toml
[Radarr-Movies.EntrySearch.Overseerr]
SearchOverseerrRequests = true
OverseerrURI = "[***]"
OverseerrAPIKey = "your-api-key"
ApprovedOnly = true               # Only process approved requests
Is4K = false                      # Set true for 4K Arr instances

Ombi Integration:

toml
[Radarr-Movies.EntrySearch.Ombi]
SearchOmbiRequests = true
OmbiURI = "[***]"
OmbiAPIKey = "your-api-key"
ApprovedOnly = true

Smart Search Modes (Sonarr):

toml
[Sonarr-TV.EntrySearch]
SearchBySeries = "smart"          # auto | true (series) | false (episode)
# smart: Series search for full seasons, episode search for singles
PrioritizeTodaysReleases = true   # Search today's episodes first (RSS-like)
AlsoSearchSpecials = false        # Include season 00 episodes
Unmonitored = false               # Include unmonitored items

Temporary Quality Profiles:

toml
[Radarr-Movies.EntrySearch]
UseTempForMissing = true
KeepTempProfile = false

# New: Map each main profile to a temp profile
QualityProfileMappings = { "Ultra-HD" = "Web-DL", "HD-1080p" = "HDTV-720p" }

# Auto-reset options
ForceResetTempProfiles = false           # Reset all on startup
TempProfileResetTimeoutMinutes = 0       # Auto-reset after timeout (0 = disabled)
ProfileSwitchRetryAttempts = 3           # Retry failed profile switches

# Searches missing items with temp profile, switches back after import

Configure via WebUI:

1. Edit your Arr instance in the Config tab
2. Click "Test Connection" to load available quality profiles
3. Add profile mappings with the interactive UI (no JSON editing needed!)
4. Select main and temp profiles from dropdowns
5. Save and restart

---

📊 Quality Management

RSS Sync Automation:

toml
[Radarr-Movies]
RssSyncTimer = 5  # Minutes between RSS feed refreshes (0 = disabled)

Keeps Arr instances checking indexers for new releases regularly.

Queue Refresh:

toml
[Radarr-Movies]
RefreshDownloadsTimer = 5  # Minutes between queue updates (0 = disabled)

Ensures Arr instances stay in sync with qBittorrent's download state.

Import Mode:

toml
[Radarr-Movies]
importMode = "Auto"  # Auto | Move | Copy

• Auto: Let Arr decide based on its settings
• Move: Move files from download folder to library
• Copy: Copy files (preserves seeding torrents)

Custom Format Score Enforcement: When ForceMinimumCustomFormat = true, qBitrr automatically removes torrents that don't meet the minimum custom format score defined in your Arr quality profile.

---

🌱 Seeding & Tracker Control

Global Seeding Limits:

toml
[Radarr-Movies.Torrent.SeedingMode]
DownloadRateLimitPerTorrent = -1  # -1 = unlimited, or KB/s
UploadRateLimitPerTorrent = -1    # -1 = unlimited, or KB/s
MaxUploadRatio = 2.0              # Stop seeding at 2.0 ratio
MaxSeedingTime = 604800           # Stop after 7 days (seconds)
RemoveTorrent = 3                 # 1=ratio, 2=time, 3=either, 4=both, -1=never

Per-Tracker Settings:

toml
[[Radarr-Movies.Torrent.Trackers]]
Name = "MyTracker"
Priority = 10                     # Higher = processed first
URI = "[***]"
MaximumETA = ***               # Override global MaxETA for this tracker
DownloadRateLimit = 5000         # KB/s limit for this tracker
UploadRateLimit = 1000           # KB/s limit for this tracker
MaxUploadRatio = 1.5             # Tracker-specific ratio limit
MaxSeedingTime = 86400           # Tracker-specific time limit (1 day)
AddTrackerIfMissing = true       # Inject this tracker into matching torrents
RemoveIfExists = false           # Remove this tracker if found
SuperSeedMode = true             # Enable super seeding for this tracker
AddTags = ["private", "MyTracker"]  # Auto-tag matching torrents

Tracker Cleanup:

toml
[Radarr-Movies.Torrent.SeedingMode]
RemoveDeadTrackers = true
RemoveTrackerWithMessage = [
  "skipping tracker announce (unreachable)",
  "No such host is known",
  "unsupported URL protocol"
]

File Filtering:

toml
[Radarr-Movies.Torrent]
CaseSensitiveMatches = false
FolderExclusionRegex = ["\\bextras?\\b", "\\bsamples?\\b", "\\bfeaturettes?\\b"]
FileNameExclusionRegex = ["\\bsample\\b", "\\btrailer\\b"]
FileExtensionAllowlist = [".mp4", ".mkv", ".avi", ".sub", ".srt"]
AutoDelete = false  # Auto-delete non-playable files (.exe, .png, etc.)

---

💾 Disk Space Management

Free Space Monitoring:

toml
[Settings]
FreeSpace = "50G"              # Pause when <50GB free (K/M/G/T units)
FreeSpaceFolder = "/downloads" # Path to monitor
AutoPauseResume = true         # Required for FreeSpace to work

How it works:

1. 📊 Continuously monitors specified folder
2. ⏸️ Pauses all torrents when space falls below threshold
3. ▶️ Auto-resumes when space is reclaimed
4. 🔔 Logs warnings when approaching limit

Disable monitoring:

toml
[Settings]
FreeSpace = ""  # Empty string or 0 disables monitoring

---

🔄 Auto-Updates & Restarts

qBitrr can automatically update itself by checking GitHub releases for new versions. The update behavior varies by installation type.

🔍 How Updates Work

Update Detection:

1. 📡 Queries GitHub API for latest published (non-draft) release
2. 🔢 Compares release version with current version using semantic versioning
3. ⏩ Skips prereleases (beta, rc, alpha) by default
4. 📦 Only updates when a newer stable version is available

Installation Types:

Why different methods?

• Git installations can checkout specific tags for precise version control
• PyPI installations can pin to exact versions for reliability
• Binary installations cannot self-update (would require replacing running executable), so qBitrr logs the download URL and version info for manual update

---

⚙️ Configuration

Basic Setup:

toml
[Settings]
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0"  # Cron expression (default: Sunday 3 AM)

Cron Expression Examples:

bash
0 3 * * 0      # Every Sunday at 3:00 AM
0 */6 * * *    # Every 6 hours
0 0 * * *      # Daily at midnight
0 2 * * 1-5    # Weekdays at 2:00 AM

---

📋 Update Process Flow

For Git & PyPI Installations:

1. Check Phase:

   • Fetch latest release from GitHub API
   • Validate release is not draft or prerelease
   • Compare versions (semantic versioning)
   • Skip if already on latest version

2. Download Phase:

   • Git: git fetch --tags && git checkout v<version>
   • PyPI: pip install --upgrade qBitrr2==<version>

3. Verification Phase:

   • Reload version information
   • Verify installed version matches target
   • Log warning if mismatch

4. Restart Phase:

   • Gracefully shutdown (close DBs, flush logs)
   • Terminate child processes
   • Execute in-place restart via os.execv()
   • Maintain same PID (systemd-friendly)

For Binary Installations:

1. Check Phase: Same as above
2. Notification: Logs message with download URL and instructions
3. Manual Update: User downloads new binary from GitHub releases
4. No Auto-Restart: User manually restarts after replacing binary

Example binary update log:

[INFO] Update available: v5.4.2 -> v5.4.3
[INFO] Binary installation detected - manual update required
[INFO] Download: [***]
[INFO] Instructions:
  1. Download the binary for your platform
  2. Extract the archive
  3. Replace current executable with new binary
  4. Restart qBitrr

---

🔧 Manual Updates

Via WebUI:

• Navigate to Config tab
• Click "Check for Updates" to see available version
• Click "Update Now" button
• Confirm when prompted
• Application restarts automatically (git/pip only)

Via Command Line:

bash
# Git installation
cd /path/to/qBitrr
git fetch --tags
git checkout v5.4.3  # or: git pull
qbitrr  # restart

# PyPI installation
pip install --upgrade qBitrr2
# or: pip install qBitrr2==5.4.3  # specific version
qbitrr  # restart

# Binary installation
# Download from: [***]
# Extract and replace binary, then restart

# Docker installation
docker pull feramance/qbitrr:latest
docker restart qbitrr
# or: docker-compose pull && docker-compose up -d

---

🔐 Security & Reliability

GitHub API Dependency:

• Auto-update requires GitHub API access
• Rate limit: 60 requests/hour (unauthenticated)
• Cron schedule should account for rate limits
• Failures are logged but don't crash the application

Version Verification:

• After update, qBitrr verifies installed version
• Helps catch failed updates or PyPI lag issues
• Logs warning if version mismatch detected

Draft & Prerelease Handling:

• Draft release