개발자 설정: 고가용성 및 다중 연결
개발자 기기에서 WhatsApp Business API 클라이언트의 고가용성 및 다중 연결 설치를 설정하는 방법을 설명합니다. 그 후에 다중 연결을 활성화하는 방법과 고가용성 다중 연결 클러스터에 필요한 변경 사항에 대한 안내도 제공합니다.
프로덕션 설정의 경우 프로덕션 설정에 나와 있는 관련 지침을 따르세요.
시작하기 전에
개발자 설정: 단일 인스턴스 지침에 따라 개발자 기기에서 WhatsApp Business API 클라이언트를 설정한 적이 있다면, 이 문서의 나머지 부분을 보기 전에 마이그레이션 가이드를 따르세요.
이 가이드의 내용은 새로 설치하는 것을 전제로 합니다.
다음과 같은 항목이 필요합니다.
- 로컬에서 설정한 개발 환경의 테스트 계정
- 빠른 개발과 새 릴리스 테스트에 사용할 용도입니다.
또한 고가용성과 다중 연결에 대한 자세한 내용은 가용성 및 확장 가이드를 참조하는 것이 좋습니다.
고가용성 클러스터 설정
1단계: 설정 스크립트를 위한 biz 디렉터리 만들기
WhatsApp Business API 클라이언트의 원하는 위치에서 다음 코드를 실행합니다.
mkdir ~/biz; cd ~/biz;
2단계: WhatsApp Business API 클라이언트 구성 파일 가져오기
WhatsApp Business API 클라이언트의 구성 파일은 WhatsApp-Business-API-Setup-Scripts GitHub 리포지토리에 있습니다. MySQL 또는 Postgres 데이터베이스 인스턴스로 WhatsApp Business API 클라이언트를 설정할 수 있습니다.
- Postgres 데이터베이스 설정의 경우 Postgre 설치 디렉터리의
multiconnect-compose.yml과db.env구성 파일을 1단계에서 생성한~/biz디렉터리로 복사합니다.
3단계: WA_API_VERSION 환경 변수 설정
WA_API_VERSION 환경 변수는 다음을 사용하여 최신 버전으로 설정해야 합니다.
export WA_API_VERSION=current-whatsapp-version
4단계: 고가용성으로 WhatsApp Business API 클라이언트 시작
고가용성 소개의 다이어그램과 유사한 백그라운드에 데이터베이스 컨테이너 1개, Webapp 컨테이너 1개, Master 컨테이너 2개, Coreapp 컨테이너 2개로 고가용성 클러스터를 시작하려면 다음 명령을 실행합니다.
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단계: 상태 점검 수행
명령줄을 사용하고 싶지 않은 경우 Postman 컬렉션을 다운로드하여 구성하면 WhatsApp Business API와 상호작용하는 데 사용할 수 있습니다.
health 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트에 상태 점검을 수행할 수 있습니다.
결과로 나오는 출력은 다음과 같습니다.
{
"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."
}
]
}
}
}
응답에서는 기본 Master 컨테이너에 대해 unregistered의 gateway_status가 gateway_status로 표시되는데, WhatsApp Business API 클라이언트가 아직 등록되지 않았기 때문입니다.
7단계: WhatsApp Business API 클라이언트 등록
account 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트를 등록할 수 있습니다.
8단계: 두 번째 상태 점검 수행
등록을 완료한 후에 health 노드로 API 호출을 보내서 WhatsApp Business API 클라이언트에 다시 한 번 상태 점검을 수행하고 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"
}
}
}
참고: 고가용성 모드에서는 하나의 Coreapp(이 예시에서는 wacore1)만 Whatsapp 서버에 연결되고 기본 Master를 포함한 그 외의 나머지 노드는 gateway_status가 disconnected로 설정됩니다. wacore1의 작동이 정지되면 wacore2가 그 자리를 대체해서 Whatsapp 서버로 연결되고 고가용성을 유지합니다.
이제 WhatsApp Business API 클라이언트가 고가용성 모드로 설정되었습니다. 이 모드에서는 Coreapp 한 개만 WhatsApp 서버에 연결되어 특정 시점에 메시지를 전송할 수 있습니다. 메시지 처리량을 높이기 위해 여러 개의 Coreapp에서 메시지를 전송하고자 하는 경우, 아래의 고가용성 다중 연결 클러스터 설정 섹션의 단계를 따르세요.
고가용성 다중 연결 클러스터 설정
1단계: 샤드 2개 설정
샤드 엔드포인트를 사용하여 샤드 2개를 설정합니다. 상태가 201 Created인 HTTP 응답이 보일 것입니다.
2단계: 상태 점검 수행
health 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트에 상태 점검을 수행할 수 있습니다.
결과로 나오는 출력은 다음과 같습니다.
{
"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"
}
}
}
참고: 샤드가 2개인 다중 연결에서는 Coreapp 2개(이 예시에서는 wacore1과 wacore2)가 WhatsApp 서버로 연결되고 기본 Master(이 예시에서는 master2)도 WhatsApp 서버에 연결됩니다.
3단계: 세 번째 Coreapp을 시작하여 고가용성 유지
이 예시에서는 Coreapp 컨테이너가 2개이고, 해당 두 컨테이너로 메시지 부하가 나뉩니다. 그러나 Coreapp 컨테이너 중 하나가 중단되면 메시지 전송의 절반이 실패합니다. 이 새로운 다중 연결 설정에서 고가용성을 유지하려면 세 번째 Coreapp을 시작하여 Coreapp 1개의 실패를 감당하도록 할 수 있습니다. 이는 다중 연결 소개의 다이어그램과 유사합니다.
세 번째 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단계: 두 번째 상태 점검 수행
health 노드로 API 호출을 보내 다시 한 번 상태 점검을 수행하고 모든 노드가 제대로 실행되고 있는지 확인합니다.
결과로 나오는 출력은 다음과 같습니다.
{
"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단계: 컨테이너 시작
설치를 업그레이드하려면 WA_API_VERSION 환경 변수를 최신 버전으로 설정한 dbupgrade-service 컨테이너를 시작합니다.
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 컨테이너 다시 시작
WA_API_VERSION 환경 변수를 최신 버전으로 설정하고 Coreapp과 Webapp Docker 컨테이너를 다시 시작합니다.
WA_API_VERSION=new-whatsapp-version docker-compose -f multiconnect-compose.yml up -d
WhatsApp Business API 클라이언트 제거
제거하기 전에 현재 앱 설정을 백업하는 것이 좋습니다. 백업 및 복원 문서를 참조하세요.
모든 컨테이너를 삭제하여 개발 환경을 재설정해야 하는 경우 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 파일에서 로그를 찾을 수 있습니다.
이 소프트웨어는 LGPLv2.1에 따라 라이선스가 부여된 FFmpeg 코드를 사용하고 소스는 여기에서 다운로드할 수 있습니다.