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 的高性能浏览器自动化工具。

# 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 是微软开发的浏览器自动化库。

# 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

请求参数：

{
  "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 信息接口

使用示例

命令行调用

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

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

# 滚动加载后全页截图
curl -X POST http://localhost:16026/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:16026/api/capture \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "action": "screenshot",
    "viewport": {"width": 375, "height": 812}
  }' \
  --output mobile.png

Python 调用

import requests

# 截图
response = requests.post(
    'http://localhost:16026/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:16026/api/capture',
    json={
        'url': 'https://example.com',
        'action': 'html'
    }
)
html = response.json()['html']
print(html)

JavaScript 调用

// 截图
const response = await fetch('http://localhost:16026/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:16026/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

gunicorn -w 4 -b 0.0.0.0:16026 app:app

使用 Systemd 服务

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

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

使用 Docker

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:16026", "app:app"]

docker build -t web-capture-api .
docker run -p 16026:16026 web-capture-api

性能优化

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

故障排除

浏览器启动失败

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

# agent-browser
agent-browser install --with-deps

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

权限错误

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

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

内存不足

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

许可证

MIT License