生產設定：單一實例

本文件示範如何在生產中設定 WhatsApp Business API 用戶端的單一實例。

準備工作

必備資料：

• Docker
• Docker Compose
  

  • 該程式應包含在安裝的 Docker 內，如果沒有的話，請進行安裝。
• 執行 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 用戶端設定檔

將 WhatsApp-Business-API-Setup-Scripts GitHub 存放庫的 Installation 目錄中的 prod-docker-compose.yml 和 db.env 設定檔複製到步驟 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：執行系統健康檢查

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

輸出結果應如下所示：

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

因為 WhatsApp Business API 用戶端目前尚未註冊，gateway_status 會顯示處於 unregistered 的 gateway_status。

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

您可以使用向 account 節點發出的 API 呼叫，註冊 WhatsApp Business API 用戶端。

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

完成註冊之後，請使用向 health 節點發出的 API 呼叫，對 WhatsApp Business API 用戶端執行另一次系統健康檢查。

輸出結果應如下所示：

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

connected 的 gateway_status 代表核心應用程式容器能夠連接至 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

針對升級至 v2.23.x 及以上版本的 MySQL 資料庫使用者

您現在可以利用資料庫升級服務，該服務允許當應用程式仍在執行中時升級資料庫，以避免發生停機時間。

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

重新啟動具有將 WA_API_VERSION 環境變數設為最新版本的核心應用程式和網路應用程式 Docker 容器：

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

針對升級至 2.29.3 及以上版本的 WhatsApp Business API 用戶端使用者

如果您是從 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 用戶端

如果您需要移除所有容器以重設開發環境，請在包含 prod-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

若要清除容器和 prod-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 檔案中的記錄。