Thiết lập dành cho nhà phát triển: Chế độ Sẵn sàng cao và Đa kết nối
Tài liệu này hướng dẫn cách thiết lập một cụm có chế độ Sẵn sàng cao trên máy của nhà phát triển. Tài liệu này cũng cung cấp hướng dẫn về cách bật chế độ Đa kết nối cùng với các thay đổi bắt buộc đối với cụm Đa kết nối có độ sẵn sàng cao.
Để thiết lập trong môi trường chính thức, hãy làm theo các hướng dẫn phù hợp nêu trong phần Thiết lập trong môi trường chính thức.
Trước khi bạn bắt đầu
Nếu trước đó, bạn đã làm theo hướng dẫn Thiết lập dành cho nhà phát triển: Một phiên bản để thiết lập ứng dụng API WhatsApp Business trên máy của nhà phát triển, vui lòng làm theo Hướng dẫn chuyển trước khi tiếp tục phần còn lại trong tài liệu này.
Nội dung trong hướng dẫn này dựa trên giả định sẽ cài đặt mới.
Bạn cần có:
- Docker Compose
- Công cụ này đi kèm với gói cài đặt Docker, nhưng nếu không, bạn có thể cài đặt công cụ đó.
- Một tài khoản thử nghiệm được thiết lập trên hệ thống trong môi trường phát triển
- Tài khoản này dùng để phát triển và thử nghiệm nhanh các bản mới phát hành.
Để tìm hiểu thêm về chế độ Sẵn sàng cao và Đa kết nối, bạn nên đọc qua hướng dẫn về Độ sẵn sàng và khả năng mở rộng.
Thiết lập cụm có chế độ Sẵn sàng cao
Bước 1: Tạo thư mục biz cho các tập lệnh thiết lập
Chạy mã sau ở vị trí bạn muốn cho ứng dụng API WhatsApp Business:
mkdir ~/biz; cd ~/biz;
Bước 2: Tải file cấu hình ứng dụng API WhatsApp Business
Các file cấu hình cho ứng dụng API WhatsApp Business có tại kho lưu trữ WhatsApp-Business-API-Setup-Scripts GitHub. Bạn có thể thiết lập ứng dụng API WhatsApp Business với một phiên bản cơ sở dữ liệu MySQL hoặc Postgres.
- Để thiết lập với cơ sở dữ liệu MySQL, hãy sao chép các file cấu hình
multiconnect-compose.ymlvàdb.envtừ thư mục Cài đặt vào thư mục~/bizmà bạn đã tạo ở Bước 1. - Để thiết lập với cơ sở dữ liệu Postgres, hãy sao chép các file cấu hình
multiconnect-compose.ymlvàdb.envtừ thư mục Cài đặt Postgres vào thư mục~/bizmà bạn đã tạo ở Bước 1.
Bước 3: Đặt biến môi trường WA_API_VERSION
Bạn nên đặt biến môi trường WA_API_VERSION thành phiên bản hiện tại bằng:
export WA_API_VERSION=current-whatsapp-version
Bước 4: Khởi động Ứng dụng API WhatsApp Business có Độ sẵn sàng cao
Để khởi động cụm có Độ sẵn sàng cao với 1 vùng chứa cơ sở dữ liệu, 1 vùng chứa Webapp, 2 vùng chứa Master và 2 vùng chứa Coreapp trong nền như sơ đồ trong phần Giới thiệu về chế độ Sẵn sàng cao, hãy chạy lệnh sau:
docker-compose -f multiconnect-compose.yml up -d db waweb master1 master2 wacore1 wacore2
Phản hồi sẽ tương tự như sau:
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
Bước 5: Xác minh rằng vùng chứa đang chạy
Bạn có thể kiểm tra để đảm bảo rằng tất cả vùng chứa đều có trạng thái UP bằng cách chạy:
docker-compose -f multiconnect-compose.yml ps
Phản hồi sẽ tương tự như sau:
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
Theo mặc định, vùng chứa Webapp sẽ chạy trên cổng 9090 và vùng chứa cơ sở dữ liệu sẽ chạy trên cổng 33060.
Bước 6: Kiểm tra sự cố
Bạn có thể tải xuống và cấu hình Bộ sưu tập Postman của chúng tôi để tương tác với API WhatsApp Business nếu không muốn sử dụng dòng lệnh.
Bạn có thể tiến hành kiểm tra sự cố trên ứng dụng API WhatsApp Business bằng cách dùng lệnh gọi API đến nút health.
Phản hồi sẽ tương tự như sau:
{
"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."
}
]
}
}
}
Phản hồi sẽ hiển thị gateway_status là unregistered với vai trò là gateway_status của vùng chứa Master chính vì chưa đăng ký ứng dụng API WhatsApp Business.
Bước 7: Đăng ký ứng dụng API WhatsApp Business
Bạn có thể đăng ký ứng dụng API WhatsApp Business bằng lệnh gọi API đến nút account.
Bước 8: Kiểm tra sự cố lần 2
Tiến hành kiểm tra sự cố một lần nữa trên ứng dụng API WhatsApp Business bằng lệnh gọi API đến nút health sau khi hoàn tất quá trình đăng ký và đảm bảo một trong các vùng chứa Coreapp có gateway_status là connected.
Phản hồi sẽ tương tự như sau:
{
"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"
}
}
}
Lưu ý: Ở chế độ Sẵn sàng cao, chỉ một Coreapp (trong ví dụ này là wacore1) được kết nối với máy chủ WhatsApp, tất cả các nút khác, kể cả Master chính, đều sẽ có gateway_status là disconnected. Nếu wacore1 gặp sự cố, wacore2 sẽ thay thế và kết nối với máy chủ WhatsApp để duy trì chế độ Sẵn sàng cao.
Giờ đây, bạn đã thiết lập ứng dụng API WhatsApp Business ở chế độ Sẵn sàng cao. Ở chế độ này, chỉ một Coreapp có thể kết nối với máy chủ WhatsApp để gửi tin nhắn ở bất kỳ thời điểm nào định sẵn. Nếu muốn có nhiều Coreapp gửi tin nhắn cùng lúc để tăng lưu lượng tin nhắn, hãy làm theo các bước trong phần Thiết lập cụm Đa kết nối có độ sẵn sàng cao ở bên dưới.
Thiết lập cụm Đa kết nối có độ sẵn sàng cao
Bước 1: Thiết lập 2 đoạn
Sử dụng điểm cuối đoạn để thiết lập 2 đoạn. Bạn sẽ thấy phản hồi HTTP có trạng thái 201 Created.
Bước 2: Kiểm tra sự cố
Bạn có thể tiến hành kiểm tra sự cố trên ứng dụng API WhatsApp Business bằng cách dùng lệnh gọi API đến nút health.
Phản hồi sẽ tương tự như sau:
{
"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"
}
}
}
Lưu ý: Ở chế độ Đa kết nối với 2 đoạn, 2 Coreapp (trong ví dụ này làwacore1 và wacore2) sẽ được kết nối với máy chủ WhatsApp, đồng thời Master chính (trong ví dụ này là master2) cũng kết nối với máy chủ WhatsApp.
Bước 3: Khởi động Coreapp thứ 3 để duy trì chế độ Sẵn sàng cao
Cho đến giờ, trong ví dụ này, bạn có 2 vùng chứa Coreapp và số lượng tin nhắn được phân chia giữa 2 vùng chứa đó. Tuy nhiên, nếu một trong 2 vùng chứa Coreapp gặp sự cố thì một nửa lượng tin nhắn sẽ không gửi được. Để duy trì chế độ Sẵn sàng cao trong bản thiết lập Đa kết nối mới này, bạn có thể khởi động một Coreapp thứ ba để hỗ trợ 1 Coreapp bị lỗi, như ở sơ đồ nêu trong phần Giới thiệu về chế độ Đa kết nối.
Để khởi động vùng chứa Coreapp thứ ba, hãy chạy lệnh sau:
docker-compose -f multiconnect-compose.yml up -d wacore3
Phản hồi sẽ tương tự như sau:
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
Bước 4: Kiểm tra sự cố lần 2
Tiến hành kiểm tra sự cố một lần nữa để xác minh rằng tất cả nút đều hoạt động bình thường bằng lệnh gọi API đến nút health.
Phản hồi sẽ tương tự như sau:
{
"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"
}
}
}
Vùng chứa Coreapp mới (trong ví dụ này là wacore3) hiện đóng vai trò là vùng chứa dự phòng nhưng chưa được kết nối với máy chủ WhatsApp. Nếu wacore1 hoặc wacore2 ngừng hoạt động, wacore3 sẽ kết nối với máy chủ WhatsApp để duy trì số đoạn chung là 2.
Nâng cấp ứng dụng API WhatsApp Business
Thời gian ngừng hoạt động sẽ xảy ra trong quá trình nâng cấp.
Bạn nên sao lưu các cài đặt ứng dụng hiện tại trước khi nâng cấp để đảm bảo có thể nhanh chóng sao lưu và chạy. Vui lòng xem Tài liệu hướng dẫn sao lưu và khôi phục.
Vì vậy, bạn nên thực hiện nâng cấp vào những lúc rảnh nhất.
Bước 1: Thay đổi biến môi trường WA_API_VERSION thành phiên bản mới
Bạn phải cập nhật biến môi trường WA_API_VERSION thành số phiên bản mới bằng:
export WA_API_VERSION=new-whatsapp-version
Bước 2: Khởi động lại các vùng chứa Docker
Khởi động lại các vùng chứa Docker bằng cách chạy:
docker-compose -f multiconnect-compose.yml up -d
Đối với người dùng cơ sở dữ liệu MySQL nâng cấp lên v2.23.x trở lên
Giờ bạn có thể sử dụng dịch vụ nâng cấp cơ sở dữ liệu để nâng cấp cơ sở dữ liệu của mình trong khi ứng dụng vẫn đang chạy nhằm tránh trường hợp ngừng hoạt động.
Bước 1: Tải file cấu hình xuống
File dbupgrade-compose.yml có các trường thông tin cho biết phiên bản vùng chứa.
Ví dụ:
services:
dbupgrade:
image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}
Bước 2: Khởi động vùng chứa
Để nâng cấp bản cài đặt, hãy khởi động vùng chứa dbupgrade-service khi đặt biến môi trường WA_API_VERSION thành phiên bản mới nhất:
WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d
Lưu ý: Nếu bạn sử dụng một tổ hợp sẽ khởi động lại vùng chứa khi thoát, bất kể mã thoát là gì, hãy khởi động dịch vụ sau khi đặt biến môi trường EXIT_ON_SUCCESS thành FALSE để tránh thoát khỏi vùng chứa khi mã thoát là 0.
Bước 3: Chờ quá trình nâng cấp hoàn tất
Nếu nâng cấp cơ sở dữ liệu thành công, vùng chứa sẽ thoát với mã 0. Để theo dõi trạng thái, bạn có thể sử dụng lệnh Docker sau:
docker wait your-database-upgrade-container-name
Lệnh này sẽ trả về mã thoát của vùng chứa dbupgrade-service.
Bước 4: Khởi động lại các vùng chứa Coreapp và Webapp
Khởi động lại các vùng chứa Coreapp và Webapp Docker khi đặt biến môi trường WA_API_VERSION thành phiên bản mới nhất:
WA_API_VERSION=new-whatsapp-version docker-compose -f multiconnect-compose.yml up -d
Gỡ cài đặt ứng dụng API WhatsApp Business
Bạn nên sao lưu các cài đặt ứng dụng hiện tại của mình trước khi gỡ cài đặt. Vui lòng xem Tài liệu hướng dẫn sao lưu và khôi phục.
Nếu bạn cần gỡ tất cả các vùng chứa để đặt lại môi trường phát triển, hãy chạy lệnh sau từ thư mục chứa file multiconnect-compose.yml:
docker-compose -f multiconnect-compose.yml down
Để loại bỏ tất cả dung lượng được xác định trong file multiconnect-compose.yml ngoài các vùng chứa, hãy chạy lệnh down bằng thông số -v:
docker-compose -f multiconnect-compose.yml down -v
Khắc phục sự cố
Để thu thập nhật ký từ tất cả vùng chứa, hãy chạy lệnh sau:
docker-compose -f multiconnect-compose.yml logs > debug_output.txt
Để thu thập nhật ký của một dịch vụ cụ thể, hãy thêm tên dịch vụ (ví dụ: waweb, master1, wacore1) vào lệnh docker-compose logs:
docker-compose -f multiconnect-compose.yml logs waweb > debug_output.txt
Bạn có thể tìm nhật ký trong file debug_output.txt ở thư mục hiện tại.
Phần mềm này sử dụng mã FFmpeg được cấp phép theo LGPLv2.1 và bạn có thể tải xuống nguồn của mã này tại đây.