web-capture-api/README.md

# Web Capture API

网页截图与代码提取服务

## 功能特性

- 📸 **网页截图** - 全页或视口截图
- 📄 **HTML提取** - 提取完整网页源码
- 🔄 **动态内容** - 支持滚动加载动态内容
- 🎯 **自定义视口** - 可调整浏览器窗口大小
- ⚡ **RESTful API** - 简单易用的HTTP接口
- 🌐 **Web界面** - 直观的前端页面

## 系统要求

- Python 3.10+ 或 Python 3.12
- Node.js 18+ (用于 agent-browser)
- 现代浏览器（Chromium/Chrome）

## 快速开始

### 方案一：使用 agent-browser（推荐）

agent-browser 是基于 Rust 的高性能浏览器自动化工具。

```bash
# 1. 安装 Python 依赖
pip install --user flask flask-cors gunicorn

# 2. 安装 agent-browser
npm install -g agent-browser

# 3. 安装浏览器依赖（需要 sudo）
sudo apt-get install -y \
    libxcb-shm0 libx11-xcb1 libx11-6 libxcb1 libxext6 \
    libxrandr2 libxcomposite1 libxcursor1 libxdamage1 \
    libxfixes3 libxi6 libgtk-3-0 libpangocairo-1.0-0 \
    libpango-1.0-0 libatk1.0-0 libcairo-gobject2 libcairo2 \
    libgdk-pixbuf-2.0-0 libxrender1 libasound2 libfreetype6 \
    libfontconfig1 libdbus-1-3 libnss3 libnspr4 libatk-bridge2.0-0 \
    libdrm2 libxkbcommon0 libatspi2.0-0 libcups2 libxshmfence1 \
    libgbm1 fonts-noto-color-emoji fonts-noto-cjk fonts-freefont-ttf

# 4. 安装浏览器
agent-browser install

# 5. 启动服务
python3.12 app.py
```

### 方案二：使用 Playwright

Playwright 是微软开发的浏览器自动化库。

```bash
# 1. 安装依赖
pip install --user playwright flask flask-cors gunicorn

# 2. 安装浏览器
python3.12 -m playwright install chromium

# 3. 启动服务
python3.12 app.py
```

## API 接口

### POST /api/capture

**请求参数：**

```json
{
  "url": "https://example.com",        // 必填：目标网址
  "action": "screenshot",              // 必填：screenshot 或 html
  "scroll_times": 3,                   // 可选：滚动次数，默认0
  "scroll_delay": 1000,                // 可选：滚动间隔(ms)，默认1000
  "full_page": true,                   // 可选：全页截图，默认false
  "viewport": {                        // 可选：视口大小
    "width": 1920,
    "height": 1080
  },
  "wait_time": 2000,                   // 可选：页面加载等待(ms)，默认2000
  "backend": "auto"                    // 可选：auto/agent-browser/playwright
}
```

**响应：**

- `screenshot` 模式：返回 PNG 图片
- `html` 模式：返回 JSON `{"success": true, "html": "..."}`

### GET /health

健康检查接口

### GET /api

API 信息接口

## 使用示例

### 命令行调用

```bash
# 基础截图
curl -X POST http://localhost:5000/api/capture \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "action": "screenshot"}' \
  --output screenshot.png

# 提取HTML
curl -X POST http://localhost:5000/api/capture \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "action": "html"}'

# 滚动加载后全页截图
curl -X POST http://localhost:5000/api/capture \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "action": "screenshot",
    "scroll_times": 5,
    "scroll_delay": 1500,
    "full_page": true
  }' \
  --output full_page.png

# 自定义视口
curl -X POST http://localhost:5000/api/capture \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "action": "screenshot",
    "viewport": {"width": 375, "height": 812}
  }' \
  --output mobile.png
```

### Python 调用

```python
import requests

# 截图
response = requests.post(
    'http://localhost:5000/api/capture',
    json={
        'url': 'https://example.com',
        'action': 'screenshot'
    }
)
with open('screenshot.png', 'wb') as f:
    f.write(response.content)

# 提取HTML
response = requests.post(
    'http://localhost:5000/api/capture',
    json={
        'url': 'https://example.com',
        'action': 'html'
    }
)
html = response.json()['html']
print(html)
```

### JavaScript 调用

```javascript
// 截图
const response = await fetch('http://localhost:5000/api/capture', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://example.com',
    action: 'screenshot',
    scroll_times: 3,
    full_page: true
  })
});
const blob = await response.blob();

// 提取HTML
const response = await fetch('http://localhost:5000/api/capture', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    url: 'https://example.com',
    action: 'html'
  })
});
const data = await response.json();
console.log(data.html);
```

## 生产部署

### 使用 Gunicorn

```bash
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```

### 使用 Systemd 服务

```bash
# 复制服务文件
sudo cp web-capture-api.service /etc/systemd/system/

# 启动服务
sudo systemctl start web-capture-api
sudo systemctl enable web-capture-api
```

### 使用 Docker

```dockerfile
FROM python:3.12-slim

# 安装依赖
RUN apt-get update && apt-get install -y \
    wget gnupg curl \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN playwright install chromium --with-deps

COPY . .
EXPOSE 5000
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]
```

```bash
docker build -t web-capture-api .
docker run -p 5000:5000 web-capture-api
```

## 性能优化

- 使用 `--headless` 模式减少资源消耗
- 合理设置 `wait_time` 避免不必要的等待
- 滚动次数适度，避免过长处理时间
- 生产环境使用 Gunicorn 多进程

## 故障排除

### 浏览器启动失败

检查是否安装了所有依赖：

```bash
# agent-browser
agent-browser install --with-deps

# playwright
python3.12 -m playwright install-deps chromium
```

### 权限错误

确保用户有权限访问浏览器缓存目录：

```bash
mkdir -p ~/.cache/ms-playwright
chmod -R 755 ~/.cache/ms-playwright
```

### 内存不足

减少并发进程数或增加系统内存。

## 许可证

MIT License