Руководство по настройке

Настройте CodeGraph для вашей среды.

Содержание

Файлы конфигурации

Файл Назначение
.env Переменные окружения (ключи API, URL баз данных)
config.yaml Основная конфигурация (LLM, поиск, анализ)
src/api/config.py Конфигурация сервера API
config/prompts/*.yaml Шаблоны промптов

Конфигурация сервера API

Настройки сервера

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

Через переменные окружения:

export API_HOST="0.0.0.0"        # Привязка ко всем интерфейсам
export API_PORT="8000"            # Номер порта
export API_WORKERS="4"            # Количество рабочих процессов
export API_DEBUG="false"          # Режим отладки (автоперезагрузка)

Через аргументы командной строки:

python -m src.api.cli run --host 0.0.0.0 --port 8000 --workers 4

Конфигурация базы данных

API требует PostgreSQL для управления пользователями, сессиями и журналами аудита.

Формат строки подключения:

postgresql+asyncpg://имя_пользователя:пароль@хост:порт/база_данных

Конфигурация через переменную окружения:

export DATABASE_URL="postgresql+asyncpg://postgres:your_password@localhost:5432/codegraph"

Настройки пула соединений:

Измените src/api/config.py, чтобы настроить пул соединений:

class DatabaseConfig(BaseModel):
    url: str = "postgresql+asyncpg://postgres:postgres@localhost:5432/codegraph"
    pool_size: int = 10          # Количество поддерживаемых соединений
    max_overflow: int = 20        # Дополнительные соединения при заполнении пула
    pool_timeout: int = 30        # Время ожидания соединения (в секундах)
    pool_recycle: int = 1800      # Пересоздание соединений после 30 минут
    echo: bool = False            # Логирование всех SQL-запросов (только для отладки)

Конфигурация аутентификации

JWT-аутентификация

Настройте параметры JWT-токенов:

# Секретный ключ для подписи токенов (ОБЯЗАТЕЛЬНО ИЗМЕНИТЬ В РАБОЧЕЙ СРЕДЕ!)
export API_JWT_SECRET="ваш-секретный-ключ-минимум-64-символа-рекомендуется"

# Алгоритм (по умолчанию: HS256)
export API_JWT_ALGORITHM="HS256"

Примечание: Время жизни токенов (access_token_expire_minutes, refresh_token_expire_days) настраивается в config.yaml или src/api/config.py, а не через переменные окружения.

В config.py:

class JWTConfig(BaseModel):
    secret_key: str = "замените-для-рабочей-среды-минимум-64-символа"
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
    refresh_token_expire_days: int = 7

Сгенерируйте надёжный секретный ключ:

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

API-ключи

Включите аутентификацию по API-ключам для программного доступа:

class AuthConfig(BaseModel):
    api_keys_enabled: bool = True  # Включить аутентификацию по API-ключам

Создание API-ключей через API:

# Требуется JWT-токен
curl -X POST http://localhost:8000/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Мой API-ключ",
    "expires_days": 365,
    "scopes": ["scenarios:read", "query:execute"]
  }'

Поставщики OAuth

Настройте поставщиков OAuth 2.0 (GitHub, Google, GitLab, Keycloak, SourceCraft, GitVerse):

# OAuth для GitHub
export OAUTH_GITHUB_CLIENT_ID="ваш_client_id_для_github"
export OAUTH_GITHUB_CLIENT_SECRET="ваш_client_secret_для_github"

# OAuth для Google
export OAUTH_GOOGLE_CLIENT_ID="ваш_client_id_для_google"
export OAUTH_GOOGLE_CLIENT_SECRET="ваш_client_secret_для_google"

# Keycloak
export OAUTH_KEYCLOAK_SERVER_URL="https://keycloak.example.com"
export OAUTH_KEYCLOAK_REALM="ваш_realm"
export OAUTH_KEYCLOAK_CLIENT_ID="ваш_client_id"
export OAUTH_KEYCLOAK_CLIENT_SECRET="ваш_client_secret"

# SourceCraft (Yandex ID)
export OAUTH_SOURCECRAFT_CLIENT_ID="ваш_sourcecraft_client_id"
export OAUTH_SOURCECRAFT_CLIENT_SECRET="ваш_sourcecraft_client_secret"
export OAUTH_SOURCECRAFT_SERVER_URL="https://sourcecraft.example.com"

# GitVerse (Sber ID)
export OAUTH_GITVERSE_CLIENT_ID="ваш_gitverse_client_id"
export OAUTH_GITVERSE_CLIENT_SECRET="ваш_gitverse_client_secret"
export OAUTH_GITVERSE_SERVER_URL="https://gitverse.example.com"

CodeGraph также предоставляет RFC 6749-совместимую конечную точку OAuth-токена (POST /api/v1/auth/oauth/token), поддерживающую grant_type=password и grant_type=refresh_token. Это позволяет MCP-клиентам и CI/CD-системам получать и автоматически обновлять токены без OAuth-процесса через браузер. Подробнее: REST API — Конечная точка OAuth-токена.

LDAP/Active Directory

Настройте LDAP для корпоративной аутентификации:

export LDAP_SERVER="ldap.example.com"
export LDAP_BASE_DN="dc=example,dc=com"
export LDAP_BIND_USER="cn=admin,dc=example,dc=com"
export LDAP_BIND_PASSWORD="admin_password"
export LDAP_USER_SEARCH_BASE="ou=users,dc=example,dc=com"
export LDAP_GROUP_SEARCH_BASE="ou=groups,dc=example,dc=com"

Настройка ограничения частоты запросов

Защитите ваш API с помощью ограничения частоты запросов:

class RateLimitConfig(BaseModel):
    enabled: bool = True
    storage: str = "memory"  # "memory" или "redis://localhost:6379"
    default_limits: List[str] = ["100/minute", "1000/hour"]

    endpoint_limits: Dict[str, str] = {
        "/api/v1/review/*": "10/minute",
        "/api/v1/chat": "60/minute",
        "/api/v1/chat/stream": "30/minute",
        "/api/v1/query/execute": "30/minute",
        "/api/v1/demo/chat": "30/minute",
    }

Используйте Redis в рабочей среде (для общего доступа между рабочими процессами):

export RATE_LIMIT_STORAGE="redis://localhost:6379"

Настройка CORS

Настройте обмен ресурсами между источниками (CORS) для веб-интерфейсов:

class CORSConfig(BaseModel):
    allowed_origins: List[str] = [
        "http://localhost:8080",
        "http://127.0.0.1:8080",
        "http://localhost:3000",
        "http://127.0.0.1:3000",
    ]
    allowed_methods: List[str] = ["GET", "POST", "PUT", "DELETE", "OPTIONS"]
    allowed_headers: List[str] = ["*"]
    allow_credentials: bool = True
    max_age: int = 600  # Время кеширования preflight-запросов (в секундах)

Конфигурация демонстрационной конечной точки

Настройте публичную демонстрационную конечную точку:

export DEMO_ENABLED="true"
export DEMO_RATE_LIMIT="30/minute"

class DemoConfig(BaseModel):
    enabled: bool = True
    rate_limit: str = "30/minute"
    allowed_scenarios: List[str] = ["onboarding"]
    max_query_length: int = 500

Настройка поставщика LLM

Настройте поставщика LLM, используемого для анализа кода и генерации запросов.

GigaChat

export GIGACHAT_AUTH_KEY="ваш_ключ_gigachat"

# config.yaml
llm:
  provider: gigachat
  model: GigaChat-2-Pro
  temperature: 0.1
  max_tokens: 4096

Локальный LLM (llama-cpp-python)

export QWEN3_MODEL_PATH="/путь/к/qwen3/model.gguf"

# config.yaml
llm:
  provider: local
  model_path: ${QWEN3_MODEL_PATH}
  n_gpu_layers: -1   # Использовать все GPU-слои (-1)
  n_ctx: 8192        # Размер окна контекста
  n_threads: 8       # Количество CPU-потоков для вывода
  temperature: 0.1
  max_tokens: 4096

OpenAI

export OPENAI_API_KEY="ваш_ключ_openai"

# config.yaml
llm:
  provider: openai
  model: gpt-4
  temperature: 0.1
  max_tokens: 4096
  api_base: https://api.openai.com/v1

Yandex Cloud AI Studio (YandexGPT)

export YANDEX_API_KEY="ваш_ключ_api_yandex"
export YANDEX_FOLDER_ID="ваш_id_папки"

# config.yaml
llm:
  provider: yandex
  yandex:
    api_key: ${YANDEX_API_KEY}
    folder_id: ${YANDEX_FOLDER_ID}
    model: yandexgpt/latest      # или: yandexgpt-lite/latest, yandexgpt/rc
    base_url: https://llm.api.cloud.yandex.net/v1
    temperature: 0.7
    max_tokens: 2000
    timeout: 60
    embedding_model: text-search-doc/latest

Доступные модели: - yandexgpt/latest — YandexGPT (основная модель) - yandexgpt-lite/latest — YandexGPT Lite (быстрее, меньше по размеру) - yandexgpt/rc — Кандидат в релиз с возможностью логического вывода - yandexgpt-32k/latest — Расширенный контекст (32K токенов)

Конфигурация домена

Переключение между различными кодовыми базами для анализа:

# config.yaml
domain:
  name: postgresql_v2  # postgresql_v2, generic_cpp, go, java, python_django и др.
  auto_activate: true

Доступные домены (12): - postgresql_v2 — база данных PostgreSQL 17.6 - generic_cpp — универсальная кодовая база C/C++ - go — кодовая база Go - java — Java/JVM - python_django — веб-фреймворк Python Django - python_generic — универсальная кодовая база Python - javascript — JavaScript/TypeScript - csharp — C#/.NET - kotlin — Kotlin/JVM - onec — 1C:Предприятие (BSL/SDBL) - php — PHP - web — веб-фронтенд (HTML/CSS/JS)

Конфигурация базы данных CPG

Настройка базы данных графа свойств кода (CPG) (для анализа кода):

# config.yaml
cpg:
  type: postgresql_v2  # Тип домена для анализа (соответствует имени домена)
  db_path: data/projects/postgres.duckdb  # Путь к DuckDB (per-project)

Примечание: Поле type указывает домен анализа (например, postgresql_v2, go, java), а не тип хранилища. Данные CPG всегда хранятся в DuckDB.

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

Настройка семантического поиска и извлечения:

# config.yaml
retrieval:
  embedding_model: paraphrase-multilingual-MiniLM-L12-v2  # Модель sentence transformer
  embedding_dimension: 384            # Размерность вектора
  top_k_qa: 3                         # Количество лучших результатов для поиска по вопросам и ответам
  top_k_graph: 5                      # Количество лучших результатов для поиска по графу (SQL)
  max_results: 50                     # Максимальное количество результатов поиска
  chunk_size: 512                     # Размер фрагмента текста для создания эмбеддингов

  # Гибридный поиск (векторный + графовый)
  hybrid:
    enabled: true
    vector_weight: 0.6      # Вес семантического поиска
    graph_weight: 0.4       # Вес структурного поиска
    rrf_k: 60               # Константа Reciprocal Rank Fusion

Ограничения запросов

# config.yaml
query:
  default_limit: 100   # Значение LIMIT по умолчанию для SQL-запросов
  max_limit: 1000      # Максимально допустимое значение LIMIT

Настройки анализа

Настройте пороговые значения анализа:

# config.yaml
analysis:
  sanitization_confidence_threshold: 0.7  # Уровень уверенности для обнаружения очистки данных
  similarity_threshold: 0.8                # Порог семантического сходства
  complexity_threshold: 10                 # Порог цикломатической сложности

Конфигурация структурных шаблонов

Настройка поиска, сканирования и перезаписи структурных шаблонов:

# config.yaml
patterns:
  enabled: true                      # Включить/выключить функцию шаблонов
  rule_dirs:                         # Каталоги правил по умолчанию
    - ".codegraph/rules"
  match_timeout: 30                  # Время ожидания (секунды) для сопоставления шаблонов
  max_matches_per_rule: 10000        # Максимальное количество совпадений на правило
  max_rules: 500                     # Максимальное количество загружаемых правил
  incremental:
    enabled: true                    # Включить инкрементальную оценку
    max_dependent_files: 100         # Максимум файлов для отслеживания
  rewrite:
    backup: true                     # Резервное копирование файлов перед исправлением
    max_fixes_per_file: 50           # Максимум исправлений на файл
    require_approval: true           # Требовать подтверждение перед применением

Параметры конфигурации

Ключ Тип По умолчанию Описание
patterns.enabled boolean true Включить/выключить функцию структурных шаблонов
patterns.rule_dirs list [".codegraph/rules"] Каталоги для загрузки YAML-правил
patterns.match_timeout integer 30 Время ожидания в секундах для сопоставления шаблонов
patterns.max_matches_per_rule integer 10000 Ограничение совпадений на правило
patterns.max_rules integer 500 Максимальное количество загружаемых правил
patterns.incremental.enabled boolean true Инкрементальная оценка (пересканировать только изменённые файлы)
patterns.incremental.max_dependent_files integer 100 Максимум зависимых файлов для инкрементального режима
patterns.rewrite.backup boolean true Создавать резервные копии перед применением исправлений
patterns.rewrite.max_fixes_per_file integer 50 Максимум исправлений на файл
patterns.rewrite.require_approval boolean true Требовать подтверждение перед применением

Пользовательские каталоги правил

Добавьте проектные правила, расширив список rule_dirs:

patterns:
  rule_dirs:
    - ".codegraph/rules"          # Правила по умолчанию
    - "./my-project-rules"        # Правила проекта
    - "/shared/team-rules"        # Общие правила команды

Правила в более поздних каталогах имеют приоритет при конфликте ID правил.

Справочник переменных окружения

Создайте файл .env в корне проекта:

# =============================================================================
# Конфигурация API-сервера
# =============================================================================
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4
API_DEBUG=false

# =============================================================================
# Конфигурация базы данных
# =============================================================================
DATABASE_URL=postgresql+asyncpg://postgres:your_password@localhost:5432/codegraph

# =============================================================================
# Аутентификация
# =============================================================================
API_JWT_SECRET=ваш-секретный-ключ-минимум-64-символа-измените-для-рабочей-среды
API_JWT_ALGORITHM=HS256

# Пользователь-администратор (для первоначальной настройки)
API_ADMIN_USERNAME=admin
API_ADMIN_PASSWORD=замените-этот-пароль

# =============================================================================
# Поставщики LLM API
# =============================================================================
GIGACHAT_AUTH_KEY=ваш_ключ_gigachat
OPENAI_API_KEY=ваш_ключ_openai
YANDEX_API_KEY=ваш_ключ_yandex_api
YANDEX_FOLDER_ID=ваш_идентификатор_папки_yandex

# =============================================================================
# Пути к локальным моделям
# =============================================================================
QWEN3_MODEL_PATH=/путь/к/qwen3/model.gguf

# =============================================================================
# Поставщики OAuth (необязательно)
# =============================================================================
OAUTH_GITHUB_CLIENT_ID=ваш_id_клиента_github
OAUTH_GITHUB_CLIENT_SECRET=ваш_секрет_клиента_github
OAUTH_GOOGLE_CLIENT_ID=ваш_id_клиента_google
OAUTH_GOOGLE_CLIENT_SECRET=ваш_секрет_клиента_google
OAUTH_SOURCECRAFT_CLIENT_ID=ваш_sourcecraft_client_id
OAUTH_SOURCECRAFT_CLIENT_SECRET=ваш_sourcecraft_client_secret
OAUTH_SOURCECRAFT_SERVER_URL=https://sourcecraft.example.com
OAUTH_GITVERSE_CLIENT_ID=ваш_gitverse_client_id
OAUTH_GITVERSE_CLIENT_SECRET=ваш_gitverse_client_secret
OAUTH_GITVERSE_SERVER_URL=https://gitverse.example.com

# =============================================================================
# Конфигурация LDAP (необязательно)
# =============================================================================
LDAP_SERVER=ldap.example.com
LDAP_BASE_DN=dc=example,dc=com
LDAP_BIND_USER=cn=admin,dc=example,dc=com
LDAP_BIND_PASSWORD=admin_password
LDAP_USER_SEARCH_BASE=ou=users,dc=example,dc=com
LDAP_GROUP_SEARCH_BASE=ou=groups,dc=example,dc=com

# =============================================================================
# Ограничение частоты запросов
# =============================================================================
RATE_LIMIT_STORAGE=memory  # или redis://localhost:6379

# =============================================================================
# Демонстрационная конечная точка
# =============================================================================
DEMO_ENABLED=true
DEMO_RATE_LIMIT=30/minute

# =============================================================================
# Настройки базы данных CPG
# =============================================================================
CPG_DB_PATH=data/projects/postgres.duckdb
# CPG_TYPE=postgresql_v2  # Тип домена для анализа (не тип хранилища)

# =============================================================================
# Логирование
# =============================================================================
LOG_LEVEL=INFO
LLM_VERBOSE=false

# =============================================================================
# Производительность
# =============================================================================
CUDA_VISIBLE_DEVICES=0
OMP_NUM_THREADS=8

Оптимизация производительности

Для промышленной эксплуатации (несколько рабочих процессов)

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

# Используйте Redis для ограничения частоты запросов (общий доступ между рабочими процессами)
export RATE_LIMIT_STORAGE="redis://localhost:6379"

# Увеличьте размер пула соединений с базой данных
# Отредактируйте src/api/config.py:
# pool_size: 20
# max_overflow: 40

Для разработки (автоматическая перезагрузка)

# Один рабочий процесс с автоматической перезагрузкой
python -m src.api.cli run --host 127.0.0.1 --port 8000 --reload --log-level debug

# Включите логирование SQL-запросов
# Отредактируйте src/api/config.py:
# echo: True

При ограниченных ресурсах

# config.yaml
retrieval:
  batch_size: 50    # Уменьшено с 100
  top_k_qa: 3       # Уменьшено с 10
  top_k_graph: 3

llm:
  max_tokens: 2048  # Уменьшено с 4096

Рекомендации по безопасности

  1. Измените пароли по умолчанию: ```bash # Сгенерируйте надёжный секретный ключ JWT python -c “import secrets; print(secrets.token_urlsafe(64))”

# Установите надёжный пароль администратора python -m src.api.cli create-admin –username admin –password <надёжный_пароль> ```

  1. Используйте переменные окружения для хранения секретов: - Никогда не добавляйте файлы .env в систему контроля версий - Добавьте .env в файл .gitignore

  2. Включите HTTPS в рабочей среде: - Используйте обратный прокси (nginx, Caddy, Traefik) - Либо настройте uvicorn с SSL-сертификатами

  3. Ограничьте источники CORS: python allowed_origins: List[str] = [ "https://yourapp.example.com", # Только клиентская часть рабочей среды ]

  4. Настройте ограничение частоты запросов: - Используйте Redis для распределённого ограничения частоты запросов - Настройте ограничения в соответствии с возможностями вашей системы

Мультитенантная изоляция

Включите мультитенантную изоляцию проектов, чтобы несколько команд могли использовать один экземпляр CodeGraph:

multi_tenant:
  enabled: false              # true = включить RBAC на уровне групп для всех эндпоинтов данных
  max_project_connections: 10 # Максимум одновременных подключений CPGQueryService (LRU-кэш)
  max_harness_instances: 5    # Максимум одновременных экземпляров Harness (LRU-кэш)
Параметр Тип По умолчанию Описание
enabled bool false Включить проверку RBAC на уровне групп. При false все проверки групп отключены.
max_project_connections int 10 Размер LRU-кэша для подключений CPG по проектам. Вытесненные подключения закрываются.
max_harness_instances int 5 Размер LRU-кэша для экземпляров Harness по проектам.

При включении каждый API-запрос разрешает ProjectContext через: 1. Заголовок X-Project-Id (UUID) — явный выбор проекта 2. Активный проект пользователя — из таблицы user_active_project 3. Глобальный откат — использует синглтон ProjectManager (CLI/демо-режим)

Миграция для существующих установок: Выполните python scripts/migrate_default_group.py один раз, чтобы создать группу по умолчанию со всеми существующими пользователями и проектами.

Проверка конфигурации

Проверьте свою конфигурацию:

# Проверка подключения к базе данных
python -c "
from src.api.database.connection import check_db_connection
import asyncio
print('База данных ОК' if asyncio.run(check_db_connection()) else 'Ошибка базы данных')
"

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

Конфигурация дашборда

Настройте портфельный дашборд CISO/CTO V2 в файле config.yaml:

# config.yaml
dashboard:
  enabled: true
  cache_ttl_seconds: 300
  max_portfolio_projects: 100

  # Веса компонентов Health Score (сумма должна равняться 1.0)
  weight_audit: 0.30
  weight_compliance: 0.25
  weight_release: 0.20
  weight_sca: 0.15
  weight_quality: 0.10

  # Пороги оценок (шкала 0–100)
  grade_a_min: 85.0
  grade_b_min: 70.0
  grade_c_min: 55.0
  grade_d_min: 40.0

  # Пороги уровней риска (максимальный балл для каждого уровня)
  risk_critical_max_score: 40.0
  risk_high_max_score: 55.0
  risk_medium_max_score: 70.0

  # Настройки экспорта
  export_enabled: true
  export_max_pages: 200

  # Ограничения трендов и сравнения
  max_trend_data_points: 365
  max_comparison_projects: 10
  max_red_zone_items: 100

Параметры конфигурации

Поле Тип По умолчанию Описание
enabled bool true Включить функцию Dashboard V2 и её эндпоинты API
cache_ttl_seconds int 300 Время жизни кэша для ответов портфеля и Health Score (секунды)
max_portfolio_projects int 100 Максимальное число проектов в виде портфеля
weight_audit float 0.30 Вес показателя аудита в составном Health Score
weight_compliance float 0.25 Вес процента соответствия в составном Health Score
weight_release float 0.20 Вес статуса ворот выпуска в составном Health Score
weight_sca float 0.15 Вес компонента уязвимостей SCA в составном Health Score
weight_quality float 0.10 Вес компонента качества кода в составном Health Score
grade_a_min float 85.0 Минимальный Health Score для оценки A
grade_b_min float 70.0 Минимальный Health Score для оценки B
grade_c_min float 55.0 Минимальный Health Score для оценки C
grade_d_min float 40.0 Минимальный Health Score для оценки D (ниже — оценка F)
risk_critical_max_score float 40.0 Максимальный Health Score для уровня риска critical
risk_high_max_score float 55.0 Максимальный Health Score для уровня риска high
risk_medium_max_score float 70.0 Максимальный Health Score для уровня риска medium (выше — low)
export_enabled bool true Включить эндпоинт /api/v2/dashboard/export
export_max_pages int 200 Максимальное число страниц для экспорта в PDF
max_trend_data_points int 365 Максимальное число точек данных в одном ряду трендов
max_comparison_projects int 10 Максимальное число проектов в одном запросе сравнения
max_red_zone_items int 100 Максимальное число элементов, возвращаемых эндпоинтом зоны риска

Примечание: Сумма weight_audit + weight_compliance + weight_release + weight_sca + weight_quality должна равняться 1.0. Система проверяет это при запуске и выбрасывает ConfigurationError, если отклонение превышает 0.001.

Полная формула расчёта Health Score описана в Методологии дашборда.

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