📦 APKPipe

Canal de publicación automatizado de APK y RSS que combina desbloqueo de enlaces con Real-Debrid, respaldo headless con JDownloader, ingesta de almacenamiento Nextcloud, alertas Apprise, panel web y servidor MCP nativo.

📖 Índice de contenido

• Descripción general

• Arquitectura

• Características principales

• Inicio rápido

  • Despliegue con Docker Compose

  • Variables de entorno

• Motores de descarga y resolutores

  • Nivel 1: API de Real-Debrid

  • Nivel 2: JDownloader 2 headless

  • Nivel 3: Cliente de scraping Playwright

• Integraciones Homelab

  • Almacenamiento Nextcloud y escaneo automático OCC

  • Notificaciones push Apprise y Ntfy

• Servidor de protocolo de contexto de modelo (MCP)

  • Herramientas MCP disponibles

  • Configuración del agente de IA

• Referencia de la API REST

• Interfaz del panel web

• Desarrollo y pruebas

• Licencia

🌟 Descripción general

Mantener una biblioteca de aplicaciones Android autoalojada y actualizada en Nextcloud o almacenamiento de red local requiere tradicionalmente una tediosa labor manual: consultar foros de lanzamientos (como Mobilism), comprobar cadenas de versión, evitar enlaces espejo de múltiples alojamientos (Rapidgator, Uploady, DropGalaxy), descomprimir archivos, renombrar APK, mover archivos a los directorios adecuados, activar la indexación de archivos de Nextcloud y realizar un seguimiento del historial de lanzamientos.

APKPipe automatiza por completo este ciclo de vida de principio a fin:

1. Supervisa fuentes RSS periódicamente en busca de nuevos lanzamientos de aplicaciones.

2. Compara los lanzamientos con una lista de seguimiento personalizable con patrones de expresiones regulares, listas blancas de publicadores ([Balatan], [derrin], [RockMODS]) y control de versiones SemVer.

3. Resuelve enlaces de descarga mediante una estrategia de 3 niveles (API de Real-Debrid $\rightarrow$ JDownloader 2 $\rightarrow$ Scraping con Playwright).

4. Descarga y descomprime archivos (.zip, .rar, .7z, .tar) para extraer binarios APK.

5. Organiza los binarios en estructuras de directorio limpias y estandarizadas ({DOWNLOAD_DIR}/{AppName}/{AppName} v{Version} [{Releaser}].apk).

6. Ejecuta comandos de escaneo OCC de Nextcloud (occ files:scan) para que los archivos aparezcan inmediatamente en tu aplicación móvil de Nextcloud.

7. Envía alertas de estado enriquecidas a Discord, Telegram, Pushover o Ntfy mediante Apprise.

8. Expone herramientas nativas de servidor MCP y un panel web para la gestión humana y las operaciones autónomas de agentes de IA.

📐 Arquitectura

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

✨ Características principales

• 🔄 Ingesta autónoma de fuentes: sondeo periódico de múltiples fuentes RSS / ATOM con deduplicación.

• 🎯 Comparador de gran precisión: apunta a aplicaciones específicas por nombre o expresión regular, exige umbrales de versión mínimos y filtra por etiquetas de publicadores de confianza.

• ⚡ Desbloqueo de enlaces en varios niveles:

  • Nivel 1 (Real-Debrid): desbloqueo directo de enlaces de alta velocidad para más de 50 alojamientos de archivos.

  • Nivel 2 (JDownloader 2): API en la nube MyJDownloader headless o captador de enlaces de carpeta local.

  • Nivel 3 (Scraping con Playwright): respaldo con navegador headless para páginas de aterrizaje dinámicas.

• 📦 Extracción automática de archivos: gestiona de forma transparente archivos .zip, .rar, .7z y .tar.gz, extrayendo binarios .apk anidados.

• 📂 Integración con Nextcloud OCC: colocación perfecta en los directorios de usuario de Nextcloud con invocación automática de occ files:scan.

• 🔔 Notificaciones multicanal para homelab: notificaciones push mediante la API de Apprise y Ntfy con metadatos del lanzamiento, tamaños de archivo y duración de la descarga.

• 🤖 Protocolo de contexto de modelo (MCP) nativo: 8 herramientas integradas compatibles con Claude Desktop, Cursor y mcp-router.

• 💻 Panel web adaptable: tema limpio oscuro/claro creado con Alpine.js y Tailwind CSS.

🚀 Inicio rápido

Despliegue con Docker Compose

La forma recomendada de ejecutar APKPipe en producción es mediante Docker Compose.

1. Crea un archivo 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. Inicia la pila:

docker compose up -d

3. Abre tu navegador en http://localhost:8429 (o https://apk.wileyriley.com si se enruta mediante Caddy).

Variables de entorno

⚡ Motores de descarga y resolutores

Nivel 1: API de Real-Debrid

APKPipe se autentica de forma nativa con la API REST /unrestrict/link de Real-Debrid. Cuando una publicación del foro contiene espejos (Rapidgator, Uploady, DropGalaxy, Mega, Katfile, etc.), Real-Debrid desbloquea el enlace en una URL directa de CDN de alta velocidad.

Para configurar Real-Debrid:

1. Genera un token de API en real-debrid.com/apitoken.

2. Establece APKPIPE_REAL_DEBRID_API_TOKEN=tu_token en tu entorno o mediante la pestaña de Ajustes de la interfaz web.

Nivel 2: JDownloader 2 headless

Para alojamientos no compatibles con Real-Debrid o que requieran descifradores especializados, APKPipe se conecta a instancias headless de JDownloader 2 mediante:

• API en la nube MyJDownloader: envía paquetes de descarga directamente a tu dispositivo conectado.

• Directorio de supervisión Linkgrabber: coloca instrucciones .crawljob en una carpeta compartida.

Nivel 3: Cliente de scraping Playwright

Cuando las páginas de aterrizaje de descarga están protegidas por redirección JavaScript o protección en la nube, APKPipe envía tareas de evaluación de páginas a playwright-csharp-scraper (http://scraper:8080), que evalúa el DOM y extrae los espejos de descarga directa finales.

🔗 Integraciones Homelab

Almacenamiento Nextcloud y escaneo automático OCC

APKPipe formatea y coloca los archivos en tu directorio de almacenamiento de Nextcloud:

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

Para informar a Nextcloud de los archivos recién descargados sin esperar a los trabajos en segundo plano de Nextcloud, APKPipe ejecuta occ files:scan:

• Docker Exec (recomendado): pasa el socket de Docker /var/run/docker.sock y establece:

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

• CLI / Ejecución en el host: invocación directa del comando si APKPipe se ejecuta directamente en el host.

Notificaciones push Apprise y Ntfy

APKPipe emite notificaciones de eventos estructurados en:

• 🔍 feed_matched: lanzamiento detectado que coincide con una regla de la lista de seguimiento.

• ⬇️ download_started: desbloqueando enlace e iniciando la descarga por streaming.

• ✅ download_completed: archivo extraído, archivo colocado, escaneo OCC completado.

• ❌ download_failed: detalles del error y causa del fallo.

Puntos de conexión de notificación compatibles:

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

• Ntfy: https://ntfy.sh/tu-tema o servidor Ntfy autoalojado.

🤖 Servidor de protocolo de contexto de modelo (MCP)

APKPipe expone un servidor MCP 2024-11-05 nativo que permite a los asistentes de IA (Claude Desktop, Cursor, mcp-router de Antigravity) gestionar listas de seguimiento, inspeccionar fuentes, activar sondeos y descargar lanzamientos de forma autónoma.

Herramientas MCP disponibles

Configuración del agente de IA

Añade APKPipe a tu claude_desktop_config.json o mcp-router:

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

O conéctate mediante el punto de conexión Streamable HTTP / SSE:

http://localhost:8429/mcp/sse

🌐 Referencia de la API REST

La interfaz interactiva OpenAPI / Swagger está disponible en http://localhost:8429/docs.

Puntos de conexión de la lista de seguimiento

• GET /api/watchlist - Lista todos los elementos de la lista de seguimiento con búsqueda/filtrado opcional.

• POST /api/watchlist - Añade una nueva aplicación a la lista de seguimiento.

• GET /api/watchlist/{id} - Recupera una entrada específica de la lista de seguimiento.

• PUT /api/watchlist/{id} - Actualiza un elemento de la lista de seguimiento.

• DELETE /api/watchlist/{id} - Elimina una entrada de la lista de seguimiento.

Puntos de conexión de fuentes

• GET /api/feeds - Lista todas las fuentes de feeds RSS configuradas.

• POST /api/feeds - Añade una nueva fuente de feed RSS.

• POST /api/feeds/{id}/poll - Activa el sondeo inmediato de un feed específico.

• POST /api/feeds/poll-all - Activa el sondeo en todas las fuentes de feed activas.

Endpoints de Descargas e Historial

• GET /api/downloads/queue - Lista las tareas activas en el pipeline de descargas.

• GET /api/downloads/history - Lista las descargas completadas, fallidas e históricas.

• POST /api/downloads/manual - Activa una descarga inmediata desde una URL directa/espejo.

• POST /api/downloads/{task_id}/retry - Reintenta una tarea de descarga fallida.

Endpoints de Sistema y Salud

• GET /health - Sonda de verificación de salud del sistema.

• GET /api/settings - Recupera la configuración actual de la aplicación.

• POST /api/settings - Actualiza la configuración en tiempo de ejecución.

🖥️ Interfaz Web del Panel de Control

APKPipe incluye una interfaz web integrada accesible en el puerto 8429:

• Panel de control (/): Métricas generales, estado de sondeo activo, descargas recientes y almacenamiento del sistema.

• Lista de seguimiento (/watchlist): Añade, edita, filtra y elimina aplicaciones monitorizadas.

• Fuentes de feed (/feeds): Gestiona URLs de RSS, frecuencias de sondeo y activa sincronizaciones manuales.

• Historial (/history): Registro de auditoría de descargas completadas, tiempos de ejecución, tamaños de archivo y trazas de error.

• Configuración (/settings): Configura tokens de Real-Debrid, rutas de Nextcloud OCC y hooks de notificación.

🛠️ Desarrollo y Pruebas

Configuración Local

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

Ejecución de la Suite de Pruebas y Cobertura

Garantizando ≥ 80% de cobertura de líneas:

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

Inicio del Servidor Local

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

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta LICENSE para más detalles.