📦 APKPipe

Real-Debrid 언리스트릭팅, 헤드리스 JDownloader 폴백, Nextcloud 저장소 수집, Apprise 알림, 웹 대시보드 및 네이티브 MCP 서버를 결합한 자동화된 APK 및 RSS 릴리스 파이프라인.

📖 목차

• 개요

• 아키텍처

• 주요 기능

• 빠른 시작

  • Docker Compose 배포

  • 환경 변수

• 다운로드 엔진 및 리졸버

  • Tier 1: Real-Debrid API

  • Tier 2: Headless JDownloader 2

  • Tier 3: Playwright Scraper Client

• 홈랩 통합

  • Nextcloud 저장소 및 OCC 자동 스캔

  • Apprise 및 Ntfy 푸시 알림

• Model Context Protocol(MCP) 서버

  • 사용 가능한 MCP 도구

  • AI 에이전트 구성

• REST API 참조

• 웹 대시보드 UI

• 개발 및 테스트

• 라이선스

🌟 개요

Nextcloud 또는 로컬 네트워크 저장소에서 최신 상태로 유지되는 자체 호스팅 Android 애플리케이션 라이브러리를 관리하려면 전통적으로 지루한 수작업이 필요했습니다. 릴리스 포럼(예: Mobilism) 탐색, 버전 문자열 확인, 멀티 호스터 미러 링크(Rapidgator, Uploady, DropGalaxy) 우회, 아카이브 압축 해제, APK 이름 변경, 파일을 올바른 디렉터리로 이동, Nextcloud 파일 인덱싱 트리거, 릴리스 기록 추적 등이 그것입니다.

APKPipe는 이 수명 주기를 종단 간 완전히 자동화합니다:

1. RSS 피드를 주기적으로 모니터링하여 새로운 애플리케이션 릴리스를 감지합니다.

2. 정규식 패턴, 릴리서 화이트리스트([Balatan], [derrin], [RockMODS]) 및 SemVer 버전 게이팅으로 맞춤형 워치리스트와 릴리스를 매칭합니다.

3. 3계층 전략(Real-Debrid API → JDownloader 2 → 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. Apprise를 통해 Discord, Telegram, Pushover 또는 Ntfy로 풍부한 상태 알림을 푸시합니다.

8. 인간 관리 및 자율 AI 에이전트 운영을 위해 네이티브 MCP 서버 도구와 웹 대시보드를 제공합니다.

📐 아키텍처

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 피드 소스를 주기적으로 폴링합니다.

• 🎯 세밀한 매처: 이름 또는 정규식으로 특정 앱을 대상으로 지정하고, 최소 버전 임계값을 요구하며 신뢰할 수 있는 릴리서 태그로 필터링합니다.

• ⚡ 다중 계층 링크 언리스트릭팅:

  • Tier 1 (Real-Debrid): 50개 이상의 파일 호스터를 지원하는 직접 고속 API 언리스트릭팅.

  • Tier 2 (JDownloader 2): 헤드리스 MyJDownloader 클라우드 API 또는 로컬 폴더 링크그래버.

  • Tier 3 (Playwright Scraper): 동적 랜딩 페이지를 위한 헤드리스 브라우저 스크레이퍼 폴백.

• 📦 자동 아카이브 추출: .zip, .rar, .7z, .tar.gz 아카이브를 투명하게 처리하여 중첩된 .apk 바이너리를 추출합니다.

• 📂 Nextcloud OCC 통합: 자동 occ files:scan 호출과 함께 Nextcloud 사용자 디렉터리로 원활하게 배치합니다.

• 🔔 다중 채널 홈랩 알림: 릴리스 메타데이터, 파일 크기, 다운로드 소요 시간과 함께 Apprise API 및 Ntfy를 통해 푸시 알림을 전송합니다.

• 🤖 네이티브 Model Context Protocol(MCP): Claude Desktop, Cursor, mcp-router와 호환되는 8가지 기본 제공 도구.

• 💻 반응형 웹 대시보드: 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(또는 Caddy를 통해 라우팅되는 경우 https://apk.wileyriley.com)을 엽니다.

환경 변수

⚡ 다운로드 엔진 및 리졸버

Tier 1: Real-Debrid API

APKPipe는 Real-Debrid의 REST API /unrestrict/link로 네이티브 인증을 수행합니다. 포럼 게시물에 미러(Rapidgator, Uploady, DropGalaxy, Mega, Katfile 등)가 포함된 경우, Real-Debrid는 링크를 언리스트릭트하여 고속 직접 CDN URL로 변환합니다.

Real-Debrid 구성 방법:

1. real-debrid.com/apitoken에서 API 토큰을 생성합니다.

2. 환경 변수 또는 웹 UI 설정 탭에서 APKPIPE_REAL_DEBRID_API_TOKEN=your_token을 설정합니다.

Tier 2: Headless JDownloader 2

Real-Debrid가 지원하지 않거나 특수 디크립터가 필요한 호스터의 경우, APKPipe는 헤드리스 JDownloader 2 인스턴스에 다음을 통해 연결합니다:

• MyJDownloader 클라우드 API: 연결된 기기에 다운로드 패키지를 직접 제출합니다.

• Linkgrabber 감시 디렉터리: 공유 폴더에 .crawljob 지침을 배치합니다.

Tier 3: Playwright Scraper Client

다운로드 랜딩 페이지가 JavaScript 리디렉션이나 클라우드 보호로 보호되는 경우, APKPipe는 페이지 평가 작업을 playwright-csharp-scraper(http://scraper:8080)에 전달합니다. 해당 서비스는 DOM을 평가하고 최종 직접 다운로드 미러를 추출합니다.

🔗 홈랩 통합

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 / 호스트 실행: APKPipe가 호스트에서 직접 실행되는 경우 명령을 직접 호출합니다.

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 에이전트 구성

claude_desktop_config.json 또는 mcp-router에 APKPipe를 추가합니다:

{
  "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 UI는 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 - 직접/미러 URL에서 즉시 다운로드를 트리거합니다.

• POST /api/downloads/{task_id}/retry - 실패한 다운로드 작업을 재시도합니다.

시스템 및 상태 엔드포인트

• GET /health - 시스템 상태 확인 프로브.

• GET /api/settings - 현재 애플리케이션 설정을 검색합니다.

• POST /api/settings - 런타임 구성을 업데이트합니다.

🖥️ 웹 대시보드 UI

APKPipe에는 포트 8429에서 접근할 수 있는 내장 웹 UI가 포함되어 있습니다:

• 대시보드 (/): 개요 메트릭, 활성 폴링 상태, 최근 다운로드 및 시스템 저장 공간.

• 관심 목록 (/watchlist): 모니터링되는 애플리케이션을 추가, 편집, 필터링 및 제거합니다.

• 피드 소스 (/feeds): RSS URL, 폴링 빈도를 관리하고 수동 동기화를 트리거합니다.

• 기록 (/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를 참조하세요.