Краткое руководство

Краткое руководство

Запустите CodeGraph API за 10 минут.

Содержание

Предварительные требования

  • Python 3.10+ (рекомендуется 3.11)
  • PostgreSQL 15+ (должна быть запущена и доступна)
  • Минимум 16 ГБ ОЗУ
  • Не менее 50 ГБ свободного места на диске

Быстрый старт: API-сервер

Шаг 1: Клонируйте репозиторий и установите зависимости

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

# Создайте и активируйте виртуальное окружение
python -m venv venv
source venv/bin/activate  # В Windows: venv\Scripts\activate

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

Шаг 2: Установите пароль базы данных

# Установите пароль PostgreSQL
export DATABASE_URL="postgresql+asyncpg://postgres:your_password@localhost:5432/codegraph"

# В Windows PowerShell:
$env:DATABASE_URL="postgresql+asyncpg://postgres:your_password@localhost:5432/codegraph"

Примечание: Замените your_password на реальный пароль пользователя postgres в вашей PostgreSQL.

Шаг 3: Инициализация базы данных

# Создание базы данных и таблиц
python -m src.api.cli init-db

Ожидаемый вывод:

Database initialized successfully

Шаг 4: Создание администратора

# Создание учётной записи администратора
python -m src.api.cli create-admin --username admin --password admin123

# Для продакшена используйте надёжный пароль:
python -m src.api.cli create-admin --username admin --password <strong_password>

Ожидаемый вывод:

Admin user created: admin (ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Шаг 5: Запуск API-сервера

# Запуск сервера
python -m src.api.cli run --host 127.0.0.1 --port 8000

Ожидаемый вывод:

INFO:     Started server process [12345]
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000

Шаг 6: Проверка установки

Вариант A: Использование Swagger UI (рекомендуется)

Откройте браузер и перейдите по адресу:

http://127.0.0.1:8000/api/docs

Вы увидите интерактивную документацию API, где сможете: 1. Нажать кнопку “Authorize” (Авторизация) 2. Использовать POST /api/v1/auth/token для получения JWT-токена 3. Интерактивно опробовать API-эндпоинты

Вариант B: Использование curl

# 1. Проверка работоспособности
curl http://127.0.0.1:8000/api/v1/health

# 2. Получение токена аутентификации
curl -X POST http://127.0.0.1:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

Ожидаемый ответ:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 1800
}

# 3. Использование токена (замените TOKEN на ваш access_token)
curl http://127.0.0.1:8000/api/v1/scenarios \
  -H "Authorization: Bearer TOKEN"

Типовые случаи использования

Случай 1: Доступ к документации API

# Запуск сервера
python -m src.api.cli run --host 127.0.0.1 --port 8000

# Открыть в браузере:
# http://127.0.0.1:8000/api/docs (Swagger UI)
# http://127.0.0.1:8000/api/redoc (ReDoc)

Случай 2: Тестирование с примерами запросов

# Получение токена
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  | python -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

# Запрос сценариев
curl http://127.0.0.1:8000/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN"

# Запуск сессии чата
curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Найти все функции, отвечающие за аутентификацию пользователей",
    "scenario_id": "security_review"
  }'

Случай 3: Создание API-ключа для программного доступа

# Сначала получите JWT-токен
TOKEN="ваш_токен_доступа"

# Создание API-ключа
curl -X POST http://127.0.0.1:8000/api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Мое приложение",
    "expires_days": 365,
    "scopes": ["scenarios:read", "query:execute"]
  }'

# Использование API-ключа в запросах
curl http://127.0.0.1:8000/api/v1/scenarios \
  -H "X-API-Key: ваш_api_ключ"

Быстрая настройка

Изменение порта сервера

# Запуск на другом порту
python -m src.api.cli run --host 127.0.0.1 --port 8080

Включение автоматической перезагрузки для разработки

# Автоматическая перезагрузка при изменении кода
python -m src.api.cli run --host 127.0.0.1 --port 8000 --reload

Запуск с несколькими рабочими процессами (для продакшена)

# Использование 4 рабочих процессов
python -m src.api.cli run --host 0.0.0.0 --port 8000 --workers 4

Устранение неполадок

Ошибка подключения к базе данных

# Ошибка: "база данных не существует"
# Решение: Выполните команду init-db
python -m src.api.cli init-db

# Ошибка: "ошибка аутентификации по паролю"
# Решение: Проверьте пароль в DATABASE_URL
export DATABASE_URL="postgresql+asyncpg://postgres:правильный_пароль@localhost:5432/codegraph"

Порт уже используется

# Ошибка: "адрес уже используется"
# Решение: Завершите процесс, использующий порт 8000

# Windows:
netstat -ano | findstr :8000
taskkill /F /PID <PID>

# Linux:
lsof -ti:8000 | xargs kill -9

# Или используйте другой порт:
python -m src.api.cli run --host 127.0.0.1 --port 8001

PostgreSQL не запущен

# Проверка состояния PostgreSQL
# Windows:
Get-Service postgresql*

# Linux:
sudo systemctl status postgresql

# Запустите PostgreSQL, если он не работает
sudo systemctl start postgresql

Обзор API-эндпоинтов

После запуска сервера становятся доступны следующие эндпоинты:

Категория Эндпоинт Описание
Auth POST /api/v1/auth/token Получить JWT-токен доступа
POST /api/v1/auth/refresh Обновить токен доступа
POST /api/v1/auth/api-keys Создать API-ключ
Chat POST /api/v1/chat Отправить сообщение в чат
POST /api/v1/chat/stream Потоковая передача чата
Scenarios GET /api/v1/scenarios Список сценариев анализа
POST /api/v1/scenarios/{id}/query Выполнить запрос сценария
Query POST /api/v1/query/execute Выполнить пользовательский запрос
Review POST /api/v1/review/patch Проверить код патча
POST /api/v1/review/pr Проверить pull request
Sessions GET /api/v1/sessions Список сессий пользователя
GET /api/v1/sessions/{id} Получить детали сессии
Health GET /api/v1/health Проверка работоспособности системы

Полную документацию по API можно посмотреть по адресу http://127.0.0.1:8000/api/docs после запуска сервера.

Дальнейшие шаги

Обязательное к прочтению

Продвинутые темы

Дополнительные интеграции

Пример: Полный рабочий процесс

Ниже приведён полный пример рабочего процесса для анализа безопасности кода:

# 1. Настройка окружения
export DATABASE_URL="postgresql+asyncpg://postgres:your_password@localhost:5432/codegraph"

# 2. Инициализация базы данных
python -m src.api.cli init-db

# 3. Создание администратора
python -m src.api.cli create-admin --username admin --password SecurePass123

# 4. Запуск сервера
python -m src.api.cli run --host 127.0.0.1 --port 8000 &

# 5. Получение токена аутентификации
TOKEN=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"SecurePass123"}' \
  | python -c "import sys, json; print(json.load(sys.stdin)['access_token'])")

# 6. Получение списка доступных сценариев
curl http://127.0.0.1:8000/api/v1/scenarios \
  -H "Authorization: Bearer $TOKEN" | python -m json.tool

# 7. Выполнение сценария проверки безопасности
curl -X POST http://127.0.0.1:8000/api/v1/scenarios/security_review/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Найти возможные уязвимости типа SQL-инъекция",
    "options": {"detailed": true}
  }' | python -m json.tool

# 8. Запуск интерактивного чата
curl -X POST http://127.0.0.1:8000/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Покажи все функции, связанные с аутентификацией",
    "scenario_id": "security_review"
  }' | python -m json.tool

Советы для успеха

  1. Используйте Swagger UI для исследования — интерактивная документация по адресу /api/docs позволяет легко опробовать конечные точки
  2. Сохраняйте токен доступа — токены действительны по умолчанию в течение 30 минут
  3. Проверяйте логи при ошибках — в логах сервера отображаются подробные сообщения об ошибках
  4. Начинайте с проверки работоспособности — всегда убеждайтесь, что /api/v1/health возвращает статус «здоров»
  5. Используйте API-ключи для автоматизации — создавайте API-ключи для скриптов и приложений

Получение помощи

  • Ознакомьтесь с руководством по устранению неполадок
  • Проверьте логи на наличие сообщений об ошибках
  • Убедитесь в работоспособности подключения к базе данных через эндпоинт проверки состояния (health endpoint)
  • Убедитесь, что PostgreSQL запущен и доступен
  • Проверьте правильность настройки переменной DATABASE_URL

Готовы изучить тему подробнее? Ознакомьтесь с руководством по установке, где описаны все варианты настройки, и руководством по конфигурации для расширенных параметров.