Thiết lập trong môi trường chính thức: Một phiên bản

Tài liệu này hướng dẫn cách thiết lập một phiên bản của ứng dụng API WhatsApp Business trong môi trường chính thức.

Trước khi bắt đầu

Bạn cần có:

• Docker
• 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 máy chủ để chạy ứng dụng API WhatsApp Business

  • Để biết các yêu cầu về hệ thống, hãy tham khảo phần 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.
• 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 chỉ được chậm hơn vài mili giây so với máy chủ lưu trữ ứng dụng API WhatsApp Business.

Quá trình thiết lập ban đầu ứng dụng API WhatsApp Business

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

Sao chép các file cấu hình prod-docker-compose.yml và db.env từ thư mục Cài đặt của kho lưu trữ WhatsApp-Business-API-Setup-Scripts GitHub vào thư mục ~/biz mà 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: Đặ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.

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 5: Thiết lập dung lượng file phương tiện trên hệ thống

Dung lượng file phương tiện trên hệ thống (whatsappMedia:/usr/local/wamedia theo mặc định) đã xác định trong file prod-docker-compose.yml dùng để lưu trữ file phương tiện. Theo mặc định, dung lượng đượ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 dung lượng file phương tiện với thư mục lưu trữ. Để thay đổi điểm liên kết dung lượng file phương tiện, hãy sửa đổi định nghĩa về dung lượng trong phần services từ whatsappMedia thành đường dẫn của thư mục lưu trữ mà bạn đang sử dụng.

services:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ... 

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

Để khởi động ứng dụng API WhatsApp Business với 1 vùng chứa Webapp và 1 vùng chứa Coreapp, hãy chạy:

docker-compose -f prod-docker-compose.yml up -d

Phản hồi sẽ tương tự như sau:

Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

Bước 7: 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 prod-docker-compose.yml  ps

Phản hồi sẽ tương tự như sau:

     Name                    Command               State                   Ports
-------------------------------------------------------------------------------------------------
biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 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.

Bước 8: 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": {
        "gateway_status": "unregistered"
    }
}

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

Bước 9: Đă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 10: 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ý.

Phản hồi sẽ tương tự như sau:

{
    "health": {
        "gateway_status": "connected"
    }
}

gateway_status là connected nghĩa là vùng chứa Coreapp có thể kết nối với máy chủ WhatsApp để kiểm tra danh bạ và gửi tin nhắn.

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

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 prod-docker-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 prod-docker-compose.yml up -d

Đối với 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 phải vấn đề trong khi 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, sau đó 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 do dung lượng file phương tiện hiện có, bạn nên khởi chạy lệnh này ngay khi nâng cấp trong thời gian bảo trì.
• Lệnh này chỉ sửa đổi quyền sở hữu của dung lượng file phương tiện trong nền (Không có ảnh hưởng/thời gian ngừng hoạt động đối với các thao tác trên file phương tiện hoặc độ trễ/ảnh hưởng về hiệu suất trong khi chạy).
• Đây là đường dẫn nâng cấp 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 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 prod-docker-compose.yml:

docker-compose -f prod-docker-compose.yml down

Phản hồi sẽ tương tự như sau:

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done

Để loại bỏ tất cả dung lượng được xác định trong file prod-docker-compose.yml ngoài vùng chứa, hãy chạy lệnh down bằng thông số -v:

docker-compose -f prod-docker-compose.yml down -v

Khắc phục sự cố

Trong trường hợp không thể sử dụng WADebug hoặc thao tác chạy công cụ này trả về lỗi, để thu thập nhật ký từ mọi vùng chứa, hãy chạy lệnh sau:

docker-compose -f prod-docker-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ụ (waweb hoặc wacore) vào lệnh docker-compose logs:

docker-compose -f prod-docker-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.