Webclone

🚀 WebClone

WebCloneは、すべてを保存する超高速で非同期を重視したウェブサイトクローニングエンジンです。

機能 • クイックスタート • 使用方法 • Docker • コントリビュート

🎯 開発背景

従来のウェブサイトクローナーは、低速、ブロッキング、脆弱です。一度に1つのリソースしかダウンロードせず、JavaScriptが多いサイトではフリーズし、不完全なミラーを生成します。

WebClone は異なります。最新のPythonのasync/awaitを使って一から構築され、以下のような特徴を持っています。

• ⚡ 同時ダウンロードにより10 - 100倍高速にクローン
• 🎭 Seleniumを使ってJavaScriptレンダリングを行い、動的なSPAを処理
• 🎨 リアルタイムの進捗と色付き出力で美しいCLI体験を提供
• 🏗️ 型安全で本番グレードのコードでクリーンアーキテクチャに従う
• 🐳 Dockerで本番環境にすぐにデプロイ可能で、完全なテストカバレッジとCI/CDを備える

ウェブサイトのアーカイブ、競合調査、トレーニングデータセットの構築など、どのような目的でも WebClone が最適な解決策です。

✨ 主な機能

🚀 超高速非同期エンジン

• 設定可能なワーカーで同時ダウンロード（5 - 50の並列接続）
• 深さ優先と幅優先の戦略を持つインテリジェントなキュー管理
• 指数バックオフによる自動リトライロジック

🎭 動的ページレンダリング

• JavaScriptが多いサイトに対応した完全なSelenium統合
• SPA（Phoenix LiveView、React、Vue）の自動サイドバーナビゲーション
• Chrome DevTools Protocolを使ったPDFスナップショット生成
• ビジュアルアーカイブ用のスクリーンショットキャプチャ

🔐 高度な認証とステルスモード ⭐ 新機能

• ボット検出を回避：自動化のシグネチャ（navigator.webdriverなど）を隠蔽
• GCM/FCMエラーを修正：Google Cloud Messagingの登録を無効化
• クッキーベースの認証：ログインセッションを保存して再利用
• 「安全でないブラウザ」ブロックを処理：Google、Facebookなどの自動回避策
• レート制限検出：スマートなスロットリングとバックオフ戦略
• 人間の行動を模倣：マウスの動きと自然なスクロール

🎨 世界クラスのCLI体験

• Richによる美しいターミナルUI
• リソースごとのステータスを表示するリアルタイムの進捗バー
• テーブルとパネルを使った色付きの整形出力
• 本番環境でのモニタリング用のJSONログ

🏗️ 本番グレードのアーキテクチャ

• 型安全：Mypyによる100%の型ヒント検証
• データ検証：厳格なスキーマを持つPydantic V2モデル
• 非同期を重視：aiohttp と asyncio をベースに構築
• モジュール化設計：依存性注入を使ったクリーンアーキテクチャ
• 包括的なロギング：コンテキストデータを持つ構造化JSONログ

📦 最新のツール

• ⚡ uv：超高速の依存関係管理
• 🔍 ruff：超高速のリントとコードフォーマット
• 🧪 pytest：90%以上のカバレッジを持つ包括的なテストスイート
• 🐳 Docker：軽量ベースイメージを使ったマルチステージビルド
• 🔒 セキュリティ：Banditによるセキュリティ監査と依存関係スキャン

🚀 クイックスタート

前提条件

• Python 3.11以上
• uv（推奨）またはpip

インストール

# uvを使ってインストール（推奨 - 超高速！）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install webclone

# またはpipを使ってインストール
pip install webclone

# またはソースからインストール
git clone https://github.com/ruslanmv/webclone.git
cd webclone
make install

最初のクローン

# ウェブサイトをクローン
webclone clone https://example.com

# カスタム設定でクローン
webclone clone https://example.com \
  --output ./my_mirror \
  --workers 10 \
  --max-pages 100 \
  --recursive

以上です！WebCloneが美しい進捗バー付きでウェブサイトを高速にダウンロードするのを見てください。

🎨 エンタープライズデスクトップGUI（新機能！）

WebCloneには、最新のTkinterを使って構築された高性能なプロフェッショナルなネイティブデスクトップインターフェイスが含まれています。

# GUIサポート付きでインストール
make install-gui

# エンタープライズデスクトップGUIを起動
make gui

GUIはネイティブデスクトップアプリケーションとして即座に開き、以下の機能を備えています。

• 🏠 ホームダッシュボード - 機能の概要とクイックスタートガイド
• 🔐 認証マネージャー - ブラウザ統合による視覚的なクッキーベースの認証ワークフロー
• 📥 クロール設定ツール - ポイントアンドクリックで設定可能で、リアルタイムの進捗表示
• 📊 結果分析 - 包括的な統計、テーブル、エクスポートオプション

誰にでも最適！ コマンドラインは不要で、即座に起動し、ネイティブなパフォーマンスとOSとのシームレスな統合を備えたプロフェッショナルなデスクトップインターフェイスです。

ウェブベースのGUIに比べた利点 ✅ 即座に起動（サーバーを起動する必要がない） ✅ ネイティブデスクトップのパフォーマンス ✅ より良いOS統合（ファイルダイアログ、通知） ✅ ポートの競合がない ✅ オフラインでも使える

🤖 AIエージェント用のMCPサーバー（新機能！）

WebCloneは現在、公式のModel Context Protocol (MCP)サーバー となり、Claude、CrewAI、およびMCP互換のフレームワークなどのAIエージェントがウェブサイトクローニングを利用できるようになりました！

# MCPサーバーをインストール
make install-mcp

# Claude Desktopと一緒に使用 - 設定に追加する:
# ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "webclone": {
      "command": "python",
      "args": ["/path/to/webclone/webclone-mcp.py"]
    }
  }
}

AIエージェントは現在、以下のことができます。

• 🌐 clone_website - ウェブサイト全体を自動的にダウンロード
• 📥 download_file - 特定のファイルまたはURLを取得
• 🔐 save_authentication - ログインセッションを保存するガイド
• 📋 list_saved_sessions - すべての認証クッキーを表示
• ℹ️ get_site_info - ダウンロード前にウェブサイトを分析

Claudeを使った例

あなた: FastAPIのドキュメントウェブサイトをクローンしてください

Claude: 承知しました。クローンします。
[WebClone MCPツールを使用]

✅ 127ページ、543アセット、合計45.2 MBをクローンしました！

互換性のあるもの

• ✅ Claude Desktop
• ✅ CrewAI
• ✅ LangChain
• ✅ すべてのMCP互換のAIフレームワーク

📖 詳細は docs/MCP_GUIDE.md と MCP_QUICKSTART.md を参照してください。

📖 使用方法

インターフェイスオプション

WebCloneには4つの使用方法があります。

1. 🎨 デスクトップGUI（最も簡単 - エンタープライズエディション）

   make gui
   

   • ネイティブデスクトップアプリケーション
   • 即座に起動し、ブラウザは不要
   • 視覚的な認証マネージャー
   • リアルタイムの進捗追跡
   • すべてのユーザーに最適！

2. 🤖 MCPサーバー（AIエージェント用）

   make install-mcp
   

   • Claude Desktopとの統合
   • CrewAI互換
   • LangChain対応
   • AIによる自動化
   • AIワークフローに最適！

3. 💻 コマンドライン（最も強力）

   webclone clone https://example.com
   

   • 自動化とスクリプト
   • CI/CDパイプライン
   • リモートサーバー
   • 上級ユーザー

4. 🐍 Python API（最も柔軟）

   from webclone.core import AsyncCrawler
   # ... あなたのコード
   

   • カスタム統合
   • 高度なワークフロー
   • 開発者

基本コマンド

# ヘルプを表示
webclone --help

# ウェブサイトをクローン
webclone clone <URL> [OPTIONS]

# ダウンロードせずにページを分析
webclone info <URL>

高度なオプション

webclone clone https://example.com \
  --output ./mirror           # 出力ディレクトリ（デフォルト: website_mirror）
  --workers 10                # 同時ワーカー数（デフォルト: 5）
  --max-pages 100            # クロールする最大ページ数（0 = 無制限）
  --max-depth 3              # 最大クロール深度（0 = 無制限）
  --delay 100                # リクエスト間の遅延（ms）
  --no-assets                # CSS、JS、画像のダウンロードをスキップ
  --no-pdf                   # PDF生成をスキップ
  --all-domains              # 他のドメインへのリンクを辿る
  --verbose                  # 詳細なログ出力
  --json-logs                # 解析用のJSON形式のログ

実際の使用例

# ニュースサイトをアーカイブ（ページ数を制限して過負荷を回避）
webclone clone https://news.example.com --max-pages 50 --workers 5

# ドキュメントサイトを再帰的にクローン
webclone clone https://docs.example.com --recursive --max-depth 5

# 最大の並列性で高速クローン
webclone clone https://example.com --workers 20 --delay 0

# JSONログを使った本番モード
webclone clone https://example.com --json-logs --output /var/data/mirror

🔐 認証とステルスモードの使用例

WebCloneには、認証を処理し、ボット検出を回避する高度な機能が含まれています。

# 対話型の認証例を実行
python examples/authenticated_crawl.py

# 例1: 手動でログインしてクッキーを保存
# ブラウザが開き、ログインしてクッキーが保存されます

# 例2: 保存されたクッキーを使って自動化
# クッキーを読み込み、認証を回避します

# 例3: ステルスモードの有効性をテスト
# ボット検出サイトにアクセスして隠蔽を確認します

認証用のPython API

from pathlib import Path
from webclone.services import SeleniumService
from webclone.models.config import SeleniumConfig

# 手動でログインしてセッションを保存
config = SeleniumConfig(headless=False)
service = SeleniumService(config)
service.start_driver()
service.manual_login_session(
    "https://accounts.google.com",
    Path("./cookies/google.json")
)

# 後で: 保存されたクッキーを使って自動化
config = SeleniumConfig(headless=True)
service = SeleniumService(config)
service.start_driver()
service.navigate_to("https://google.com")
service.load_cookies(Path("./cookies/google.json"))
# 現在、認証されています！

一般的な問題を解決

• ✅ "サインインできません - ブラウザが安全ではない可能性があります"
• ✅ GCM/FCM登録エラー
• ✅ Navigator.webdriver検出
• ✅ レート制限とCAPTCHAチャレンジ

詳細な手順については、認証ガイド を参照してください。

🐳 Docker

WebCloneをコンテナ化された環境で実行するには、以下の手順を実行します。

# イメージをビルド
make docker-build

# または手動でビルド
docker build -t webclone:latest .

# クローンを実行
docker run --rm -v $(pwd)/output:/data webclone:latest \
  clone https://example.com --max-pages 10

# インタラクティブシェル
docker run --rm -it -v $(pwd)/output:/data \
  --entrypoint /bin/bash webclone:latest

Docker Composeの例

version: '3.8'
services:
  webclone:
    image: webclone:latest
    volumes:
      - ./output:/data
    command: clone https://example.com --workers 10
    environment:
      - WEBCLONE_MAX_PAGES=100

🏗️ アーキテクチャ

WebCloneは クリーンアーキテクチャ の原則に従っています。

src/webclone/
├── cli.py              # Typer CLIインターフェイス
├── core/               # コアビジネスロジック
│   ├── crawler.py      # 非同期ウェブクローラー
│   └── downloader.py   # アセットダウンローダー
├── models/             # Pydanticデータモデル
│   ├── config.py       # 設定スキーマ
│   └── metadata.py     # 結果メタデータ
├── services/           # 外部サービス統合
│   └── selenium_service.py
└── utils/              # 共有ユーティリティ
    ├── logger.py
    └── helpers.py

主要な設計決定

1. 非同期を重視：すべてのI/O操作に asyncio を使って最大の並列性を実現
2. 型安全：厳格なMypyチェックによる100%の型カバレッジ
3. Pydantic V2：システムの境界でデータ検証を行う
4. 依存性注入：サービスはコンストラクタを通じて依存関係を受け取る
5. 単一責任原則：各モジュールは1つの明確な目的を持つ

🧪 開発

開発環境のセットアップ

# リポジトリをクローン
git clone https://github.com/ruslanmv/webclone.git
cd webclone

# 開発用の依存関係をインストール
make dev

# テストを実行
make test

# リンターと型チェッカーを実行
make audit

# コードをフォーマット
make format

テストの実行

# カバレッジ付きの完全なテストスイート
make test

# カバレッジなしの高速テスト
make test-fast

# HTMLカバレッジレポートを生成
make coverage

コード品質

# ruffでリント
make lint

# mypyで型チェック
make typecheck

# コードをフォーマット
make format

# すべての品質チェックを実行
make audit

🤝 コントリビュート

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

コントリビューションのワークフロー

1. リポジトリをフォーク
2. 機能ブランチを作成（git checkout -b feature/amazing-feature）
3. 変更を加える
4. 品質チェックを実行（make audit）
5. 変更をコミット（git commit -m 'Add amazing feature'）
6. ブランチにプッシュ（git push origin feature/amazing-feature）
7. プルリクエストを作成

📊 ベンチマーク

標準的な4コアマシンで100 Mbpsの接続でテストされました。

*wgetはJavaScriptベースのSPAをレンダリングできません

📄 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

👤 作者

Ruslan Magana

• ウェブサイト: ruslanmv.com
• GitHub: @ruslanmv
• メール: contact@ruslanmv.com

🌟 スター履歴

WebCloneが便利だと思ったら、スターをつけてください！ ⭐

🙏 謝辞

• Typer - 美しいCLIフレームワーク
• Rich - 高度なターミナルフォーマット
• Pydantic - データ検証
• aiohttp - 非同期HTTPクライアント
• uv - 超高速のパッケージインストーラー