正式版設定：單一實例

本文件將講解如何在正式版環境中設定 WhatsApp Business API 用戶端的單一實例。

如要完成初始設定，請查閱必要條件，然後按照下列步驟操作：

1. 為設定指令碼建立 biz 目錄
2. 獲取 WhatsApp Business API 用戶端配置檔案
3. 設定 WA_API_VERSION 環境變數
4. 設定資料庫環境變數
5. 設定本機影音素材磁碟區
6. 啟動 WhatsApp Business API 用戶端
7. 確認容器是否正在運行
8. 執行系統健康檢查
9. 註冊 WhatsApp Business API 用戶端
10. 執行第二次系統健康檢查

完全設定好實例後，您可以選擇升級實例。如要解除安裝用戶端，請按照這些步驟操作。

準備工作

您需要以下項目或執行相關動作：

• 安裝 Docker Desktop 和 Docker Compose
• 用於運行 WhatsApp Business API 用戶端的伺服器。如需了解系統要求，請參閱常見問題中的運行 WhatsApp Business API 用戶端的伺服器系統要求是什麼？。
• 用於運行 MySQL 或 PostgreSQL 程序的獨立資料庫伺服器。資料庫伺服器與託管 WhatsApp Business API 用戶端的伺服器之間應只有幾毫秒的延遲時間。

WhatsApp Business API 用戶端的初始設定

第 1 步：為設定指令碼建立 biz 目錄

在 WhatsApp Business API 用戶端的首選位置執行以下程式碼：

mkdir ~/biz; cd ~/biz;

第 2 步：獲取 WhatsApp Business API 用戶端配置檔案

請將 prod-docker-compose.yml 和 db.env 配置檔案從 WhatsApp-Business-API-Setup-Scripts GitHub 儲存庫的安裝目錄複製到您在第 1 步中建立的 ~/biz 目錄。

第 3 步：設定 WA_API_VERSION 環境變數

您需要使用以下程式碼，將 WA_API_VERSION 環境變數設定為當前版本：

export WA_API_VERSION=current-whatsapp-version

第 4 步：設定資料庫環境變數

更改 ~/biz 目錄下之 db.env 檔案的資料庫環境變數，以反映 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

第 5 步：設定本機影音素材磁碟區

系統會使用 prod-docker-compose.yml 檔案定義的本機影音素材磁碟區（預設為 whatsappMedia:/usr/local/wamedia）來儲存影音素材檔案。在預設情況下，系統會將磁碟區掛接在 Docker 裝置的目錄。或者，您可選擇將影音素材磁碟區掛接在主機目錄。如想更改影音素材磁碟區的掛接位置，請將 services 區段的磁碟區定義由 whatsappMedia 修改為您目前使用的主機目錄路徑。

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

第 6 步：啟動 WhatsApp Business API 用戶端

如要啟動含有 1 個網頁應用程式容器和 1 個核心應用程式容器的 WhatsApp Business API 用戶端，請運行以下程式碼：

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

所得的輸出結果應如下所示：

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

第 7 步：確認容器是否正在運行

您可以運行下列程式碼，以檢查全部容器是否均處於 UP 狀態：

docker-compose -f prod-docker-compose.yml  ps

所得的輸出結果應如下所示：

     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

在預設情況下，網頁應用程式容器會在 9090 端口上運行。

第 8 步：執行系統健康檢查

您可以在 WhatsApp Business API 用戶端上對 health 節點使用 API 呼叫，以執行系統健康檢查。

所得的輸出結果應如下所示：

{
    "health": {
        "gateway_status": "unregistered"
    }
}

由於 WhatsApp Business API 用戶端尚未註冊，因此回應會將 gateway_status 顯示為 unregistered 的 gateway_status。

第 9 步：註冊 WhatsApp Business API 用戶端

您可對 account 節點使用 API 呼叫，以註冊 WhatsApp Business API 用戶端。

第 10 步：執行第二次系統健康檢查

完成註冊後，在 WhatsApp Business API 用戶端對 health 節點使用 API 呼叫，以執行另一次系統健康檢查。

所得的輸出結果應如下所示：

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

如果 gateway_status 為 connected，即代表核心應用程式容器能夠連接至 WhatsApp 伺服器，以供檢查聯絡人和傳送訊息。

升級 WhatsApp Business API 用戶端

第 1 步：將 WA_API_VERSION 環境變數改為新版本

請使用以下程式碼，將 WA_API_VERSION 環境變數更新為新版本編號：

export WA_API_VERSION=new-whatsapp-version

第 2 步：重新啟動 Docker 容器

運行下列程式碼，以重新啟動 Docker 容器：

docker-compose -f prod-docker-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 步：啟動容器

如要升級安裝程式，請啟動 dbupgrade-service 容器，並將 WA_API_VERSION 環境變數設為最新版本：

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 步：重新啟動核心應用程式和網頁版應用程式容器

將 WA_API_VERSION 環境變數設為最新版本，並重新啟動核心應用程式和網頁版應用程式 Docker 容器：

WA_API_VERSION=new-whatsapp-version docker-compose -f prod-docker-compose.yml up -d

將 WhatsApp Business API 用戶端用戶升級至版本 2.29.3 或更高版本的方式

如果您從 v2.29.1、v2.29.2 升級，或在升級至這些版本期間遇到問題且必須回復至原有版本以確保穩定性，我們建議您升級至 v2.29.3，然後在網頁應用程式 Docker 容器上運行以下指令：

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

除非您已作出變更，否則預設影音素材目錄為 /usr/local/wamedia。

備註：

• 視乎之前的影音素材磁碟區大小，此指令需要一些時間才能完成，因此我們建議您在維護期間升級時立即開始執行此指令。
• 此指令僅會在背景修改影音素材磁碟區的擁有權（運行時不會對影音素材操作帶來影響或產生停機時間，或導致延遲/影響性能）。
• 此為一次性升級路徑，用於修正 v2.29.1 和 v2.29.2 中的向下相容問題。

解除安裝 WhatsApp Business API 用戶端

如果您需要移除所有容器以重設開發環境，請從包含 docker-compose.yml 檔案的目錄中運行以下指令：

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

所得的輸出結果應如下所示：

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

除容器以外，如要清除在 docker-compose.yml 檔案中定義的所有磁碟區，請運行 down 指令及 -v 參數：

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

解決疑難

如果無法使用 WADebug，或在運行此工具時系統傳回錯誤，請執行以下指令，以從所有容器收集記錄：

docker-compose -f prod-docker-compose.yml logs > debug_output.txt

如要收集特定服務的記錄，則請將服務名稱（waweb 或 wacore）附加至 docker-compose logs 指令：

docker-compose -f prod-docker-compose.yml logs waweb > debug_output.txt

您可以在目前目錄的 debug_output.txt 檔案中找到記錄。