Геозоны

Использование геозон доступно с версии IVA CS 1.8

Географический вынос позволяет выделить отдельный домен IVA CS в отдельную географическую зону с синхронизацией данных через gRPC.

Это решение предназначено для распределенной установки IVA CS. Разделение на географические зоны (геозоны) доступно как при первоначальной установке сервера телефонии IVA CS, так и на ранее развернутом сервере.

Геозона — автономный сервер телефонии IVA CS, который синхронизируется с родительским и получает от него настройки.

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

Требования для организации геозон:

доступ к серверам (исходному и целевому) с правами Администратора

Целевой сервер — сервер с установленным IVA CS, предназначенный для геовыноса
Исходный сервер — кластер IVA CS с тремя хостами

IVA CS должен быть установлен на обоих серверах: на целевом и исходном

Особенности установки целевого сервера, предназначенного для геовыноса:

не создавать базу данных
не запускать сервисы

версии IVA CS должны совпадать на исходном и целевом серверах
версии миграций баз данных на серверах должны совпадать

на жестком диске достаточно свободного места для резервной копии базы данных IVA CS

Чтобы проверить наличие свободного места на жестком диске, Администратору IVA CS необходимо в консоли базы данных выполнить запрос SELECT pg_size_pretty(pg_database_size('ivasw'));

Скрипты для установки геозон поставляются в составе дистрибутива сервера телефонии IVA CS и располагаются в папке, в которой распаковывался дистрибутив IVA CS, по адресу ivacs-A.B.C-YYYY-MM-DD-<TYPE_INSTALL>/script/geo_zone.

где

A.B.C — номер версии IVA CS (например, 1.8.0)
YYYY-MM-DD — дата сборки дистрибутива в формате год-месяц-день (например, 2025-12-04)
<TYPE_INSTALL> — тип дистрибутива (single, single-full, multi, multi-full)

Подготовка исходного сервера

Настройка gRPC-сервера для синхронизации

Настройки необходимо производить на каждом хосте кластера

Существуют следующие способы настройки gRPC-сервера для синхронизации:

автоматическая настройка через скрипт

На каждом хосте кластера запустить скрипт для настройки gRPC-сервера:
```
./geo_zone_update_yaml_server.sh
```
ручное редактирование файла конфигурации

На каждом хосте кластера любым доступным редактором открыть файл /etc/ivasw/logic.yaml и внести следующие изменения:
```
SWL:
  SYNC:
    GRPC_SERVER_HOSTPORT: 50051
    GRPC_SERVER_HOSTHOST: 0.0.0.0
    GRPC_SERVER_ENABLED: true
  GEO_ZONE_ENABLED: true
```
При необходимости, Администратор IVA CS может изменять параметры установленные в файле /etc/ivasw/logic.yaml

Остановка сервисов IVA CS

Необходимо остановить сервисы IVA CS на всех хостах кластера.

На главном хосте кластера IVA CS необходимо выполнить команду:

ivacs-ctl stop all

Создание отдельной зоны для домена

Создание отдельной зоны для домена проводится с главного хоста кластера.

Для выделения домена в отдельную зону необходимо выполнить скрипт geo_zone_create_for_domain.sh одним из следующих способов:

# По имени домена (автоматическая генерация имени зоны, создается имя вида "zone_for_<DOMAIN_NAME>")
./geo_zone_create_for_domain.sh --domain-name <DOMAIN_NAME>

# С указанием имени зоны
./geo_zone_create_for_domain.sh --domain-name <DOMAIN_NAME> -z <ZONE_NAME>

# С описанием зоны
./geo_zone_create_for_domain.sh --domain-name <DOMAIN_NAME> --zone-desc <ABOUT_ZONE>

# По ID домена
./geo_zone_create_for_domain.sh --domain-id <DOMAIN_ID>

Использовать скрипт с упоминанием ID домена рекомендуется только в случае крайней необходимости и только Администраторам IVA CS, умеющим работать с базой данных

где:

<DOMAIN_NAME> — имя домена, например, `ivasw`
<ZONE_NAME> — имя зоны, например, `moscow_zone`
<ABOUT_ZONE> — описание зоны, например, `Геовынос для московского филиала`
<DOMAIN_ID> — идентификатор (ID) домена, например, `cfc3c428-0ff4-40ee-b9c0-a6b52867d630` (параметр domain_id из таблицы domain базы данных IVA CS)

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

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

Создание фильтрованного дампа базы данных

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

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

# Создание дампа с настройками по умолчанию
./geo_zone_dump_create.sh

# Создание дампа с устанавливаемыми параметрами подключения
DB_HOST=<DB_HOST> DB_USER=<DB_USER> SOURCE_DB=<SOURCE_DB> ./geo_zone_dump_create.sh

где:

<DB_HOST> — IP-адрес или доменное имя сервера СУБД, например, 192.168.1.100
<DB_USER> — имя пользователя для подключения к базе данных, например, myuser
<SOURCE_DB> — название базы данных, из которой делается дамп, например, production_db

Описание скрипта:

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

Копирование дампа на целевой сервер

На целевом и исходном серверах должны быть одинаковые настройки, поэтому все настройки домена исходного сервера необходимо скопировать на целевой сервер.
С исходного сервера на целевой переносится вся техническая информация, за исключением информации о звонках, различных временных записей и файлов (информация об используемых файлах переносится в базу данных, но сами файлы необходимо переносить отдельно).

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

# Определение имени созданного дампа
LATEST_DUMP=$(ls -t ivasw_filtered_*.sql | head -1)

# Копирование на целевой сервер
scp "${LATEST_DUMP}" <USER>@<TARGET_SERVER>:<PATH_TO_DUMPS>

или

scp <IVA_CS_DUMP> <USER>@<TARGET_SERVER>:<PATH_TO_DUMPS>

где:

<IVA_CS_DUMP> — имя файла дампа
<USER> — имя пользователя на целевом сервере
<TARGET_SERVER> — адрес целевого сервера (IP, домен или hostname)
<PATH_TO_DUMPS> — путь на целевом сервере, куда будет скопирован файл дампа, например, /path/to/dumps/

Настройка целевого сервера

Установка IVA CS

Установка сервера телефонии IVA CS проводится стандартным способом.

Особенности установки целевого сервера, предназначенного для геовыноса:

не создавать базу данных
не запускать сервисы

Применение дампа базы данных

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

# Переход в директорию с дампом
cd /path/to/dumps/

# Применение последнего дампа (для запуска по умолчанию скрипт должен лежать в одной директории с дампом)
# Если в каталоге несколько файлов дампов, будет использован последний
./geo_zone_dump_apply.sh

# Применение конкретного файла дампа
./geo_zone_dump_apply.sh <DUMP_NAME>

где <DUMP_NAME> — имя конкретного файла дампа, например, ivasw_filtered_20231215_143022.sql

Существующая база данных целевого сервера будет удалена

Настройка геозоны и gRPC-клиента

Настройки необходимо производить на каждом хосте кластера

Для настройки геозоны и gRPC-клиента существуют следующие способы:

автоматическая настройка через скрипт

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

# Базовое использование (обязательные параметры)
./geo_zone_update_yaml_client.sh -z zone_for_<DOMAIN_NAME> -s <GENERAL_HOST>

# С указанием порта
./geo_zone_update_yaml_client.sh -z zone_for_<DOMAIN_NAME> -s <GENERAL_HOST> -p 50052

# Показать справку
./geo_zone_update_yaml_client.sh -h

где

<DOMAIN_NAME> — имя домена, например, `ivasw`
<GENERAL_HOST> — IP-адрес главного хоста кластера, например, 192.168.1.100

ручное редактирование файла конфигурации

Открыть файл /etc/ivasw/logic.yaml и внести следующие изменения:
```
SWL:
  GEO_ZONE_ENABLED: true
  GEO_ZONE_ID: <GEO_ZONE_ID>
  SYNC:
    GRPC_CLIENT_ENABLED: true
    GRPC_CLIENT_SERVER_HOST: <GRPC_CLIENT_SERVER_HOST>
    GRPC_CLIENT_SERVER_PORT: <GRPC_CLIENT_SERVER_PORT>
```
где:
- <GEO_ZONE_ID> — ID геозоны (обязательный параметр, в формате zone_for_<DOMAIN_NAME>)
- <GRPC_CLIENT_SERVER_HOST> — адрес исходного gRPC-сервера (обязательный параметр, в формате <GENERAL_HOST>, например, 192.168.1.100)
- <GRPC_CLIENT_SERVER_PORT> — порт gRPC-сервера (опциональный параметр, по умолчанию 50051)

Запуск сервисов IVA CS

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

ivacs-ctl start all

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

проверка статуса сервисов на целевом сервере
```
ivacs-ctl status all
```

проверка синхронизации

# Проверка лога синхронизации
journalctl -u swl-sync -f

# Проверка подключения к gRPC-серверу
netstat -tulpn | grep 50051

Синхронизация данных CDR

Для синхронизации данных CDR между исходным и целевым серверами используются два скрипта: cdr_sync_export.sh и cdr_sync_import.sh.

Данный набор скриптов предназначен для извлечения записей из таблицы базы данных cdr на целевом сервере и их переноса на исходный сервер с автоматическим разрешением конфликтов (UPSERT).

Описание скриптов

cdr_sync_export.sh

Скрипт для экспорта данных.
- свойства скрипта:
  - подключается к исходной базе данных
  - динамически определяет актуальный список колонок таблицы базы данных cdr
  - генерирует SQL-файл с командами INSERT … ON CONFLICT (id) DO UPDATE, что позволяет обновлять существующие записи, если запись с таким id уже присутствует в целевой базе
  - пропускает генерируемые колонки (например, duration) в блоке обновления
  - поддерживает инкрементальный экспорт (экспортируются только изменения с момента последней выгрузки, а не все данные полностью) по полю updated с использованием временных таблиц для обеспечения целостности данных
- использование скрипта:
  chmod +x cdr_sync_export.sh ./cdr_sync_export.sh [OPTIONS]
- опции скрипта:
  - --since DATE: экспортировать записи, измененные, начиная с указанной даты (фильтрация по полю updated). Формат: 'YYYY-MM-DD' или 'YYYY-MM-DD HH:MM:SS'
  - --compress: сжать выходной файл с помощью gzip. Рекомендуется для больших объемов данных (несколько тысяч записей и более) для экономии места и ускорения передачи файла
  - --help: показать справку
- примеры применения скрипта:
  - экспорт всех данных с компрессией
    
    ./cdr_sync_export.sh --compress
  - экспорт данных, измененных с определенной даты
    
    ./cdr_sync_export.sh --since "2024-01-01"
- переменные окружения:
  - DB_HOST: по умолчанию 127.0.0.1
  - DB_PORT: по умолчанию 5432
  - DB_USER: по умолчанию postgres
  - DB_PASSWORD: по умолчанию ivasw
  - SOURCE_DB: по умолчанию ivasw
cdr_sync_import.sh

Скрипт для импорта данных.
- свойства скрипта:
  - принимает путь к SQL-файлу, который был создан при экспорте данных
  - выполняет SQL-команды в целевой базе данных
- использование скрипта:
  - для обычных файлов:
    
    chmod +x cdr_sync_import.sh ./cdr_sync_import.sh cdr_export_YYYYMMDD_HHMMSS.sql
  - для сжатых файлов:
    
    ./cdr_sync_import.sh cdr_export_YYYYMMDD_HHMMSS.sql.gz
- переменные окружения:
  - DB_HOST: по умолчанию 127.0.0.1
  - DB_PORT: по умолчанию 5432
  - DB_USER: по умолчанию postgres
  - DB_PASSWORD: по умолчанию ivasw
  - TARGET_DB: по умолчанию ivasw

Пример процесса синхронизации

выполнить экспорт данных на целевом сервере:
```
./cdr_sync_export.sh
```
перенести созданный файл cdr_export_*.sql на исходный сервер
выполнить импорт данных на исходном сервере:
```
./cdr_sync_import.sh cdr_export_*.sql
```

Особенности синхронизации CDR

Особенности, возникающие в процессе синхронизации CDR между серверами:

в качестве ключа для разрешения конфликтов используется колонка id (UUID)
при конфликте обновляются все поля записи значениями из файла экспорта
скрипты автоматически определяют список колонок, что делает их устойчивыми к изменениям схемы (кроме изменения первичного ключа или удаления колонок)
генерируемые колонки (например, duration) исключаются из процесса вставки и обновления
в процессе экспорта и импорта скрипты не должны формировать ошибки. При возникновении ошибок необходимо обратиться к специалистам технической поддержки компании IVA Technologies через сервисный портал

Устранение неполадок

ошибки подключения gRPC

Порядок выполняемых действий:
- проверка firewall: убедиться, что порт 50051 открыт между серверами
- проверка настроек хоста: убедиться, что адрес gRPC-сервера доступен с целевого сервера
- проверка версии: убедиться, что версии IVA CS совпадают
ошибки базы данных

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

Важные замечания

синхронизация: данные синхронизируются в режиме реального времени через gRPC
производительность: пропускная способность сети должна быть достаточной
безопасность: для межсерверного общения необходимо использовать VPN или шифрование
мониторинг: логи синхронизации и состояние сервисов должны регулярно проверяться

Поддержка и справочная информация

справка по скрипту создания зон
```
./geo_zone_create_for_domain.sh --help
```
справка по скрипту настройки клиента
```
./geo_zone_update_yaml_client.sh -h
```
справка по скриптам работы с базой данных
```
cat db-zone-readme.md
```

Примечания по использованию скриптов

скрипты запускаются с правами Администратора
необходимо создать резервные копии (backup-копии) конфигурационных файлов перед изменениями
скрипты сохраняют существующую структуру YAML-файлов
после автоматической настройки конфигурационных файлов доступна возможность их ручной проверки (с помощью текстового редактора nano)