Настройка рабочей версии: повышенная доступность и распределение нагрузки

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

Прежде, чем начать любую из этих настроек, ознакомьтесь с требованиями.

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

1. Создание каталога biz для скриптов настройки
2. Получение файлов конфигурации для клиента WhatsApp Business API
3. Установка переменных среды базы данных
4. Настройка тома локальных медиа
5. Запуск клиента WhatsApp Business API
6. Проверка, что контейнеры запущены
7. Проведение проверки работоспособности
8. Регистрация клиента WhatsApp Business API
9. Проведение повторной проверки работоспособности

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

1. Настройка двух осколков (сегментирования)
2. Проверьте работоспособность.
3. Запустите третий контейнер Coreapp для обеспечения повышенной доступности.
4. Проведение повторной проверки работоспособности

После того, как вы полностью настроите свой экземпляр, вы можете обновить его. Чтобы удалить клиент, выполните эти действия.

Прежде чем начать

Вам понадобятся:

• Несколько вычислительных серверов для выполнения различных компонентов клиента WhatsApp Business API (в том числе контейнеры Webapp, Coreapp и основного контейнера)

  • Системные требования см. в разделе Каковы системные требования к серверу для выполнения клиента WhatsApp Business API? часто задаваемых вопросов.
  • Для рабочей версии с повышенной доступностью рекомендуем использовать не менее одной машины для контейнера Webapp, не менее двух для контейнеров Coreapp и не менее двух для основных контейнеров. Нагрузка на основные контейнеры невелика, поэтому их можно разместить на одном хосте с контейнерами Coreapp.
• Установка Docker Desktop и Docker Compose.
• Полностью независимый сервер базы данных с MySQL или PostgreSQL

  • Сервер базы данных не должен быть выполнен ни на каком другом вычислительном сервере, на котором размещен клиент WhatsApp Business API, и задержка от других вычислительных серверов не должна превышать несколько миллисекунд.

• Общая файловая система (например, NFS), смонтированная к локальному каталогу на всех хостах Webapp, Coreapp и основных хостах, если вы хотите поддерживать отправку и получение сообщений с медиафайлом.

  • Убедитесь, что 755 устанавливается как файловый режим на пути монтирования и всех его подкаталогах.

mkdir your-local-media-volume-path
mount -t nfs nfs_server_IP_addr:/shared_directory /your-local-media-volume-path

Настройка кластера повышенной доступности

Шаг 1. Создание каталога biz для скриптов настройки

Выполните следующий код в каталоге, где будет установлен клиент WhatsApp Business API:

mkdir ~/biz; cd ~/biz;

Шаг 2. Получение файлов конфигурации для клиента WhatsApp Business API

Клонируйте файлы конфигурации prod-multiconnect-compose.yml и db.env из каталога Установкарепозитория GitHub WhatsApp-Business-API-Setup-Scripts в каталог ~/biz, который вы создали на шаге 1.

Шаг 3. Установка переменных среды базы данных

Измените переменные среды базы данных в файле db.env под каталогом ~/biz, чтобы отразить вашу конфигурацию MySQL/PostgreSQL.

WA_DB_ENGINE=MYSQL | PGSQL
WA_DB_HOSTNAME=your-database-server
WA_DB_PORT=your-database-server-port
WA_DB_USERNAME=your-database-username
WA_DB_PASSWORD=your-database-password

Шаг 4. Настройка объема локальных медиа

Том локальных медиафайлов (по умолчанию whatsappMedia:/usr/local/wamedia), определенный в файле prod-docker-compose.yml, используется для хранения медиафайлов. По умолчанию этот том смонтирован в каталоге на устройстве с Docker. Кроме того, вы можете смонтировать том медиафайлов в каталоге хоста. Чтобы изменить точку монтирования тома медиа, измените определение тома в разделе services от whatsappMedia на путь к используемому вами хост-каталогу.

services:
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
  ...
  master:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia

Шаг 5. Запуск клиента WhatsApp Business API

Для запуска клиента WhatsApp Business API с одним контейнером Webapp, двумя основными контейнерами и двумя контейнерами Coreapp, схожими с диаграммой введения повышенной доступности, используйте следующие команды с изменениями, необходимыми для вашей среды (т. е. имена хостов, имена пользователей хостов и локальные пути):

# copy configuration scripts to each Webapp host, ssh to each Webapp host, execute scripts to install Webapp on the host
for host in your-webapp-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done 
# copy configuration scripts to each Master host, ssh to each Master host, execute scripts to install Master on the host
for host in your-master1-hostname your-master2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# copy configuration scripts to each Coreapp host, ssh to each Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

В целом, вышеперечисленные команды:

• скопируют файлы конфигурации prod-multiconnect-compose.yml и db.env на все хосты Webapp (your-webapp-hostname в данном примере) и запустят службу waweb на этих хостах;
• скопируют файлы конфигурации prod-multiconnect-compose.yml и db.env на все основные хосты (your-master1-hostname и your-master2-hostname в данном примере) и запустят службу основного контейнера на этих хостах;
• скопируют файлы конфигурации prod-multiconnect-compose.yml и db.env на все хосты Coreapp (your-coreapp1-hostname и your-coreapp2-hostname в данном примере) и запустят службу wacore на этих хостах.

Шаг 6. Проверка работы контейнеров

Вы можете проверить, что все контейнеры имеют статус ВЫПОЛНЯЕТСЯ, выполнив:

EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f prod-multiconnect-compose.yml ps

Шаг 7. Проверка работоспособности

Проверить работоспособность клиента WhatsApp Business API можно с помощью вызова API к узлу health.

Ответ должен выглядеть так:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "unregistered",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        }
    }
}
200

В ответе gateway_status имеет значение unregistered, так как клиент WhatsApp Business API ещё не зарегистрирован.

Шаг  8. Регистрация клиента WhatsApp Business API

Зарегистрировать клиент WhatsApp Business API можно с помощью вызова API к узлу account.

Шаг 9. Повторная проверка работоспособности

После регистрации ещё раз проверьте работоспособность клиента WhatsApp Business API с помощью вызова API к узлу health и убедитесь в том, что один из контейнеров Coreapp имеет gateway_status со значением connected.

Ответ должен выглядеть так:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}
200

Примечание: В режиме повышенной доступности к серверу WhatsApp будет подключен только один хост Coreapp (your-coreapp1-hostname:753efb1cf72c в данном примере), а все другие узлы, включая главный основной, будут иметь статус gateway_status как disconnected. Если your-coreapp1-hostname:753efb1cf72c выйдет из строя, your-coreapp2-hostname:75d7355eaaaa заменит его и подключится к серверу WhatsApp для сохранения повышенной доступности.

Теперь клиент WhatsApp Business API настроен в режиме повышенной доступности. В этом режиме подключаться к серверу WhatsApp для отправки сообщений может только один узел Coreapp. Если вам нужно отправлять много сообщений с нескольких узлов Coreapp одновременно, настройте распределение нагрузки, как описано ниже.

Настройка кластера повышенной доступности с распределением нагрузки

Шаг 1. Настройка двух сегментов

С помощью конечной точки сегментов настройте два сегмента. В ответе HTTP должен быть указан статус 201 Created.

Шаг 2. Проверка работоспособности

Проверить работоспособность клиента WhatsApp Business API можно с помощью вызова API к health узлу для удостоверения, что все узлы работают правильно.

Ответ должен выглядеть так:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}      
200    

Примечание. В режиме распределения нагрузки с использованием двух сегментов к серверу WhatsApp будут подключены два узла Coreapp (в данном примере — your-coreapp1-hostname:753efb1cf72c и your-coreapp2-hostname:75d7355eaaaa) и главный основной узел (в данном примере — your-master2-hostname:8dd3f5bea27d) также подключится к серверу.

Шаг 3. Запуск третьего контейнера Coreapp для обеспечения повышенной доступности

На этом этапе у вас есть два контейнера Coreapp, несущие одинаковую нагрузку по обработке сообщений. Однако если один из контейнеров выйдет из строя, половина сообщений не будет доставлена. Чтобы поддерживать повышенную доступность в этой новой настройке распределения нагрузки, вы можете запустить третий контейнер Coreapp на новом хосте Coreapp (

в этом примере) допустить 1 сбой Coreapp, что похоже на диаграмму, показанную на Распределение нагрузки: введение.

Чтобы запустить третий контейнер Coreapp, выполните следующую команду:

# copy configuration scripts to the 3rd Coreapp host, ssh to the Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp3-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

Шаг 4. Повторная проверка работоспособности

Ещё раз проверьте работоспособность всех узлов с помощью вызова API к узлу health.

Ответ должен выглядеть так:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp3-hostname:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}      
200 

На этом этапе новый контейнер Coreapp (в данном примере — your-coreapp3-hostname:23b50199bec2) действует как независимый контейнер, но не подключен к серверу WhatsApp. Если один из двух других контейнеров перестанет работать, третий подключится к серверу WhatsApp, и общее количество сегментов останется равным двум.

Правила и рекомендации

Количество контейнеров Webapps

Для отправки 100–150 сообщений в секунду рекомендуется настроить не менее двух контейнеров Webapps. Чтобы использовать их в режиме повышенной доступности, запустите их на более, чем двух хостах с применением балансировщика нагрузки (например, HAProxy, Nginx или ELB). Для доступа к конечным точкам клиента WhatsApp Business API используйте не https://your-webapp-hostname:your-webapp-port/, а https://your-load-balancer-name:your-load-balancer-port/.

Количество основных контейнеров

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

Количество контейнеров Coreapp

Для обеспечения оптимальной работоспособности клиента рекомендуется использовать shard_number + X контейнеров Coreapp на разных хостах. Здесь X — количество потенциальных отказов хостов.

Обновление клиента WhatsApp Business API

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

# ssh to each Webapp host, execute scripts with new WA_API_VERSION to upgrade Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts with new WA_API_VERSION to upgrade Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts with new WA_API_VERSION to upgrade Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

Для пользователей базы данных MySQL, выполняющих обновление до версии 2.23.x и выше

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

Шаг 1. Скачивание файла конфигурации

В файле dbupgrade-compose.yml есть поля, в которых указана версия контейнера.

Пример:

services:
  dbupgrade:
      image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

Шаг 2. Запуск контейнера

Чтобы обновить установленную базу данных, запустите контейнер dbupgrade-service, указав в значении переменной среды WA_API_VERSION последнюю версию базы:

EXTERNAL_HOSTNAME=$host_to_upgradedb WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

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

Шаг 3. Дождитесь завершения обновления

Если оно будет успешным, контейнер завершит работу с выходным кодом 0. Отслеживать статус можно с помощью следующей команды Docker:

docker wait your-database-upgrade-container-name

Она показывает выходной код контейнера dbupgrade-service.

Шаг 4. Перезапуск контейнеров Coreapp и Webapp

Перезапустите контейнеры Docker Coreapp и Webapp, указав последнюю версию в переменной среды WA_API_VERSION:

EXTERNAL_HOSTNAME=$host_to_upgradedb WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

Для пользователей клиента WhatsApp Business API, выполняющих обновление до версии 2.29.3 и выше

Если вы обновляете с v2.29.1, v2.29.2или столкнулись с проблемами при обновлении до этих версий и были вынуждены выполнить откат для стабильности, мы рекомендуем вам выполнить обновление до v2.29.3, затем выполните следующую команду в контейнере Webapp Docker:

chown -R root your-media-directory/incoming your-media-directory/outgoing your-media-directory/shared

Если вы не изменили его, каталогом медиа по умолчанию будет /usr/local/wamedia.

Примечание.

• Поскольку для выполнения этой команды может потребоваться некоторое время в зависимости от размера уже существующего тома медиа, мы рекомендуем запускать эту команду сразу после обновления во время периода обслуживания.
• Эта команда только изменяет право собственности на тома медиа в фоновом режиме (Задержка/производительность не влияют на/задерживают операции с медиафайлами).
• Это одноразовый способ обновления для устранения проблем обратной совместимости в v2.29.1 и v2.29.2.

Удаление клиента WhatsApp Business API

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

# ssh to each Webapp host, execute scripts to uninstall Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts to uninstall Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts to uninstall Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd wacore
done

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

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

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs > debug_output.txt

Чтобы собрать журналы определенной службы, укажите ее название (например, waweb, master1 или wacore1) в команде docker-compose logs.

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs waweb > debug_output.txt

Журналы событий можно найти в файле debug_output.txt, который находится в текущем каталоге.