Установка

Требования#

Требования к серверам#

серверы на Linux из семейств Debian-compatible или RHEL-compatible;
версия ядра Linux не ниже 5;
локальные средства host firewall (firewalld, ufw и аналогичные) на серверах SmartCPD должны быть отключены;
системное время на всех серверах SmartCPD должно быть синхронизировано с единым источником времени;
для выполнения setup нужен пользователь с правами запуска команд docker и sudo.

Синхронизация времени#

Все серверы SmartCPD должны использовать единый доверенный источник времени через NTP-совместимый механизм, например systemd-timesyncd, chrony или корпоративные NTP-серверы.

Если инфраструктура входит в домен Active Directory, в качестве источника времени рекомендуется использовать контроллеры домена или доменное имя, предоставляющее доступ к ним.

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

NTP-синхронизация включена и находится в рабочем состоянии;
расхождение времени между серверами SmartCPD не превышает 1 секунду;
серверы service, worker, balancer, analyzer, PostgreSQL и внешние балансировщики, участвующие в контуре вызова, используют согласованное время.

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

Worker-ноды#

На worker-нодах настоятельно рекомендуется полностью отключить swap. Использование swap может приводить к непредсказуемому росту задержек в latency-чувствительном контуре обработки вызовов.

Отключить swap до следующей перезагрузки:

sudo swapoff -a

Проверить состояние:

swapon --show

Если команда не выводит ни одного устройства или файла, swap отключен.

Чтобы swap не включился после перезагрузки, необходимо также отключить соответствующие swap-разделы или swap-файлы в конфигурации операционной системы. Например, для конфигурации через /etc/fstab следует удалить или закомментировать записи с типом swap.

Требования к Docker#

должен быть установлен Docker версии не ниже 26;
версия Docker должна быть одинаковой на всех серверах установки;
если на серверах используются SELinux или AppArmor, должны применяться стандартные механизмы безопасности Docker.

Рекомендуемые материалы Docker:

Доступ к артефактам#

все серверы должны иметь доступ к Docker-репозиторию Altuera cr.repo.altuera.ru;
доступ к репозиторию запрашивается у аккаунт-менеджера Altuera.

Если доступ к cr.repo.altuera.ru отсутствует, образы необходимо заранее подготовить и загрузить на все серверы, участвующие в установке SmartCPD. Для подготовки offline-набора и его загрузки на целевые серверы можно использовать команды images-save и images-load скрипта smartcpd-setup.sh, см. Справка по smartcpd-setup.sh.

Требования к размещению ролей#

до начала установки должны быть определены серверы, на которые будут назначены роли service, balancer, worker, analyzer;
состав ролей и их допустимое совмещение должны соответствовать выбранной схеме развертывания.

Требования к ролям нод описаны в разделе Роли нод SmartCPD, а требования к HA-схеме и размещению контуров — в разделе Поддерживаемая HA-конфигурация.

Требования к качеству сети#

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

Для SmartCPD важны задержка, потери, jitter и длительность кратковременных сетевых обрывов между нодами Docker Swarm cluster. Ориентиры нормального режима и зоны риска приведены в разделе Требования к качеству сети.

Требования к хранилищам#

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

Local data root, по умолчанию /opt/scpd;
Shared data root, по умолчанию /opt/shared_data.

Local data root используется для данных конкретной ноды. Этот путь должен быть подготовлен на всех серверах, участвующих в установке SmartCPD.

Shared data root используется для компонентов, которым требуется переносимое состояние. В отказоустойчивой схеме этот путь должен быть подготовлен и примонтирован по одному и тому же пути на всех серверах, где используется общее хранилище. Записи детекций CDR Collector размещаются в подкаталоге detections_data этого пути.

Использование хранилищ по ролям:

service - использует Local data root, а в HA-схеме также Shared data root;
balancer - использует Local data root;
worker - использует Local data root;
analyzer - использует Local data root.
корневые пути должны быть одинаковыми на всех серверах, где они используются;
корневые пути должны быть доступны пользователю контейнеров по заданным uid и gid;
корневые пути подготавливаются до начала установки;
необходимые рабочие подкаталоги внутри этих путей создаются setup-скриптами.

Если отказоустойчивое распределенное хранилище не используется, в параметре Shared data root можно указать путь локального хранилища.

Архитектурная модель local/shared storage описана в разделе Хранилища данных, включая подраздел Отказоустойчивое распределенное хранилище данных.

Состав поставки#

Поставка setup SmartCPD строится вокруг каталога setup/.

В состав поставки входят:

smartcpd-docker-setup.sh для настройки Docker на сервере и Docker Swarm, подробнее в документе Настройка Docker и Docker Swarm;
smartcpd-setup.sh для подготовки конфигурации SmartCPD, генерации stack-артефактов и deployment;
smartcpd-stack-template.yml как основной шаблон стека из поставки;
compose.override.example.yml как пример локального compose.override.yml для override-настроек и observability-параметров;
compose.override.migrate.yml как готовый временный override для миграции с SmartCPD 5.2.x или 5.3.x на 6.0.0;
secrets.example.env как пример файла исходных секретов для non-interactive генерации setup-секретов;
versions.env с версией поставки;
db/postgres со SQL-скриптами для подготовки PostgreSQL.

В ходе setup формируются и используются следующие state-файлы и runtime-артефакты:

smartcpd-setup.env как сохраненные параметры setup;
stack/compose.generated.yml как сгенерированный stack из шаблона;
stack/compose.runtime.yml как итоговый compose-файл с учетом compose.override.yml;
stack/smartcpd-node-*-setup.sh как сгенерированные скрипты настройки нод;
images/ как каталог для offline-набора образов;
backup/ как каталог с резервными копиями параметров setup и сгенерированных файлов стека.

Сгенерированные файлы в stack/ и docker/ считаются рабочими файлами setup. Их не следует редактировать вручную, если это не предусмотрено отдельным описанным сценарием через compose.override.yml.

Подготовка PostgreSQL#

До запуска setup PostgreSQL должна быть подготовлена со стороны инфраструктуры Заказчика.

Необходимо:

использовать PostgreSQL версии 14+;
если PostgreSQL используется в отказоустойчивой схеме, подготовить единый endpoint PostgreSQL для SmartCPD; требования к HA-схеме БД описаны в разделе База данных;
выбрать модель использования PostgreSQL: общую учетную запись для сервисов, включая billing, или отдельные per-service роли; поддерживаемые варианты описаны в разделе Модель доступа;
определить, используются ли optional SIPCapture- и/или PDS-слои;
определить, нужны ли optional administrative roles dbo и/или read-only;
обеспечить сетевую доступность PostgreSQL со стороны компонентов SmartCPD;
создать БД SmartCPD и учетные записи PostgreSQL с правами, соответствующими выбранной модели доступа.

Для подготовки БД можно использовать SQL-скрипты из поставки:

db/postgres/sql/00-sa-create-db-once.sql - создание БД;
db/postgres/sql/01-sa-users.sql - создание ролей/пользователей, паролей и administrative memberships;
db/postgres/sql/02-dbo-grants.sql - применение схем, search_path, default privileges и grants.

Подробный состав учетных записей и правила выбора модели доступа описаны в разделе Модель доступа, а порядок применения SQL-скриптов — в разделе Скрипты поставки.

Данные, которые нужно собрать до установки#

До запуска setup должны быть известны:

Значения по умолчанию, если они есть, указаны в квадратных скобках.

Организация и администратор портала

ИНН организации, на которую будет выписана лицензия;
email администратора портала;
пароль администратора портала;
имя стека Docker Swarm [scpd].

Доступ к порталу

будет ли портал публиковаться напрямую или через reverse-proxy с терминированием TLS;
полное доменное имя (FQDN) портала;
порт публикации портала [443];
режим публикации портала [HTTPS]: HTTP (только при использовании reverse-proxy) или HTTPS;
файл сертификата и файл ключа портала, если используется HTTPS;

Доступ к БД

хост, порт и имя базы данных PostgreSQL;
timezone БД в формате IANA, например Europe/Moscow; значение обязательно, сохраняется в SMARTCPD_DB_TZ и должно точно совпадать с timezone контейнеров SMARTCPD_TZ;
учетные данные пользователей БД в соответствии с выбранной моделью использования PostgreSQL.

Интеграция со SmartContact

требуется ли интеграция со SmartContact;
URL сервера SmartContact.

Установка и настройка SmartContact не входят в состав поставки SmartCPD.
Для работы интеграции SmartContact требуется включенный SIP trace backend. Параметры backend, требования к PostgreSQL и параметры SIP trace web UI описаны в разделе SIP trace.
Для доступа SmartContact к данным SmartCPD требуется доступ к БД SmartCPD: таблице public.cdr_cdr и схеме homer.
Если для внешней интеграции нужен отдельный пользователь с доступом к CDR-данным и homer, задайте DB_PDS_USER/DB_PDS_PASSWORD при запуске db/postgres/sql/01-sa-users.sql, а затем примените db/postgres/sql/02-dbo-grants.sql.

Хранилища данных

локальный путь Local data root [/opt/scpd];
путь Shared data root [/opt/shared_data], если используется переносимое общее хранилище;

Параметры запуска контейнеров и подключения к Docker

uid и gid пользователя контейнеров (опционально);
часовой пояс контейнеров SMARTCPD_TZ [Europe/Moscow];
диапазон адресов Docker-сетей размера /16 [172.27.0.0];
способ подключения контейнеров к Docker API: [unix socket] или mTLS over TCP;
путь к Docker socket или TCP-параметры и TLS-секреты Docker API;
имя группы с доступом к Docker socket [docker];

Доступ к облаку Altuera для обновления моделей

будет ли использоваться автоматическое обновление моделей из облака Altuera [Да];
адрес и параметры HTTPS proxy, если он используется для доступа в интернет;
CA-файл proxy, если он требуется;
подготовленные файлы моделей, если обновление будет выполняться вручную.

Сроки хранения данных

срок хранения CDR [6 месяцев];
срок хранения истории детекций [30 дней];
срок хранения полных записей детекций [1 день];
срок хранения записей клиентской стороны (b_side) [7 дней];
срок хранения метрик [6 месяцев];
размер docker logs для каждого контейнера [100 MB];
срок хранения архива логов [14 дней];
размещение архива логов на локальном или сетевом диске [/opt/scpd/logs];
лимит места для всех лог-файлов в выбранном месте размещения [100 GB].

Процесс установки#

Все команды этого раздела выполняются на сервере, который в целевой схеме одновременно будет service-нодой SmartCPD и manager-нодой Docker Swarm, если явно не указано иное.

1. Подготовить рабочую директорию setup#

Скопировать данные поставки в рабочую директорию на выбранном сервере.

Пример:

mkdir -p /opt/scpd/setup
cp -r <поставка>/setup/* /opt/scpd/setup/
cd /opt/scpd/setup

Сделать setup-скрипты исполняемыми:

chmod +x *.sh

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

2. Настроить Docker и Docker Swarm#

Docker и Docker Swarm можно подготовить вручную по документу Docker. В этом случае шаг с smartcpd-docker-setup.sh можно пропустить.

Если используется штатный сценарий поставки, запустить smartcpd-docker-setup.sh от имени обычного пользователя с доступом к docker и sudo.

Если Docker Swarm cluster уже создан, это не мешает установке: скрипт подхватит существующие настройки. Если кластер еще не создан, скрипт создаст его автоматически.

В результате будет сгенерирован скрипт:

docker/smartcpd-docker-node-setup.sh

Этот файл нужно скопировать на все остальные ноды кластера и выполнить там от имени root или через sudo. На текущем сервере выполнять этот скрипт не нужно.

После этого следует убедиться, что все серверы добавлены в Docker Swarm cluster:

docker node ls

3. Выполнить настройку SmartCPD#

Запустить smartcpd-setup.sh от имени обычного пользователя:

./smartcpd-setup.sh

Заполнить необходимые параметры setup.

Если интерактивная настройка была прервана или завершилась ошибкой, ее можно продолжить с того же места:

./smartcpd-setup.sh --continue

На вопрос о запуске установки сразу после завершения setup следует ответить отказом.

4. Разметить ноды#

После завершения интерактивной настройки запустить:

./smartcpd-setup.sh labels

И назначить всем нодам требуемые роли SmartCPD.

5. Подготовить ноды к запуску#

После генерации setup-артефактов будут сформированы role-specific скрипты:

stack/smartcpd-node-*-setup.sh

Эти скрипты нужно скопировать на серверы с соответствующими ролями и выполнить на них.

Если сервер совмещает несколько ролей, на него нужно скопировать и последовательно выполнить все требуемые role-specific скрипты.

В отличие от docker/smartcpd-docker-node-setup.sh, role-specific setup scripts должны выполняться и на текущем сервере установки, если ему назначены соответствующие роли.

6. Выполнить запуск#

После подготовки всех нод выполнить:

./smartcpd-setup.sh deploy

Эта команда развернет или обновит стек SmartCPD в Docker Swarm.

Пример вывода:

==> Deploying stack scpd
Creating service scpd_metrics
Creating service scpd_grafana
Creating service scpd_log2file
Creating service scpd_balancer
Creating service scpd_config-server
Creating service scpd_license-server
Creating service scpd_analyzer
Creating service scpd_cdr-collector
Creating service scpd_amd
Creating service scpd_billing-server
Creating service scpd_dircleaner
Creating service scpd_mgw
Creating service scpd_resolver
Creating service scpd_docker-health-exporter
Creating service scpd_redis
Creating service scpd_portal-api
Creating service scpd_portal-frontend
Creating service scpd_smartcpd
Creating service scpd_cloud-connector
Creating service scpd_redis-sentinel
overall progress: 0 out of 1 tasks
1/1: starting  [============================================>      ]

Когда появляется строка overall progress: - выполнение команды можно остановить Ctrl+C. Это нормально и не прервет процесс.

7. Дождаться окончания запуска#

Дождаться запуска сервисов. Старт может занять некоторое время - должны скачаться и развернуться образы, запуститься сервисы, развернуться схемы БД. Контролировать процесс можно командой: docker stack services <stack_name>.

Пример нормального состояния после запуска:

ID             NAME                          MODE         REPLICAS
wg6z9yolitfm   scpd_amd                      global       1/1
wwo18k7m2q0x   scpd_analyzer                 replicated   1/1
m3jne8o06379   scpd_balancer                 global       1/1
r3fdm3a2uz1r   scpd_billing-server           replicated   1/1
0itxyppublbj   scpd_cloud-connector          replicated   1/1
xxyvu2xghrjj   scpd_config-server            replicated   1/1
pov175b12p5f   scpd_dircleaner               global       1/1
b366ca9vdg4u   scpd_docker-health-exporter   global       4/4
78lawwkpkptl   scpd_grafana                  replicated   1/1
x65pfn71ujxr   scpd_license-server           replicated   1/1
m85ys0xwsudk   scpd_log2file                 global       4/4
cgywvqj7y72b   scpd_cdr-collector            replicated   1/1
ecvcmk4zleyd   scpd_metrics                  replicated   1/1
bo7jcqbbsk04   scpd_mgw                      global       1/1
ajc9kuhv7yht   scpd_portal-api               replicated   1/1
60itfaqdjm2p   scpd_portal-frontend          replicated   1/1
obzll0l9kzdu   scpd_redis                    global       1/1
onijinos2cky   scpd_redis-sentinel           replicated   2/3 (max 2 per node)
ijb654n9a251   scpd_resolver                 replicated   1/1
ut26d7hqf0g1   scpd_smartcpd                 global       1/1

Нормальное состояние запуска определяется по столбцу REPLICAS: для включенных сервисов левое значение не должно быть 0, а левое и правое значения должны совпадать.

Исключения:
redis-sentinel может иметь состояние 2/3, если в схеме используется только одна service-нода;
cloud-connector, docker-health-exporter и log2file могут иметь 0/0, если они не были включены в setup.

8. Проверка запуска#

После deployment рекомендуется проверить:

стек появился в Docker Swarm под ожидаемым именем;
обязательные сервисы перешли в рабочее состояние;
портал открывается по настроенному адресу;
авторизация администратора работает;
сервисы не находятся в цикле постоянных рестартов;
у billing-server нет признаков незавершенной миграции, если выполняется обновление с миграцией данных;
labels нод соответствуют целевой схеме размещения.

Для первичной проверки обычно используются:

docker stack services <stack_name>
docker service ps --no-trunc <service_name>
docker service logs <service_name>

Состояние встроенного контура мониторинга и рекомендации по диагностике инфраструктуры описаны в документе Логирование и мониторинг.

9. После запуска#

Залогиниться, используя логин и пароль администратора, указанные при установке.
Открыть раздел tenant Лицензия и загрузить временный лицензионный файл версии 3, если он был предоставлен.
В разделе Лицензия скачать Fingerprint и отправить его аккаунт-менеджеру Altuera для генерации постоянной лицензии.
После получения постоянного лицензионного файла версии 3 загрузить его в том же разделе Лицензия.
Если cloud-connector не используется, открыть раздел уровня платформы Модели и загрузить файлы облачных моделей вручную.

Изменение настроек#

Для изменения runtime-параметров SmartCPD следует использовать ./smartcpd-setup.sh.

Изменение через повторный запуск setup#

Для полного изменения параметров через интерактивный сценарий запустить:

./smartcpd-setup.sh

Скрипт заново пройдет по параметрам setup и сохранит обновленное состояние в smartcpd-setup.env.

Если в ходе такого прохода изменились role-specific настройки нод, следует отказаться от немедленного deployment, выполнить обновленные stack/smartcpd-node-*-setup.sh на нужных нодах и затем отдельно запустить ./smartcpd-setup.sh deploy.

Если интерактивная настройка была прервана, ее можно продолжить:

./smartcpd-setup.sh --continue

Изменение через `smartcpd-setup.env`#

Если требуется точечно изменить runtime-параметры, можно отредактировать smartcpd-setup.env напрямую, затем выполнить:

./smartcpd-setup.sh generate
./smartcpd-setup.sh deploy

В smartcpd-setup.env обязательно должны быть заданы SMARTCPD_DB_TZ и SMARTCPD_TZ с одинаковым непустым значением. При генерации stack timezone БД передаётся сервисам как DB_TZ, а SMARTCPD_TZ управляет timezone контейнеров. Setup проверяет точное совпадение значений при интерактивной настройке, а также перед командами generate и deploy; конфигурация с разными timezone не поддерживается. Поэтому установку и изменение конфигурации необходимо выполнять через smartcpd-setup.sh.

generate безопасен: эта команда только обновляет сгенерированные файлы и сохраняет предыдущее состояние в backup/.
deploy ПЕРЕЗАПУСТИТ все инстансы измененных сервисов. Неизмененные сервисы Docker Swarm затронуты не будут.

Если изменения затрагивают role-specific настройки нод, после generate нужно скопировать и при необходимости повторно выполнить соответствующие stack/smartcpd-node-*-setup.sh на нужных нодах, а затем выполнить deploy.

Изменение ролей нод#

Если существующей ноде нужно добавить новую роль SmartCPD, сначала следует выполнить на ней соответствующие stack/smartcpd-node-*-setup.sh для добавляемых ролей.

После этого нужно запустить:

./smartcpd-setup.sh labels

И назначить ноде новые labels.

После изменения labels Docker Swarm автоматически переразместит сервисы в соответствии с текущей конфигурацией стека. Отдельный deploy для этого сценария не требуется.

Добавление новой ноды#

Перед добавлением новой ноды рекомендуется заново запустить smartcpd-docker-setup.sh на активной service-ноде, которая одновременно является manager-нодой Docker Swarm. Это позволяет заново сгенерировать актуальный docker/smartcpd-docker-node-setup.sh с корректным адресом manager-ноды.

Далее порядок действий такой:

скопировать docker/smartcpd-docker-node-setup.sh на новую ноду и выполнить его там от имени root или через sudo;
скопировать на новую ноду соответствующие stack/smartcpd-node-*-setup.sh для назначаемых ролей и выполнить их;
запустить ./smartcpd-setup.sh labels и назначить новой ноде требуемые labels.

После назначения labels Docker Swarm автоматически подключит новую ноду к текущей схеме размещения сервисов. Отдельный deploy для этого сценария не требуется.

Полный останов и повторный запуск#

Если требуется полностью остановить стек и затем поднять его снова, можно использовать:

./smartcpd-setup.sh down
./smartcpd-setup.sh deploy

Подробности по этим командам описаны ниже в разделе Справка по smartcpd-setup.sh.

Использование `compose.override.yml`#

compose.override.yml нужен для локальных настроек поверх стандартной схемы установки из поставки.

Основная причина использовать именно compose.override.yml состоит в том, что обновления и повторная генерация файлов стека не должны переписывать такие локальные изменения.

compose.override.yml размещается в корне каталога setup/ рядом с smartcpd-setup.sh.

Для миграции с SmartCPD 5.2.x или 5.3.x поставляется готовый файл compose.override.migrate.yml. Порядок его использования и удаления описан в разделе «5.2.12, 5.3.2 -> 6.0.0» документа «Обновление».

Рабочий compose.override.yml:

не генерируется setup-скриптом;
предназначен для локальных настроек поверх основного шаблона из поставки;
учитывается при сборке stack/compose.runtime.yml;
не должен заменять базовые параметры setup, которые уже поддерживаются через smartcpd-setup.sh.

Сгенерированные файлы stack/compose.generated.yml и stack/compose.runtime.yml не следует править вручную. Для нестандартных локальных настроек нужно использовать compose.override.yml.

После изменения compose.override.yml следует выполнить:

./smartcpd-setup.sh generate
./smartcpd-setup.sh deploy

Порядок применения такой:

внести изменения в compose.override.yml;
выполнить ./smartcpd-setup.sh generate;
выполнить ./smartcpd-setup.sh deploy.

При deploy Docker Swarm применит обновленный runtime compose. Сервисы, конфигурация которых изменилась через compose.override.yml, будут перезапущены. Такие изменения следует выполнять в согласованное окно работ, если перезапуск может повлиять на эксплуатацию.

Если compose.override.yml существует, он также попадает в локальные snapshot-бэкапы в каталоге backup/.

Сброс временных переменных окружения#

Простое удаление переменной из compose.override.yml или удаление самого файла не гарантирует сброс ранее применённого значения в существующем Docker Swarm service. Если для переменной в основном smartcpd-stack-template.yml не задано штатное значение, при обновлении service прежнее значение может сохраниться.

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

services:
  billing-server:
    environment:
      BILLING_SYNC: "true"

  portal-api:
    environment:
      SUPERADMIN_RESTORE: "false"

После изменения выполнить:

./smartcpd-setup.sh generate
./smartcpd-setup.sh deploy

Убедиться, что Docker Swarm применил требуемые значения:

docker service inspect <stack_name>_billing-server \
  --format '{{range .Spec.TaskTemplate.ContainerSpec.Env}}{{println .}}{{end}}' \
  | grep '^BILLING_SYNC='

docker service inspect <stack_name>_portal-api \
  --format '{{range .Spec.TaskTemplate.ContainerSpec.Env}}{{println .}}{{end}}' \
  | grep '^SUPERADMIN_RESTORE='

Если переменная должна быть полностью удалена из service spec и штатное значение невозможно задать явно, удалить временный override, заново сформировать конфигурацию и полностью пересоздать stack:

./smartcpd-setup.sh generate
./smartcpd-setup.sh down
./smartcpd-setup.sh deploy

Полное пересоздание stack вызывает остановку всех сервисов и должно выполняться только в согласованное окно работ. После запуска необходимо повторно проверить переменные через docker service inspect.

Настройка дополнительной безопасности NGINX#

Если для portal-frontend требуется дополнительная настройка TLS и NGINX сверх базового сценария setup, это следует оформлять через compose.override.yml.

Пример:

services:
  portal-frontend:
    environment:
      NGINX_SSL_PROTOCOLS: "TLSv1.2 TLSv1.3"
      NGINX_SSL_CIPHERS: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305"
      NGINX_SSL_PREFER_SERVER_CIPHERS: "off"
      NGINX_SSL_ECDH_CURVE: "X25519:prime256v1:secp384r1"
      NGINX_SSL_CONF_COMMAND: ""

Такое переопределение нужно, если инсталляция должна соответствовать дополнительным корпоративным требованиям по TLS, наборам шифров и параметрам NGINX.

Настройка таймаута для `cloud-connector` при использовании proxy#

Если доступ к облаку Altuera идет через прокси и в контуре есть повышенная сетевая задержка, таймаут cloud-connector можно увеличить через compose.override.yml.

Пример:

services:
  cloud-connector:
    environment:
      CLOUD_HTTP_TIMEOUT: "5m"

Такое переопределение нужно, если стандартного таймаута недостаточно при работе через корпоративный прокси, проверку TLS-трафика или медленный внешний канал.

Восстановление `superadmin`#

Для разового восстановления bootstrap-пользователя superadmin используется параметр SUPERADMIN_RESTORE.

Его можно временно включить через compose.override.yml.

Пример:

services:
  portal-api:
    environment:
      SUPERADMIN_RESTORE: "true"
      SUPERADMIN_USERNAME: "superadmin"
      SUPERADMIN_ROLE_NAME: "superadmin"

Такой override включает режим восстановления superadmin при старте portal-api. При этом portal пересоздает bootstrap-роль с id=0 и bootstrap-пользователя с id=0. Email берется из setup-параметра SMARTCPD_SUPERADMIN_EMAIL, а пароль — из секрета, связанного с SMARTCPD_SUPERADMIN_PASSWORD_SECRET.

Если восстановление не выполнилось, это обычно означает конфликт с уже существующими пользователями или ролями. Информация о таком конфликте выводится в логах portal-api.

В этом случае конфликтующие bootstrap-данные можно изменить:

через обычные setup-параметры, если нужно изменить SMARTCPD_SUPERADMIN_EMAIL;
через дополнительные переменные окружения в compose.override.yml, если нужно временно изменить SUPERADMIN_USERNAME и/или SUPERADMIN_ROLE_NAME.

Этот режим следует использовать только как временную операционную меру для восстановления доступа. После восстановления override нужно убрать, затем снова выполнить:

./smartcpd-setup.sh generate
./smartcpd-setup.sh deploy

Системные изменения, выполняемые скриптами#

`smartcpd-setup.sh`#

smartcpd-setup.sh работает в пределах текущей рабочей директории setup/ и не изменяет системные файлы сервера вне нее.

Скрипт:

собирает и сохраняет параметры setup в env-файлы;
генерирует stack-артефакты в stack/;
формирует offline-набор образов в images/;
создает локальные snapshot-бэкапы в backup/;
выполняет deployment и удаление Docker Swarm stack через Docker CLI.

В штатном сценарии smartcpd-setup.sh не требует sudo и должен запускаться от обычного пользователя с доступом к Docker daemon.

`stack/smartcpd-node-*-setup.sh`#

Сгенерированные node setup scripts применяются на нодах соответствующих ролей и подготавливают файловую структуру данных для контейнеров SmartCPD.

Эти скрипты могут:

создавать директории в Local data root;
создавать директории в Shared data root, если он используется в текущей схеме установки;
задавать права владения этими каталогами пользователю контейнеров в соответствии с настроенным uid.

Поскольку такие каталоги обычно размещаются в системных путях, например под /opt, выполнение stack/smartcpd-node-*-setup.sh может требовать root или sudo.

Справка по `smartcpd-setup.sh`#

smartcpd-setup.sh используется для подготовки конфигурации SmartCPD, генерации stack-артефактов и развертывания или обновления стека в Docker Swarm.

Скрипт следует запускать от имени обычного пользователя с доступом к Docker daemon.

Нода, на которой запускается smartcpd-setup.sh, должна соответствовать одному из двух сценариев:

для существующей инсталляции это текущая нода SmartCPD с ролями service и manager;
для новой инсталляции это нода, которая в целевой схеме станет service-нодой SmartCPD и одновременно manager-нодой Docker Swarm.

Скрипт поддерживает следующие варианты запуска:

./smartcpd-setup.sh Запускает основной интерактивный setup flow. Скрипт собирает параметры, сохраняет их в smartcpd-setup.env, генерирует stack-артефакты и предлагает сразу выполнить deployment.
./smartcpd-setup.sh --help Показывает краткую встроенную справку по командам скрипта.
./smartcpd-setup.sh --continue Продолжает интерактивный setup flow из временного состояния, сохраненного в smartcpd-setup.tmp.env, после прерванной настройки.
./smartcpd-setup.sh generate Генерирует файлы стека на основе текущего smartcpd-setup.env и перед генерацией сохраняет снимок предыдущего состояния в backup/. Команда формирует:
- stack/compose.generated.yml;
- stack/compose.runtime.yml;
- stack/smartcpd-node-*-setup.sh.
./smartcpd-setup.sh generate --with-secrets Выполняет ту же генерацию, но при наличии secrets.env предварительно синхронизирует Docker secrets и обновляет ссылки *_SECRET в smartcpd-setup.env.
./smartcpd-setup.sh deploy Разворачивает или обновляет SmartCPD stack в Docker Swarm на основе stack/compose.runtime.yml. Если compose.runtime.yml устарел относительно smartcpd-setup.env, smartcpd-stack-template.yml, versions.env или состояния compose.override.yml, скрипт предложит сначала выполнить generate. Изменением состояния считается также создание или удаление compose.override.yml после последней генерации.
./smartcpd-setup.sh deploy --ci Выполняет deployment в non-interactive режиме. Если compose.runtime.yml устарел, скрипт автоматически соглашается на предварительный generate, а docker stack deploy запускается в detached-режиме.
./smartcpd-setup.sh down Останавливает и удаляет текущий SmartCPD stack из Docker Swarm после явного подтверждения.
./smartcpd-setup.sh images-list Показывает список container images, требуемых для текущего варианта стека.
./smartcpd-setup.sh images-pull Скачивает образы, необходимые для текущего стека, и при необходимости подготавливает их для дальнейшего сохранения в images/.
./smartcpd-setup.sh images-save Скачивает необходимые образы, сохраняет их в images/ и удаляет локально подтянутые копии после сохранения. Это основной режим для offline или air-gapped поставки.
./smartcpd-setup.sh images-load Загружает все image archives из images/ в локальный Docker.
./smartcpd-setup.sh labels Показывает ноды Swarm и позволяет интерактивно управлять role labels SmartCPD. Через эту команду можно назначать или снимать labels ролей:
- service;
- worker;
- analyzer;
- balancer.

CI setup и non-interactive генерация#

Для CI-сценариев и автоматизированной переконфигурации setup может использоваться без интерактивного ввода, если все необходимые параметры уже заданы в smartcpd-setup.env.

Для такого сценария поддерживается следующая схема:

при необходимости подготовить или обновить smartcpd-setup.env;
при необходимости подготовить secrets.env на основе примера secrets.example.env, идущего в setup-поставке;
выполнить ./smartcpd-setup.sh generate --with-secrets;
затем выполнить ./smartcpd-setup.sh deploy --ci.

Поведение generate --with-secrets:

если secrets.env отсутствует, команда работает как обычный generate;
если secrets.env существует, скрипт создает или переиспользует соответствующие Docker secrets, обновляет ссылки *_SECRET в smartcpd-setup.env и затем выполняет обычную генерацию;
неизвестные ключи из secrets.env игнорируются с предупреждением;
перед обновлением smartcpd-setup.env создается локальная резервная копия.

Файл secrets.example.env служит только примером структуры. Его не следует использовать как рабочий файл с реальными значениями секретов.

Env-файлы в корне `setup/`#

В корне каталога setup/ используются следующие env-файлы:

smartcpd-setup.env Основной файл с сохраненными параметрами setup, который используется для повторной генерации файлов стека и последующих запусков setup.
secrets.env Опциональный локальный файл исходных секретов для команды ./smartcpd-setup.sh generate --with-secrets. В поставке вместо него идет только пример secrets.example.env.
smartcpd-setup.tmp.env Временное состояние незавершенного интерактивного setup flow. Используется командой ./smartcpd-setup.sh --continue.
setup.env Исторический файл старого setup, который может использоваться как источник значений для переноса в новую схему setup.

Файлы smartcpd-setup.env и связанные setup-артефакты следует хранить и включать в резервное копирование. Если они потеряны, повторная генерация конфигурации и последующая переконфигурация потребуют повторного ручного ввода параметров setup.

Дополнительно smartcpd-setup.sh создает локальные резервные копии в каталоге backup/ рядом с setup-файлами. Эти резервные копии помогают восстановить предыдущее состояние сгенерированных файлов и параметров setup после регенерации или переконфигурации.

Сгенерированные `smartcpd-node-*-setup.sh`#

smartcpd-setup.sh generate формирует набор node setup scripts в каталоге stack/.

Каждый такой скрипт предназначен для запуска на ноде с соответствующей ролью SmartCPD.

Если на одной ноде совмещено несколько ролей, на ней нужно последовательно выполнить все соответствующие скрипты.

smartcpd-node-global-setup.sh не предназначен для запуска на целевых нодах как скрипт настройки конкретной роли. Он используется для подключения мониторинга остальных нод и связанных global-настроек. Подробности по этому контуру описаны в документе Логирование и мониторинг.

Установка

Требования#

Требования к серверам#

Синхронизация времени#

Worker-ноды#

Требования к Docker#

Доступ к артефактам#

Требования к размещению ролей#

Требования к качеству сети#

Требования к хранилищам#

Состав поставки#

Подготовка PostgreSQL#

Данные, которые нужно собрать до установки#

Процесс установки#

1. Подготовить рабочую директорию setup#

2. Настроить Docker и Docker Swarm#

3. Выполнить настройку SmartCPD#

4. Разметить ноды#

5. Подготовить ноды к запуску#

6. Выполнить запуск#

7. Дождаться окончания запуска#

8. Проверка запуска#

9. После запуска#

Изменение настроек#

Изменение через повторный запуск setup#

Изменение через smartcpd-setup.env#

Изменение ролей нод#

Добавление новой ноды#

Полный останов и повторный запуск#

Использование compose.override.yml#

Сброс временных переменных окружения#

Настройка дополнительной безопасности NGINX#

Настройка таймаута для cloud-connector при использовании proxy#

Восстановление superadmin#

Системные изменения, выполняемые скриптами#

smartcpd-setup.sh#

stack/smartcpd-node-*-setup.sh#

Справка по smartcpd-setup.sh#

CI setup и non-interactive генерация#

Env-файлы в корне setup/#

Сгенерированные smartcpd-node-*-setup.sh#

Изменение через `smartcpd-setup.env`#

Использование `compose.override.yml`#

Настройка таймаута для `cloud-connector` при использовании proxy#

Восстановление `superadmin`#

`smartcpd-setup.sh`#

`stack/smartcpd-node-*-setup.sh`#

Справка по `smartcpd-setup.sh`#

Env-файлы в корне `setup/`#

Сгенерированные `smartcpd-node-*-setup.sh`#