Questo documento è stato aggiornato.
La traduzione in Italiano non è ancora completa.
Aggiornamento inglese: 12 gen

Stiamo disattivando l'API On-Premises. Consulta il nostro documento Disattivazione API On-Premises per i dettagli e per scoprire come eseguire la migrazione alla nostra API Cloud di nuova generazione.

Configurazione di produzione: High Availability e Multiconnect

Questo documento mostra come configurare un cluster High Availability in produzione. Fornisce inoltre tutte le indicazioni necessarie per abilitare Multiconnect insieme alle modifiche richieste per un cluster Multiconnect ad High Availability.

Se non l'hai ancora fatto, ti consigliamo di configurare l'istanza High Availability/Multiconnect del client dell'API di WhatsApp Business su una macchina per sviluppatori seguendo le istruzioni Configurazione per sviluppatori: High Availability e Multiconnect per testare la configurazione prima di seguire questo documento per configurare il client dell'API di WhatsApp Business in produzione.

Prima di iniziare una qualsiasi di queste configurazioni, consulta i nostri requisiti.

Per configurare un cluster ad High Availability:

  1. Crea una directory biz per gli script di configurazione
  2. Ottieni i file di configurazione del client dell'API di WhatsApp Business
  3. Imposta le variabili d'ambiente del database
  4. Configura il volume del contenuto multimediale locale
  5. Avvia il client dell'API di WhatsApp Business
  6. Verifica che i contenitori siano in esecuzione
  7. Effettua un controllo integrità
  8. Registra il client dell'API di WhatsApp Business
  9. Esegui un secondo controllo integrità

Per configurare un cluster Multiconnect ad High Availability:

  1. Configura due shard
  2. Esegui un controllo integrità
  3. Avvia una terza coreapp per mantenere l'High Availability
  4. Esegui un secondo controllo integrità

Una volta configurata completamente la tua istanza, puoi scegliere di aggiornarla. Per disinstallare il client, segui questi passaggi.

Prima di iniziare

Se hai già eseguito una configurazione per sviluppatori e desideri riutilizzare il numero di telefono in produzione, consulta la Guida alla migrazione prima di proseguire con le sezioni rimanenti di questo documento.

Il contenuto di questo documento si basa sul presupposto di una nuova installazione con un nuovo numero di telefono.

Ecco cosa ti servirà:

  • Più server di calcolo per eseguire i vari componenti del client dell'API di WhatsApp Business (ad es. Webapp, Master e Coreapp)
  • Un server di database standalone che esegue un processo MySQL o PostgreSQL
    • Il server di database non deve essere eseguito su uno qualsiasi degli altri server di calcolo che ospitano il client dell'API di WhatsApp Business; tra esso e gli altri server di calcolo dovrebbero intercorrere solo pochi millisecondi di latenza.

È necessario MySQL 5.7.xx/8.0.xx o PostgreSQL 13.x/12.x/11.x.

La password del database non deve contenere alcuno di questi caratteri: ?{}&~!()^=

Il mancato rispetto di queste indicazioni potrebbe determinare l'esito negativo della configurazione.

  • Un file system condiviso (ad es. NFS) montato su una directory locale su tutti gli host Webapp, Master e Coreapp, se vuoi supportare l'invio e la ricezione di messaggi multimediali
    • Assicurati che 755 sia impostato come modalità file sul percorso di montaggio e su tutte le sue sottodirectory.
mkdir your-local-media-volume-path
mount -t nfs nfs_server_IP_addr:/shared_directory /your-local-media-volume-path

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.

Configurazione di un cluster ad High Availability

Passaggio 1: creazione di una directory biz per gli script di configurazione

Esegui il codice seguente nella posizione che preferisci per il client dell'API di WhatsApp Business:

mkdir ~/biz; cd ~/biz;

Passaggio 2: acquisizione dei file di configurazione del client dell'API di WhatsApp Business

Clona i file di configurazione prod-multiconnect-compose.yml e db.env dalla directory di installazione del repository GitHub WhatsApp-Business-API-Setup-Scripts nella directory ~/biz che hai creato nel Passaggio 1.

Passaggio 3: impostazione delle variabili d'ambiente del database

Modifica le variabili d'ambiente del database nel file db.env nella directory ~/biz per riflettere la tua configurazione 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

Passaggio 4: configurazione del volume dei contenuti multimediali locali

Il volume dei contenuti multimediali locali (whatsappMedia:/usr/local/wamedia per impostazione predefinita) definito nel file prod-docker-compose.yml viene utilizzato per la memorizzazione dei file multimediali. Per impostazione predefinita, il volume viene montato su una directory nella macchina Docker. In alternativa, puoi scegliere di montare il volume dei contenuti multimediali su una directory host. Per modificare il punto di montaggio del volume dei contenuti multimediali, modifica la definizione di volume all'interno della sezione services da whatsappMedia al percorso della directory host utilizzata.

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

Passaggio 5: avvio del client dell'API di WhatsApp Business

Per avviare il client dell'API di WhatsApp Business con 1 contenitore Webapp, 2 contenitori Master e 2 contenitori Coreapp simili al diagramma di introduzione High Availability, usa i seguenti comandi con le modifiche necessarie per il tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

In sintesi, con i comandi sopra riportati verranno eseguite le azioni seguenti:

  • copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Webapp (your-webapp-hostname in questo esempio) e avvio del servizio waweb su questi host;
  • copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Master (your-master1-hostname e your-master2-hostname in questo esempio) e avvio del servizio Master su questi host;
  • copia dei file di configurazione prod-multiconnect-compose.yml e db.env su tutti gli host Coreapp (your-coreapp1-hostname e your-coreapp2-hostname in questo esempio) e avvio del servizio wacore su questi host.

Passaggio 6: verifica che i contenitori siano in esecuzione

Puoi controllare che tutti i contenitori abbiano uno stato RUNNING eseguendo:

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

Passaggio 7: esecuzione di un controllo integrità

Puoi scaricare e configurare la nostra raccolta Postman per interagire con l'API di WhatsApp Business se non desideri utilizzare la riga di comando.

Puoi eseguire un controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata all'API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

{
    "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

La risposta mostra un gateway_statusunregistered come gateway_status perché il client dell'API di WhatsApp Business non è ancora stato registrato.

Passaggio 8: registrazione del client dell'API di WhatsApp Business

Puoi registrare il tuo client dell'API di WhatsApp Business mediante una chiamata API al nodo account.

Passaggio 9: esecuzione di un secondo controllo integrità

Esegui un altro controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata API al nodo health al completamento della registrazione e assicurati che uno dei contenitori Coreapp abbia connected come gateway_status.

L'output risultante dovrebbe essere simile al seguente:

{
    "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

Nota: in modalità High Availability, solo un Coreapp (your-coreapp1-hostname:753efb1cf72c in questo esempio) viene connesso al server WhatsApp, tutti gli altri nodi, compreso il Master primario, presenteranno disconnected come gateway_status. Se your-coreapp1-hostname:753efb1cf72c smette di funzionare, your-coreapp2-hostname:75d7355eaaaa lo sostituisce connettendosi al server WhatsApp per mantenere High Availability.

È consigliabile configurare il monitoraggio per il client dell'API di WhatsApp Business di produzione.

Ora hai configurato il client dell'API di WhatsApp Business in modalità High Availability. In questa modalità, solo un Coreapp è in grado di connettersi al server WhatsApp per inviare messaggi in qualsiasi momento. Se desideri avere a disposizione più Coreapp in grado di inviare messaggi contemporaneamente per incrementare il throughput dei messaggi, esegui la procedura indicata nella sezione Configurazione di un cluster Multiconnect ad High Availability di seguito.

Configurazione di un cluster Multiconnect ad High Availability

Passaggio 1: configurazione di due shard

Usa l'endpoint shards per configurare 2 shard. Dovresti vedere una risposta HTTP con stato 201 Created.

Passaggio 2: esecuzione di un controllo integrità

Per verificare che tutti i nodi siano correttamente in esecuzione, puoi eseguire un controllo integrità sul client dell'API di WhatsApp Business mediante una chiamata API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

{
    "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    

Nota: in modalità Multiconnect con 2 shard, saranno connessi al server WhatsApp 2 Coreapp (your-coreapp1-hostname:753efb1cf72c e your-coreapp2-hostname:75d7355eaaaa in questo esempio) e il Master primario (your-master2-hostname:8dd3f5bea27d in questo esempio).

Passaggio 3: avvio di un terzo Coreapp per mantenere l'High Availability

Finora in questo esempio disponi di 2 contenitori Coreapp tra cui è ripartito il carico di messaggi. Tuttavia, se uno dei contenitori Coreapp smette di funzionare, l'invio di metà dei messaggi fallisce. Per mantenere l'High Availability in questa nuova configurazione Multiconnect, puoi avviare un terzo Coreapp su un nuovo host Coreapp (

your-coreapp3-hostname

in questo esempio) così da poter tollerare 1 errore Coreapp, in modo simile al diagramma mostrato nella Introduzione a Multiconnect.

Per avviare il terzo contenitore Coreapp, esegui questo comando:

# 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

Passaggio 4: esecuzione di un secondo controllo integrità

Esegui un altro controllo integrità per verificare che tutti i nodi funzionino correttamente mediante una chiamata API al nodo health.

L'output risultante dovrebbe essere simile al seguente:

{
    "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 

Il nuovo contenitore Coreapp (your-coreapp3-hostname:23b50199bec2 in questo esempio) ora agisce da contenitore di standby, ma non è attualmente connesso al server WhatsApp. Se uno degli altri 2 contenitori Coreapp connessi smette di funzionare, il terzo contenitore si connette al server WhatsApp per mantenere un numero totale di shard pari a 2.

Linee guida e best practice

Numero di Webapp

Per supportare 100-150 messaggi/sec., sono consigliati almeno 2 Webapp. Se desideri ottenere High Availability per Webapp, puoi eseguire i contenitori Webapp su più di 2 host e avvalerti di un servizio di bilanciamento del carico come HAProxy, Nginx o ELB. Invece di accedere agli endpoint del client dell'API di WhatsApp Business tramite https://your-webapp-hostname:your-webapp-port/, dovresti usare https://your-load-balancer-name:your-load-balancer-port/.

Numero di Master

È consigliabile avere 3 Master in esecuzione su diversi host. Non è necessario avere più di 3 Master in produzione, indipendentemente dal numero di shard di cui si dispone. I carichi sui Master sono leggeri, pertanto potresti collocarli insieme ai contenitori Coreapp.

Numero di Coreapp

È consigliabile avere shard_number + X Coreapp in esecuzione su diversi host per poter tollerare X guasti dell'host.

Aggiornamento del client dell'API di WhatsApp Business

Si verificherà un tempo di inattività durante il processo di aggiornamento.

Si consiglia vivamente di eseguire il backup delle impostazioni correnti dell'app prima dell'aggiornamento per assicurarsi che il processo sia rapido ed efficace. Segui la documentazione su backup e ripristino.

È sempre consigliabile eseguire gli aggiornamenti negli orari di minor attività.

La variabile d'ambiente WA_API_VERSION deve essere aggiornata al nuovo numero di versione. Esegui i seguenti comandi con le modifiche necessarie per il tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

Per gli utenti del database MySQL che eseguono l'aggiornamento alla versione 2.23.x o successive

Ora puoi avvalerti di un servizio di aggiornamento database per aggiornare il tuo database mentre l'app è ancora in esecuzione, evitando così tempi di inattività.

Passaggio 1: download del file di configurazione

Il file dbupgrade-compose.yml contiene dei campi indicanti la versione dei contenitori.

Esempio:

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

Passaggio 2: avvio del contenitore

Per aggiornare un'installazione, avvia il contenitore dbupgrade-service con la variabile d'ambiente WA_API_VERSION impostata sull'ultima versione:

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

Nota: se stai utilizzando un'orchestrazione che riavvia il contenitore all'uscita indipendentemente dal codice di uscita, inizia il servizio con la variabile d'ambiente EXIT_ON_SUCCESS impostata su FALSE per evitare di uscire dal contenitore quando il codice di uscita è 0.

Passaggio 3: attesa della conclusione dell'aggiornamento

Se l'aggiornamento del database è avvenuto correttamente, il contenitore uscirà con codice 0. Puoi usare il comando Docker seguente per monitorare lo stato:

docker wait your-database-upgrade-container-name

Questa operazione genererà il codice di uscita del contenitore dbupgrade-service.

Passaggio 4: riavvio dei contenitori Coreapp e Webapp

Riavvia i contenitori Docker Coreapp e Webapp con la variabile d'ambiente WA_API_VERSION impostata sull'ultima versione:

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

Per gli utenti del client dell'API di WhatsApp Business che eseguono l'aggiornamento alla versione 2.29.3 e successive

Se stai eseguendo l'aggiornamento dalla versione v2.29.1, v2.29.2o hai riscontrato problemi durante l'aggiornamento a quelle versioni e hai dovuto eseguire il ripristino per la stabilità, è consigliabile eseguire l'aggiornamento alla versione v2.29.3, quindi eseguire il seguente comando nel contenitore Docker Webapp:

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

A meno che tu non abbia modificato la directory dei contenuti multimediali, quella predefinita è /usr/local/wamedia.

Nota:

  • Poiché il completamento di questo comando può richiedere del tempo in base alle dimensioni del volume dei contenuti multimediali preesistenti, è consigliabile avviare questo comando non appena si esegue l'aggiornamento durante la finestra di manutenzione.
  • Questo comando modifica solo la proprietà dei volumi dei contenuti multimediali in background (non è previsto alcun impatto/tempo di inattività per operazioni multimediali o latenza/prestazioni durante l'esecuzione).
  • Questo è un percorso di aggiornamento unico per risolvere i problemi di compatibilità con le versioni precedenti in v2.29.1 e v2.29.2.

Disinstallazione del client dell'API di WhatsApp Business

Se devi reimpostare il tuo ambiente di sviluppo rimuovendo tutti i contenitori, usa i seguenti comandi con le modifiche necessarie al tuo ambiente (ovvero nomi host, nomi utente host e percorsi locali):

# 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

Risoluzione dei problemi

Per acquisire i registri da tutti i contenitori su un host, esegui il comando seguente:

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

Per acquisire i registri di un determinato servizio, aggiungi il nome del servizio (ad es., waweb, master1 o wacore1) al comando docker-compose logs.

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

I registri sono disponibili nel file debug_output.txt nella directory corrente.


Questo software utilizza il codice di FFmpeg concesso in licenza ai sensi della LGPLv2.1 e il relativo codice sorgente può essere scaricato qui.