Развёртывание CodeGraph в инфраструктуре заказчика

Выберите способ установки CodeGraph в инфраструктуре организации, подготовьте хранилища и сетевой доступ, затем проверьте работу API и анализ проекта. Руководство предназначено для администратора платформы: оно помогает связать установку, обновление, резервное копирование и восстановление в один план эксплуатации.

Для первоначальной установки на Ubuntu начните с руководства по установке. Ниже описаны варианты развёртывания и проверки после запуска.

Поддерживаемые профили

Выберите один профиль и зафиксируйте его в плане:

Поддерживаемые профили
Профиль	Сопровождаемый источник	Применение
Установка из исходников	`scripts/run_app_stack.py`	Локальная интеграция и операторская проверка.
Docker Compose	`docker-compose.yml`, `docker-compose.override.yml`, `docker-compose.prod.yml`	Контейнерное развёртывание на управляемом хосте.
Kubernetes	`deploy/helm/codegraph`	Развёртывание в кластере через сопровождаемый Helm chart.
Сервер Ubuntu заказчика	Руководство по установке	Контролируемая установка на Ubuntu с сервисами заказчика.

Helm chart создаёт Deployment, Service, Ingress, HPA, PVC, Secret и ConfigMap по выбранным настройкам. Администратор кластера заранее готовит сетевые политики, мониторинг, внешнюю БД, хранилище секретов, ingress-контроллер и класс хранения.

Планирование до изменений

До изменения инфраструктуры зафиксируйте:

неизменяемые commit, tag, хеш образа и версии пакетов CodeGraph;
выбранный профиль и точные параметры либо настройки окружения;
DNS, TLS termination, ingress, proxy и правила исходящей сети;
зависимости PostgreSQL, OpenViking, GoCPG, model provider и объектного или файлового хранилища;
владельца секретов, способ ротации и механизм внешних ссылок;
постоянные тома, сроки хранения, состав резервной копии и место восстановления;
лимиты ресурсов по измеренному корпусу пилота;
окно обслуживания, условие отката и ответственного оператора.

Не помещайте реальные секреты в Git, закоммиченные Helm values, снимки экрана, тикеты и историю команд. Получайте их через одобренный заказчиком канал.

Проверка установки из исходников

Используйте PowerShell из одобренного checkout CodeGraph с установленными Python-зависимостями. Эти команды предназначены для локального интеграционного стека, а не для промышленного сервиса заказчика. restart останавливает и запускает локальные процессы; логи могут содержать чувствительные данные.

python scripts/run_app_stack.py status --local --with-mcp
python scripts/run_app_stack.py restart --local --with-mcp
python scripts/run_app_stack.py logs --local --with-mcp

До изменений выполните status. После рестарта дождитесь завершения команды и подтвердите ту же ревизию через API, MCP-клиент, если он включён, и project-context status. Обслуживание запросов новым кодом подтверждайте через эти проверки.

Развёртывание через Compose или Helm

Для Compose используйте production-конфигурацию выбранного выпуска. Перед запуском проверьте её:

docker compose -f docker-compose.prod.yml config --quiet
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps

Выполняйте команды из каталога исходников выбранного выпуска. Заранее установите Docker Engine и плагин Compose, затем заполните защищённый .env.

config --quiet проверяет конфигурацию, не печатая подставленные секреты.

При успешной проверке команда завершается с кодом 0. Если Docker сообщает, что переменная не задана и заменена пустой строкой, заполните соответствующее значение в .env и повторите проверку перед up -d.

Просматривайте итоговую конфигурацию только в защищённой сессии.

В файлах есть значения образов latest: привяжите развёртывание к утверждённому неизменяемому выпуску и сохраните хеши образов. После запуска проверьте вход, импорт проекта и актуальность CPG по разделам ниже.

Подготовьте параметры Kubernetes

Скопируйте deploy/helm/codegraph/values.yaml из выбранного выпуска в новый защищённый customer-values.yaml. Сохраните существующий файл отдельно, если настройки уже подготовлены.
В image.registry, image.repository и image.tag укажите образ API из одобренного реестра и неизменяемого выпуска. Проверьте право кластера на загрузку образа; для закрытого реестра укажите imagePullSecrets.
Настройте resources, persistence.cpgData и класс хранения под выбранный корпус и инфраструктуру. Для OpenViking укажите openviking.configSecretName и параметры openviking.dataPersistence. Secret должен находиться в целевом пространстве имён и содержать файл с именем из openviking.configFileName — по умолчанию ov.conf.
Подготовьте внешние сервисы и задайте secrets.databaseUrl, secrets.jwtSecret и данные выбранного провайдера модели. Значения secrets попадут в Kubernetes Secret. Доступ к этому файлу должен быть только у операторов, которые разворачивают систему.
Если используете ingress, включите ingress.enabled и задайте ingress.className, ingress.hosts и ingress.tls для публичного адреса API. Проверьте выбранные контекст Kubernetes и пространство имён.

Для Kubernetes сначала отрисуйте сопровождаемый chart с подготовленными параметрами:

helm template codegraph deploy/helm/codegraph -f customer-values.yaml > rendered.yaml
helm upgrade --install codegraph deploy/helm/codegraph -f customer-values.yaml --atomic

Запускайте Helm из корня checkout с настроенными Kubernetes context и namespace. Подготовьте защищённый customer-values.yaml для этого кластера.

Если openviking.enabled равен true, задайте в openviking.configSecretName имя подготовленного Secret с конфигурацией OpenViking в целевом пространстве имён. Шаблон подключает этот Secret к контейнеру OpenViking.

Рендер может записать секреты в base64 в rendered.yaml; base64 не шифрует данные.

Ограничьте доступ к обоим файлам и не помещайте их в Git или публичные артефакты. Перед upgrade --install проверьте целевой context, затем rollout, readiness и приложение по утверждённому URL.

Chart разворачивает API и дополнительный контейнер OpenViking, если он включён. Остальные зависимости подготовьте отдельно. Шаблон образа использует registry, repository и tag, а не поле image.digest. Задайте защищённый неизменяемый тег и проверьте digest полученного образа после развёртывания. Параметры хранения, сети и ресурсов выберите для целевого кластера.

Проверьте в rendered.yaml адреса и теги образов, пространства имён, параметры безопасности контейнеров, тома, ingress и ссылки на секреты. --atomic помогает восстановить состояние Helm release, но не возвращает данные приложения и внешних сервисов.

Защита сети, секретов и данных

Как минимум:

завершайте TLS на согласованной границе и ограничивайте административные маршруты;
не публикуйте PostgreSQL, GoCPG, OpenViking и внутренние сервисные порты в недоверенную сеть;
требуйте аутентификацию для API, сетевых MCP transport, ACP и gRPC по профилю;
разрешайте исходящие подключения только к одобренным моделям, репозиториям, системам задач, телеметрии и обновлениям;
включайте обязательные для профиля контроли DLP, аудита и SIEM;
применяйте политики шифрования, хранения, резервного копирования и удаления данных заказчика.

Настройте вход через OAuth или LDAP, роли и проекты, проверку контента DLP и доставку событий в SIEM. Эти руководства содержат параметры, проверочные действия и ожидаемые результаты.

Обновление и откат

Перед обновлением сохраните текущее состояние работоспособности, состояние БД и схемы, активную конфигурацию, хеш образа и проверенную точку восстановления. Разворачивайте один неизменяемый кандидат и выполняйте согласованные приёмочные проверки.

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

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

Резервное копирование и восстановление

Резервная копия должна охватывать все зависимости профиля, которые хранят состояние: PostgreSQL, настройки проекта, управляемые заказчиком тома, метаданные шифрования и необходимые исходные данные для восстановления OpenViking или графа. Проверьте восстановление данных из сохранённой копии.

Проведите пробное восстановление в согласованной тестовой среде или в среде восстановления заказчика:

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

Работоспособность и наблюдаемость

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

/api/v1/health — здоровье приложения и зависимостей;
/metrics — настроенный маршрут сбора метрик Prometheus;
состояние и журналы локального стека — диагностика установки из исходников;
состояние развёртывания Kubernetes, события pod и журналы выбранных сервисов — диагностика кластера;
статус доставки SIEM и подтверждение получения целевой системой — события безопасности.

Для проверки здоровья задайте адрес API без завершающего слеша и выполните запрос из сети, в которой доступен сервер:

$api = '<api-base-url>'
$health = Invoke-RestMethod -Uri "$api/api/v1/health" -TimeoutSec 10
$health | Select-Object status, version, timestamp, uptime_seconds
$health.components | ConvertTo-Json -Depth 4

Ответ содержит общее состояние status, версию приложения version, время проверки timestamp, время работы uptime_seconds и состояния сервисов в components. Сопоставьте результат каждого сервиса с выбранным профилем развёртывания. Маршрут /metrics отдаёт данные Prometheus; настройте их сбор через внутренний адрес сервера и согласованные сетевые правила.

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

Доказательства готовности

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

неизменяемый релиз и хеши итоговой конфигурации;
результаты установки либо обновления и проверки работоспособности;
проверки аутентификации, авторизации, DLP и отсутствия секретов в публикации;
результаты импорта проекта, проверки актуальности CPG и пользовательского сценария;
метрики, журналы, маршруты оповещений и подтверждение получения событий SIEM;
ссылки на проверки резервного копирования, восстановления и отката;
известные ограничения, недоступные каналы, владельцев и действия для восстановления.

Подключите автоматические проверки

После первого импорта перейдите к настройке автоматических проверок проекта. Выберите инструкцию вебхуков GitHub, GitLab, GitVerse или SourceCraft, проверьте обновление CPG после коммита и результат ревью PR/MR. Затем задайте расписание аудитов и правила контроля архитектуры. Сохраните результат первого запуска вместе с выбранными настройками.