📦 APKPipe

自动化 APK 与 RSS 发布流水线，集成 Real-Debrid 解锁、无头 JDownloader 备用方案、Nextcloud 存储摄取、Apprise 告警、Web 仪表盘及原生 MCP Server。

📖 目录

• 概述

• 架构

• 核心特性

• 快速开始

  • Docker Compose 部署

  • 环境变量

• 下载引擎与解析器

  • 第一层：Real-Debrid API

  • 第二层：无头 JDownloader 2

  • 第三层：Playwright 爬虫客户端

• Homelab 集成

  • Nextcloud 存储与 OCC 自动扫描

  • Apprise 与 Ntfy 推送通知

• 模型上下文协议（MCP）服务器

  • 可用的 MCP 工具

  • AI 代理配置

• REST API 参考

• Web 仪表盘 UI

• 开发与测试

• 许可证

🌟 概述

在 Nextcloud 或本地网络存储上维护一个最新、自托管的 Android 应用库，传统上需要繁琐的手动操作：浏览发布论坛（如 Mobilism）、检查版本字符串、绕过多网盘镜像链接（Rapidgator、Uploady、DropGalaxy）、解压归档、重命名 APK、将文件移动到正确的目录、触发 Nextcloud 文件索引以及跟踪发布历史。

APKPipe 完全自动化了这一端到端的生命周期：

1. 定期监控 RSS 订阅源，获取新的应用发布。

2. 根据可自定义的监视列表匹配发布，支持正则表达式模式、发布者白名单（[Balatan]、[derrin]、[RockMODS]）以及 SemVer 版本门控。

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 Server 工具和 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 订阅源，并支持去重。

• 🎯 细粒度匹配器：按名称或正则表达式定位特定应用，要求最低版本阈值，并按可信发布者标签过滤。

• ⚡ 多层链接解锁：

  • 第一层（Real-Debrid）：为 50+ 文件托管商提供直接高速 API 解锁。

  • 第二层（JDownloader 2）：无头 MyJDownloader 云 API 或本地文件夹 linkgrabber。

  • 第三层（Playwright 爬虫）：针对动态落地页的无头浏览器爬虫备用方案。

• 📦 自动化归档解压：透明处理 .zip、.rar、.7z 和 .tar.gz 归档，提取嵌套的 .apk 二进制文件。

• 📂 Nextcloud OCC 集成：无缝放置到 Nextcloud 用户目录中，并自动调用 occ files:scan。

• 🔔 多渠道 Homelab 通知：通过 Apprise API 和 Ntfy 推送通知，包含发布元数据、文件大小和下载耗时。

• 🤖 原生模型上下文协议（MCP）：8 个内置工具，兼容 Claude Desktop、Cursor 和 mcp-router。

• 💻 响应式 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）。

环境变量

⚡ 下载引擎与解析器

第一层：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. 在您的环境中设置 APKPIPE_REAL_DEBRID_API_TOKEN=your_token，或通过 Web UI 的“设置”选项卡进行设置。

第二层：无头 JDownloader 2

对于 Real-Debrid 不支持或需要专用解密器的托管商，APKPipe 通过以下方式连接无头 JDownloader 2 实例：

• MyJDownloader 云 API：将下载包直接提交到您已连接的设备。

• Linkgrabber 监视目录：将 .crawljob 指令放入共享文件夹。

第三层：Playwright 爬虫客户端

当下载落地页受 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 / 主机执行：如果 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 服务器。

🤖 模型上下文协议（MCP）服务器

APKPipe 暴露了一个原生 MCP 2024-11-05 Server，允许 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} - 移除监视列表条目。

订阅源端点

• 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 仪表盘界面

APKPipe 包含一个内置的 Web 界面，可通过端口 8429 访问：

• 仪表盘（/）：概览指标、活动轮询状态、最近下载和系统存储。

• 监视列表（/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。