📦 APKPipe

Автоматизированный конвейер выпуска APK и RSS, объединяющий разблокировку Real-Debrid, резервный headless JDownloader, приём файлов в Nextcloud, уведомления Apprise, веб-панель и нативный MCP-сервер.

📖 Содержание

• Обзор

• Архитектура

• Ключевые возможности

• Быстрый старт

  • Развёртывание через Docker Compose

  • Переменные окружения

• Движки загрузки и резолверы

  • Уровень 1: Real-Debrid API

  • Уровень 2: Headless JDownloader 2

  • Уровень 3: Playwright Scraper Client

• Интеграции для Homelab

  • Хранилище Nextcloud и автосканирование OCC

  • Push-уведомления Apprise и Ntfy

• Сервер Model Context Protocol (MCP)

  • Доступные MCP-инструменты

  • Настройка AI-агента

• Справочник REST API

• Веб-панель

• Разработка и тестирование

• Лицензия

🌟 Обзор

Поддержание актуальной, самостоятельно размещённой библиотеки Android-приложений на Nextcloud или локальном сетевом хранилище традиционно требует утомительной ручной работы: просмотр форумов с релизами (например, Mobilism), проверка строк версий, обход зеркальных ссылок мультихостингов (Rapidgator, Uploady, DropGalaxy), распаковка архивов, переименование APK, перемещение файлов в нужные каталоги, запуск индексации файлов Nextcloud и отслеживание истории выпусков.

APKPipe полностью автоматизирует этот жизненный цикл от начала до конца:

1. Периодически отслеживает RSS-каналы на предмет новых выпусков приложений.

2. Сопоставляет выпуски с настраиваемым списком отслеживания с помощью regex-шаблонов, белых списков релизеров ([Balatan], [derrin], [RockMODS]) и проверки версий по SemVer.

3. Разрешает ссылки на загрузку с помощью трёхуровневой стратегии (Real-Debrid API $\rightarrow$ JDownloader 2 $\rightarrow$ Playwright Scraper).

4. Загружает и распаковывает архивы (.zip, .rar, .7z, .tar) для извлечения APK-бинарников.

5. Упорядочивает бинарники в чистую, стандартизированную структуру каталогов ({DOWNLOAD_DIR}/{AppName}/{AppName} v{Version} [{Releaser}].apk).

6. Запускает команды сканирования Nextcloud OCC (occ files:scan), чтобы файлы немедленно появлялись в вашем мобильном приложении Nextcloud.

7. Отправляет подробные уведомления о статусе в Discord, Telegram, Pushover или Ntfy через Apprise.

8. Предоставляет нативные инструменты MCP-сервера и веб-панель для управления человеком и автономных операций AI-агентов.

📐 Архитектура

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

✨ Ключевые возможности

• 🔄 Автономный приём каналов: Периодический опрос нескольких источников RSS / ATOM с дедупликацией.

• 🎯 Точный сопоставитель: Нацеливание на конкретные приложения по имени или regex, требование минимальных порогов версий и фильтрация по доверенным тегам релизеров.

• ⚡ Многоуровневое разблокирование ссылок:

  • Уровень 1 (Real-Debrid): Прямое высокоскоростное разблокирование через API для 50+ файлообменников.

  • Уровень 2 (JDownloader 2): Headless MyJDownloader Cloud API или локальный linkgrabber по каталогу.

  • Уровень 3 (Playwright Scraper): Резервный headless-браузерный скрапер для динамических целевых страниц.

• 📦 Автоматическое извлечение архивов: Прозрачная обработка архивов .zip, .rar, .7z и .tar.gz с извлечением вложенных APK-бинарников.

• 📂 Интеграция с Nextcloud OCC: Бесшовное размещение файлов в пользовательских каталогах Nextcloud с автоматическим вызовом occ files:scan.

• 🔔 Многоканальные уведомления для Homelab: Push-уведомления через Apprise API и Ntfy с метаданными выпуска, размерами файлов и длительностью загрузки.

• 🤖 Нативный Model Context Protocol (MCP): 8 встроенных инструментов, совместимых с Claude Desktop, Cursor и mcp-router.

• 💻 Адаптивная веб-панель: Чистая тёмная/светлая тема на базе Alpine.js и Tailwind CSS.

🚀 Быстрый старт

Развёртывание через Docker Compose

Рекомендуемый способ запуска APKPipe в производственной среде — использование Docker Compose.

1. Создайте файл docker-compose.yaml:

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. Запустите стек:

docker compose up -d

3. Откройте браузер по адресу http://localhost:8429 (или https://apk.wileyriley.com, если маршрутизация через Caddy).

Переменные окружения

⚡ Движки загрузки и резолверы

Уровень 1: Real-Debrid API

APKPipe нативно аутентифицируется с REST API Real-Debrid /unrestrict/link. Когда сообщение на форуме содержит зеркала (Rapidgator, Uploady, DropGalaxy, Mega, Katfile и т. д.), Real-Debrid разблокирует ссылку в высокоскоростной прямой URL CDN.

Для настройки Real-Debrid:

1. Сгенерируйте API-токен на real-debrid.com/apitoken.

2. Установите APKPIPE_REAL_DEBRID_API_TOKEN=your_token в вашем окружении или через вкладку «Настройки» веб-интерфейса.

Уровень 2: Headless JDownloader 2

Для хостингов, не поддерживаемых Real-Debrid, или требующих специализированных дешифраторов, APKPipe подключается к headless-экземплярам JDownloader 2 через:

• MyJDownloader Cloud API: Отправляет пакеты загрузки напрямую на ваше подключённое устройство.

• Каталог наблюдения Linkgrabber: Помещает инструкции .crawljob в общую папку.

Уровень 3: Playwright Scraper Client

Когда целевые страницы загрузки защищены JavaScript-редиректами или облачной защитой, APKPipe отправляет задачи оценки страницы в playwright-csharp-scraper (http://scraper:8080), который оценивает DOM и извлекает финальные прямые зеркала загрузки.

🔗 Интеграции для Homelab

Хранилище Nextcloud и автосканирование OCC

APKPipe форматирует и размещает файлы в вашем каталоге хранилища Nextcloud:

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

Чтобы сообщить Nextcloud о недавно загруженных файлах, не дожидаясь фоновых задач Nextcloud, APKPipe выполняет occ files:scan:

• Docker Exec (рекомендуется): Передайте Docker-сокет /var/run/docker.sock и установите:

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

• CLI / Host Exec: Прямой вызов команды, если APKPipe запущен непосредственно на хосте.

Push-уведомления Apprise и Ntfy

APKPipe отправляет структурированные уведомления о событиях:

• 🔍 feed_matched: Обнаружен выпуск, соответствующий правилу списка отслеживания.

• ⬇️ download_started: Разблокирование ссылки и запуск потоковой загрузки.

• ✅ download_completed: Архив извлечён, файл размещён, сканирование OCC завершено.

• ❌ download_failed: Детали ошибки и причина сбоя.

Поддерживаемые конечные точки уведомлений:

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

• Ntfy: https://ntfy.sh/your-topic или собственный сервер Ntfy.

🤖 Сервер Model Context Protocol (MCP)

APKPipe предоставляет нативный MCP-сервер 2024-11-05, позволяющий AI-ассистентам (Claude Desktop, Cursor, Antigravity mcp-router) автономно управлять списками отслеживания, просматривать каналы, запускать опросы и загружать выпуски.

Доступные MCP-инструменты

Настройка AI-агента

Добавьте APKPipe в ваш claude_desktop_config.json или mcp-router:

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

Или подключитесь через конечную точку Streamable HTTP / SSE:

http://localhost:8429/mcp/sse

🌐 Справочник REST API

Интерактивный интерфейс OpenAPI / Swagger доступен по адресу http://localhost:8429/docs.

Конечные точки списка отслеживания

• GET /api/watchlist — Список всех элементов списка отслеживания с необязательным поиском/фильтрацией.

• POST /api/watchlist — Добавить новое приложение в список отслеживания.

• GET /api/watchlist/{id} — Получить конкретную запись списка отслеживания.

• PUT /api/watchlist/{id} — Обновить элемент списка отслеживания.

• DELETE /api/watchlist/{id} — Удалить запись списка отслеживания.

Конечные точки источников каналов

• GET /api/feeds — Список всех настроенных источников RSS-лент.

• POST /api/feeds — Добавить новый источник RSS-ленты.

• POST /api/feeds/{id}/poll — Запустить немедленный опрос конкретной ленты.

• POST /api/feeds/poll-all — Запустить опрос всех активных источников лент.

Конечные точки загрузок и истории

• GET /api/downloads/queue — Список активных задач в конвейере загрузок.

• GET /api/downloads/history — Список завершённых, неудачных и исторических загрузок.

• POST /api/downloads/manual — Запустить немедленную загрузку по прямой/зеркальной ссылке.

• POST /api/downloads/{task_id}/retry — Повторить неудачную задачу загрузки.

Конечные точки системы и состояния

• GET /health — Проверка состояния системы.

• GET /api/settings — Получить текущие настройки приложения.

• POST /api/settings — Обновить конфигурацию во время выполнения.

🖥️ Веб-интерфейс панели управления

APKPipe включает встроенный веб-интерфейс, доступный на порту 8429:

• Панель управления (/): Обзор метрик, статус активного опроса, последние загрузки и системное хранилище.

• Список отслеживания (/watchlist): Добавление, редактирование, фильтрация и удаление отслеживаемых приложений.

• Источники лент (/feeds): Управление RSS-ссылками, частотой опроса и запуск ручной синхронизации.

• История (/history): Журнал аудита завершённых загрузок, времени выполнения, размеров файлов и следов ошибок.

• Настройки (/settings): Настройка токенов Real-Debrid, путей Nextcloud OCC и хуков уведомлений.

🛠️ Разработка и тестирование

Локальная настройка

# 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 .

Запуск набора тестов и покрытия

Обеспечение покрытия строк ≥ 80%:

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

Запуск локального сервера

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

📄 Лицензия

Этот проект лицензирован под лицензией MIT. Подробности см. в LICENSE.