📦 APKPipe

Automatisierte APK- & RSS-Release-Pipeline mit Real-Debrid-Entsperrung, Headless-JDownloader-Fallback, Nextcloud-Speicher-Integration, Apprise-Benachrichtigungen, Web-Dashboard und nativem MCP-Server.

📖 Inhaltsverzeichnis

• Überblick

• Architektur

• Hauptfunktionen

• Schnellstart

  • Docker-Compose-Bereitstellung

  • Umgebungsvariablen

• Download-Engines & Resolver

  • Stufe 1: Real-Debrid-API

  • Stufe 2: Headless JDownloader 2

  • Stufe 3: Playwright-Scraper-Client

• Homelab-Integrationen

  • Nextcloud-Speicher & OCC-Auto-Scanning

  • Apprise- & Ntfy-Push-Benachrichtigungen

• Model Context Protocol (MCP)-Server

  • Verfügbare MCP-Tools

  • KI-Agenten-Konfiguration

• REST-API-Referenz

• Web-Dashboard-Oberfläche

• Entwicklung & Tests

• Lizenz

🌟 Überblick

Die Pflege einer aktuellen, selbst gehosteten Android-Anwendungsbibliothek auf Nextcloud oder lokalem Netzwerkspeicher erfordert traditionell mühsame Handarbeit: das Durchsuchen von Release-Foren (wie Mobilism), das Prüfen von Versionszeichenfolgen, das Umgehen von Multi-Hoster-Mirror-Links (Rapidgator, Uploady, DropGalaxy), das Entpacken von Archiven, das Umbenennen von APKs, das Verschieben von Dateien in die richtigen Verzeichnisse, das Auslösen der Nextcloud-Dateiindizierung und das Verfolgen der Release-Historie.

APKPipe automatisiert diesen Lebenszyklus vollständig von Anfang bis Ende:

1. Überwacht RSS-Feeds regelmäßig auf neue Anwendungs-Releases.

2. Gleicht Releases mit einer anpassbaren Watchlist ab mit Regex-Mustern, Releaser-Whitelists ([Balatan], [derrin], [RockMODS]) und SemVer-Versionsprüfung.

3. Löst Download-Links auf über eine 3-stufige Strategie (Real-Debrid-API $\rightarrow$ JDownloader 2 $\rightarrow$ Playwright-Scraper).

4. Lädt Archive herunter und entpackt sie (.zip, .rar, .7z, .tar), um APK-Binärdateien zu extrahieren.

5. Organisiert Binärdateien in saubere, standardisierte Verzeichnisstrukturen ({DOWNLOAD_DIR}/{AppName}/{AppName} v{Version} [{Releaser}].apk).

6. Sendet Nextcloud-OCC-Scan-Befehle (occ files:scan), sodass Dateien sofort in Ihrer mobilen Nextcloud-App erscheinen.

7. Sendet umfangreiche Status-Benachrichtigungen an Discord, Telegram, Pushover oder Ntfy über Apprise.

8. Stellt native MCP-Server-Tools und ein Web-Dashboard bereit für menschliche Verwaltung und autonome KI-Agenten-Operationen.

📐 Architektur

flowchart TD
    subgraph Sources["Feeds & Control Interfaces"]
        RSS["Mobilism RSS Feeds\n(Apps, Games, Custom)"]
        WebUI["FastAPI Web Dashboard\n(Alpine.js + Tailwind)"]
        MCP["MCP Server Tools\n(AI Agents / mcp-router)"]
    end

    subgraph APKPipeCore["APKPipe Core Engine"]
        Scheduler["AsyncIO / Periodic Poller"]
        Parser["Feed & Post Parser"]
        Matcher["Watchlist Matcher\n(Regex, Releaser Filter, SemVer)"]
        DB[("SQLite Database\n(Watchlist, Feeds, Tasks, History)")]
        Resolver["Tiered Link Resolver"]
        Downloader["Stream Downloader & Extractor"]
        Organizer["File Organizer & Sanitizer"]
        Notifier["Apprise / Ntfy Client"]
    end

    subgraph Resolvers["Download Engines"]
        RD["Real-Debrid API (Tier 1)\n(/unrestrict/link)"]
        JD["Headless JDownloader 2 (Tier 2)\n(MyJDownloader API / Watch Dir)"]
        Scraper["playwright-csharp-scraper (Tier 3)\n(Captcha / Browser Evaluator)"]
    end

    subgraph StorageNotify["Homelab Storage & Alerts"]
        NextcloudFS["Nextcloud Storage\n(/downloads/{AppName}/...)"]
        AppriseAPI["Apprise API (8000) / Ntfy"]
        NextcloudOCC["Nextcloud OCC Scan\n(docker exec occ files:scan)"]
    end

    RSS --> Scheduler
    Scheduler --> Parser
    Parser --> Matcher
    Matcher <--> DB
    WebUI <--> DB
    MCP <--> DB
    Matcher --> Resolver

    Resolver -->|RD Supported Link| RD
    Resolver -->|RD Unsupported / Direct| JD
    Resolver -->|JS / Captcha Protected| Scraper

    RD --> Downloader
    JD --> Downloader
    Scraper --> Downloader
    Downloader --> Organizer
    Organizer --> NextcloudFS
    Organizer --> NextcloudOCC
    Organizer --> Notifier
    Notifier --> AppriseAPI

✨ Hauptfunktionen

• 🔄 Autonome Feed-Erfassung: Periodisches Abrufen mehrerer RSS-/ATOM-Feed-Quellen mit Deduplizierung.

• 🎯 Fein abgestimmter Matcher: Zielgenaue Auswahl bestimmter Apps nach Name oder Regex, Mindestversions-Schwellenwerte und Filterung nach vertrauenswürdigen Releaser-Tags.

• ⚡ Mehrstufige Link-Entsperrung:

  • Stufe 1 (Real-Debrid): Direkte High-Speed-API-Entsperrung für über 50 Filehoster.

  • Stufe 2 (JDownloader 2): Headless-MyJDownloader-Cloud-API oder lokaler Linkgrabber.

  • Stufe 3 (Playwright-Scraper): Headless-Browser-Scraper als Fallback für dynamische Landingpages.

• 📦 Automatische Archiv-Extraktion: Transparente Verarbeitung von .zip, .rar, .7z- und .tar.gz-Archiven mit Extraktion verschachtelter .apk-Binärdateien.

• 📂 Nextcloud-OCC-Integration: Nahtlose Ablage in Nextcloud-Benutzerverzeichnissen mit automatischem occ files:scan-Aufruf.

• 🔔 Multi-Kanal-Homelab-Benachrichtigungen: Push-Benachrichtigungen über Apprise-API und Ntfy mit Release-Metadaten, Dateigrößen und Download-Dauer.

• 🤖 Natives Model Context Protocol (MCP): 8 integrierte Tools, kompatibel mit Claude Desktop, Cursor und mcp-router.

• 💻 Responsives Web-Dashboard: Sauberes Dark-/Light-Theme mit Alpine.js und Tailwind CSS.

🚀 Schnellstart

Docker-Compose-Bereitstellung

Die empfohlene Methode, APKPipe in Produktion auszuführen, ist Docker Compose.

1. Erstellen Sie eine docker-compose.yaml-Datei:

services:
  apkpipe:
    image: ghcr.io/spelech/apkpipe:latest
    container_name: apkpipe
    restart: unless-stopped
    ports:
      - "8429:8000"
    environment:
      - APKPIPE_APP_NAME=APKPipe
      - APKPIPE_HOST=0.0.0.0
      - APKPIPE_PORT=8000
      - APKPIPE_DATABASE_URL=sqlite+aiosqlite:////data/apkpipe.db
      - APKPIPE_DOWNLOAD_DIR=/downloads
      - APKPIPE_STAGING_DIR=/data/staging
      - APKPIPE_POLL_INTERVAL_SECONDS=900
      - APKPIPE_REAL_DEBRID_API_TOKEN=your_real_debrid_token_here
      - APKPIPE_NEXTCLOUD_URL=http://nextcloud:80
      - APKPIPE_NEXTCLOUD_OCC_COMMAND=docker exec nextcloud-aio-nextcloud sudo -u www-data php /var/www/html/occ files:scan --path="{path}"
      - APKPIPE_APPRISE_URL=http://apprise:8000/notify/apprise
      - APKPIPE_NTFY_TOPIC=apkpipe-alerts
    volumes:
      - ./data:/data
      - /drives/storage/Nextcloud/APKs:/downloads
      - /var/run/docker.sock:/var/run/docker.sock:ro
    labels:
      - "caddy=apk.wileyriley.com"
      - "caddy.reverse_proxy={{upstreams 8000}}"
      - "caddy.import=tinyauth"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    networks:
      - default
      - caddy

networks:
  default:
    name: apkpipe_net
  caddy:
    external: true

2. Starten Sie den Stack:

docker compose up -d

3. Öffnen Sie Ihren Browser unter http://localhost:8429 (oder https://apk.wileyriley.com, wenn über Caddy geroutet).

Umgebungsvariablen

⚡ Download-Engines & Resolver

Stufe 1: Real-Debrid-API

APKPipe authentifiziert sich nativ mit der Real-Debrid-REST-API /unrestrict/link. Wenn ein Forenbeitrag Mirrors enthält (Rapidgator, Uploady, DropGalaxy, Mega, Katfile usw.), entsperrt Real-Debrid den Link in eine High-Speed-Direkt-CDN-URL.

So konfigurieren Sie Real-Debrid:

1. Generieren Sie einen API-Token unter real-debrid.com/apitoken.

2. Setzen Sie APKPIPE_REAL_DEBRID_API_TOKEN=your_token in Ihrer Umgebung oder über den Einstellungen-Tab der Web-Oberfläche.

Stufe 2: Headless JDownloader 2

Für Hoster, die von Real-Debrid nicht unterstützt werden oder spezielle Decrypter erfordern, verbindet sich APKPipe mit Headless-JDownloader-2-Instanzen über:

• MyJDownloader-Cloud-API: Übermittelt Download-Pakete direkt an Ihr verbundenes Gerät.

• Linkgrabber-Überwachungsverzeichnis: Legt .crawljob-Anweisungen in einen gemeinsamen Ordner.

Stufe 3: Playwright-Scraper-Client

Wenn Download-Landingpages durch JavaScript-Umleitung oder Cloud-Schutz geschützt sind, sendet APKPipe Seitenauswertungsaufgaben an playwright-csharp-scraper (http://scraper:8080), das das DOM auswertet und die endgültigen direkten Download-Mirrors extrahiert.

🔗 Homelab-Integrationen

Nextcloud-Speicher & OCC-Auto-Scanning

APKPipe formatiert und platziert Dateien in Ihrem Nextcloud-Speicherverzeichnis:

/downloads/
├── Spotify/
│   └── Spotify v8.9.18.534 [Balatan].apk
└── Nova Launcher/
    └── Nova Launcher v8.0.18 [Prime].apk

Um Nextcloud über neu heruntergeladene Dateien zu informieren, ohne auf Nextcloud-Hintergrundjobs zu warten, führt APKPipe occ files:scan aus:

• Docker Exec (empfohlen): Docker-Socket /var/run/docker.sock übergeben und setzen:

  APKPIPE_NEXTCLOUD_OCC_COMMAND=docker exec nextcloud-aio-nextcloud sudo -u www-data php /var/www/html/occ files:scan --path="{path}"

• CLI-/Host-Ausführung: Direkter Befehlsaufruf, wenn APKPipe direkt auf dem Host läuft.

Apprise- & Ntfy-Push-Benachrichtigungen

APKPipe sendet strukturierte Ereignisbenachrichtigungen bei:

• 🔍 feed_matched: Release gefunden, das einer Watchlist-Regel entspricht.

• ⬇️ download_started: Link wird entsperrt und Streaming-Download gestartet.

• ✅ download_completed: Archiv extrahiert, Datei platziert, OCC-Scan abgeschlossen.

• ❌ download_failed: Fehlerdetails und Fehlerursache.

Unterstützte Benachrichtigungs-Endpunkte:

• Apprise-API: http://apprise:8000/notify/apprise

• Ntfy: https://ntfy.sh/your-topic oder selbst gehosteter Ntfy-Server.

🤖 Model Context Protocol (MCP)-Server

APKPipe stellt einen nativen MCP-2024-11-05-Server bereit, der KI-Assistenten (Claude Desktop, Cursor, Antigravity mcp-router) ermöglicht, Watchlists zu verwalten, Feeds zu prüfen, Abfragen auszulösen und Releases autonom herunterzuladen.

Verfügbare MCP-Tools

KI-Agenten-Konfiguration

Fügen Sie APKPipe zu Ihrer claude_desktop_config.json oder mcp-router hinzu:

{
  "mcpServers": {
    "apkpipe": {
      "command": "python",
      "args": ["-m", "apkpipe.mcp.server"],
      "env": {
        "APKPIPE_DATABASE_URL": "sqlite+aiosqlite:////data/apkpipe.db",
        "APKPIPE_DOWNLOAD_DIR": "/downloads"
      }
    }
  }
}

Oder verbinden Sie sich über den Streamable-HTTP-/SSE-Endpunkt:

http://localhost:8429/mcp/sse

🌐 REST-API-Referenz

Die interaktive OpenAPI-/Swagger-Oberfläche ist unter http://localhost:8429/docs verfügbar.

Watchlist-Endpunkte

• GET /api/watchlist - Alle Watchlist-Einträge mit optionaler Suche/Filterung auflisten.

• POST /api/watchlist - Neue Anwendung zur Watchlist hinzufügen.

• GET /api/watchlist/{id} - Bestimmten Watchlist-Eintrag abrufen.

• PUT /api/watchlist/{id} - Watchlist-Eintrag aktualisieren.

• DELETE /api/watchlist/{id} - Watchlist-Eintrag entfernen.

Feed-Quellen-Endpunkte

• GET /api/feeds - Alle konfigurierten RSS-Feed-Quellen auflisten.

• POST /api/feeds - Eine neue RSS-Feed-Quelle hinzufügen.

• POST /api/feeds/{id}/poll - Sofortiges Abrufen eines bestimmten Feeds auslösen.

• POST /api/feeds/poll-all - Abrufen über alle aktiven Feed-Quellen auslösen.

Downloads- und Verlaufs-Endpunkte

• GET /api/downloads/queue - Aktive Aufgaben in der Download-Pipeline auflisten.

• GET /api/downloads/history - Abgeschlossene, fehlgeschlagene und historische Downloads auflisten.

• POST /api/downloads/manual - Sofortigen Download von direkter/Mirror-URL auslösen.

• POST /api/downloads/{task_id}/retry - Einen fehlgeschlagenen Download-Auftrag erneut versuchen.

System- und Health-Endpunkte

• GET /health - System-Health-Check-Sonde.

• GET /api/settings - Aktuelle Anwendungseinstellungen abrufen.

• POST /api/settings - Laufzeitkonfiguration aktualisieren.

🖥️ Web-Dashboard-UI

APKPipe enthält eine integrierte Web-UI, die auf Port 8429 erreichbar ist:

• Dashboard (/): Übersichtsmetriken, aktiver Polling-Status, letzte Downloads und Systemspeicher.

• Watchlist (/watchlist): Überwachte Anwendungen hinzufügen, bearbeiten, filtern und entfernen.

• Feed-Quellen (/feeds): RSS-URLs verwalten, Polling-Häufigkeiten festlegen und manuelle Synchronisierungen auslösen.

• Verlauf (/history): Prüfpfad abgeschlossener Downloads, Ausführungszeiten, Dateigrößen und Fehlerabläufe.

• Einstellungen (/settings): Real-Debrid-Tokens, Nextcloud-OCC-Pfade und Benachrichtigungs-Hooks konfigurieren.

🛠️ Entwicklung und Testen

Lokale Einrichtung

# Clone repository
git clone https://github.com/spelech/apkpipe.git
cd apkpipe

# Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install development dependencies and editable package
pip install -r requirements-dev.txt
pip install -e .

Testsuite und Abdeckung ausführen

Erzwingen von ≥ 80 % Zeilenabdeckung:

# Run pytest with coverage report
pytest --cov=src/apkpipe --cov-report=term-missing tests/

Lokalen Server starten

# Start FastAPI application with live reloading
uvicorn apkpipe.main:app --host 0.0.0.0 --port 8000 --reload

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Siehe LICENSE für Details.