Browser-Use API

基于 browser-use 的浏览器自动化API服务，使用 FastAPI 构建的 REST API 接口。

功能特性

• 🚀 基于 FastAPI 的高性能 REST API
• 🤖 集成 browser-use 库进行浏览器自动化
• 🔄 支持异步处理和并发控制
• 📝 完整的 API 文档（Swagger UI）
• 🐳 Docker 容器化部署
• 📊 健康检查和监控接口
• 🔒 可选的 API 密钥认证
• 📋 详细的错误处理和日志记录

快速开始

环境要求

• Python 3.11+
• OpenAI API Key
• Docker（可选，用于容器化部署）

本地开发

1. 克隆项目

git clone <repository-url>
cd browser-use-api

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，设置必要的环境变量

4. 安装 Playwright 浏览器

playwright install chromium

5. 启动服务

python -m app.main
# 或者使用 uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Docker 部署

1. 使用 Docker Compose（推荐）

# 复制环境变量文件
cp .env.example .env
# 编辑 .env 文件，设置 OPENAI_API_KEY 等必要变量

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f browser-use-api

2. 使用 Docker

# 构建镜像
docker build -t browser-use-api .

# 运行容器
docker run -d \
  --name browser-use-api \
  -p 8000:8000 \
  -e OPENAI_API_KEY=your_api_key \
  browser-use-api

API 接口

基础信息

• Base URL: http://localhost:8000
• API 文档: http://localhost:8000/docs
• ReDoc 文档: http://localhost:8000/redoc

主要接口

1. 执行浏览器任务

POST /api/v1/execute

执行浏览器自动化任务。

请求参数:

{
  "url": "https://example.com",
  "prompt": "点击登录按钮并填写表单",
  "timeout": 30,
  "headless": true
}

响应示例:

{
  "success": true,
  "result": "任务执行成功",
  "data": {
    "page_title": "Example Domain",
    "page_url": "https://example.com",
    "result": "任务完成"
  },
  "error": null,
  "execution_time": 5.2
}

2. 健康检查

GET /api/v1/health

检查服务运行状态。

响应示例:

{
  "status": "healthy",
  "service": "browser-use-api",
  "timestamp": "2024-01-01T12:00:00"
}

3. 服务状态

GET /api/v1/status

获取详细的服务状态信息。

响应示例:

{
  "service": "browser-use-api",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2024-01-01T12:00:00",
  "config": {
    "max_concurrent_browsers": 5,
    "default_timeout": 30,
    "headless_mode": true,
    "openai_model": "gpt-4-vision-preview"
  }
}

配置说明

环境变量

变量名	描述	默认值	必需
HOST	服务监听地址	0.0.0.0	否
PORT	服务端口	8000	否
DEBUG	调试模式	false	否
OPENAI_API_KEY	OpenAI API 密钥	-	是
OPENAI_MODEL	OpenAI 模型	gpt-4-vision-preview	否
BROWSER_HEADLESS	无头模式	true	否
BROWSER_TIMEOUT	默认超时时间(秒)	30	否
MAX_CONCURRENT_BROWSERS	最大并发浏览器数	5	否
API_KEY	API 密钥认证	-	否
LOG_LEVEL	日志级别	INFO	否

API 认证

如果设置了 API_KEY 环境变量，需要在请求头中包含：

X-API-Key: your_api_key

使用示例

Python 客户端

import requests

# 基本请求
response = requests.post(
    "http://localhost:8000/api/v1/execute",
    json={
        "url": "https://example.com",
        "prompt": "获取页面标题",
        "timeout": 30
    }
)

result = response.json()
print(result)

cURL 示例

# 执行浏览器任务
curl -X POST "http://localhost:8000/api/v1/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "prompt": "点击页面上的链接",
    "timeout": 30,
    "headless": true
  }'

# 健康检查
curl "http://localhost:8000/api/v1/health"

JavaScript 客户端

// 使用 fetch API
const response = await fetch('http://localhost:8000/api/v1/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    prompt: '获取页面信息',
    timeout: 30
  })
});

const result = await response.json();
console.log(result);

项目结构

browser-use-api/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py        # API 路由定义
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py        # 配置管理
│   │   └── browser_agent.py # browser-use 封装
│   └── models/
│       ├── __init__.py
│       └── schemas.py       # Pydantic 模型
├── requirements.txt         # Python 依赖
├── Dockerfile              # Docker 镜像构建
├── docker-compose.yml      # Docker Compose 配置
├── .env.example            # 环境变量示例
└── README.md               # 项目文档

开发指南

添加新功能

1. 在 app/models/schemas.py 中定义新的数据模型
2. 在 app/core/browser_agent.py 中实现业务逻辑
3. 在 app/api/routes.py 中添加新的路由
4. 更新文档和测试

代码规范

# 格式化代码
black app/
isort app/

# 代码检查
flake8 app/

# 运行测试
pytest

故障排除

常见问题

1. OpenAI API Key 错误

   • 确保设置了正确的 OPENAI_API_KEY
   • 检查 API Key 是否有效且有足够余额

2. 浏览器启动失败

   • 确保已安装 Playwright 浏览器：playwright install chromium
   • 在 Docker 中确保有足够的内存和 CPU 资源

3. 超时错误

   • 增加 timeout 参数值
   • 检查目标网站是否可访问
   • 优化 prompt 指令

4. 并发限制

   • 调整 MAX_CONCURRENT_BROWSERS 环境变量
   • 监控系统资源使用情况

日志查看

# Docker Compose
docker-compose logs -f browser-use-api

# Docker
docker logs -f browser-use-api

# 本地开发
tail -f browser-use-api.log

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 基础 API 功能实现
• Docker 支持
• 完整文档