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

Поддерживаемый customer-профиль разворачивает основной Compose-стек на VM заказчика с Ubuntu 22.04/24.04. Установку должен выполнять профессиональный системный администратор с одобренным неизменяемым ref, местом для резервной копии, сетевой политикой и процедурой работы с секретами.

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

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

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

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

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

Ниже приведён поддерживаемый baseline для single-VM customer-развёртывания. Профиль VM выбирают по объёму CPG, числу одновременных импортов и рабочих процессов. Минимальный профиль предназначен для проверки установки, а не для промышленной нагрузки.

Сервер 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-артефактов в проекте развёртывания: эта страница не объявляет ARM64 поддерживаемым production-профилем. Нужны 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 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 нужен, если используется долговременная память. Устаревший workaround Codex 0.147 с корневым используйте актуальный поток установки Codex и пакет плагина; прежний root-manifest для Codex 0.147 архивирован.
Для OpenCode нужны runtime с @opencode-ai/plugin >=1.2.0, npm-пакет opencode-codegraph 0.1.38 и доступ к CodeGraph API. Текущий launcher по умолчанию использует openai/gpt-5.4, но модель заменяют на утверждённую через поддерживаемую конфигурацию. Установка описана в быстром старте OpenCode, а переменные и жизненный цикл — в руководстве по интеграции.

ИИ-модели

Не смешивайте два независимых выбора: серверная модель CodeGraph выполняет генерацию и embedding внутри runtime, а модель 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+. Это рекомендация по ёмкости, а не универсальная гарантия совместимости: фактический prompt вместе с ответом и запасом должен помещаться в лимит выбранной модели и подтверждаться приёмочным сценарием.

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

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

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

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

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

Точные версии браузеров, production-поддержка ARM64, HA/Kubernetes и единый для всех моделей контекстный лимит не входят в этот single-VM контракт и должны оформляться отдельным проектным решением.

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

Сначала выполните немутирующую проверку из одобренного 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. Настройте секреты

До запуска сервиса заполните /opt/codegraph/.env по защищённой процедуре заказчика. Как минимум замените пустые значения:

POSTGRES_PASSWORD;
API_JWT_SECRET — случайное значение длиной не менее 64 символов;
API_ADMIN_PASSWORD — уникальные начальные учётные данные администратора;
credential одобренного LLM-провайдера;
остальные обязательные ключи из .env.example конкретной релизной версии.

Файл должен принадлежать root и иметь ограниченные права. Не помещайте значения секретов в тикеты, историю 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

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

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

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

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

Связанная внешняя документация

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