Перейти к основному содержимому

Установка CodeGraph на Ubuntu-сервер заказчика

Подготовьте Ubuntu-сервер, установите CodeGraph, настройте секреты и модель. Проверьте запуск сервисов, обновление и откат на своей конфигурации.

Начало работы

Профиль заказчика разворачивает основной Compose-стек на выделенной виртуальной машине с Ubuntu 22.04/24.04. Руководство предназначено для системного администратора: подготовьте согласованный тег или коммит выпуска, место для резервной копии, сетевую схему и процедуру работы с секретами.

Профиль по умолчанию не включает публичные домены CodeGraph, сервис leads, self-hosted Sentry и GitHub autodeploy.

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

  • выделенная VM с Ubuntu 22.04/24.04 и административным доступом;
  • доступ к одобренному репозиторию CodeGraph или чистому release checkout;
  • неизменяемый тег или коммит, одобренный для пилота;
  • внешний доступ либо внутреннее зеркало пакетов и образов;
  • согласованные заказчиком DNS, TLS, резервное копирование и хранение секретов.

Не помещайте логин, токен или пароль в адрес репозитория либо командную строку. Для закрытого зеркала используйте SSH agent или системный credential helper.

Требования к серверу, клиентам и ИИ-моделям

Выберите размер виртуальной машины по объёму графа свойств кода (CPG), числу одновременных импортов и рабочих процессов. Минимальный профиль позволяет проверить установку; для промышленной нагрузки начните с рекомендуемого или крупного профиля.

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

Сервер CodeGraph

Сервер CodeGraph
Профиль vCPU ОЗУ Диск SSD Назначение
Проверка установки 4 vCPU 16 GB 100 GB UI/API, небольшой демонстрационный проект, без тяжёлого self-analysis и конкурентных импортов
Рекомендуемая рабочая VM 8 vCPU 32 GB 200 GB Полный Compose-стек, OpenViking, Temporal, MCP, мониторинг и умеренная нагрузка
Крупный self-analysis 16 vCPU 64 GB 500 GB Крупные CPG, повторные импорты и конкурентные процессы digital employees

Поддерживаемая серверная ОС — Ubuntu 22.04/24.04 на x86_64. Для развёртывания на ARM64 предварительно проверьте совместимость контейнерных образов и GoCPG-артефактов. Нужны Docker Engine с Compose plugin, Git, Bash, curl, openssl, синхронизация времени и доступ к неизменяемому release ref. GPU не требуется при использовании удалённого LLM-провайдера; локальный inference рассчитывают отдельно вместе с VRAM, RAM и диском под выбранную модель.

Снаружи обычно публикуют только HTTPS 443; HTTP 80 нужен, если используется redirect или получение сертификата, SSH 22 — только из административной сети. Порты API 8000, панели 3100, MCP 27495, GoCPG 50051, OpenViking 1933/8020 и Temporal 7233/8233 считаются внутренними, пока утверждённая сетевая схема явно не говорит обратное. Серверу нужен исходящий доступ либо внутренние зеркала для пакетов, контейнеров и репозитория, а также утверждённые направления к модельному провайдеру, DNS и NTP.

Опубликованные порты Docker могут обходить правила UFW. Проверьте привязки портов Compose и сетевой фильтр с внешней машины: одной настройки UFW недостаточно для изоляции. См. ограничения сетевого фильтра Docker.

Диск должен вмещать Docker volumes, PostgreSQL, workspace, CPG, OpenViking, логи и запас для обновления. До пилота задайте отдельное резервное хранилище и проверьте восстановление .env, config.yaml, projects.yaml, данных приложения, workspace, OpenViking и постоянных volumes. Параметры секретов, TLS, CORS и hosts приведены в руководстве по конфигурации.

Клиентское ПО

  • Для панели нужен поддерживаемый производителем актуальный браузер с JavaScript, HTTPS и WSS. Пользователю заранее выдают URL, учётную запись, tenant/project scope и требуемую роль.
  • MCP-клиент работает с MCP 2026-07-28, native JSON arrays/objects, авторизацией и одним из транспортов: stdio или Streamable HTTP POST /mcp. Настройка и проверка вызова инструмента описаны в руководстве оператора MCP.
  • Для Codex нужны Windows 10/11 с PowerShell 5+ либо Linux/macOS с Bash 4+, Git, рекомендуемый Python 3.11+, не менее 1 GB свободного места для client home/cache/logs, Codex 0.149.1+ и нативный пакет плагина Codex. Клиенту требуется доступ к CodeGraph API/MCP; OpenViking нужен, если используется долговременная память. Используйте актуальный поток установки Codex и пакет плагина.
  • Для OpenCode нужны runtime с @opencode-ai/plugin >=1.2.0, npm-пакет opencode-codegraph 0.1.38 и доступ к CodeGraph API. Текущий launcher по умолчанию использует openai/gpt-5.4, но модель заменяют на утверждённую через поддерживаемую конфигурацию. Установка описана в быстром старте OpenCode, а переменные и жизненный цикл — в руководстве по интеграции.

ИИ-модели

Выберите модели для двух задач. Серверная модель CodeGraph генерирует ответы и векторные представления данных, а модель Codex/OpenCode планирует шаги агента и вызывает инструменты MCP.

Серверный runtime поддерживает provider types local, codex_subscription, gigachat, openai и yandex. Для удалённого провайдера требуются endpoint и credential утверждённого tenant, TLS, квоты и возможность передавать system/user prompts в UTF-8. Модель должна работать с русским и английским текстом, кодом, diff и CPG-сводками, принимать настройки temperature, max_tokens и timeout и возвращать диагностируемые ошибки. Параметры конкретных провайдеров см. в руководствах Yandex AI Studio и GigaChat.

Для первого пилота выбирайте контекст не менее 32K; для крупных репозиториев и многошаговых задач предпочтительно 64K+. Проверьте, что запрос вместе с ответом и запасом помещается в лимит выбранной модели. Подтвердите это на типичной задаче пилота.

Agent-модель должна надёжно вызывать инструменты по JSON Schema, сохранять точные story/task/ project identifiers и source refs, выполнять многошаговый цикл и явно сообщать об отказе или недоступности инструмента. Embedding-модель должна покрывать русский, английский и исходный код, поддерживать batching и стабильную размерность в пределах индекса. Смена embedding-модели либо размерности требует явной переиндексации; смешивать в одном индексе несовместимые векторы нельзя.

До включения внешней модели зафиксируйте endpoint, tenant, регион обработки, использование данных для обучения, retention, TLS, access logs, квоты, стоимость, fallback и порядок инцидента. Какие данные могут покидать контур и как проверить DLP, описано в руководстве по безопасности LLM.

Приёмка требований

Развёртывание принимают только после шести независимых проверок:

  1. install receipt указывает утверждённый commit, обязательные контейнеры healthy, общая readiness успешна;
  2. пользователь входит через браузер по HTTPS, открывает проект, а browser WebSocket работает;
  3. Codex или OpenCode выполняет реальный авторизованный MCP tool call после discovery;
  4. серверная модель выполняет тестовую генерацию и embedding на синтетических данных;
  5. DLP блокирует или маскирует синтетический canary без использования настоящего секрета;
  6. резервная копия восстанавливается в проверочном окружении с сохранением project scope.

Для развёртывания на ARM64, отказоустойчивого кластера или Kubernetes подготовьте отдельную схему установки и её проверки.

1. Проверьте план

Команды ниже выполняются в Bash. До запуска замените <immutable-tag-or-commit> на согласованный тег или полный хеш коммита, а <approved-repository-url> — на адрес репозитория, разрешённый для этого развёртывания. Замените значения целиком, включая угловые скобки, и сохраните кавычки. В checkout должен находиться scripts/install-ubuntu.sh из выбранного выпуска.

Сначала выполните немутирующую проверку из одобренного release checkout:

bash scripts/install-ubuntu.sh \
  --profile customer-baremetal \
  --source-ref "<immutable-tag-or-commit>" \
  --plan

Проверьте итоговый профиль и ref. В customer-плане сервис leads, порт 8001, публичные nginx-hosts CodeGraph, self-hosted Sentry и autodeploy должны оставаться выключенными, если их не добавляет одобренный проект развёртывания.

2. Установите одобренную версию

sudo bash scripts/install-ubuntu.sh \
  --profile customer-baremetal \
  --source-repository "<approved-repository-url>" \
  --source-ref "<immutable-tag-or-commit>"

Установщик разрешает ref до коммита и записывает квитанцию /opt/codegraph/data/deployment-evidence/install-source.json. Для продолжения checkout должен быть чистым, ref — одобренным, а resolved commit — совпадать с ним.

3. Настройте секреты

При новой установке установщик создаёт POSTGRES_PASSWORD, API_JWT_SECRET, API_ADMIN_PASSWORD и другие секреты среды. Файл .env принадлежит root, имеет группу codegraph и права 0640. Профиль заказчика не выводит созданные пароли в консоль. При обновлении установщик сохраняет существующий .env и добавляет отсутствующие параметры. Не заменяйте пароль базы и ключи подписи при обычном обновлении: их ротация требует согласованной процедуры.

До запуска сервиса проверьте /opt/codegraph/.env по защищённой процедуре заказчика, выберите одобренного модельного провайдера и замените его шаблонные учётные данные. Сверьте остальные обязательные ключи с .env.example выбранного выпуска. Получите начальный пароль администратора по защищённой процедуре. Не помещайте значения секретов в тикеты, историю shell, снимки экрана или установочные доказательства. Подробнее: Конфигурация.

4. Запустите и проверьте

sudo systemctl start codegraph
sudo systemctl status codegraph --no-pager
cd /opt/codegraph
sudo docker compose -f docker-compose.yml ps
sudo docker compose -f docker-compose.yml exec -T api \
  python scripts/run_app_stack_readiness.py --network compose --include-mcp --mcp-auth-required

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

После проверки сервисов перейдите к быстрому старту: войдите в панель и импортируйте первый репозиторий. Затем настройте автоматические проверки проекта по ссылкам ниже.

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

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

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

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

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

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

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

Перед обновлением сохраните /opt/codegraph/.env, config.yaml, projects.yaml, данные приложения, workspace, OpenViking и постоянные Docker volumes. Сохраните квитанцию текущей ревизии.

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

Проверка восстановленной поставки

Восстанавливайте резервную копию в отдельное проверочное окружение с тем же тегом или коммитом выпуска. Подготовьте копию .env, ключей шифрования и файлов конфигурации. Для PostgreSQL восстановите логическую резервную копию; для файлов проектов и CPG сохраните структуру каталогов и права доступа. Включите в восстановление используемые тома и данные OpenViking.

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

  1. Сверьте ревизию миграций PostgreSQL и список проектов с резервной копией.
  2. Войдите под восстановленной учётной записью и откройте проект. Проверьте его группу, настройки области анализа и сохранённые метаданные.
  3. Выполните запрос к восстановленному CPG и сравните результат с контрольным запросом до резервного копирования.
  4. Проверьте поиск по восстановленным данным OpenViking, если используется долговременная память.
  5. Выполните проверку готовности из шага 4 и проверки клиентов, модели и DLP из раздела «Приёмка требований».

Запишите время восстановления, время создания резервной копии, проверенный выпуск и результаты. Эти данные показывают, сколько времени занимает восстановление и какой период изменений покрывает копия.

Связанные руководства

Конфигурация · Быстрый старт · MCP · Безопасность LLM · OpenCode

Сообщить об ошибке в документации