Руководство задаёт поддерживаемую границу развёртывания и ссылается на сопровождаемые артефакты. Compose-файлы, Kubernetes-объекты и цифры ёмкости проверяйте по репозиторию. Готовность пилота подтверждается привязанными к ревизии результатами health-, security-, backup-, restore-, rollback- и observability-проверок выбранной среды.
Поддерживаемые профили
Выберите один профиль и зафиксируйте его в плане:
| Профиль | Сопровождаемый источник | Применение |
|---|---|---|
| Source checkout | scripts/run_app_stack.py |
Локальная интеграция и операторская проверка. |
| Docker Compose | docker-compose.yml, docker-compose.override.yml, docker-compose.prod.yml |
Контейнерное развёртывание на управляемом хосте. |
| Kubernetes | deploy/helm/codegraph |
Развёртывание в кластере через сопровождаемый Helm chart. |
| Bare metal заказчика | Руководство по установке | Контролируемая установка на Ubuntu с сервисами заказчика. |
Helm chart сейчас владеет шаблонами deployment, service, ingress, HPA, PVC, secret и config map. NetworkPolicy, ServiceMonitor, Alertmanager, внешняя БД, secret manager, ingress controller и storage class остаются ответственностью платформы заказчика, пока выпущенный артефакт явно не добавит их.
Планирование до изменений
До изменения инфраструктуры зафиксируйте:
- неизменяемые commit, tag, image digest и версии пакетов CodeGraph;
- выбранный профиль и точные values либо environment overlay;
- DNS, TLS termination, ingress, proxy и правила исходящей сети;
- зависимости PostgreSQL, OpenViking, GoCPG, model provider и объектного или файлового хранилища;
- владельца секретов, способ ротации и механизм внешних ссылок;
- постоянные тома, retention, scope резервной копии и цель восстановления;
- resource limits по измеренному корпусу пилота, а не по универсальной таблице sizing;
- окно обслуживания, условие отката и ответственного оператора.
Не помещайте реальные секреты в Git, закоммиченные Helm values, снимки экрана, тикеты и историю команд. Получайте их через одобренный заказчиком канал.
Проверка source checkout
Сопровождаемые команды локального стека находятся в
docs/development/reference/operator/CODEGRAPH_RUNTIME_RELEASE_RUNBOOK.md:
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 считайте контрактом файлы из репозитория и до запуска проверьте effective config:
docker compose -f docker-compose.yml -f docker-compose.prod.yml config
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker compose -f docker-compose.yml -f docker-compose.prod.yml ps
Для Kubernetes сначала отрисуйте сопровождаемый chart с values заказчика:
helm template codegraph deploy/helm/codegraph -f customer-values.yaml > rendered.yaml
helm upgrade --install codegraph deploy/helm/codegraph -f customer-values.yaml --atomic
Проверьте в rendered.yaml image digests, namespaces, security contexts, volumes, ingress и ссылки
на секреты. --atomic помогает восстановить состояние Helm release, но не возвращает данные
приложения и внешних сервисов.
Защита сети, секретов и данных
Как минимум:
- завершайте TLS на согласованной границе и ограничивайте административные маршруты;
- не публикуйте PostgreSQL, GoCPG, OpenViking и внутренние сервисные порты в недоверенную сеть;
- требуйте аутентификацию для API, сетевых MCP transport, ACP и gRPC по профилю;
- разрешайте egress только к одобренным моделям, репозиториям, issue-системам, телеметрии и обновлениям;
- включайте обязательные для профиля DLP, audit и SIEM controls;
- применяйте политики шифрования, retention, backup и удаления данных заказчика.
Прямая запись в DuckDB и передача сырых путей к БД — диагностические либо внутренние границы, а не поддерживаемая удалённая интеграция.
Обновление и откат
Перед обновлением сохраните текущее health-состояние, состояние БД и схемы, активную конфигурацию, image digest и проверенную точку восстановления. Разворачивайте один неизменяемый кандидат и выполняйте согласованные приёмочные probes.
Откат означает возврат предыдущего release-артефакта и совместимой с ним конфигурации. Если релиз включает необратимую миграцию данных, следуйте отдельному recovery plan: смена image tag сама по себе не возвращает сохранённое состояние.
Условия отката могут включать отказ health-зависимостей, регрессию авторизации, нарушение целостности данных, неприемлемую частоту ошибок или провал приёмки пилота. Зафиксируйте trigger, владельца решения, команды, результат и восстановленную ревизию.
Резервное копирование и восстановление
Backup scope должен включать все stateful-зависимости профиля: PostgreSQL, настройки проекта, управляемые заказчиком тома, метаданные шифрования и необходимые входы для восстановления OpenViking или графа. Восстановление скопированного файла подтверждается проверенным restore.
Проведите rehearsal в одобренной non-production цели или заданном заказчиком recovery-контексте:
- проверьте идентификатор, digest, шифрование и retention резервной копии;
- восстановите конфигурацию и данные совместимой процедурой;
- запустите точную версию, ожидаемую резервной копией;
- проверьте health, authentication, project, graph и репрезентативный запрос;
- запишите время восстановления, окно потери данных, исключения и evidence refs.
Health и наблюдаемость
Используйте аутентифицированный контекст и текущий контракт маршрутов:
/api/v1/health— здоровье приложения и зависимостей;/metrics— настроенная поверхность Prometheus scrape;- local-stack status и logs — диагностика source checkout;
- Kubernetes rollout, pod events и выбранные service logs — диагностика кластера;
- SIEM delivery status и подтверждение получения downstream-системой — события безопасности.
HTTP-успех intake endpoint не равен завершению фоновой работы или доставке получателю. Alert thresholds и retention определяются SLO заказчика и измеренным baseline пилота.
Доказательства готовности
Пакет развёртывания должен содержать:
- неизменяемый релиз и digests effective configuration;
- успешный install либо upgrade и health probes;
- проверки authentication, authorization, DLP и отсутствия секретов в публикации;
- репрезентативные результаты import, CPG freshness и пользовательского сценария;
- metrics, logs, alert routing и подтверждение получения SIEM;
- ссылки на rehearsal backup, restore и rollback;
- известные ограничения, недоступные каналы, владельцев и recovery actions.
Эти доказательства относятся к контуру DevOps/SRE. Продуктовая приёмка, QA, AppSec, документация, трассировка, поддержка и финансовое закрытие ведутся отдельными пакетами свидетельств.