# crawl4ai-url2md-project

**Repository Path**: aylerh/crawl4ai-url2md-project

## Basic Information

- **Project Name**: crawl4ai-url2md-project
- **Description**: 功能：（1）url2md;(2)string2md：网页内容检索；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-27
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔗 Crawl4AI URL转Markdown服务

基于 [Crawl4AI](https://github.com/unclecode/crawl4ai) 实现的智能网页内容提取工具，将任意URL转换为干净的Markdown格式。

## 页面样式
### url转markdown
![1](./images/1.png)
可追加下载链接；

### 链接提取-指定模块-指定内容
![2](./images/2.png)

### 关键词搜索URL
![3](./images/3.png)

- 默认支持 Bing / 百度，并预留搜狗 / 360 搜索扩展位
- 默认按相关度搜索最匹配结果
- 搜索结果可直接导出 Markdown、复制 URL 列表，或批量导入其他标签页
- 搜索引擎选项由后端配置接口提供，后续新增引擎前端会自动显示

## 优点
- spa页面智能提取(默认设置即可)：DOM提取质量不佳(长度=1)，尝试预加载数据提取；


## ✨ 功能特性

- 🚀 **智能提取**: 基于Crawl4AI的强大网页内容提取能力
- 🔎 **关键词搜索URL**: 支持多搜索引擎聚合、去重、相关度排序与 Markdown 导出，当前默认启用 Bing / 百度
- 🎯 **智能Fallback机制**: DOM提取失败时自动使用预加载数据提取（Zero配置）
- 🎭 **广泛SPA支持**: ModelScope, Next.js, Nuxt, Redux等多种框架
- 🔍 **预加载数据提取**: 自动识别并提取`window.__detail_data__`等预加载数据
- ⏱️ **灵活等待策略**: 支持时间等待和CSS选择器等待
-  **Markdown输出**: 自动转换为标准Markdown格式
- 🎨 **现代化界面**: 美观的中文Web界面
- 🐳 **Docker部署**: 开箱即用的容器化部署
- ⚙️ **可配置参数**: 支持等待时间、表单过滤、JS执行等自定义选项
- 💾 **文件下载**: 支持直接下载转换后的.md文件

## 🏗️ 项目结构

```
crawl4ai-url2md-project/
├── app/                    # 应用核心代码
│   ├── __init__.py        # Python包初始化
│   ├── app.py             # FastAPI应用主文件
│   ├── spa_extractor.py   # 通用SPA数据提取器
│   └── modelscope_parser.py # ModelScope专用解析器
├── Dockerfile.base         # 基础镜像构建文件
├── Dockerfile              # 应用镜像构建文件
├── docker-compose.yml      # Docker Compose配置
├── requirements-base.txt   # 基础依赖
├── requirements.txt        # 应用依赖（预留）
├── .env                    # 环境变量配置
├── static/                 # 静态文件目录
│   ├── style.css          # 样式文件
│   └── script.js          # 前端脚本
├── models/                 # 模型文件挂载目录（空）
└── docs/                   # 文档目录
    ├── 实现.md
    ├── 优化.md
    ├── SPA页面爬取指南.md
    ├── SPA爬取问题分析.md
    ├── ModelScope成功案例.md
    └── 智能爬取使用指南.md
```

## 🚀 快速开始

### 前置要求

- Docker
- Docker Compose

### 启动服务

#### 完整构建（首次使用）

1. **克隆或进入项目目录**

```powershell
cd d:\ProjectWorkspace\docker-compose-projects\url2md-project\crawl4ai-url2md-project
```

2. **配置环境变量**

编辑 `.env` 文件（已默认配置）:
```env
INNER_PORT=8101
OUTER_PORT=8101
```

3. **构建基础镜像（第一、二阶段）（可选）**

```powershell
docker build -f Dockerfile.base -t ayler/crawl4ai-url2md-base:latest .
```

> 基础镜像包含所有Python依赖和Playwright浏览器，只需构建一次。

4. **构建并启动应用（第三阶段）**

```powershell
docker compose up --build
```

5. **访问服务**

打开浏览器访问: http://localhost:8101

#### 后续启动（基础镜像已构建）

```powershell
# 直接启动（不重新构建）
docker compose up

# 或更新应用代码后重新构建
docker compose up --build
```

## 📖 使用说明

### Web界面使用

#### 基础使用

1. 在输入框中输入要转换的URL
2. 设置等待时间（默认5秒，用于页面完全加载）
3. 选择是否移除表单元素
4. 点击"开始转换"按钮
5. 查看转换结果，可复制或下载Markdown文件

#### SPA页面爬取（如ModelScope、GitHub等）

针对使用React/Vue/UmiJS等框架的单页应用：

1. **启用JavaScript执行** ✓ (默认开启)
2. **设置等待时间**: 建议5-10秒
3. **可选：输入CSS选择器**: 如`#root`、`#app`，等待特定元素加载
4. **启用预加载数据提取** ✓ (默认开启)

**示例配置（ModelScope）:**
```
URL: https://www.modelscope.cn/models/Tencent-Hunyuan/HY-MT1.5-1.8B-GPTQ-Int4
等待时间: 8秒
执行JavaScript: ✓
等待选择器: #root
提取预加载数据: ✓
```

详细说明请参考: [SPA页面爬取指南](docs/SPA页面爬取指南.md)

#### 关键词搜索URL

1. 在“关键词搜索URL”标签中输入关键词
2. 选择要使用的搜索引擎；引擎列表由后端动态下发
3. 如需精确控制，可在“设置”中切换为“同时匹配”或“或匹配”
4. 搜索完成后可查看分组结果、复制 Markdown、复制 URL 纯文本，或导入 Tab1/Tab2 继续处理

说明：
- Bing 已改为使用 BeautifulSoup 解析搜索结果，解决了因 HTML 空白/换行导致抓不到结果的问题
- 如需新增其他搜索引擎，可在后端搜索引擎配置表中注册，前端无需再手工写新的复选框

搜索结果 Markdown 包含以下列：

| 列名 | 说明 |
| --- | --- |
| 网站标题 | 结果所属网站名称，优先从搜索标题尾段提取，回退为域名主段 |
| 结果名称 | 搜索引擎返回的结果标题 |
| 链接 | 目标网页链接 |
| 时间 | 本次搜索时间 |
| 相关度 | 系统按标题命中、URL命中和原始排名综合计算的分数 |

### API接口使用

**转换接口**: `POST /convert`

请求示例:
```json
{
  "url": "https://example.com",
  "wait_for": 5,
  "remove_forms": true,
  "js_execution": true,
  "wait_for_selector": "#root",
  "extract_preloaded_data": true
}
```

响应示例:
```json
{
  "success": true,
  "url": "https://example.com",
  "markdown": "# 页面标题\n\n内容...",
  "metadata": {
    "title": "Example Domain",
    "description": "示例网站",
    "word_count": 150,
    "preloaded_data_keys": ["__detail_data__", "routerBase"]
  }
}
```

**健康检查**: `GET /health`

**关键词搜索接口**: `POST /search-urls`

**搜索引擎配置接口**: `GET /search-engines`

请求示例:
```json
{
  "keywords": "天津 招聘公告",
  "engines": ["bing", "baidu"],
  "results_per_engine": 10,
  "match_mode": "relevance",
  "dedup": true
}
```

搜索引擎配置响应示例:
```json
{
  "engines": [
    {"id": "bing", "label": "Bing", "enabled": true, "description": "微软 Bing 搜索"},
    {"id": "baidu", "label": "百度", "enabled": true, "description": "百度搜索"},
    {"id": "sogou", "label": "搜狗", "enabled": false, "description": "搜狗搜索（扩展示例）"},
    {"id": "so360", "label": "360搜索", "enabled": false, "description": "360 搜索（扩展示例）"}
  ]
}
```

响应关键字段:
```json
{
  "searched_at": "2026-03-27 15:30:00",
  "match_mode": "relevance",
  "match_mode_label": "相关度搜索",
  "total": 12,
  "markdown": "# 关键词搜索结果\n...",
  "flat_urls": ["https://example.com"],
  "flat_with_source": [
    {
      "url": "https://example.com/job",
      "title": "天津招聘公告",
      "site_title": "Example",
      "engine": "bing",
      "score": 136,
      "searched_at": "2026-03-27 15:30:00"
    }
  ]
}
```

## 🔧 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `INNER_PORT` | 容器内部端口 | 8101 |
| `OUTER_PORT` | 宿主机映射端口 | 8101 |

### Docker配置

- **多阶段构建**: 优化镜像大小
- **清华镜像源**: apt和pip使用清华大学镜像源，加速国内下载
- **Volume挂载**: 
  - `./models:/app/models` - 模型文件持久化
  - `./app.py:/app/app.py` - 支持代码热更新
  - `./static:/app/static` - 静态文件挂载

## 🏗️ 三阶段Docker构建

本项目采用优化的三阶段构建策略：

### 阶段划分

1. **第一阶段** (`Dockerfile.base`)：构建Python依赖
   - 安装编译工具
   - 编译并安装所有Python包

2. **第二阶段** (`Dockerfile.base`)：配置运行时环境
   - 安装Playwright浏览器依赖
   - 安装Chromium浏览器
   - 输出基础镜像：`ayler/crawl4ai-url2md-base:latest`

3. **第三阶段** (`Dockerfile`)：复制应用代码
   - 基于基础镜像
   - 仅复制应用代码文件
   - 输出应用镜像：`ayler/crawl4ai-url2md:latest`

### 优势

- ✅ **快速迭代**：修改代码时只需重新构建轻量级的第三阶段
- ✅ **缓存利用**：依赖和浏览器只需安装一次
- ✅ **镜像优化**：通过分层构建减少镜像大小
- ✅ **清晰分离**：依赖管理与应用代码完全分离

详细构建说明请查看 [Docker构建指南](docs/Docker构建指南.md)

## 🛠️ 技术栈

- **后端框架**: FastAPI
- **爬虫引擎**: Crawl4AI
- **浏览器自动化**: Playwright (Chromium)
- **容器化**: Docker + Docker Compose (三阶段构建)
- **前端**: 原生HTML/CSS/JavaScript
- **镜像源**: 清华大学开源镜像站（apt、pip）

## 📝 开发说明

### 本地开发

如果要在本地开发而不使用Docker:

```powershell
# 安装依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装Playwright浏览器
playwright install chromium

# 启动服务
python app.py
```

### 更新依赖时重新构建

```powershell
# 停止服务
docker compose down

# 重新构建基础镜像（如果修改了requirements.txt）
docker build -f Dockerfile.base -t ayler/crawl4ai-url2md-base:latest . --no-cache

# 重新构建并启动应用
docker compose up --build
```

### 仅更新应用代码时

```powershell
# 停止服务
docker compose down

# 重新构建应用镜像
docker compose up --build
```

### 查看日志

```powershell
docker compose logs -f
```

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License

## 🙏 致谢

- [Crawl4AI](https://github.com/unclecode/crawl4ai) - 强大的网页爬虫库
- [FastAPI](https://fastapi.tiangolo.com/) - 现代化的Python Web框架
- [Playwright](https://playwright.dev/) - 跨浏览器自动化工具