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 - 超快速的包安装器