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.
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:
biz
per gli script di configurazionePer configurare un cluster Multiconnect ad High Availability:
Una volta configurata completamente la tua istanza, puoi scegliere di aggiornarla. Per disinstallare il client, segui questi passaggi.
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à:
È 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.
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
To install Docker Desktop on your developer machine:
The remaining steps are based on macOS and should be very similar for Linux or Windows 10.
To install Docker using macOS:
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.
biz
per gli script di configurazioneEsegui il codice seguente nella posizione che preferisci per il client dell'API di WhatsApp Business:
mkdir ~/biz; cd ~/biz;
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.
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
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
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:
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;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;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.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
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_status
unregistered
perché il client dell'API di WhatsApp Business non è ancora stato registrato.
Puoi registrare il tuo client dell'API di WhatsApp Business mediante una chiamata API al nodo account
.
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.
Usa l'endpoint shards per configurare 2 shard. Dovresti vedere una risposta HTTP con stato 201 Created
.
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).
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
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.
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/
.
È 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.
È consigliabile avere shard_number + X
Coreapp in esecuzione su diversi host per poter tollerare X
guasti dell'host.
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
2.23.x
o successiveOra puoi avvalerti di un servizio di aggiornamento database per aggiornare il tuo database mentre l'app è ancora in esecuzione, evitando così tempi di inattività.
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}
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
.
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.
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
2.29.3
e successiveSe stai eseguendo l'aggiornamento dalla versione v2.29.1
, v2.29.2
o 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:
v2.29.1
e v2.29.2
.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
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.