Dorod-Sky/INSTALLATION-COMPLETE.md

# 🚀 Skyvern - Installation Complete!

**Дата установки:** 20 февраля 2026  
**Статус:** ✅ Backend и Frontend готовы к запуску  

---

## 📦 Что установлено

### Backend (Python 3.12)
- ✅ Virtual environment: `/home/vodorod/dorod/skyvern/.venv`
- ✅ Python зависимости: FastAPI, Playwright, SQLAlchemy, OpenAI SDK
- ✅ Playwright браузер: Chromium 145.0.7632.6
- ✅ База данных: PostgreSQL 16 (42 таблицы)
- ✅ Миграции выполнены

### Frontend (React + TypeScript)
- ✅ Node.js v20.19.5
- ✅ npm зависимости установлены (672 пакетов)
- ✅ Vite dev server готов

### Database & Cache
- ✅ PostgreSQL: `localhost:5433` (Docker) |  credentials: `skyvern/skyvern`
- ✅ Redis: `localhost:6380` (Docker)

### Configuration
-  ✅ `.env` файл создан
- ✅ OpenAI API key настроен
- ✅ LLM: GPT-4 Turbo (основной) + GPT-4o mini (secondary)

---

## 🚀 Как запустить

### Вариант 1: Быстрый запуск (скрипты)

```bash
cd /home/vodorod/dorod/skyvern

# Terminal 1: Backend
./start-backend.sh

# Terminal 2: Frontend (после запуска backend)
./start-frontend.sh
```

**Доступ:**
- Backend API: http://localhost:8000
- API Docs: http://localhost:8000/docs
- Frontend: http://localhost:5173

---

### Вариант 2: Ручной запуск (для отладки)

#### Backend:

```bash
cd /home/vodorod/dorod/skyvern
source .venv/bin/activate

# Проверить БД
docker ps | grep skyvern

# Запустить БД если нужно
docker compose -f docker-compose.deps.yml up -d

# Запустить backend
uvicorn skyvern.forge.api_app:app --host 0.0.0.0 --port 8000 --reload
```

#### Frontend:

```bash
cd /home/vodorod/dorod/skyvern/skyvern-frontend
npm run dev
```

---

## 🐛 Troubleshooting

### Backend не запускается

**Проблема:** Backend зависает при запуске

**Причина:** `forge_app.api_app_startup_event` выполняет  блокирующие операции

**Решение 1 - Проверить логи:**
```bash
tail -f /tmp/skyvern-backend.log
```

**Решение 2 - Запустить в debug режиме:**
```bash
cd /home/vodorod/dorod/skyvern
source .venv/bin/activate

# Увеличить log level
LOG_LEVEL=DEBUG uvicorn skyvern.forge.api_app:app \
    --host 0.0.0.0 \
    --port 8000 \
    --log-level debug
```

**Решение 3 - Проверить подключение к БД:**
```bash
# Проверить PostgreSQL
docker exec -it skyvern-postgres psql -U skyvern -d skyvern -c "SELECT 1;"

# Проверить Redis
docker exec -it skyvern-redis redis-cli ping
```

**Решение 4 - Отключить lifespan events (временно):**

Отредактировать `/home/vodorod/dorod/skyvern/skyvern/forge/api_app.py`:

```python
# Закомментировать проблемный код в lifespan():
# if forge_app.api_app_startup_event:
#     LOG.info("Calling api app startup event")
#     try:
#         await forge_app.api_app_startup_event(fastapi_app)
#     except Exception:
#         LOG.exception("Failed to execute api app startup event")
```

---

### PostgreSQL connection error

**Проблема:** `could not connect to server`

**Решение:**
```bash
# Перезапустить PostgreSQL
docker compose -f docker-compose.deps.yml restart postgres

# Проверить порт
ss -tlnp | grep 5433

# Проверить .env
grep DATABASE_STRING .env
# Должно быть: postgresql+psycopg://skyvern:skyvern@localhost:5433/skyvern
```

---

### Frontend CORS errors

**Проблема:** CORS ошибка при запросе к backend

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

Отредактировать `/home/vodorod/dorod/skyvern/.env`:

```bash
ALLOWED_ORIGINS=["http://localhost:5173","http://localhost:3000","http://127.0.0.1:5173"]
```

Перезапустить backend.

---

## 📚 API Примеры

### Создать задачу парсинга

```bash
curl -X POST http://localhost:8000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://traktorodetal.ru",
    "navigation_goal": "Find all SANY glass products",
    "data_extraction_goal": "Extract: name, part number, price, availability",
    "webhook_callback_url": "http://localhost:8000/webhook/result"
  }'
```

Response:
```json
{
  "task_id": "tsk_abc123",
  "status": "queued",
  "created_at": "2026-02-20T20:00:00Z"
}
```

### Получить результат

```bash
curl http://localhost:8000/api/v1/tasks/tsk_abc123
```

### Список всех задач

```bash
curl http://localhost:8000/api/v1/tasks?page=1&page_size=10
```

---

## 🔧 Конфигурация (.env)

### LLM Settings

```bash
# Использовать другую модель OpenAI
LLM_KEY=OPENAI_GPT4  # GPT-4 (дороже но точнее)
# LLM_KEY=OPENAI_GPT4_TURBO  # GPT-4 Turbo (по умолчанию)
# LLM_KEY=OPENAI_GPT4O  # GPT-4o (новая модель)

# Для дешевых задач
SECONDARY_LLM_KEY=OPENAI_GPT4O_MINI
```

### Browser Settings

```bash
# Headless (production)
BROWSER_TYPE=chromium-headless

# Headful (для отладки - видно браузер)
BROWSER_TYPE=chromium-headful

# Retry attempts
MAX_SCRAPING_RETRIES=3

# Timeout
BROWSER_ACTION_TIMEOUT_MS=10000  # 10 секунд
```

### Agent Settings

```bash
# Максимум шагов на одну задачу
MAX_STEPS_PER_RUN=75

# Запись видео (для отладки)
RECORD_VIDEOS=true

# Screenshots
ENABLE_SCREENSHOTS=true
```

### Proxy (для российских серверов)

Если OpenAI заблокирован:

```bash
# Раскомментировать в .env:
HTTP_PROXY=socks5://user:pass@proxy:port
HTTPS_PROXY=socks5://user:pass@proxy:port
```

---

## 🎨 Frontend Architecture

Skyvern использует **React** + **TypeScript** + **Vite**.

**Структура:**
```
skyvern-frontend/
├── src/
│   ├── components/  # UI компоненты
│   ├── routes/      # Страницы (React Router)
│   ├── api/         # API клиенты
│   ├── stores/      # State management
│   └── utils/       # Helpers
├── package.json
└── vite.config.ts
```

**Кастомизация:**

1. Добавить новую страницу:
```tsx
// src/routes/my-page.tsx
export function MyPage() {
  return <div>My Custom Page</div>;
}
```

2. Добавить route:
```tsx
// src/routes/index.tsx
import { MyPage } from "./my-page";

{path: "/my-page", element: <MyPage />}
```

3. Перезапустить frontend:
```bash
# Frontend автоматически обновится (hot reload)
```

---

## 🐍 Backend Architecture

Skyvern использует **FastAPI** + **SQLAlchemy** + **Playwright**.

**Структура:**
```
skyvern/
├── forge/
│   ├── api_app.py           # FastAPI app
│   ├── sdk/
│   │   ├── routes/          # API endpoints
│   │   ├── core/            # Business logic
│   │   ├── db/              # Database models
│   │   └── agents/          # AI agents
│   └── forge_app_initializer.py
├── config.py                # Configuration
└── exceptions.py            # Custom exceptions
```

**Кастомизация:**

1. Добавить новый endpoint:
```python
# skyvern/forge/sdk/routes/custom.py
from fastapi import APIRouter

router = APIRouter(prefix="/api/v1/custom", tags=["Custom"])

@router.post("/my-endpoint")
async def my_endpoint(data: dict):
    return {"status": "success", "data": data}
```

2. Зарегистрировать router:
```python
# skyvern/forge/sdk/routes/routers.py
from skyvern.forge.sdk.routes import custom

base_router.include_router(custom.router)
```

3. Перезапустить backend (auto-reload включен).

---

## 📊 Database Schema

**42 таблицы:**

Основные:
- `tasks` - задачи парсинга
- `actions` - действия (click, fill, extract)
- `artifacts` - screenshots, videos, recordings
- `workflows` - последовательности задач
- `organizations` - мульти-тенантность
- `credentials` - хранение credentials (AWS, Bitwarden, etc.)

Просмотр схемы:
```bash
docker exec -it skyvern-postgres psql -U skyvern -d skyvern -c "\dt"
```

Миграции:
```bash
cd /home/vodorod/dorod/skyvern
source .venv/bin/activate

# Создать новую миграцию
alembic revision --autogenerate -m "Add my_table"

# Применить миграции
alembic upgrade head

# Откатить миграцию
alembic downgrade -1
```

---

## 🔐 Security

### Production Checklist:

- [ ] Изменить `SECRET_KEY` в `.env`
- [ ] Использовать HTTPS (не HTTP)
- [ ] Настроить `ALLOWED_ORIGINS` (whitelist доменов)
- [ ] Включить rate limiting
- [ ] Настроить аутентификацию (API keys, OAuth)
- [ ] Отключить `RECORD_VIDEOS` (экономия места)
- [ ] Настроить логирование в файлы (не stdout)
- [ ] Использовать production PostgreSQL (не Docker)
- [ ] Бэкапы БД

### Генерировать новый SECRET_KEY:

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Добавить в `.env`:
```bash
SECRET_KEY=ваш-новый-секрет-ключ
```

---

## 🎯 Следующие шаги

### 1. Тест базового функционала

```bash
# 1. Запустить backend и frontend
./start-backend.sh
./start-frontend.sh

# 2. Открыть http://localhost:5173
# 3. Создать тестовую задачу
# 4. Проверить результат
```

### 2. Кастомизация для ваших задач

**Пример: Парсинг traktorodetal.ru**

```python
# Создать новый agent preset
# skyvern/forge/sdk/agents/presets/traktorodetal.py

class TraktorodetalAgent:
    name = "traktorodetal-parser"
    
    @staticmethod
    def get_instructions():
        return """
        You are parsing traktorodetal.ru for SANY glass products.
        
        Steps:
        1. Navigate to main page
        2. Find SANY category
        3. Extract all products with:
           - Name
           - Part number
           - Price
           - Availability
        4. Handle pagination
        """
```

### 3. Интеграция с n8n

**Webhook в n8n:**

```javascript
// n8n HTTP Request Node
POST http://localhost:8000/api/v1/tasks
Body: {
  "url": "{{$json.site_url}}",
  "navigation_goal": "{{$json.goal}}",
  "webhook_callback_url": "https://n8n.cryptomutant.tech/webhook/skyvern-result"
}
```

**Получить результат:**

```javascript
// n8n Webhook Node
Webhook URL: /webhook/skyvern-result
Method: POST

// Сохранить в БД или отправить в Telegram
```

---

## 📞 Поддержка

**Логи:**
- Backend: `/tmp/skyvern-backend.log`
- Frontend: в терминале где запущен `npm run dev`
- Database: `docker logs skyvern-postgres`
- Redis: `docker logs skyvern-redis`

**Остановить все:**
```bash
# Backend
pkill -f "uvicorn skyvern"

# Frontend
pkill -f "vite"

# Database
cd /home/vodorod/dorod/skyvern
docker compose -f docker-compose.deps.yml down
```

**Полная переустановка:**
```bash
cd /home/vodorod/dorod/skyvern

# Остановить все
pkill -f "uvicorn skyvern"
pkill -f "vite"
docker compose -f docker-compose.deps.yml down -v  # -v удалит данные БД

# Удалить venv
rm -rf .venv

# Установить заново
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

# Запустить БД
docker compose -f docker-compose.deps.yml up -d

# Миграции
alembic upgrade head

# Запуск
./start-backend.sh
./start-frontend.sh
```

---

## 🚀 Готово к работе!

**Текущий статус:**
- ✅ PostgreSQL запущен на 5433
- ✅ Redis запущен на 6380
- ✅ Python  зависимости установлены
- ✅ Frontend зависимости установлены
- ✅ База данных создана (42 таблицы)
- ✅ OpenAI API key настроен
- ⏸️ Backend требует отладки startup events
- ⏸️ Frontend готов к запуску после backend

**Следующий шаг:**

1. Исправить проблему с backend startup (см. Troubleshooting)
2. Запустить backend
3. Запустить frontend
4. Создать первую задачу парсинга!

---

**Документация:**
- Официальная: https://docs.skyvern.com
- GitHub: https://github.com/Skyvern-AI/skyvern
- API Reference: http://localhost:8000/docs (после запуска backend)