Webclone

🚀 WebClone

WebClone 是一款超快的、以異步為優先設計的網站克隆引擎，能完整保留網站的所有內容。它解決了傳統網站克隆工具速度慢、易阻塞且不穩定的問題，可用於網站存檔、競品研究或構建訓練數據集等場景，為用戶提供高效、全面的網站克隆解決方案。

🚀 快速開始

前提條件

• 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 以閃電般的速度下載你的網站，並伴有漂亮的進度條。

🎨 企業桌面圖形用戶界面（新增！）

WebClone 現在包含一個專業的原生桌面界面，它基於現代的 Tkinter 構建，性能卓越：

# 安裝帶有圖形用戶界面支持的版本
make install-gui

# 啟動企業桌面圖形用戶界面
make gui

該圖形用戶界面作為原生桌面應用程序可立即打開，具備以下功能：

• 🏠 主頁儀表盤 - 功能概述和快速入門指南
• 🔐 認證管理器 - 基於視覺的基於 cookie 的認證工作流程，並與瀏覽器集成
• 📥 爬取配置器 - 點擊式設置，並即時顯示進度
• 📊 結果分析 - 全面的統計信息、表格和導出選項

適合所有人！ 無需命令行操作 - 專業的桌面界面，啟動迅速，具備原生性能，並能與操作系統無縫集成。

相較於基於 Web 的圖形用戶界面的優勢： ✅ 立即啟動（無需啟動服務器） ✅ 原生桌面性能 ✅ 更好的操作系統集成（文件對話框、通知） ✅ 無端口衝突 ✅ 離線友好

🤖 面向 AI 代理的 MCP 服務器（新增！）

WebClone 現在是一個 官方的模型上下文協議（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 - 查看所有認證 cookie
• ℹ️ 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

✨ 主要特性

🚀 超快的異步引擎

• 支持通過可配置的工作線程進行併發下載（5 - 50 個並行連接）
• 採用智能隊列管理，具備深度優先和廣度優先策略
• 擁有自動重試邏輯，並採用指數退避算法

🎭 動態頁面渲染

• 與 Selenium 深度集成，適用於 JavaScript 密集型網站
• 為單頁應用（如 Phoenix LiveView、React、Vue）提供自動側邊欄導航功能
• 利用 Chrome DevTools 協議生成 PDF 快照
• 支持截圖功能，用於視覺存檔

🔐 高級認證與隱身模式 ⭐ 新增

• 繞過機器人檢測：屏蔽自動化簽名（如 navigator.webdriver 等）
• 修復 GCM/FCM 錯誤：禁用 Google Cloud Messaging 註冊
• 基於 cookie 的認證：保存並複用登錄會話
• 處理“不安全瀏覽器”阻止：自動繞過 Google、Facebook 等的相關限制
• 速率限制檢測：智能節流和退避策略
• 模擬人類行為：模擬鼠標移動和自然滾動

🎨 世界級的命令行界面體驗

• 由 Rich 提供支持的精美終端用戶界面
• 即時進度條，顯示每個資源的狀態
• 彩色、格式化的輸出，包含表格和麵板
• 支持 JSON 日誌，便於生產環境監控

🏗️ 生產級架構

• 類型安全：100% 類型提示，並通過 Mypy 驗證
• 數據驗證：使用 Pydantic V2 模型，具備嚴格的模式
• 異步優先：基於 aiohttp 和 asyncio 構建
• 模塊化設計：遵循 Clean Architecture 原則，採用依賴注入
• 全面的日誌記錄：結構化的 JSON 日誌，包含上下文數據

📦 現代工具

• ⚡ uv：超快速的依賴管理工具
• 🔍 ruff：超快速的代碼檢查和格式化工具
• 🧪 pytest：全面的測試套件，覆蓋率超過 90%
• 🐳 Docker：多階段構建，使用無發行版基礎鏡像
• 🔒 安全：進行 Bandit 審計和依賴掃描

💻 使用示例

接口選項

WebClone 提供四種使用方式：

1. 🎨 桌面圖形用戶界面（最簡單 - 企業版）

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                # 請求之間的延遲時間（單位：毫秒）
  --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：手動登錄並保存 cookie
# 打開瀏覽器，你進行登錄操作，cookie 會被保存

# 示例 2：使用保存的 cookie 進行自動化操作
# 加載 cookie，繞過認證

# 示例 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")
)

# 稍後：使用保存的 cookie 進行自動化操作
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 檢測
• ✅ 速率限制和驗證碼挑戰

查看 認證指南 以獲取詳細說明。

🐳 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

# 交互式 shell
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 遵循 Clean Architecture 原則：

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. 類型安全：100% 類型覆蓋，並通過嚴格的 Mypy 檢查
3. Pydantic V2：在系統邊界進行數據驗證
4. 依賴注入：服務通過構造函數接收依賴項
5. 單一職責：每個模塊都有一個明確的目的

🧪 開發

設置開發環境

# 克隆倉庫
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. 打開拉取請求

📊 基準測試

在配備 100 Mbps 網絡連接的標準 4 核機器上進行測試：

*wget 無法渲染基於 JavaScript 的單頁應用

📄 許可證

本項目採用 Apache 許可證 2.0 - 詳情請參閱 LICENSE 文件。

👤 作者

Ruslan Magana

• 個人網站：ruslanmv.com
• GitHub：@ruslanmv
• 郵箱：contact@ruslanmv.com

🌟 星標歷史

如果你覺得 WebClone 有用，請考慮給它加個星！ ⭐

🙏 致謝

• Typer - 精美的命令行界面框架
• Rich - 豐富的終端格式化工具
• Pydantic - 數據驗證工具
• aiohttp - 異步 HTTP 客戶端
• uv - 超快速的包安裝器