WhatsApp Business 开放平台本地 API

生产环境设置：单一实例

本文档将向您介绍如何在生产环境中设置 WhatsApp Business API 客户端的单一实例。

如果您尚未执行此操作，我们建议您根据开发者设置：单一实例的说明，在开发者机器中设置 WhatsApp Business API 用户端的单一实例，以便在生产环境中按照本文档的说明设置 WhatsApp Business API 用户端前，测试您的设置。

准备工作

如果您已运行开发者设置并希望在生产环境中使用相同的手机号，请先参阅迁移指南，然后继续阅读本指南的剩余内容。

本文档中的内容均基于使用新手机号进行重新安装的假设。

您将需要使用：

必须使用 MySQL 5.7.xx 或 PostgreSQL 10.6/9.6.x/9.5.x。

您的数据库密码不应包含以下任何字符：?{}&~!()^=

违反此项要求可能会导致设置失败。

MySQL 8 还存在一个已知的兼容性问题。请暂时不要使用最新版本，我们正在积极修复相关问题。

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 Machine 的某个目录下。或者，您也可选择将媒体卷挂载至主机目录下。如要更改媒体卷的挂载点，请将 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 步：执行运行状况检查

如果不希望使用命令行，您可以下载并配置 Postman 收藏夹，以与 WhatsApp Business API 进行互动。

您可以在 WhatsApp Business API 客户端上使用 API 调用 health 节点，以执行运行状况检查。

所得输出结果应如下所示：

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

由于 WhatsApp Business API 客户端尚未注册，因此响应会将 unregistered 的 gateway_status 显示为 gateway_status。

第 9 步：注册 WhatsApp Business API 客户端

您可以使用 API 调用 account 节点，以注册 WhatsApp Business API 客户端。

第 10 步：再次执行运行状况检查

完成注册后，在 WhatsApp Business API 客户端上使用 API 调用 health 节点，以再次执行运行状况检查。

所得输出结果应如下所示：

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

如果 gateway_status 为 connected，则表示核心应用容器已能够连接至 WhatsApp 服务器，可用于检查联系人和发送消息。

建议您为生产环境下的 WhatsApp Business API 客户端设置监控程序。

升级 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

针对升级至版本 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 文件中定义的所有卷，请使用 -v 参数运行 down 命令：

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

疑难解决

建议使用 WADebug，以便更有效地解决问题。WADebug 是一个命令行工具，可助您找到 WhatsApp Business API 设置中的任何潜在问题，并让您更有效地向 WhatsApp 支持团队请求帮助。

在无法使用 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 文件中找到相应记录。

此软件使用受 LGPLv2.1 许可证保护的 FFmpeg 代码，点击此处即可下载源代码。