Thiết lập trong môi trường chính thức: Độ sẵn sàng cao và Đa kết nối

Tài liệu này hướng dẫn bạn cách thiết lập một cụm có Độ sẵn sàng cao trong môi trường chính thức. 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.

Trước khi bạn bắt đầu bất kỳ cách thiết lập nào nêu trên, hãy xem các yêu cầu của chúng tôi.

Cách thiết lập cụm có Độ sẵn sàng cao:

1. Tạo thư mục biz cho các tập lệnh thiết lập
2. Tải file cấu hình ứng dụng API WhatsApp Business
3. Đặt biến môi trường cơ sở dữ liệu
4. Thiết lập ổ đĩa file phương tiện cục bộ
5. Khởi động ứng dụng API WhatsApp Business
6. Xác minh rằng vùng chứa đang chạy
7. Kiểm tra sự cố
8. Đăng ký ứng dụng API WhatsApp Business
9. Kiểm tra sự cố lần 2

Cách thiết lập cụm Đa kết nối có độ sẵn sàng cao:

1. Thiết lập 2 đoạn
2. Kiểm tra sự cố
3. Khởi động coreapp thứ 3 để duy trì Độ sẵn sàng cao
4. Kiểm tra sự cố lần 2

Sau khi thiết lập hoàn chỉnh phiên bản, bạn có thể chọn nâng cấp phiên bản đó. Để gỡ cài đặt ứng dụng, hãy làm theo các bước sau.

Trước khi bạn bắt đầu

Bạn sẽ cần:

• Nhiều máy chủ điện toán để chạy các thành phần khác nhau của ứng dụng API WhatsApp Business (ví dụ: Webapp, Master và Coreapp)

  • Vui lòng tham khảo câu hỏi Các yêu cầu về hệ thống máy chủ để chạy ứng dụng API WhatsApp Business là gì? trong phần Câu hỏi thường gặp để biết các yêu cầu về hệ thống.
  • Để thiết lập phiên bản có Độ sẵn sàng cao trong môi trường chính thức, bạn nên có ít nhất 1 máy cho vùng chứa Webapp, 2 máy cho vùng chứa Coreapp và 2 máy cho vùng chứa Master. Dung lượng trên các Master khá nhẹ nên bạn có thể đặt đồng thời các vùng chứa Master và Coreapp trên cùng một máy chủ.
• Cài đặt Docker Desktop và Docker Compose.
• Một máy chủ cơ sở dữ liệu độc lập chạy quy trình MySQL hoặc PostgreSQL

  • Máy chủ cơ sở dữ liệu không được chạy trên bất kỳ máy chủ điện toán nào khác lưu trữ ứng dụng API WhatsApp Business và chỉ được chậm hơn vài mili giây so với các máy chủ điện toán khác.

• Một hệ thống file dùng chung (ví dụ: NFS) được liên kết với thư mục cục bộ trên tất cả máy chủ Webapp, Master và Coreapp, nếu bạn muốn hỗ trợ gửi và nhận tin nhắn có chứa file phương tiện

  • Đảm bảo 755 được đặt làm chế độ file trên đường dẫn liên kết và tất cả thư mục con của đường dẫn đó.

mkdir your-local-media-volume-path
mount -t nfs nfs_server_IP_addr:/shared_directory /your-local-media-volume-path

Thiết lập cụm có độ 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: Lấy file cấu hình ứng dụng API WhatsApp Business

Sao chép các file cấu hình prod-multiconnect-compose.yml và db.env từ thư mục Cài đặt của kho lưu trữ GitHub WhatsApp-Business-API-Setup-Scripts vào thư mục ~/biz mà bạn đã tạo ở Bước 1.

Bước 3: Đặt biến môi trường cơ sở dữ liệu

Thay đổi các biến môi trường cơ sở dữ liệu trong file db.env thuộc thư mục ~/biz để phản ánh cấu hình MySQL/PostgreSQL của bạn.

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

Bước 4: Thiết lập ổ đĩa file phương tiện cục bộ

Ổ đĩa file phương tiện cục bộ (whatsappMedia:/usr/local/wamedia theo mặc định) được xác định trong file prod-docker-compose.yml được dùng để lưu trữ file phương tiện. Theo mặc định, ổ đĩa này được liên kết với thư mục trên máy Docker. Ngoài ra, bạn có thể chọn liên kết ổ đĩa file phương tiện với thư mục máy chủ. Để thay đổi điểm liên kết của ổ đĩa file phương tiện, hãy sửa đổi định nghĩa ổ đĩa trong phần services từ whatsappMedia thành đường dẫn của thư mục máy chủ mà bạn đang sử dụng.

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

Bước 5: Khởi động ứng dụng API WhatsApp Business

Để khởi động ứng dụng API WhatsApp Business có 1 vùng chứa Webapp, 2 vùng chứa Master và 2 vùng chứa Coreapp tương tự như sơ đồ trong phần Giới thiệu về Độ sẵn sàng cao, hãy sử dụng các lệnh sau với những thay đổi cần thiết cho môi trường của bạn (ví dụ: tên máy chủ, tên người dùng máy chủ và đường dẫn cục bộ):

# 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

Tóm lại, các lệnh nêu trên sẽ:

• Sao chép các file cấu hình prod-multiconnect-compose.yml và db.env vào tất cả máy chủ Webapp (trong ví dụ này là your-webapp-hostname) rồi khởi động dịch vụ waweb trên những máy chủ này;
• Sao chép các file cấu hình prod-multiconnect-compose.yml và db.env vào tất cả máy chủ Master (trong ví dụ này là your-master1-hostname và your-master2-hostname) rồi khởi động dịch vụ Master trên những máy chủ này;
• Sao chép các file cấu hình prod-multiconnect-compose.yml và db.env vào tất cả máy chủ Coreapp (trong ví dụ này là your-coreapp1-hostname và your-coreapp2-hostname) rồi khởi động dịch vụ wacore trên những máy chủ này.

Bước 6: 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 ĐANG CHẠY bằng cách chạy:

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

Bước 7: 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 gửi lệnh gọi API đến nút health.

Phản hồi sẽ có dạng như sau:

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

Phản hồi sẽ hiển thị gateway_status là unregistered vì bạn chưa đăng ký ứng dụng API WhatsApp Business.

Bước 8: Đăng ký ứng dụng API WhatsApp Business

Bạn có thể đăng ký ứng dụng API WhatsApp Business bằng cách gửi lệnh gọi API đến nút account.

Bước 9: 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 cách gửi lệnh gọi API đến nút health sau khi hoàn tất quy 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ẽ có dạng như sau:

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

Lưu ý: Ở chế độ Độ sẵn sàng cao, sẽ chỉ có một Coreapp (trong ví dụ này là your-coreapp1-hostname:753efb1cf72c) được kết nối với máy chủ WhatsApp. Tất cả nút khác - kể cả Master chính - đều sẽ có gateway_status là disconnected. Nếu your-coreapp1-hostname:753efb1cf72c gặp sự cố, your-coreapp2-hostname:75d7355eaaaa sẽ thay thế nó và kết nối với máy chủ WhatsApp để duy trì Độ sẵn sàng cao.

Giờ thì 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 tại bất kỳ thời điểm cụ thể nào. Nếu bạn muốn có nhiều Coreapp gửi tin nhắn cùng lúc để tăng thông 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 dưới đây.

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 là 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 gửi lệnh gọi API đến nút health để xác minh rằng tất cả các nút đều đang chạy đúng cách.

Phản hồi sẽ có dạng như sau:

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

Lưu ý: Ở chế độ Đa kết nối có 2 đoạn, 2 Coreapp (trong ví dụ này là your-coreapp1-hostname:753efb1cf72c và your-coreapp2-hostname:75d7355eaaaa) sẽ được kết nối với máy chủ WhatsApp. Đồng thời, Master chính (trong ví dụ này là your-master2-hostname:8dd3f5bea27d) cũng sẽ được kết nối với máy chủ đó.

Bước 3: Khởi động Coreapp thứ 3 để duy trì Độ sẵn sàng cao

Cho đến giờ, trong ví dụ này, bạn có 2 vùng chứa Coreapp và dung 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ì Độ 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ứ 3 trên máy chủ Coreapp mới (trong ví dụ này là

) để hỗ trợ 1 Coreapp bị lỗi, tương tự 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ứ 3, hãy chạy lệnh sau:

# 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

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ả các nút đều đang chạy đúng cách bằng việc gửi lệnh gọi API đến nút health.

Phản hồi sẽ có dạng như sau:

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

Vùng chứa Coreapp mới (trong ví dụ này là your-coreapp3-hostname:23b50199bec2) 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 1 trong 2 vùng chứa Coreapp đã kết nối còn lại ngừng hoạt động, vùng chứa thứ 3 sẽ kết nối với máy chủ WhatsApp để duy trì số đoạn tổng thể là 2.

Nguyên tắc và cách làm tốt nhất

Số lượng Webapp

Để hỗ trợ 100 - 150 tin nhắn/giây, bạn nên dùng tối thiểu 2 Webapp. Nếu muốn đạt được Độ sẵn sàng cao cho Webapp, bạn có thể chạy vùng chứa Webapp trên 2 máy chủ trở lên và lưu trữ các vùng chứa đó phía sau bộ cân bằng tải, chẳng hạn như HAProxy, Nginx hoặc ELB. Thay vì truy cập vào điểm cuối của ứng dụng API WhatsApp Business thông qua https://your-webapp-hostname:your-webapp-port/, bạn nên sử dụng https://your-load-balancer-name:your-load-balancer-port/.

Số lượng Master

Bạn nên chạy 3 Master trên các máy chủ khác nhau. Cho dù bạn có bao nhiêu đoạn thì cũng không nên chạy quá 3 Master. Dung lượng trên các Master khá nhẹ nên bạn có thể đặt đồng thời các vùng chứa Master và Coreapp.

Số lượng Coreapp

Bạn nên chạy shard_number + X Coreapp trên các máy chủ khác nhau để hỗ trợ X máy chủ bị lỗi.

Nâng cấp ứng dụng API WhatsApp Business

Bạn cần cập nhật biến môi trường WA_API_VERSION thành số phiên bản mới. Chạy các lệnh sau với những thay đổi cần thiết cho môi trường của bạn (ví dụ: tên máy chủ, tên người dùng máy chủ và đường dẫn cục bộ):

# 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

Đối với những người dùng cơ sở dữ liệu MySQL nâng cấp lên phiên bản 2.23.x trở lên

Giờ đây, 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 thời gian dừng chạy.

Bước 1: Tải file cấu hình xuống

File dbupgrade-compose.yml có các trường 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 và đặt biến môi trường WA_API_VERSION thành phiên bản mới nhất:

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

Lưu ý: Nếu bạn đang 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ụ và đặ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ờ quy trình nâng cấp hoàn tất

Nếu quy trình 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 rồi đặt biến môi trường WA_API_VERSION thành phiên bản mới nhất:

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

Đối với những người dùng ứng dụng API WhatsApp Business nâng cấp lên phiên bản 2.29.3 trở lên

Nếu đang nâng cấp từ v2.29.1, v2.29.2hoặc gặp sự cố trong quá trình nâng cấp lên các phiên bản đó và phải quay về phiên bản cũ để đạt được sự ổn định, bạn nên nâng cấp lên v2.29.3 rồi chạy lệnh sau trên vùng chứa Webapp Docker:

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

Thư mục file phương tiện mặc định là /usr/local/wamedia, trừ khi bạn thay đổi.

Lưu ý:

• Vì lệnh này có thể mất một khoảng thời gian mới hoàn tất tùy theo kích thước ổ đĩa file phương tiện có sẵn, bạn nên khởi chạy lệnh này ngay sau khi nâng cấp trong khoảng thời gian bảo trì.
• Lệnh này chỉ sửa đổi quyền sở hữu ổ đĩa file phương tiện trong nền (Không ảnh hưởng đến/dừng chạy các thao tác trên file phương tiện hay ảnh hưởng đến độ trễ/hiệu suất trong khi chạy).
• Đây là đường dẫn nâng cấp chỉ dùng một lần để khắc phục các sự cố tương thích ngược trong v2.29.1 và v2.29.2.

Gỡ cài đặt ứng dụng API WhatsApp Business

Nếu bạn cần đặt lại môi trường phát triển bằng cách gỡ tất cả vùng chứa, hãy sử dụng các lệnh sau với những thay đổi cần thiết cho môi trường của bạn (ví dụ: tên máy chủ, tên người dùng máy chủ và đường dẫn cục bộ):

# 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

Khắc phục sự cố

Để thu thập nhật ký từ tất cả vùng chứa trên một máy chủ, hãy chạy lệnh sau:

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-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.

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-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.