Конфигурация развёртывания CodeGraph

Администратор задаёт секреты и параметры окружения в .env, а несекретные настройки приложения — в config.yaml. Используйте файлы из установленной версии CodeGraph. После изменения перезапустите затронутые сервисы и проверьте их готовность по шагам ниже.

Источники конфигурации

Полный перечень переменных серверной поставки, значений в образце и резервных значений Docker Compose приведён в справочнике переменных окружения.

Настраивайте развёртывание через .env и config.yaml. Учётные данные храните в защищённом .env или хранилище секретов заказчика; исключите их из Git, аргументов команд, файлов служб и журналов.

Обязательные production-значения

Используйте .env.example из установленной релизной версии. Как минимум задайте:

POSTGRES_PASSWORD=<secret-from-approved-store>
API_JWT_SECRET=<random-secret-at-least-64-characters>
API_ADMIN_PASSWORD=<unique-initial-admin-secret>
API_PROVIDER_SECRET_KEY=<independent-random-encryption-secret>
ENVIRONMENT=production

Также настройте обязательные ключи целостности Евы и учётные данные хотя бы одного одобренного модельного провайдера, перечисленные в этой версии. Замените значения-заглушки рабочими значениями и задайте отдельные значения для каждого окружения.

Для API_JWT_SECRET используйте случайное значение длиной от 64 символов. Это рекомендуемый размер для настройки; приложение отклоняет пустой секрет и стандартное значение из образца. При его ротации существующие токены перестают действовать, поэтому согласуйте перезапуск и повторную авторизацию пользователей. Начальные учётные данные администратора считайте секретом первоначальной настройки и меняйте по процедуре управления учётными данными заказчика.

В стандартной установке Ubuntu файл docker-compose.yml передаёт API_PROVIDER_SECRET_KEY и CODEGRAPH_OUTBOUND_GIT_ORIGIN_ALLOWLIST в api и temporal-worker. Следующие шаги настройки шифрования подключений и внутренних Git-адресов относятся к этому профилю. Отдельный docker-compose.prod.yml в этой версии эти переменные не передаёт. Для настройки этих двух параметров используйте стандартный профиль.

API_PROVIDER_SECRET_KEY шифрует токены Git-провайдеров и секреты вебхуков, сохранённые через интерфейс или REST API. По умолчанию ключ пустой; в промышленной установке без него нельзя сохранить токен подключения.

Создайте отдельное случайное значение, например командой python3 -c 'import secrets; print(secrets.token_urlsafe(48))', и сохраните его в защищённом .env. Генерируйте его в защищённом терминале без записи вывода в журналы или свидетельства.

В Bash из /opt/codegraph передайте ключ API и рабочему процессу, пересоздав контейнеры с Compose-файлами выбранной установки:

sudo docker compose up -d --no-deps --force-recreate api temporal-worker

Храните ключ вместе с защищённой резервной копией конфигурации: он нужен для расшифровки токенов из восстановленной базы. Не заменяйте его при обычном обновлении. При замене ключа ранее сохранённые токены необходимо заново ввести в подключения.

Сетевые адреса и источники браузерных запросов

Явно перечислите доступные снаружи имена хостов и источники браузерных запросов:

CORS_ALLOWED_ORIGINS=https://codegraph.customer.example
API_ALLOWED_HOSTS=codegraph.customer.example,api,codegraph-api

Не используйте * в источниках браузерных запросов с учётными данными. TLS завершается в точке, определённой проектом развёртывания, а наружу публикуются только одобренные маршруты. Для подключения моделей, репозиториев, телеметрии и уведомлений задайте учётные данные и разрешённые сетевые направления выбранной интеграции.

Для внутреннего Git-сервера, чей DNS-адрес указывает на частную сеть, администратор может разрешить точный HTTPS-адрес источника в защищённом .env:

CODEGRAPH_OUTBOUND_GIT_ORIGIN_ALLOWLIST=https://git.internal.example

Значение по умолчанию пустое: исключений для частных адресов нет. Несколько адресов перечисляйте через запятую. Укажите только доверенные серверы; диапазоны IP и шаблоны со знаком * не поддерживаются. После изменения пересоздайте api и temporal-worker, затем проверьте создание подключения в интерфейсе или через POST /api/v1/integrations/repositories/provider-connections. Схема запроса доступна в Swagger по адресу <API_BASE_URL>/api/docs. Для подключения укажите токен доступа к Git-серверу.

Несекретные настройки приложения

В config.yaml задайте включённые возможности приложения, лимиты, выбор провайдера и ссылки ${VARIABLE}. Сверьте имена и типы параметров с config.yaml установленной версии. Сохраняйте остальные настройки при изменении нужного раздела.

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

Область аудита проекта

В версиях с поддержкой metadata.audit.scope задавайте область отдельно для каждого проекта. Для изменения нужны права администратора или роль editor группы с доступом к этому проекту. Назначение ролей и проектов описано в руководстве RBAC. Настройка определяет каталоги выбранного репозитория.

Стандартные исключения: .git, .svn, .hg, node_modules, __pycache__, .venv, venv, vendor, third_party, build, dist, target, bin, obj, .idea, .vscode. Каталоги управления версиями исключаются даже при пустом exclude_paths.

Пути чувствительны к регистру. Поддерживаются *, ? и **; абсолютные пути, .. и шаблоны с !, {}, [] отклоняются. test_paths не расширяет область: чтобы анализировать тесты, включите их каталог и не исключайте его.

Следующий пример включает проект целиком со стандартными исключениями и считает tests тестовым каталогом. Замените test_paths путями вашего проекта. Сохраните код как configure-audit-scope.py на рабочей станции. Нужен Python 3; сторонние пакеты не требуются. На Linux/macOS запустите python3 configure-audit-scope.py, на Windows — py -3 configure-audit-scope.py. URL API возьмите у администратора, например https://codegraph.customer.example; Swagger находится по адресу <API_BASE_URL>/api/docs.

import getpass
import json
import urllib.request
from urllib.parse import urlsplit

base = input("API base URL: ").strip().rstrip("/")
parsed = urlsplit(base)
local_http = parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
if not parsed.hostname or parsed.username or parsed.password:
    raise ValueError("API URL must contain a host and no credentials")
if parsed.scheme != "https" and not local_http:
    raise ValueError("Use HTTPS; HTTP is allowed only for a local loopback API")
username = input("Username: ").strip()
password = getpass.getpass("Password: ")

def call(path, token=None, data=None, method=None):
    headers = {"Content-Type": "application/json"}
    if token:
        headers["Authorization"] = "Bearer " + token
    request = urllib.request.Request(
        base + path, headers=headers, method=method,
        data=None if data is None else json.dumps(data).encode(),
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response)

token = call("/api/v1/auth/token", data={
    "username": username, "password": password
})["access_token"]
del password
projects = call("/api/v1/projects", token)["projects"]
print("Available projects:", ", ".join(p["name"] for p in projects))
name = input("Project name: ").strip()
project_id = next(p["id"] for p in projects if p["name"] == name)
project = call("/api/v1/projects/" + project_id, token)
metadata = project["metadata"]
scope = {"version": 1, "include_paths": ["."], "test_paths": ["tests"]}
metadata.setdefault("audit", {})["scope"] = scope
call("/api/v1/projects/" + project_id, token,
     data={"metadata": metadata}, method="PUT")
saved = call("/api/v1/projects/" + project_id, token)
assert saved["metadata"]["audit"]["scope"] == scope
print("Saved scope:", json.dumps(scope))

Скрипт принимает HTTPS-адреса и локальные HTTP-адреса обратной петли. Адрес с учётными данными отклоняется до запроса пароля. Выполняйте пример только для согласованного изменения области проекта.

Пример читает текущую metadata и сохраняет остальные поля, включая архитектурную политику. Согласуйте изменение с коллегами: не выполняйте параллельные изменения этого объекта. После сохранения запустите новый аудит через UI или Swagger: POST /api/v1/traceability/projects/{project_name}/audit-report-jobs с телом {"language":"ru","force_refresh":true} и вашим Bearer-токеном. Имя проекта возьмите из списка API; UUID применяется только в запросах /api/v1/projects/{id}.

Проверяйте задание через GET /api/v1/traceability/audit-report-jobs/{id}, используя id из ответа запуска. Изменение scope без нового Git commit всё равно требует новой проверки CPG. В скачанном отчёте и его manifest проверьте source_revision и scope_digest. Скачайте отчёт по download_url и проверьте полноту анализа. При report_quality_status: "incomplete" используйте его для диагностики: найдите разделы со статусами unsupported, not_measured или timeout и указанные причины. Они показывают неподдерживаемую проверку, отсутствие измерения или истечение времени выполнения. По этим причинам подготовьте следующий запуск. При score_eligible: false итоговый балл недоступен.

Задание со статусом failed и report_quality_status: "incomplete" может содержать диагностический отчёт. Если ответ содержит непустой download_url, скачайте его с тем же Bearer-токеном. Если ссылки нет, найдите причину в error, report_quality_reason и stage_history; по ней подготовьте следующий запуск.

Каталог отчётов аудита

Markdown-отчёты и файлы проверки их целостности сохраняются в каталоге dashboard.audit_report_output_dir. Значение по умолчанию — data/dashboard-audit-reports, относительно рабочего каталога сервера. В стандартной Compose-поставке это /app/data/dashboard-audit-reports: каталог data подключён с сервера и сохраняется при пересоздании контейнеров.

Чтобы выбрать другое постоянное хранилище, добавьте параметр в существующую секцию dashboard файла config.yaml, сохранив остальные настройки:

dashboard:
  audit_report_output_dir: data/dashboard-audit-reports

Нестандартный каталог должен быть подключён в контейнер api как постоянный том и доступен его пользователю для записи.

Дождитесь завершения аудитов и перезапустите API с теми же Compose-файлами, которые используются в установленной поставке. Запустите аудит через UI или REST, скачайте доступный отчёт, затем повторите скачивание после пересоздания контейнера. Файлы отчётов и их .manifest.json должны сохраняться вместе.

Этот параметр задаёт администратор сервера в config.yaml.

Необязательная память OpenViking

OpenViking нужен для поиска по документации и долговременной памяти. Embedding переводит текст в векторы для поиска, rerank уточняет порядок найденного, VLM создаёт текстовые обзоры и, при поддержке модели, обрабатывает изображения. Это три отдельные настройки. Если нужны только CPG и детерминированный аудит исходников, отключите загрузку документов: import_docs: false в REST или --no-docs в CLI.

На Ubuntu-сервере шаблон deploy/openviking/ov.local-models.conf задаёт локальные embedding и rerank. Перед эксплуатацией проверьте условия использования указанных в нём моделей. В защищённом .env задайте:

COMPOSE_PROFILES=local-models
OPENVIKING_CONFIG_TEMPLATE=ov.local-models.conf
OPENVIKING_API_KEY=<secret-from-approved-store>

В поставляемом шаблоне VLM по умолчанию настроена через Yandex. Для этого провайдера дополнительно задайте YANDEX_API_KEY и YANDEX_FOLDER_ID в .env.

Если нужен OpenAI, сохраните копию шаблона и замените в ней секцию vlm: задайте provider: "openai", api_base: "https://api.openai.com/v1", доступный model и api_key через секретную переменную. Имя копии задайте в OPENVIKING_CONFIG_TEMPLATE; добавьте переменную ключа в environment сервиса openviking и список подстановки его команды запуска в Compose.

Переменные GIGACHAT_* основного API сами по себе не настраивают OpenViking: для GigaChat потребуется совместимый адрес API с обновлением OAuth-токена либо проверенный адаптер.

После изменения из каталога установки выполните на сервере:

sudo docker compose -f docker-compose.yml up -d --force-recreate openviking
sudo docker compose -f docker-compose.yml exec -T openviking curl -fsS http://127.0.0.1:1933/health

После ответа /health, подтверждающего доступность сервиса, импортируйте документацию проекта. Проверьте результат импорта через codegraph_project_context_sync_status с {}.

Настройте автоматические проверки проекта

После импорта подключите события репозитория. Вебхук push передаёт новые коммиты для обновления CPG; события pull request или merge request запускают подготовку ревью. Выберите руководство вашего Git-сервера:

• GitHub: подключение репозитория, вебхук и ревью pull request.
• GitLab: подключение репозитория, вебхук и ревью merge request.
• GitVerse: вебхук, синхронизация и публикация ревью pull request.
• SourceCraft: координаты репозитория, вебхук и ревью merge request.

Настройте события для выбранных веток и проверьте обработку тестового push: дождитесь задания синхронизации и сравните коммит CPG с коммитом репозитория. Для PR/MR проверьте результат ревью и его публикацию в целевом запросе.

Контроль архитектуры объясняет, как описать компоненты и разрешённые зависимости в YAML, проверить правила и включить их в проверку изменений.

Чтобы запускать проверки регулярно, настройте автоматические аудиты проекта: выберите периодичность, часовой пояс, сервисный аккаунт и правила обработки пропущенных запусков. Проверьте первый запуск и сохранённый отчёт.

Применение и проверка изменения

1. Создайте резервную копию .env, config.yaml и объявления проектов.
2. Измените только одобренные значения, сохранив владельца и ограниченные права файлов.
3. Перезапустите CodeGraph через менеджер служб.
4. Выполните общую команду проверки готовности из руководства по установке.
5. Проверьте авторизацию, доступность проектов, актуальность CPG и изменённую интеграцию.

Сохраните результаты проверки промышленной установки после изменения: контейнеров и зависимостей, контроля доступа, происхождения исходного кода и связи с системами заказчика.

Устранение ошибок

• Приложение отклоняет секрет JWT: создайте новое значение длиной от 64 символов и обновите защищённый .env.
• Запрос браузера отклонён: сравните точные протокол и имя хоста с CORS_ALLOWED_ORIGINS и API_ALLOWED_HOSTS.
• Провайдер недоступен: проверьте ссылку на секрет, правила исходящих соединений и доверенный центр сертификации; не отключайте проверку TLS.
• Параметр неизвестен: сравните его с .env.example и config.yaml точной релизной версии, не изменяя код приложения.

Далее: Установка · Быстрый старт