📦 APKPipe

APKとRSSリリースパイプラインを自動化。Real-Debridのアンリストリクト、ヘッドレスJDownloaderフォールバック、Nextcloudストレージ取り込み、Appriseアラート、Webダッシュボード、ネイティブMCPサーバーを統合。

📖 目次

• 概要

• アーキテクチャ

• 主な機能

• クイックスタート

  • Docker Composeでのデプロイ

  • 環境変数

• ダウンロードエンジンとリゾルバー

  • ティア1: Real-Debrid API

  • ティア2: ヘッドレスJDownloader 2

  • ティア3: Playwrightスクレイパークライアント

• ホームラボ統合

  • NextcloudストレージとOCC自動スキャン

  • AppriseとNtfyプッシュ通知

• Model Context Protocol (MCP) サーバー

  • 利用可能なMCPツール

  • AIエージェント設定

• REST APIリファレンス

• WebダッシュボードUI

• 開発とテスト

• ライセンス

🌟 概要

Nextcloudやローカルネットワークストレージ上で最新のセルフホスト型Androidアプリライブラリを維持するには、従来は手間のかかる手作業が必要でした。リリースフォーラム（Mobilismなど）の閲覧、バージョン文字列の確認、マルチホスターのミラーリンク（Rapidgator、Uploady、DropGalaxy）の回避、アーカイブの解凍、APKのリネーム、適切なディレクトリへの移動、Nextcloudのファイルインデックスのトリガー、リリース履歴の追跡などです。

APKPipe はこのライフサイクルを完全に自動化します。

1. RSSフィードを定期的に監視し、新しいアプリのリリースを検出します。

2. カスタマイズ可能なウォッチリストと照合し、正規表現パターン、リリーサーのホワイトリスト（[Balatan]、[derrin]、[RockMODS]）、SemVerバージョンゲートを使用します。

3. 3層戦略（Real-Debrid API $\rightarrow$ JDownloader 2 $\rightarrow$ Playwrightスクレイパー）でダウンロードリンクを解決します。

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. ネイティブMCPサーバーツールとWebダッシュボードを公開し、人間による管理と自律的な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フィードソースを定期的にポーリングし、重複を排除します。

• 🎯 細粒度マッチャー: 名前または正規表現で特定のアプリをターゲットにし、最小バージョンしきい値を要求し、信頼できるリリーサータグでフィルタリングします。

• ⚡ マルチティアリンクアンリストリクト:

  • ティア1 (Real-Debrid): 50以上のファイルホスター向けの直接高速APIアンリストリクト。

  • ティア2 (JDownloader 2): ヘッドレスMyJDownloaderクラウドAPIまたはローカルフォルダーリンクグラバー。

  • ティア3 (Playwrightスクレイパー): 動的ランディングページ向けのヘッドレスブラウザスクレイパーフォールバック。

• 📦 自動アーカイブ抽出: .zip、.rar、.7z、.tar.gzアーカイブを透過的に処理し、ネストされた.apkバイナリを抽出します。

• 📂 Nextcloud OCC統合: Nextcloudユーザーディレクトリへのシームレスな配置と、自動occ files:scan呼び出し。

• 🔔 マルチチャネルホームラボ通知: Apprise APIとNtfyを介したプッシュ通知。リリースメタデータ、ファイルサイズ、ダウンロード時間を含みます。

• 🤖 ネイティブModel Context Protocol (MCP): Claude Desktop、Cursor、mcp-routerと互換性のある8つの組み込みツール。

• 💻 レスポンシブWebダッシュボード: 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）を開きます。

環境変数

⚡ ダウンロードエンジンとリゾルバー

ティア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. 環境変数またはWeb UIの設定タブでAPKPIPE_REAL_DEBRID_API_TOKEN=your_tokenを設定します。

ティア2: ヘッドレスJDownloader 2

Real-Debridがサポートしていないホスターや、特殊なデクリプターが必要な場合、APKPipeはヘッドレスJDownloader 2インスタンスに接続します:

• MyJDownloaderクラウドAPI: 接続されたデバイスにダウンロードパッケージを直接送信します。

• リンクグラバー監視ディレクトリ: 共有フォルダーに.crawljob命令をドロップします。

ティア3: Playwrightスクレイパークライアント

ダウンロードランディングページが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エージェント設定

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 UIはhttp://localhost:8429/docsで利用できます。

ウォッチリストエンドポイント

• GET /api/watchlist - オプションの検索/フィルタリング付きで全ウォッチリスト項目を一覧表示。

• POST /api/watchlist - ウォッチリストに新しいアプリを追加。

• GET /api/watchlist/{id} - 特定のウォッチリストエントリを取得。

• PUT /api/watchlist/{id} - ウォッチリスト項目を更新。

• DELETE /api/watchlist/{id} - ウォッチリストエントリを削除。

フィードソースエンドポイント

APIエンドポイント

• 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 - ランタイム設定を更新します。

🖥️ WebダッシュボードUI

APKPipeには、ポート8429でアクセス可能な組み込みのWeb 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を参照してください。