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: Быстрый запуск (скрипты)

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:

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:

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

---

🐛 Troubleshooting

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

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

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

Решение 1 - Проверить логи:

tail -f /tmp/skyvern-backend.log

Решение 2 - Запустить в debug режиме:

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 - Проверить подключение к БД:

# Проверить 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:

# Закомментировать проблемный код в 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

Решение:

# Перезапустить 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:

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

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

---

📚 API Примеры

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

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:

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

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

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

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

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

---

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

LLM Settings

# Использовать другую модель 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

# 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

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

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

# Screenshots
ENABLE_SCREENSHOTS=true

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

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

# Раскомментировать в .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. Добавить новую страницу:

// src/routes/my-page.tsx
export function MyPage() {
  return <div>My Custom Page</div>;
}

2. Добавить route:

// src/routes/index.tsx
import { MyPage } from "./my-page";

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

3. Перезапустить frontend:

# 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:

# 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:

# 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.)

Просмотр схемы:

docker exec -it skyvern-postgres psql -U skyvern -d skyvern -c "\dt"

Миграции:

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:

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

Добавить в .env:

SECRET_KEY=ваш-новый-секрет-ключ

---

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

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

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

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

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

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

# Создать новый 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:

// 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"
}

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

// 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

Остановить все:

# Backend
pkill -f "uvicorn skyvern"

# Frontend
pkill -f "vite"

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

Полная переустановка:

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)