Обновление

Основным источником требований и ограничений для обновления между релизами являются Release Notes.

Этот документ дополняет Release Notes в двух случаях:

  • когда нужно описать типовой повторяемый процесс обновления, который нецелесообразно дублировать в каждом релизе;
  • когда для отдельного релиза требуется более подробная процедура, чем уместно держать в Release Notes.

Таким образом, Release Notes остаются основным источником требований конкретного релиза, а этот документ описывает общий порядок обновления и дополнительные шаги, которые могут расширять соответствующий релизный раздел.

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

  • прямом обновлении с версии 5.2.12 до 6.0.0, 6.0.1 или 6.0.2;
  • обновлении на версию 5.3.0;
  • обновлении между версиями 5.3.0 и выше.

Кроме отдельно описанного перехода с 5.2.12 на 6.0.0, 6.0.1 или 6.0.2, данный документ не подходит для обновлений с целевой версией ниже 5.3.0. Для обновлений вида 5.2.1 -> 5.2.5 следует использовать только соответствующие Release Notes.

Общие правила обновления#

Резервное копирование#

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

  • БД решения;
  • данные контура переносимого состояния сервисов;
  • текущая рабочая директория установки, из которой используется smartcpd-setup.sh.

Резервное копирование БД обязательно, если в Release Notes указано изменение схемы БД.

Под данными контура переносимого состояния сервисов в этом документе понимаются данные, которые в отказоустойчивой схеме обычно размещаются в общем хранилище. В non-HA установках эти же данные могут размещаться локально на соответствующей ноде, поэтому для резервного копирования нужно ориентироваться на фактическое размещение данных в текущем контуре.

Точный состав таких данных в текущей схеме поставки описан в разделе Отказоустойчивое распределенное хранилище данных.

Обновление без остановки сервиса#

Обновление без остановки сервиса допустимо только если одновременно выполняются следующие условия:

  • обязательные настройки Docker не изменялись;
  • миграция данных в БД не выполняется;
  • обновление не затрагивает компоненты balancer, worker, redis и redis-sentinel по версиям или runtime-параметрам.

Такое обновление может вызвать временную деградацию service-слоя. В этот период могут быть затронуты:

  • UI;
  • API;
  • мониторинг и алертинг;
  • возможности управления и изменения настроек решения.

При этом обновление не должно останавливать процесс обзвона и не должно приводить к потере данных.

Во всех остальных случаях рекомендуется заранее снять трафик и выполнять обновление в технологическое окно.

Если Release Notes явно требуют остановки стека, это требование должно соблюдаться независимо от состава затронутых компонентов.

Если обновление выполняется по цепочке промежуточных версий, решение о возможности обновления без остановки сервиса нужно принимать по всей цепочке целиком, а не только по целевой версии.

В этом случае необходимо кумулятивно учитывать:

  • обязательные изменения Docker;
  • миграции данных в БД;
  • все компоненты, затронутые изменениями версий и runtime-параметров на каждом промежуточном шаге.

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

Восстановление предыдущей версии#

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

  1. Остановить SmartCPD:
docker stack rm <stack_name>
  1. Восстановить БД из резервной копии.
  2. Восстановить прежнюю структуру каталогов и данные контура переносимого состояния сервисов из резервной копии.
  3. Восстановить последнюю рабочую директорию установки.
  4. Из восстановленной директории установки выполнить штатную процедуру deployment предыдущей версии.

Порядок обновления#

Выполнить требования Release Notes#

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

В Release Notes должны быть отражены:

  • компоненты, затронутые обновлением;
  • наличие или отсутствие миграции данных в БД;
  • изменение обязательных параметров Docker, если такие изменения есть.

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

В этом случае необходимо последовательно выполнить требования каждого промежуточного обновления. Пропуск неподдерживаемых шагов обновления не допускается.

Подготовить новую директорию поставки#

Рекомендуется выполнять обновление из новой директории поставки, а не поверх предыдущей.

Необходимо:

  • скопировать новую поставку в новую рабочую директорию;
  • перенести в нее smartcpd-setup.env;
  • перенести в нее smartcpd-docker-setup.env;
  • перенести compose.override.yml, если он используется.

Это позволяет сохранить предыдущее состояние поставки и выполнять обновление из чистой директории новой версии.

Обновление настроек БД#

При необходимости перед этим шагом следует выполнить резервное копирование. Перед выполнением этого шага следует определить, допустимо ли обновление без остановки сервиса.

Обычно обновление настроек БД требуется, когда релиз добавляет нового пользователя БД или изменяет права доступа пользователей. Для схемы использования per-service такие изменения обычно явно указываются в Release Notes.

Для обновления настроек БД нужно выполнить SQL-скрипты из новой поставки:

  • db/postgres/sql/01-sa-users.sql — обновляет роли, login/password и administrative memberships;
  • db/postgres/sql/02-dbo-grants.sql — восстанавливает CONNECT, схемы, search_path, default privileges и grants.

db/postgres/sql/00-sa-create-db-once.sql используется только при первичном создании БД.

Подробности по назначению и запуску этих скриптов описаны в документе База данных.

Обновление настроек Docker#

Релиз может включать изменение обязательных параметров Docker.

Если Docker в контуре SmartCPD настраивается вручную, такие изменения должны применяться вручную в соответствии с Release Notes и разделом Ручная настройка Docker daemon.

Если для настройки Docker используется smartcpd-docker-setup.sh, что является рекомендуемым вариантом, нужно запустить его в новой директории поставки на текущей service-ноде SmartCPD, которая одновременно является manager-нодой Docker Swarm.

При запуске скрипт сам определяет, требуется ли обновление настроек Docker относительно предыдущей версии. Это используется для обновления обязательных параметров daemon.json.

Если обновление настроек Docker не требуется, дополнительных действий не нужно.

Если обновление требуется, необходимо:

  1. Выделить технологическое окно, так как применение новых настроек приведет к перезапуску Docker на manager-ноде и остальных нодах.
  2. Остановить контур SmartCPD командой:
./smartcpd-setup.sh down
  1. Выполнить smartcpd-docker-setup.sh на текущей service + manager ноде.
  2. После генерации скрипта docker/smartcpd-docker-node-setup.sh выполнить его на всех остальных нодах кластера.
  3. После завершения обновления Docker перейти к следующему шагу обновления SmartCPD.

Обновление SmartCPD#

При необходимости перед этим шагом следует выполнить резервное копирование. Перед выполнением этого шага следует определить, допустимо ли обновление без остановки сервиса.

Запустить smartcpd-setup.sh в новой директории поставки на текущей service + manager ноде:

./smartcpd-setup.sh

Скрипт использует сохраненные параметры из smartcpd-setup.env.

Если обязательного обновления setup-параметров для текущей версии не требуется, скрипт сообщит об этом и спросит, нужно ли изменять параметры. Если обновление параметров требуется, скрипт сразу перейдет к полному setup flow.

При обновлении SmartCPD рекомендуется выполнить полный проход setup-скрипта и проверить актуальность параметров новой поставки.

Перед подтверждением deployment необходимо:

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

После подготовки нод можно подтверждать deployment.

Дальнейший порядок действий соответствует разделам Процесс установки и Проверка запуска документа Установка.

Обновления отдельных версий#

Обновление 6.0.3#

Этот раздел применяется только при обновлении с версий 6.0.0, 6.0.1 и 6.0.2. При установке с нуля описанные ниже действия не требуются.

Резервное копирование биллинга#

Перед обновлением остановить billing-server. Если резервное копирование всей БД не планируется, DBA должен выполнить резервное копирование следующих биллинг-сущностей:

  • billing_call_facts;
  • billing_tariff_history;
  • billing_tariffs_license;
  • billing_tariffs_cloud;
  • billing_tariffs;
  • billing_tariff_labels;
  • billing_known_tenants;
  • billing_jobs_state;
  • billing_schema_version.

Способ резервного копирования и восстановления определяет DBA. Копия должна обеспечивать восстановление структуры, данных и связанных объектов БД, включая значения последовательностей.

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

  1. Остановить billing-server.

  2. Удалить текущие биллинг-сущности из списка резервного копирования, а также новые и промежуточные сущности, если они существуют:

    • billing_call_facts_legacy;
    • billing_tariff_windows;
    • billing_tariff_window_counters;
    • billing_call_fact_attributes;
    • billing_daily_aggregates.

  3. Удалить оставшиеся биллинг-последовательности. DBA должен восстановить предыдущие биллинг-сущности из резервной копии.

  4. Запустить предыдущую версию billing-server.

5.2.12, 5.3.2 -> 6.0.X#

Переход с SmartCPD 5.x на линейку 6.0 изменяет архитектуру решения, структуру данных, внешние API и ролевую модель. Обновление требует ручных действий и должно выполняться в заранее запланированное технологическое окно. Описанный ниже порядок применяется при прямом обновлении до 6.0.0, 6.0.1 и 6.0.2; для команд с образами используйте версию целевой поставки.

Важно: лицензионный файл, используемый в SmartCPD 5.x, не подходит для SmartCPD версии 6 и выше. До начала обновления необходимо запросить у вендора новую лицензию с поддержкой SmartCPD 6.

Прямое обновление до SmartCPD 6.0.0, 6.0.1 или 6.0.2 поддерживается только с версий 5.2.12 и 5.3.2. Установку более ранней версии необходимо сначала обновить до последнего релиза своей линейки: до 5.2.12 для ветки 5.2.x либо до 5.3.2 для ветки 5.3.x.

При прямом обновлении с ветки 5.2.x необходимо также ознакомиться с разделом «5.2.8+ -> 5.3.0» и выполнить описанные в нём применимые подготовительные действия. Переход на новую структуру каталогов, перенос параметров старого setup flow, перенос расширенных настроек NGINX в compose.override.yml и остальные изменения setup в равной степени относятся к прямой миграции с 5.2.x на 6.0.0, 6.0.1 или 6.0.2.

Перед началом миграции необходимо:

  • создать полную резервную копию БД SmartCPD и проверить возможность её восстановления;
  • запросить у вендора новый лицензионный файл с поддержкой SmartCPD 6. Дата начала действия лицензии должна быть не позднее первого дня календарного месяца, в котором выполняется миграция, а лицензия должна содержать тариф, применимый на эту дату. Для предварительного тестирования можно запросить временную тестовую лицензию и перед вводом обновлённой системы в эксплуатацию заменить её постоянной;
  • обеспечить дополнительное свободное место в PostgreSQL для переноса данных старого биллинга в новый контур: CDR, статистики, результатов расчета и тарифов:
    • при переносе всей накопленной истории учитывать суммарный текущий размер таблиц cdr, stats, billing и tariff, включая их партиции и индексы. Во время миграции старые и новые объекты существуют одновременно; при расчёте свободного места необходимо учитывать новые таблицы и индексы, временные данные и WAL PostgreSQL;
    • если давняя история не нужна в новом CDR-контуре, глубину миграции можно ограничить параметром PARTITIONS_HISTORY_MONTHS, передав его при запуске мигратора. В целевую схему будут перенесены текущий календарный месяц и указанное число предыдущих месяцев. Текущий месяц переносится в любом случае;
    • при ограниченной глубине дополнительное место для новых CDR, stats и разметки оценивается только по выбранному диапазону. Исходные legacy-таблицы сохраняются до отдельной очистки;
    • после успешного завершения миграции и проверки перенесенных данных старые объекты можно удалить в соответствии с описанной ниже процедурой;
  • если используются внешние API SmartCPD, изучить документ «External API» и подготовить интеграции к переходу на новые API. Прежние контракты и способы авторизации не должны использоваться после обновления;
  • после обновления проверить все пользовательские роли и скорректировать назначенные им привилегии в соответствии с документом «Ролевая модель и управление доступом». Ролевая модель в версии 6.0.0 изменилась, поэтому существующий набор прав может не обеспечивать ожидаемый доступ к разделам и действиям интерфейса;
  • при использовании модели с отдельным логином БД для каждого сервиса подготовить пользователя cdr для cdr-collector;
  • учесть, что setup-скрипт SmartCPD 6.0.0 использует единый корневой каталог переносимых данных сервисов вместо отдельных путей для каждого компонента. Перед запуском setup-скрипта необходимо собрать существующие каталоги переносимых данных под одним общим корнем либо убедиться, что они уже расположены таким образом, и указать этот корневой каталог в параметрах установки. Содержимое каталогов не следует объединять в один плоский каталог: необходимо сохранить подкаталоги соответствующих сервисов. Это требуется, чтобы сервисы новой версии нашли существующие файлы;
  • выделить дополнительную ёмкость в корневом каталоге переносимых данных для хранения записей детекций в каталоге detections_data: минимум 40 GB на каждую worker-ноду установки. Например, для четырёх worker-нод требуется не менее 160 GB. В HA-схеме это должно быть переносимое общее хранилище, доступное по одинаковому пути на всех service-нодах. Требования к размещению описаны в разделе «Хранилища данных»;
  • проверить текущую схему развертывания и привести её в соответствие с архитектурой SmartCPD 6.0.0, описанной в документе «Архитектура».

Порядок обновления:

  1. Если серверы установки не имеют доступа к registry или образы не могут быть загружены во время deployment, заранее загрузить на все ноды Docker-образы целевой версии SmartCPD. Для offline-сценария можно использовать команды ./smartcpd-setup.sh images-save и ./smartcpd-setup.sh images-load, описанные в справке по setup-скрипту.

  2. Для установки версии 5.3.x остановить текущий стек SmartCPD через setup-скрипт действующей установки:

./smartcpd-setup.sh down

Для установки версии 5.2.x удалить текущий stack напрямую:

docker stack rm <stack_name>

Перед продолжением убедиться, что сервисы удалённого стека остановлены.

  1. Если используется модели с отдельными логинами БД для каждого сервиса - выполнить обновление настроек БД с обязательным созданием пользователя cdr для cdr-collector.

  2. Если Docker daemon и Docker Swarm управляются через поставляемый скрипт - выполнить обновление настроек Docker.

  3. Скопировать файл состояния setup из каталога действующей установки в корень целевого каталога setup, сохранив исходное имя файла:

    • при миграции с версии 5.2.x скопировать setup.env;
    • при миграции с версии 5.3.x скопировать smartcpd-setup.env.

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

  4. До запуска основного setup flow включить временные параметры миграции. В поставке уже находится готовый файл compose.override.migrate.yml; если локальный compose.override.yml ещё не используется, переименовать шаблон:

mv compose.override.migrate.yml compose.override.yml

Если compose.override.yml уже содержит постоянные локальные настройки либо готового шаблона нет, создать или дополнить файл вручную:

services:
  # Временное отключение синхронизации billing-server на время миграции
  billing-server:
    environment:
      BILLING_SYNC: "false"

  # Создание нового суперадминистратора при миграции
  portal-api:
    environment:
      SUPERADMIN_RESTORE: "true"

Рабочий compose.override.yml необходимо подготовить до генерации stack-артефактов, чтобы временные параметры вошли в первую и единственную конфигурацию начального deployment:

  • BILLING_SYNC=false не позволяет новому billing-server загружать и рассчитывать вызовы до полного завершения миграции CDR и проверки нового тарифа. После включения синхронизации billing-server пересчитает данные с начала текущего календарного месяца по новой лицензии; данные за предыдущие месяцы останутся доступны в архиве и повторно пересчитаны не будут;
  • SUPERADMIN_RESTORE=true обеспечивает создание отдельного системного суперадминистратора и его роли при первом запуске portal-api. Параметр нужно сохранять до успешной проверки входа под новой учётной записью, чтобы её создание повторялось при возможных рестартах portal-api во время первоначального запуска.
  1. Запустить основной setup flow SmartCPD:
./smartcpd-setup.sh

При миграции с версии 5.3.x сохранённая в перенесённом smartcpd-setup.env версия ниже минимальной версии setup-state для линейки 6.0. Поэтому скрипт автоматически запустит полный интерактивный setup. Необходимо последовательно пройти его и проверить параметры новой установки.

Проверить и при необходимости обновить параметры установки. При прохождении setup указать email и пароль нового суперадминистратора. Целевая версия SmartCPD создаст отдельную системную учётную запись и отдельную роль с полным набором привилегий; существующий административный пользователь предыдущей версии не преобразуется и не обновляется.

Setup сформирует stack-артефакты с учётом временного compose.override.yml. После генерации отказаться от предложенного deployment.

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

Deployment SmartCPD на этом шаге не выполнять: сначала необходимо запустить миграцию CDR и stats и дождаться готовности нового CDR-контура принимать вызовы.

Миграция CDR и stats#

Миграция последовательно копирует данные legacy-таблиц cdr и stats в единую таблицу CDR новой версии. Исходные таблицы при этом сохраняются. В зависимости от объёма накопленных данных и производительности PostgreSQL операция может выполняться длительное время.

В тестовых условиях на рекомендованном сайзинге БД миграция примерно 200 млн записей CDR заняла 4 часа. Пиковый объём БД во время миграции увеличился примерно на 72% относительно исходного, то есть составил около 1,72 исходного объёма. Это ориентиры по результатам тестирования, а не гарантированные сроки или верхняя граница роста: фактические значения зависят от состава данных, глубины миграции, производительности хранилища и текущей нагрузки. При планировании необходимо предусмотреть запас времени и свободного места.

На service-ноде выполнить полную миграцию legacy CDR, stats и разметки. Выберите целевую версию SmartCPD и используйте соответствующий образ мигратора:

docker run --rm --no-healthcheck \
  -e 'DB_URI=postgres://<db_host>:<db_port>/<db_name>?sslmode=disable' \
  -e DB_TZ=<database_timezone> \
  -e PARTITIONS_HISTORY_MONTHS=<history_months> \
  -e MIGRATOR_DB_BILLING_USER=<billing_user> \
  -e MIGRATOR_DB_BILLING_PASSWORD=<billing_password> \
  -e MIGRATOR_DB_MARKUP_USER=<markup_user> \
  -e MIGRATOR_DB_MARKUP_PASSWORD=<markup_password> \
  -e MIGRATOR_DB_CDR_USER=<cdr_user> \
  -e MIGRATOR_DB_CDR_PASSWORD=<cdr_password> \
  cr.repo.altuera.ru/smartcpd/prod/cdr-collector:6.0.2 \
  /app/cdr-collector-migrator full \
    --migrator-cdr-batch-size=100000 \
    --migrator-markup-batch-size=1000 \
    --with-stats \
    --recreate
docker run --rm --no-healthcheck \
  -e 'DB_URI=postgres://<db_host>:<db_port>/<db_name>?sslmode=disable' \
  -e DB_TZ=<database_timezone> \
  -e PARTITIONS_HISTORY_MONTHS=<history_months> \
  -e MIGRATOR_DB_BILLING_USER=<billing_user> \
  -e MIGRATOR_DB_BILLING_PASSWORD=<billing_password> \
  -e MIGRATOR_DB_MARKUP_USER=<markup_user> \
  -e MIGRATOR_DB_MARKUP_PASSWORD=<markup_password> \
  -e MIGRATOR_DB_CDR_USER=<cdr_user> \
  -e MIGRATOR_DB_CDR_PASSWORD=<cdr_password> \
  cr.repo.altuera.ru/smartcpd/prod/cdr-collector:6.0.1 \
  /app/cdr-collector-migrator full \
    --migrator-cdr-batch-size=100000 \
    --migrator-markup-batch-size=1000 \
    --with-stats \
    --recreate
docker run --rm --no-healthcheck \
  -e 'DB_URI=postgres://<db_host>:<db_port>/<db_name>?sslmode=disable' \
  -e DB_TZ=<database_timezone> \
  -e PARTITIONS_HISTORY_MONTHS=<history_months> \
  -e MIGRATOR_DB_BILLING_USER=<billing_user> \
  -e MIGRATOR_DB_BILLING_PASSWORD=<billing_password> \
  -e MIGRATOR_DB_MARKUP_USER=<markup_user> \
  -e MIGRATOR_DB_MARKUP_PASSWORD=<markup_password> \
  -e MIGRATOR_DB_CDR_USER=<cdr_user> \
  -e MIGRATOR_DB_CDR_PASSWORD=<cdr_password> \
  cr.repo.altuera.ru/smartcpd/prod/cdr-collector:6.0.0 \
  /app/cdr-collector-migrator full \
    --migrator-cdr-batch-size=100000 \
    --migrator-markup-batch-size=1000 \
    --with-stats \
    --recreate

Параметры команды:

  • DB_URI — строка подключения к БД SmartCPD без логина и пароля;
  • DB_TZ — обязательная IANA timezone, в которой были записаны исторические legacy timestamps без информации о часовом поясе, например Europe/Moscow. Она не обязана совпадать с TZ контейнера мигратора: DB_TZ определяет интерпретацию переносимых данных, а TZ — локальное время выполнения контейнера;
  • PARTITIONS_HISTORY_MONTHS — глубина миграции: число предыдущих календарных месяцев, переносимых вместе с текущим месяцем. Минимальное значение — 1; если строку удалить из команды, используется значение по умолчанию 6, что допустимо только при таком же значении SMARTCPD_CDR_RETENTION_MONTHS в setup;
  • MIGRATOR_DB_BILLING_*, MIGRATOR_DB_MARKUP_* и MIGRATOR_DB_CDR_* — логины и пароли пользователей исходных billing/markup-объектов и целевого контура cdr-collector. При использовании одного пользователя БД указать одинаковые логин и пароль во всех трёх парах параметров;
  • --migrator-cdr-batch-size=100000 — переносить CDR и stats пакетами до 100 000 строк;
  • --migrator-markup-batch-size=1000 — переносить разметку пакетами до 1 000 строк;

Текущий календарный месяц мигрируется всегда. Например, PARTITIONS_HISTORY_MONTHS=3 означает перенос текущего и трёх предыдущих календарных месяцев. Для переноса всей доступной истории указать значение, охватывающее период от самой ранней нужной записи. Обязательное требование: значение PARTITIONS_HISTORY_MONTHS при запуске мигратора должно совпадать с количеством месяцев хранения CDR, заданным при setup в SMARTCPD_CDR_RETENTION_MONTHS.

Параметр --days <N> может дополнительно сузить диапазон до последних N дней. Если необходимо перенести текущий месяц целиком, этот параметр не следует указывать:

/app/cdr-collector-migrator full \
  --migrator-cdr-batch-size=100000 \
  --migrator-markup-batch-size=1000 \
  --with-stats \
  --recreate \
  --days <N>

Размеры пакетов влияют на скорость миграции и нагрузку на PostgreSQL. Значения 100000 для CDR/stats и 1000 для markup являются рекомендуемыми начальными параметрами. Фактическая скорость зависит от характеристик БД, объёма и распределения данных, состояния индексов и текущей нагрузки.

Для мощной БД размер пакета CDR/stats можно увеличить до 200000. Для менее производительной БД его можно уменьшать. Размер пакета markup увеличивать выше 1000 не рекомендуется; при высокой нагрузке или недостаточной производительности БД его можно уменьшать.

При большом объёме данных рекомендуется предварительно проверить скорость миграции на отдельной копии БД и подобрать размер пакета CDR/stats в диапазоне до 200000, а размер пакета markup — только в сторону уменьшения от 1000.

Мигратор не изменяет исходные таблицы cdr, stats и markup, поэтому проверочный запуск можно повторять. Параметр --recreate перед каждым запуском полностью удаляет и заново создаёт целевые объекты нового контура cdr-collector. Повторный запуск допустим только до начала эксплуатации целевой версии SmartCPD и поступления новых CDR или разметки в целевой контур; иначе новые данные будут удалены.

Во время миграции в логе появляется сообщение:

READY TO ACCEPT NEW CALLS

Важно: сообщение READY TO ACCEPT NEW CALLS означает готовность нового CDR-контура принимать записи новых вызовов, но не означает завершение миграции исторических данных. Если после появления сообщения продолжается deployment и возвращается обработка вызовов, мигратор необходимо оставить работающим до его полного успешного завершения. Контур загрузки разметки, включая внешние интеграции и cdr-collector-markup-uploader, до этого момента запускать нельзя.

Это сообщение означает, что целевая структура CDR подготовлена, а последовательности идентификаторов и ingest sequence настроены так, чтобы новые записи не пересекались с переносимыми legacy-данными. После появления сообщения доступны два варианта:

  1. Дождаться полного завершения мигратора и только затем продолжить обновление. Это рекомендуемый вариант, если допустимо технологическое окно требуемой длительности.
  2. Не останавливая мигратор, продолжить deployment целевой версии SmartCPD и вернуть обработку вызовов. Новые вызовы будут записываться в новый CDR-контур одновременно с переносом исторических данных.

Во втором варианте до полного завершения миграции возможна временная деградация:

  • поиск и формирование отчётов могут выполняться медленнее из-за дополнительной нагрузки на PostgreSQL и отсутствия части финальных индексов;
  • исторические результаты будут неполными, пока соответствующие legacy-записи ещё не перенесены;
  • обращения к CDR-таблицам могут создавать повышенную нагрузку на БД.

Обработка новых вызовов при этом может выполняться в штатном режиме. До завершения миграции разметка может обратиться к ещё не перенесённым CDR-записям, поэтому соответствующий контур должен оставаться остановленным.

Запуск SmartCPD 6.0.0, 6.0.1 или 6.0.2#

Запустить целевую версию SmartCPD можно после появления в логе мигратора сообщения READY TO ACCEPT NEW CALLS либо после полного завершения миграции CDR:

./smartcpd-setup.sh deploy

Проверить состояние сервисов в соответствии с разделом «Проверка запуска». Войти в портал под новой учётной записью суперадминистратора и убедиться, что пользователю назначена созданная суперадминистративная роль с полным набором привилегий. До успешной проверки входа параметр SUPERADMIN_RESTORE=true удалять нельзя.

Если новый суперадминистратор не был создан, проверить логи portal-api. Типичная причина — конфликт с существующими email, именем пользователя superadmin или именем роли superadmin. Порядок изменения конфликтующих параметров описан в разделе «Восстановление superadmin» документа «Установка».

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

Действия после запуска#

Если во время запуска SmartCPD миграция CDR ещё выполнялась, оставить временный compose.override.yml на месте и дождаться её полного успешного завершения.

Перед включением синхронизации billing-server:

  1. Войти в портал под созданной учётной записью суперадминистратора.
  2. Открыть раздел tenant Лицензия и загрузить новый лицензионный файл версии 3, подготовленный для SmartCPD 6.
  3. Открыть раздел Биллинг и убедиться, что загруженная лицензия содержит применимый тариф для текущего tenant и этот тариф доступен в интерфейсе.

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

  • вход под новым суперадминистратором успешно проверен;
  • миграция CDR полностью и успешно завершена;
  • лицензия версии 3 загружена, а применимый тариф проверен в интерфейсе.

После выполнения этих условий удалить временные настройки миграции:

  • если compose.override.yml был создан только для обновления, удалить файл;
  • если compose.override.yml уже использовался для постоянных локальных настроек, удалить из него только временно добавленные параметры BILLING_SYNC и SUPERADMIN_RESTORE.

После удаления временных параметров повторно применить stack-конфигурацию:

./smartcpd-setup.sh deploy

Setup обнаружит изменение состояния compose.override.yml и предложит заново сформировать runtime compose. Подтвердить регенерацию ответом по умолчанию yes; отдельный запуск команды generate не требуется.

Это безопасно выполнять на работающем stack: изменение временных параметров затрагивает только сервисы billing-server и portal-api. Будут перезапущены только эти два сервиса; сервисы обработки вызовов затронуты не будут, и текущие вызовы продолжат обрабатываться.

После deployment обязательно:

  • убедиться по логам billing-server, что инициализация и синхронизация CDR начались;
  • убедиться, что архив старого биллинга доступен в интерфейсе и содержит данные за предыдущие периоды;
  • пересмотреть существующие пользовательские роли и перенастроить их в соответствии с новой политикой, описанной в документе «Ролевая модель и управление доступом».
Опциональная очистка старых данных#

Объекты предыдущей версии можно удалять только после успешного завершения миграции, проверки полноты новых CDR-данных и разметки и подтверждения работоспособности целевой версии SmartCPD. До этого момента они необходимы для проверки результата и возможного отката.

Для опционального удаления исходных объектов старого billing-server включить prune непосредственно для legacy-сервиса:

docker service update \
  --env-add BILLING_LEGACY_PRUNE=true \
  <stack_name>_billing-server-legacy

Команда обновляет и перезапускает только старый billing-сервис, не выполняя повторный deployment всего stack. Значение <stack_name> заменить на имя stack текущей установки. Проверить завершение обновления и результат очистки по состоянию сервиса и его логам:

docker service ps <stack_name>_billing-server-legacy
docker service logs --tail 100 <stack_name>_billing-server-legacy

Флаг удаляет исходные таблицы старого биллинга, включая legacy-таблицы cdr и stats, только после проверки созданных архивных таблиц. Операция необратима без восстановления БД из резервной копии. Отдельно возвращать флаг в false не требуется: при следующем штатном deployment stack получит значение по умолчанию false.

Отдельно после проверки можно удалить legacy-объекты старого markup-api:

  • таблицу markup вместе с месячными партициями markup_YYYY_MM и индексами idx_markup_YYYY_MM_unique;
  • таблицы markup_dict_result и markup_dict_call_id_type;
  • функции markup_part_create(integer, integer) и markup_part_prune(text, timestamp, integer, boolean);
  • пользователя БД markup, если он больше не используется другими объектами или внешними интеграциями.

5.2.8+ -> 5.3.0#

Для обновления с версии 5.2.8+ до 5.3.0 требуется переход на новый setup flow.

Порядок действий:

  1. Остановить стек SmartCPD:
docker stack rm smartcpd

  1. Выполнить полное резервное копирование в соответствии с разделом Резервное копирование.

  2. Выполнить резервное копирование текущей схемы каталогов и их данных на всех нодах.

  3. На всех нодах привести структуру каталогов к новой схеме:

  • Local data root [/opt/scpd];
  • Shared data root [/opt/shared_data].

В текущем setup flow используются только эти два корневых пути. В non-HA установке допускается указать один и тот же локальный путь и для Local data root, и для Shared data root.

Размещение обязательных каталогов по ролям:

  • service:
    • ${LOCAL_DATA_ROOT}/redis_data
    • ${SHARED_DATA_ROOT}/config-server_data
    • ${SHARED_DATA_ROOT}/metrics_data
  • worker:
    • ${LOCAL_DATA_ROOT}/node_records
    • ${LOCAL_DATA_ROOT}/node_results
    • ${LOCAL_DATA_ROOT}/node_prompts
  • analyzer и balancer:
    • для этих ролей в текущей схеме установки отдельные обязательные каталоги не используются.

Role-specific node-setup scripts сами создают и проверяют нужные подкаталоги с корректными правами доступа. На этапе подготовки к обновлению нужно привести существующие данные к новой схеме корневых путей и убедиться, что целевые root-каталоги доступны на нужных нодах.

  1. Скопировать новую поставку в новую рабочую директорию.
  2. Скопировать файл setup.env из текущего deployment в новую директорию поставки.

При необходимости можно дополнительно выполнить smartcpd-docker-setup.sh, если требуется перевести контур на managed-схему настройки Docker.

При таком переходе следует учитывать, что параметры mTLS для Docker daemon должны задаваться через systemd override, а не через daemon.json, если они уже использовались в предыдущем контуре. Подробности описаны в документе Docker.

  1. Запустить:
./smartcpd-setup.sh

Скрипт подхватит старый setup.env, выполнит миграцию параметров в новый формат и покажет перенесенные значения перед продолжением setup.

В новом setup вместо отдельных путей к данным задаются только Local data root и Shared data root.

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

Расширенные настройки NGINX больше не задаются через интерактивный setup и должны оформляться через compose.override.yml. То же относится к настройке таймаута cloud-connector при работе через proxy. Подробности описаны в разделах Использование compose.override.yml, Настройка дополнительной безопасности NGINX и Настройка таймаута для cloud-connector при использовании proxy документа Установка.

  1. Перед немедленным применением стека отказаться от deployment.
  2. Выполнить:
./smartcpd-setup.sh labels

И проверить назначение labels на нодах.

  1. Скопировать stack/smartcpd-node-*-setup.sh на серверы с соответствующими ролями и выполнить их, включая текущий сервер, если ему назначены соответствующие роли.
  2. После этого выполнить:
./smartcpd-setup.sh deploy

В остальном этот переход соответствует разделам Процесс установки и Проверка запуска документа Установка. Специфика сценария 5.2.8+ -> 5.3.0 состоит в необходимости перенести старый setup.env в новую поставку и пройти миграцию параметров на новый setup flow.

Дата формирования

Backward Настройка Docker и Docker Swarm Мониторинг Forward
Powered by Altuera