Руководство системного администратора

Развёртывание продуктового экземпляра программы «Голосовой ИИ-тренажёр».

Наименование программы

Голосовой ИИ-тренажёр (pichi.ai)

Правообладатель

ООО «Аспирити», ИНН 2463256437, КПП 246001001, ОГРН 1142468034741

Техническая поддержка

pichi@aspirity.com, тел. +7 (391) 205-00-55

По умолчанию работа Голосового ИИ-тренажёра реализована в виде облачного сервиса. Развёртывание системы в контуре клиента не предполагается и выполняется только по отдельному соглашению.

Прод-контур поднимается одним файлом docker-compose.prod.yml. В его состав входят: серверное приложение, СУБД (PostgreSQL), лендинг и вспомогательный стек (наблюдаемость/логи, административные сервисы). Образы приложения и лендинга — заранее собранные, берутся из реестра образов и на месте не собираются. Конфигурация и секреты подаются через файл окружения (.env) в каталоге запуска — Docker Compose сам подставляет значения из него в шаблон compose-файла.

1. Предварительные требования

Компонент	Требование
ОС	Linux-сервер с Docker Engine + Docker Compose v2
Реестр образов	Доступ для загрузки образов приложения и лендинга
Внешняя сеть Docker	Предварительно созданная внешняя сеть
Каталог данных	Постоянное хранилище для томов (БД, загрузки, логи и пр.)
Reverse-proxy	Внешний
Доступы к внешним сервисам	Реквизиты подключения к интеграциям (см. п. 3)

2. Подготовка сервера

Получить проект

Нужны compose-файлы и сопутствующие каталоги конфигурации.
Создать внешнюю сеть Docker (если ещё не создана)
```
docker network create http-entry
```
Создать каталоги постоянного хранилища под выбранный контур

Значение ENV — например, prod:
```
sudo mkdir -p /storage/aicallstudio/prod/{pgdata,uploads,logs,loki,grafana,nocodb,wikijs}
```

Загрузить образы из реестра

docker pull <образ-приложения>:<tag>
docker pull <образ-лендинга>:<tag>

3. Файл окружения

Создать файл .env в корне проекта (рядом с docker-compose.prod.yml) — Compose подхватит его автоматически. Перечень переменных и их шаблон приведены в .env.example; при разворачивании их следует заполнить реальными значениями.

Состав конфигурации логически делится на следующие группы:

Параметры контура и развёртывания — имя окружения, теги образов приложения и лендинга, публичный URL, порты, разрешённые источники запросов.
Подключение к СУБД — реквизиты PostgreSQL и строка подключения.
Криптографические ключи приложения — для подписи пользовательских сессий и служебных токенов (обязательны).
Интеграции с языковыми моделями (LLM) — провайдер(ы) обработки и анализа диалогов; при необходимости — параметры прокси и резервного канала.
Голосовой стек — выбор провайдера голосовых звонков и реквизиты доступа к нему (распознавание/синтез речи, медиатранспорт).
Транскрипция записей — сервис расшифровки аудио.
Почтовые уведомления — параметры SMTP-сервера.
Платёжная интеграция — реквизиты платёжного провайдера и подпись вебхуков.
Объектное хранилище — доступ к S3-совместимому хранилищу записей и артефактов.
Защита от ботов — параметры сервиса проверки запросов.
Аналитика и оповещения — продуктовая аналитика и канал уведомлений.
Вспомогательные сервисы — учётные данные административных и инфраструктурных компонентов (панель логов, админ-инструменты).

Файл окружения содержит секреты

Ограничить права доступа (chmod 600 .env) и не помещать файл в систему контроля версий.

4. Запуск

Запуск выполняется штатным docker compose — файл окружения читается автоматически.

# поднять весь контур
docker compose -f docker-compose.prod.yml up -d

Либо поэтапно — сначала СУБД, затем приложение (стартует после готовности БД), затем остальные сервисы:

docker compose -f docker-compose.prod.yml up -d <сервис-БД>
docker compose -f docker-compose.prod.yml up -d <сервис-приложения>
docker compose -f docker-compose.prod.yml up -d <остальные-сервисы>

Если файл окружения расположен отдельно — указать его явно: --env-file /path/to/prod.env.

Миграции применять вручную не требуется

Контейнер приложения при старте сначала выполняет миграции и только затем поднимает сервер. Приложение запускается после перехода СУБД в состояние healthy.

5. Первичный посев администратора

Выполняется однократно на свежей базе данных:

docker exec -it <контейнер-приложения> node dist/seed-admin.js

6. Проверка работоспособности

# все сервисы должны быть в состоянии running/healthy
docker compose -f docker-compose.prod.yml ps

# логи серверного приложения
docker compose -f docker-compose.prod.yml logs --tail=100 <сервис-приложения>

Признаки успешного старта

В логах приложения — применённые миграции и запуск сервера без ошибок.
Приложение и лендинг слушают свои локальные порты (проброшены через reverse-proxy на публичный URL).
Открытие публичного URL, вход под созданным администратором и проведение тестового звонка подтверждают связку с голосовым провайдером и языковой моделью.

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

Обновление

Изменить тег образа приложения в файле окружения → загрузить образ (docker pull) → пере-поднять сервис приложения. Миграции применятся при рестарте автоматически.

Откат версии

Вернуть предыдущий тег образа и пере-поднять сервис.

Откат БД выполнять с осторожностью

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

Остановка

docker compose -f docker-compose.prod.yml down

Данные в постоянном хранилище при этом сохраняются.