octobrowser-api

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #android #machine-learning #linux #java #nodejs #windows #kubernetes #open-source

octobrowser-api

(★ 9)

No description available.

octobrowser-api Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OctoBrowser Service API

Микросервис для автоматизации браузерного скрейпинга через OctoBrowser с использованием Playwright и FastAPI.

## 📋 Содержание

- [Архитектура](#архитектура)
- [Требования](#требования)
- [Установка и настройка](#установка-и-настройка)
- [API Endpoints](#api-endpoints)
- [Деплой через Docker](#деплой-через-docker)
- [Конфигурация](#конфигурация)
- [Troubleshooting](#troubleshooting)

## 🏗️ Архитектура

### Основные компоненты

1. **FastAPI Application** (`main.py`)
   - Запускает веб-сервер
   - Управляет жизненным циклом приложения
   - Инициализирует WorkerManager

2. **WorkerManager** (`app/services/worker_manager.py`)
   - Управляет пулом браузеров OctoBrowser
   - Распределяет задачи между браузерами
   - Обрабатывает ротацию прокси
   - Выполняет обновление (refresh) браузеров

3. **Browser** (`app/services/browser.py`)
   - Подключается к OctoBrowser через Playwright CDP
   - Обрабатывает HTTP запросы
   - Детектирует и восстанавливается после капчи (403 ошибки)
   - Очищает куки и кеш через Chrome DevTools Protocol

4. **OctoAPI** (`app/services/octo_api.py`)
   - Взаимодействует с локальным и облачным API OctoBrowser
   - Запуск/остановка профилей браузеров
   - Получение списка профилей

5. **ProxyRotationService** (`app/services/proxy_rotation.py`)
   - Автоматическая ротация мобильных прокси
   - Периодическое обновление IP адресов

## 📦 Требования

### Системные требования

- **Python**: 3.11+
- **OctoBrowser**: Установлен и запущен локально
- **Docker** (опционально): Для контейнеризации
- **RAM**: Минимум 4GB (рекомендуется 8GB+)
- **CPU**: 2+ ядра

### Зависимости Python
Полный список в `requirements.txt`.

## 🚀 Установка и настройка

### 1. Клонирование и установка зависимостей

```bash
# Клонируйте репозиторий
git clone <repository-url>
cd octobrowser

# Создайте виртуальное окружение
python3.11 -m venv env
source env/bin/activate  # Linux/Mac
# или
.\env\Scripts\activate  # Windows

# Установите зависимости
pip install -r requirements.txt

# Установите браузеры Playwright
playwright install chromium
playwright install-deps chromium
```

### 2. Настройка OctoBrowser

#### ⚠️ КРИТИЧЕСКИ ВАЖНО!

**Создание профилей браузеров с правильными именами:**

OctoBrowser должен содержать профили с названиями, соответствующими пулам в конфигурации.

**Пример правильной настройки:**

Если в `main.py` указаны пулы `['ozon', 'wildberries']`, то профили в OctoBrowser должны называться:

```
ozon_1
ozon_2
ozon_3
...
wildberries_1
wildberries_2
wildberries_3
...
```

**Формат названия:** `{pool_name}_{номер}`

Где:
- `pool_name` - название пула (должно совпадать с именем в main.py)
- `номер` - порядковый номер (любое число)

#### Настройка OctoBrowser:

1. **Запустите OctoBrowser**
   
2. **Включите локальное API:**
   - Откройте настройки OctoBrowser
   - Найдите раздел "API"
   - Включите опцию "Enable local API"
   - Убедитесь что API доступен на порту 58888

3. **Создайте профили:**
   - Создайте необходимое количество профилей
   - Назовите их правильно: `ozon_1`, `ozon_2`, `wildberries_1` и т.д.
   - Настройте прокси для каждого профиля (если требуется)
   - Задайте Start Pages (стартовую страницу для проверки работоспособности)

4. **Получите API токен:**
   - Зайдите в [OctoBrowser Dashboard](https://app.octobrowser.net)
   - Скопируйте API токен из настроек аккаунта

### 3. Конфигурация переменных окружения

Создайте файл `app/.env`:

```bash
# Обязательные параметры
AUTH_TOKEN=your_secure_token_here_for_api_authentication

# Токен OctoBrowser для облачного API (опционально)
TOKEN=your_octobrowser_api_token

# Настройки сервера
HOST=127.0.0.1
PORT=8085
LOG_LEVEL=info

# Количество браузеров в пуле
COUNT_WORKERS=50

# Интервал ротации прокси (секунды)
PROXY_ROTATION_INTERVAL=30
```

#### Описание переменных:

| Переменная | Обязательная | Описание | По умолчанию |
|-----------|-------------|----------|--------------|
| `AUTH_TOKEN` | ✅ Да | Токен для аутентификации API запросов | - |
| `TOKEN` | ❌ Нет | Токен OctoBrowser для облачного API | "" |
| `HOST` | ❌ Нет | IP адрес для прослушивания | 127.0.0.1 |
| `PORT` | ❌ Нет | Порт сервера | 8085 |
| `LOG_LEVEL` | ❌ Нет | Уровень логирования | info |
| `COUNT_WORKERS` | ❌ Нет | Максимальное количество браузеров | 50 |
| `PROXY_ROTATION_INTERVAL` | ❌ Нет | Интервал ротации прокси (сек) | 30 |

### 4. Настройка пулов браузеров в main.py

⚠️ **ВАЖНО:** Отредактируйте `main.py` и укажите правильные названия пулов:

```python
# main.py, строка ~17
pool_names = ['ozon', 'wildberries']  # указываем нужные пулы
```

Названия должны соответствовать префиксам профилей в OctoBrowser!

### 5. Запуск приложения

#### Локальный запуск:

```bash
# Простой запуск
python main.py

# Или через uvicorn с дополнительными параметрами
uvicorn main:app --host 0.0.0.0 --port 8085 --timeout-graceful-shutdown 60
```

Сервер будет доступен по адресу: `http://127.0.0.1:8085`

## 📡 API Endpoints

### Authentication

Все запросы требуют аутентификации через Bearer токен в заголовке:

```http
Authorization: Bearer your_auth_token_here
```

### 1. GET /get - Выполнить скрейпинг

**Описание:** Отправляет запрос на указанный URL через браузер из пула и возвращает HTML контент.

**Query Parameters:**

| Параметр | Тип | Обязательный | Описание |
|----------|-----|-------------|----------|
| `url` | string | ✅ Да | URL для скрейпинга |
| `timeout` | integer | ❌ Нет | Таймаут запроса в секундах (по умолчанию: 30) |
| `selector` | string | ❌ Нет | CSS селектор для извлечения конкретного элемента |
| `spider` | string | ❌ Нет | Название пула браузеров (по умолчанию: spider_default) |
| `cookies` | string | ❌ Нет | JSON строка с куками для установки |

**Пример запроса:**

```bash
curl -X GET "http://localhost:8085/get?url=https://example.com&timeout=30&spider=ozon" \
  -H "Authorization: Bearer your_auth_token_here"
```

**С параметрами:**

```bash
curl -X GET "http://localhost:8085/get?url=https://ozon.ru/category/12345&timeout=60&selector=.product-card&spider=ozon" \
  -H "Authorization: Bearer your_auth_token_here"
```

**Ответ (200 OK):**

```json
{
  "url": "https://example.com",
  "html": "<!DOCTYPE html><html>...</html>",
  "cookies": {
    "session_id": "abc123",
    "user_token": "xyz789"
  },
  "status_code": 200
}
```

**Ошибки:**

- `401 Unauthorized` - Неверный или отсутствующий токен
- `408 Request Timeout` - Превышено время ожидания
- `502 Bad Gateway` - Ошибка подключения к браузеру
- `503 Service Unavailable` - WorkerManager не инициализирован
- `500 Internal Server Error` - Внутренняя ошибка сервера

### 2. GET /health - Проверка здоровья сервиса

**Описание:** Возвращает статус сервиса и информацию о пуле браузеров.

**Пример запроса:**

```bash
curl -X GET "http://localhost:8085/health"
```

**Ответ (200 OK):**

```json
{
  "status": "healthy",
  "worker_manager": {
    "total_browsers": 10,
    "available_browsers": 8,
    "busy_browsers": 2,
    "active_tasks": 2,
    "pools": {
      "ozon": {
        "total": 5,
        "available": 4,
        "busy": 1
      },
      "wildberries": {
        "total": 5,
        "available": 4,
        "busy": 1
      }
    },
    "browser_profiles": [
      {
        "profile_uuid": "abc-123-def-456",
        "title": "ozon_1",
        "browser_pid": 12345,
        "is_busy": false,
        "pool": "ozon"
      }
    ]
  }
}
```

### 3. GET /status - Детальный статус

**Описание:** Возвращает детальную информацию о состоянии всех браузеров.

**Пример запроса:**

```bash
curl -X GET "http://localhost:8085/status"
```

**Ответ:** Аналогичен `/health` без обёртки status.

## 🐳 Деплой через Docker

### Подготовка

1. **Убедитесь что OctoBrowser запущен на хост-машине**
2. **Создайте файл `app/.env` с необходимыми переменными**
3. **Отредактируйте `docker-compose.yaml` если требуется изменить порты**

### Сборка и запуск

```bash
# Сборка образа
docker-compose build

# Запуск контейнера
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановка
docker-compose down
```

### Особенности Docker деплоя

#### Network Mode: Host

```yaml
network_mode: "host"
```

⚠️ **ВАЖНО:** Используется `network_mode: "host"` чтобы контейнер мог подключаться к OctoBrowser API на `localhost:58888`.

Это означает:
- Контейнер использует сетевой стек хоста
- Порты приложения напрямую доступны на хосте
- Работает только на Linux (на Mac/Windows может потребоваться настройка)

#### Health Check

```yaml
healthcheck:
  test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8085/health', timeout=5.0)"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

Docker автоматически проверяет здоровье контейнера каждые 30 секунд.

### Логи

Логи записываются в:
- Stdout контейнера (просмотр через `docker-compose logs`)
- Файл `app/log.txt` (только ошибки)

Настройки ротации логов:
```yaml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
```

## ⚙️ Конфигурация

### Настройка прокси ротации

Прокси URL настраиваются в `app/resources/proxy_urls.py`:

```python
proxy_urls = {
    "proxys.io": [
        "https://proxys.io/ru/api/v2/change-mobile-proxy-ip?key=YOUR_KEY&order=12345&proxy=1",
    ],
    "mobileproxy.space": [
        "https://changeip.mobileproxy.space/?proxy_key=YOUR_KEY",
    ]
}
```

Для отключения ротации прокси - оставьте словарь пустым:
```python
proxy_urls = {}
```

### Настройка лимитов браузеров

В `app/services/browser.py`:

```python
self.max_request_count = random.randint(500, 1000)  # Запросов до обновления
self._max_connection_errors = 20  # Ошибок подключения до обновления
```

### Интервалы между запросами

В `app/services/worker_manager.py`:

```python
min_interval = 4.0  # Минимальный интервал между запросами (секунды)
```

## 🔧 Troubleshooting

### Проблема: "AUTH_TOKEN не задан"

**Ошибка:**
```
❌ ОШИБКА: Переменная AUTH_TOKEN не задана в .env файле!
```

**Решение:**
1. Создайте файл `app/.env`
2. Добавьте строку: `AUTH_TOKEN=your_secure_token_here`
3. Перезапустите приложение

### Проблема: "OctoBrowser локальное API недоступно"

**Ошибка:**
```
⚠️ ПРЕДУПРЕЖДЕНИЕ: OctoBrowser локальное API недоступно!
Не удалось подключиться к http://localhost:58888
```

**Решение:**
1. Убедитесь что OctoBrowser запущен
2. Проверьте что локальное API включено в настройках
3. Проверьте доступность:
   ```bash
   curl http://localhost:58888/api/profiles/active
   ```

### Проблема: "No browsers initialized"

**Причины:**
- Неправильные названия профилей в OctoBrowser
- Профили не совпадают с пулами в `main.py`

**Решение:**
1. Проверьте названия профилей в OctoBrowser
2. Убедитесь что они следуют формату: `{pool_name}_{number}`
3. Проверьте что pool_names в `main.py` совпадают с префиксами профилей:
   ```python
   pool_names = ['ozon', 'wildberries']  # должны совпадать с префиксами
   ```

### Проблема: Браузер постоянно попадает на капчу

**Решение:**
1. Система автоматически детектирует капчу
2. Очищает куки и кеш
3. Ждёт ротацию IP (через ProxyRotationService)
4. Проверяет доступность start_page
5. Если капча всё ещё есть - выполняет полное обновление браузера

Убедитесь что:
- Настроена ротация прокси
- У профилей задана start_page для проверки

### Проблема: Docker контейнер не может подключиться к OctoBrowser

**Решение:**

На **Linux**: Используйте `network_mode: "host"` (уже настроено)

На **Mac/Windows**: 
1. Замените в `docker-compose.yaml`:
   ```yaml
   network_mode: "bridge"
   ```
2. В `app/core/octo.py` измените:
   ```python
   api_url_local: str = "http://host.docker.internal:58888"
   ```

### Проблема: Медленная работа / высокая нагрузка

**Решение:**
1. Уменьшите `COUNT_WORKERS` в `.env`
2. Увеличьте `min_interval` между запросами
3. Оптимизируйте таймауты запросов
4. Используйте более мощное железо

### Логирование и отладка

Логи содержат детальную информацию:

```bash
# Просмотр всех логов
tail -f app/log.txt

# Просмотр только ошибок
grep "❌\|ERROR" app/log.txt

# Просмотр логов Docker
docker-compose logs -f octobrowser
```

Уровни логирования:
- `🔍 DEBUG` - Детальная отладочная информация
- `✅ INFO` - Обычная работа
- `⚠️ WARNING` - Предупреждения
- `❌ ERROR` - Ошибки
- `🔥 CRITICAL` - Критические ошибки

## 🛠️ Используемые технологии и библиотеки

### Backend Framework
- **FastAPI** - Современный веб-фреймворк для создания API
- **Uvicorn** - ASGI сервер для запуска FastAPI
- **Pydantic** - Валидация данных и настроек

### Браузерная автоматизация
- **Playwright** - Управление браузерами через Chrome DevTools Protocol
- **OctoBrowser** - Антидетект браузер для обхода защиты

### HTTP клиенты
- **HTTPX** - Async HTTP клиент для взаимодействия с OctoBrowser API
- **Requests** - HTTP библиотека

### Прокси и ротация IP
- **ProxyRotationService** - Кастомный сервис для автоматической ротации

### Конфигурация
- **python-dotenv** - Загрузка переменных окружения из .env
- **pydantic-settings** - Управление настройками приложения

### База данных (опционально)
- **psycopg2-binary** - PostgreSQL адаптер для Python

---

**Важные напоминания:**
- ✅ Всегда проверяйте соответствие названий профилей в OctoBrowser и пулов в main.py
- ✅ Создайте и настройте app/.env перед запуском
- ✅ Убедитесь что OctoBrowser запущен и доступен на localhost:58888
- ✅ Используйте правильный AUTH_TOKEN для API запросов
- ✅ Для production деплоя используйте Docker с правильными настройками сети

octobrowser-api

octobrowser-api Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

octobrowser-api

octobrowser-api Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README