Локальный API платформы WhatsApp Business

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

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

Прежде, чем начинать эти настройки, ознакомьтесь со списком требований.

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

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

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

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

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

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

Если вы настроили клиент WhatsApp Business API согласно руководству для среды разработки с одним экземпляром, сначала следуйте инструкциям из руководства по миграции, а затем переходите к этому документу.

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

Перед началом работы вам понадобится:

Install Docker Desktop

To install Docker Desktop on your developer machine:

  1. Navigate to the Docker website.
  2. If you do not have an existing Docker account, create one by clicking on Sign Up.
  3. After you have created your account, you will be directed to the Docker download page.
  4. Download Docker Desktop based on your OS (This should be automatically detected and presented as the default option).

The remaining steps are based on macOS and should be very similar for Linux or Windows 10.

To install Docker using macOS:

  1. Install the package (docker.dmg for macOS).
  2. After extraction, Finder will pop-up and you will be presented with a dialog that instructs you to drag the Docker icon to Applications. Drag Docker icon to the Application folder in Finder.
  3. In Applications launch Docker and then click the Open button.
  4. You may be prompted to enter your password Docker needs priviledged/administrator access.
  5. Docker will present you with a tutorial, you can click Start to launch a tutorial or you can click Skip Tutorial to start using Docker.

Verify Docker Compose is installed

Docker Compose is a plugin that is bundled with Docker Desktop and should have installed automatically. For more information about using or Docker Compose, see Overview of Docker Compose. If for some reason Docker Compose was not installed, you can install it by following the instructions located at Install Docker Compose.

Другие предварительные требования

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

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

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

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

mkdir ~/biz; cd ~/biz;

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

Файлы конфигурации для клиента WhatsApp Business API находятся в репозитории GitHub WhatsApp-Business-API-Setup-Scripts. Настроить клиент WhatsApp Business API можно с экземпляром базы данных MySQL или Postgres.

Шаг 3. Настройка переменной среды WA_API_VERSION

Укажите в переменной среды WA_API_VERSION текущую версию, выполнив следующую команду:

export WA_API_VERSION=current-whatsapp-version

Шаг 4. Запуск клиента WhatsApp Business API с повышенной доступностью

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

docker-compose -f multiconnect-compose.yml up -d db waweb master1 master2 wacore1 wacore2

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

Creating network "biz_default" with the default driver
Creating volume "biz_mysqlData" with local driver
Creating volume "biz_whatsappMedia" with local driver
Creating biz_db_1 ... done
Creating biz_waweb_1 ... done
Creating biz_master1_1 ... done
Creating biz_master2_1 ... done
Creating biz_wacore2_1 ... done
Creating biz_wacore1_1 ... done

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

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

docker-compose -f multiconnect-compose.yml ps

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

      Name                    Command               State                                                 Ports
--------------------------------------------------------------------------------------------------------------------------------------------------------------
biz_db_1        docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_master1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32931->6250/tcp, 0.0.0.0:32930->6251/tcp, 0.0.0.0:32928->6252/tcp, 0.0.0.0:32926->6253/tcp
biz_master2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32929->6250/tcp, 0.0.0.0:32927->6251/tcp, 0.0.0.0:32925->6252/tcp, 0.0.0.0:32924->6253/tcp
biz_wacore1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32937->6250/tcp, 0.0.0.0:32935->6251/tcp, 0.0.0.0:32933->6252/tcp, 0.0.0.0:32932->6253/tcp
biz_wacore2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32939->6250/tcp, 0.0.0.0:32938->6251/tcp, 0.0.0.0:32936->6252/tcp, 0.0.0.0:32934->6253/tcp
biz_waweb_1     /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

По умолчанию контейнер Webapp использует порт 9090, а контейнер базы данных — порт 33060.

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

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

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

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

{
    "health": {
      "master1:b28d835cd579": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "master2:7fe542d305b4": {
          "gateway_status": "unregistered",
          "role": "primary_master"
      },
      "wacore1:35a5fabfc79d": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "wacore2:05e1a6d70665": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      }
  }
}

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

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

Чтобы зарегистрировать клиент WhatsApp Business API, выполните вызов API к узлу account.

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

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

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

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

Примечания. В режиме повышенной доступности к серверу WhatsApp будет подключен только один контейнер (в данном примере —wacore1). У остальных узлов, включая главный основной, в значении gateway_status будет указано disconnected. Если wacore1 выйдет из строя, wacore2 заменит его и подключится к серверу WhatsApp для сохранения повышенной доступности.

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

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

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

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

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

Чтобы проверить работоспособность клиента WhatsApp Business API, выполните вызов API к узлу health.

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

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}

Примечания. В режиме распределения нагрузки с использованием двух сегментов к серверу WhatsApp будут подключены два контейнера Coreapp (в этом примере — wacore1 и wacore2) и главный основной контейнер (в этом примере — master2).

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

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

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

docker-compose -f multiconnect-compose.yml up -d wacore3

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

biz_db_1 is up-to-date
biz_waweb_1 is up-to-date
biz_master1_1 is up-to-date
Creating biz_wacore3_1 ... done

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

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

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

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore3:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

Сейчас новый контейнер Coreapp (в этом примере — wacore3) находится в состоянии готовности, но не подключен к серверу WhatsApp. Если wacore1 или wacore2 перестанет работать, wacore3 подключится к серверу WhatsApp, и общее количество сегментов останется равным 2.

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

Во время обновления будьте готовы к простою.

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

Поэтому рекомендуется выполнять все обновления в периоды наименьшей активности.

Шаг 1. Указание новой версии в переменной среды WA_API_VERSION

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

export WA_API_VERSION=new-whatsapp-version

Шаг 2. Перезапуск контейнеров Docker

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

docker-compose -f multiconnect-compose.yml up -d

Для пользователей базы данных MySQL, выполняющих обновление до версии v2.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 последнюю версию базы:

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:

WA_API_VERSION=new-whatsapp-version docker-compose -f multiconnect-compose.yml up -d

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

Перед удалением настоятельно рекомендуем создать резервную копию текущих настроек приложения. Следуйте инструкциям из статьи Резервное копирование и восстановление настроек.

Чтобы сбросить среду разработки и удалить все контейнеры, выполните следующую команду из каталога, в котором находится файл multiconnect-compose.yml:

docker-compose -f multiconnect-compose.yml down

Чтобы помимо контейнеров удалить и все тома, определенные в файле multiconnect-compose.yml, выполните команду down с параметром -v:

docker-compose -f multiconnect-compose.yml down -v

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

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

docker-compose -f multiconnect-compose.yml logs > debug_output.txt

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

docker-compose -f multiconnect-compose.yml logs waweb > debug_output.txt

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

В этом программном обеспечении используется исходный код из набора библиотек FFmpeg, предоставляемый по лицензии LGPLv2.1. Скачать его можно здесь.