Развёртывание Deconflictor в компании
Deconflictor принимает изменения через веб-интерфейс, API и нормализованные вебхуки, сопоставляет их окна с графом зависимостей и сохраняет решение с проверяемыми основаниями. Это прототип: одна компания, одна БД и один процесс приложения на установку. Для начала используйте режим рекомендаций advisory; решение о выпуске принимает ваша интеграция.
Английская версия. Контракт API: OpenAPI. В вашей установке интерактивный справочник Swagger находится на /docs, схема — на /openapi.json. Публичная копия справочника не отправляет запросы в установки компаний.
Подготовка
Нужны Docker Engine с Compose v2, доступ к выданному исходному коду или согласованному образу, HTTPS-прокси и доступ к выбранной модели. Команды ниже выполняются в корне репозитория. Образ собирается для Linux; базовые образы и зависимости закреплены в исходном коде. Подберите ресурсы по своему объёму заявок и нагрузке: универсальной гарантии пропускной способности нет. Приложение оценивает заявки последовательно и сохраняет заявки и решения в PostgreSQL. Очередь worker находится в памяти; незавершённые оценки восстанавливаются из БД.
Подготовьте каталог deployment/ с двумя файлами: catalog-info.yaml и policy.yaml. В каталоге Backstage используйте устойчивые имена Component и Resource; ребро frontend → database означает «frontend зависит от database». Начните с примера каталога, заменив его сервисами компании. Внешние Location рекурсивно не загружаются; доставку свежего файла из вашей CMDB или Backstage настраивает администратор.
Возьмите пример политики и замените поверхности и окна. Без ограничений файл содержит:
blackouts: []
maintenance_windows: []
Повтор неизменённого импорта не меняет граф. Приложение отказывается работать с пустым каталогом. Текущий предел Intake — 300 поверхностей; до подключения более крупной области проверьте полноту графа и ограничения прототипа. Разделение установок не должно скрывать межсервисные зависимости.
Установка с ключом API
Это обычный вариант автоматизации. Используйте отдельный ключ провайдера с контролем расходов.
cp production.env.example .env.production
openssl rand -hex 32
openssl rand -hex 32
chmod 600 .env.production
Два случайных значения задайте в .env.production как POSTGRES_PASSWORD и DECONFLICTOR_API_TOKEN. Они должны различаться. Не сохраняйте их в истории команд, репозитории, заявках или снимках экрана. Заполните:
DECONFLICTOR_LLM_ADAPTER=api
DECONFLICTOR_AGENT_MODEL=openai:MODEL_ID
DECONFLICTOR_AGENT_EFFORT=medium
DECONFLICTOR_EXPLAIN_LANGUAGE=ru
DECONFLICTOR_MODE=advisory
OPENAI_API_KEY=
Вместо MODEL_ID укажите доступную вашему API-аккаунту модель со структурированными ответами, а в OPENAI_API_KEY — ключ. Название модели API не обязано совпадать с названием в подписке. Для совместимого шлюза задайте DECONFLICTOR_API_OPENAI_BASE_URL; сначала проверьте поддержку JSON-схем и выбранного effort. Другие модели по ролям задаются через DECONFLICTOR_INTAKE_MODEL, DECONFLICTOR_JUDGE_MODEL, DECONFLICTOR_CHALLENGER_MODEL, DECONFLICTOR_CHAIR_MODEL и соответствующие переменные *_EFFORT.
docker compose --env-file .env.production -f compose.production.yaml up --build -d --wait
Сервис setup применяет миграции и импортирует каталог, затем запускается app. PostgreSQL хранится в томе pgdata и не публикует порт. Приложение доступно с хоста по http://127.0.0.1:8000; DECONFLICTOR_PORT меняет этот порт.
Установка с подпиской Codex
Этот вариант использует выделенную организацией учётную запись подписки. Её квота общая с другими сеансами аккаунта; доступность модели и условия подписки проверяет администратор. Ключ API не требуется. В .env.production задайте:
DECONFLICTOR_LLM_ADAPTER=codex_cli
DECONFLICTOR_AGENT_MODEL=gpt-6-astra
DECONFLICTOR_AGENT_EFFORT=medium
OPENAI_API_KEY=
Названия моделей Codex пишутся без префикса openai:. Во всех командах этого варианта добавляйте -f compose.codex.yaml после -f compose.production.yaml:
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml build app codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml up --build -d --wait
Команда входа показывает адрес и одноразовый код: подтвердите вход в браузере разрешённой учётной записью. Вход по коду устройства должен быть разрешён в настройках аккаунта. Не передавайте код в журналы общего доступа. Состояние входа хранится в отдельном томе codex-home, доступном процессу UID 10001 для обновления сессии. Это секрет, не обычный кэш. Приложение запускает закреплённую версию CLI внутри своего контейнера, без Docker socket, с отключёнными инструментами и пользовательской конфигурацией. Переключения на API при ошибке входа нет.
docker compose --env-file .env.production -f compose.production.yaml -f compose.codex.yaml run --rm --no-deps codex-auth python -m deconflictor.api.codex status
Для повторного входа остановите только app, выполните команду входа и снова запустите up -d --wait. Для выхода после остановки приложения замените status на logout. Статус входа проверяется локально; истёкшая серверная сессия может обнаружиться только при запросе модели. Документация OpenAI по авторизации.
Подробный контракт настройки моделей описывает версии CLI, окружение процесса и хранение входа.
HTTPS, доступ и первая проверка
Перед приложением нужен корпоративный обратный прокси с HTTPS. Веб-интерфейс и /api обслуживаются с одного адреса. Для событий SSE отключите буферизацию и разрешите долгие соединения. Запускайте один экземпляр приложения: очередь и уведомления координируются внутри процесса. DECONFLICTOR_FORWARDED_ALLOW_IPS должен перечислять только доверенные адреса прокси; по умолчанию эти заголовки игнорируются.
В браузере откройте адрес установки и введите API-токен. В Swagger нажмите Authorize и введите только токен, без слова Bearer. Справочник загружает все ресурсы локально, не использует внешнюю проверку схем и не сохраняет этот токен после обновления страницы. Прототип использует один общий токен: персональных ролей, SSO и изоляции арендаторов внутри установки нет. Корпоративные ограничения доступа настройте на прокси.
Проверьте GET /api/info: llm.answers должно быть live, llm.adapter — api или codex_cli, а graph_version — ненулевым. Затем отправьте одну безопасную заявку команды и дождитесь решения с обоснованием. Это реальный расход API или квоты подписки. Успешный запуск проверяет настройки и БД, но не баланс и доступность провайдера.
Интеграция CI/CD и тикетов
Для повторяемой доставки используйте POST /api/integrations/changes с заголовками Authorization: Bearer <token> и Content-Type: application/json. Это нормализованный входящий вебхук: ваша автоматизация переводит поля исходного CI или тикета в эту схему. Сырые события конкретного вендора и его подпись этим маршрутом не интерпретируются.
{
"source": "ci-checkout",
"external_id": "checkout/deploy/8142",
"change": {
"title": "Обновление checkout",
"body": "Поэтапно обновляем checkout; запись остаётся доступной.",
"kind": "deploy",
"author": "team-checkout",
"environment": "prod",
"window": {"start": "2026-10-14T08:00:00Z", "end": "2026-10-14T08:30:00Z"},
"declared_surfaces": ["component:default/checkout"],
"links": ["https://issues.example.org/releases/8142"]
}
}
Замените дату и имя сервиса. Все даты требуют часового пояса; окно включает начало и не включает конец. source — постоянное имя интеграции, external_id — неизменная ревизия выпуска или тикета, а не номер попытки доставки. Повтор того же содержимого с той же парой ключей возвращает 200 и тот же UUID; первый приём — 202. Другое содержимое с тем же ключом даёт 409 external_identity_conflict. Для нового плана нужна новая ревизия, старую отмените. После таймаута повторите то же тело либо найдите заявку через GET /api/integrations/changes?source=ci-checkout&external_id=checkout/deploy/8142.
Ответ подтверждает сохранение. Для автоматического разрешения выпуска интеграция должна заново прочитать карточку по card и проверить все условия:
status=activeиevaluation.state=done.recordиoutcomeсуществуют;record.id=outcome.record_idиrecord.content_version=content_version.record.final_verdict=outcome.final_verdict=approve.record.chair.status—okилиcarried.not_askedиskipped_standardдопустимы только по явной политике компании.- Нет действующего
override: ручное несогласие требует отдельного процесса согласования компании и не меняет вердикт сервиса.
При pending дождитесь объяснения и прочитайте карточку повторно: председатель может ужесточить разрешение до эскалации. failed, неизвестный статус Chair, reject, escalate, ошибка оценки, таймаут и неполный ответ не разрешают автоматический выпуск. Ограничьте время ожидания; ошибки передавайте человеку. Повтор webhook восстанавливает только отсутствующую первоначальную оценку, а не повторяет ожидающий или неудачный Chair.
Повторно прочитайте карточку непосредственно перед выпуском: другие заявки или действия могут изменить решение. Чтение API не блокирует календарь и не выдаёт атомарного разрешения на внешний запуск; сервис сам не развёртывает изменения. Полные правила доставки и примеры интеграций хранятся вместе с кодом.
Обычный POST /api/changes также доступен: UUID можно передать самим, но повтор UUID возвращает конфликт. Изменения принимаются через веб-форму, без внешней интеграции. После отмены или исполнения отправьте PATCH /api/changes/{id}/status со значением withdrawn или executed; связанные решения пересчитаются. Deconflictor не выполняет само развёртывание. Человеческое переопределение с причиной хранит несогласие в истории, но не меняет решение кода. Перенос окна принимает только предложение из актуальной карточки.
События доступны по events и /api/events. Для продолжения передайте Last-Event-ID с последним полученным seq. Браузерный EventSource допускает параметр access_token; уберите этот параметр из журналов прокси. Для других клиентов используйте заголовок. Исходящие уведомления отдельно настраиваются через DECONFLICTOR_NOTIFY_WEBHOOK_URL; это не адрес приёма входящих заявок.
Безопасность и хранение
Тексты заявок, сведения о сервисах и цитаты передаются выбранной модели. Согласуйте разрешённые данные, условия провайдера и сроки хранения до подключения внутренних проектов. Запросы и обоснования остаются в PostgreSQL; автоматической политики удаления сейчас нет. Не передавайте в описаниях пароли, ключи и персональные данные без необходимости.
Ограничьте сеть БД, доступ к хосту, исходящие адреса модели и право чтения .env.production. Шифруйте диски и резервные копии средствами инфраструктуры. Приложение работает без root, с кодом только для чтения. Проверьте журналы прокси на токены в URL. При утечке общего API-токена замените его в конфигурации, пересоздайте app и обновите доверенные клиенты. Для Codex отдельно отзовите вход и войдите снова; не копируйте codex-home в обычные архивы.
Резервные копии и восстановление
Сохраняйте дамп БД, точную версию приложения, каталог и политику. Секреты храните отдельно. Для Codex добавляйте второй Compose-файл во все команды, как выше.
docker compose --env-file .env.production -f compose.production.yaml exec -T db pg_dump -U deconflictor -d deconflictor -Fc > backup.dump
Проверяйте восстановление в отдельной установке той же версии с новым пустым томом БД: поднимите только db, дождитесь его готовности, затем импортируйте дамп. Не запускайте setup до восстановления, иначе новая БД уже будет содержать таблицы. В отдельной копии исходников задайте DECONFLICTOR_PORT=8001 и DECONFLICTOR_API_RESUME=0 в своём .env.production, чтобы не занять рабочий порт и не оценивать восстановленные заявки автоматически. Отдельное имя проекта Compose ниже изолирует тома. Для Codex выполните новый вход в этом проекте до запуска приложения.
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait db
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml exec -T db pg_restore --exit-on-error --no-owner -U deconflictor -d deconflictor < backup.dump
docker compose -p deconflictor-restore --env-file .env.production -f compose.production.yaml up -d --wait
Сверьте граф, количество заявок, историю и одну карточку. Для подписки выполните новый вход в отдельной установке. Не используйте down -v для штатной остановки: это удаляет данные.
Обновление и изменение каталога
Сначала сохраните резервную копию и версии конфигурации. Остановите app, получите проверенную версию исходников/образа и пересоздайте setup для миграций перед запуском:
docker compose --env-file .env.production -f compose.production.yaml stop app
docker compose --env-file .env.production -f compose.production.yaml build
docker compose --env-file .env.production -f compose.production.yaml up --force-recreate --no-deps --exit-code-from setup setup
docker compose --env-file .env.production -f compose.production.yaml up -d --wait
При ошибке миграции не запускайте новую версию приложения. Откат кода не откатывает схему: восстанавливайте проверенный дамп в отдельную БД вместе с прежней версией приложения. После успешного обновления проверьте /api/info, журнал setup и тестовую заявку.
Для обновления каталога замените файл и выполните импорт без вызова модели:
docker compose --env-file .env.production -f compose.production.yaml run --rm --no-deps setup deconflictor graph import /config/catalog-info.yaml
После изменения политики пересоздайте app. Старые Decision Record сохраняют прежнюю версию графа, политики и сведения о моделях; история не переписывается.
Поиск неисправностей
docker compose --env-file .env.production -f compose.production.yaml ps
docker compose --env-file .env.production -f compose.production.yaml logs --tail=100 app setup
401: проверьте токен приложения и клиента; в Swagger вводится только значение токена.403: приложение запущено без токена и запрещает внешние запросы; не обходите эту проверку заголовками.409: прочитайте код ошибки; повтор вебхука с другим телом требует новой ревизии, устаревшая карточка — повторного чтения.422: ответ содержит все нарушения с полями; проверьте часовой пояс, окно и канонические имена поверхностей.503: проверьте готовность БД, миграции и конфигурацию сервиса.- Оценка
failed: найдите причину в карточке и журнале; исправьте ключ, вход или лимит модели. Перезапуск по умолчанию восстанавливает незавершённые оценки. - Нет событий: проверьте буферизацию и таймаут прокси, токен, последний
seq; повторное подключение продолжает поток. - Неизвестный сервис: проверьте
/api/surfacesи импорт каталога; имя в заявке должно совпадать с каноническим ref или его алиасом.
Для поддержки подготовьте версию приложения, время ошибки с часовым поясом, UUID заявки, код ошибки и очищенный фрагмент журнала. Не прикладывайте .env.production, содержимое тома входа, дамп с внутренними заявками или токены.