部署 Evolution API（WhatsApp API）

简介

要在 Square Cloud 上开发和托管 Evolution API，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。

前置条件

Square Cloud 账户：通过注册页面使用你的邮箱进行注册。
有效套餐：为你的应用提供专属资源和优化的性能。查看我们可用的套餐，选择最适合你需求的方案。

为什么使用 Evolution API？

Evolution API 是一个开源的 WhatsApp API。它通过 Web 管理器或 REST API 在一处管理多个 WhatsApp 实例，并将它们连接到 n8n、Chatwoot 和 Typebot 等工具。

搭建项目

从我们的 evolutionapi-web releases 下载项目，其中已经包含在 Square Cloud 上部署所需的文件；也可以从官方仓库下载。

官方仓库将 typescript 列在 devDependencies 中。Square Cloud 以生产模式安装依赖，不安装 devDependencies，因此 npm run build 步骤会失败。我们的 release 已经将它移到 dependencies；使用官方仓库时，请自行移动。

Evolution API 在启动时会读取项目根目录的 .env 文件，因此该文件要放进你的 ZIP。请以我们 release 中的 .env（或官方仓库中的 .env.example）为基础，编辑下面的变量。在控制面板的 Environment Variables 中设置的变量优先于 .env 文件，因此控制面板更适合存放 AUTHENTICATION_API_KEY 和 DATABASE_CONNECTION_URI 等密钥。请参阅环境变量。

数据库配置

Evolution API 需要一个 PostgreSQL 数据库。如果你拥有 Standard 或更高的套餐，可以在 Square Cloud 上托管一个：请参阅如何创建并连接托管数据库。创建后，在 .env 中将它的 URL 设置为 DATABASE_CONNECTION_URI，并配置 PostgreSQL 连接的客户端证书。以下是所需配置的示例：

.env

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI='postgresql://squarecloud:password@host:port/database?sslmode=require&sslidentity=path/to/client-identity.p12&sslpassword=p12password'
DATABASE_CONNECTION_CLIENT_NAME='evolution_exchange'
DATABASE_SAVE_DATA_INSTANCE=true
DATABASE_SAVE_DATA_NEW_MESSAGE=true
DATABASE_SAVE_MESSAGE_UPDATE=true
DATABASE_SAVE_DATA_CONTACTS=true
DATABASE_SAVE_DATA_CHATS=true
DATABASE_SAVE_DATA_LABELS=true
DATABASE_SAVE_DATA_HISTORIC=true
DATABASE_SAVE_IS_ON_WHATSAPP=true
DATABASE_SAVE_IS_ON_WHATSAPP_DAYS=7
DATABASE_DELETE_MESSAGE=true

Evolution API 通过 Prisma 连接数据库，而 Prisma 需要 .p12 格式的客户端证书。从控制面板中数据库的页面下载证书文件（.crt 和 .key），转换后将 .p12 放入你的项目：

openssl pkcs12 -export -out client-identity.p12 -inkey <certificate>.key -in <certificate>.crt

你选择的导出密码就是 URL 中的 sslpassword，sslidentity 则是 .p12 文件的路径。请将 .p12 保留在 ZIP 中，因为应用会从磁盘读取它。设置好环境变量和证书后，在数据库上应用迁移。在你电脑上的项目文件夹中，用 npm install 安装依赖（它需要 runWithProvider.js 文件），然后运行以下命令：

Windows
Linux

npm run db:deploy:win

npm run db:deploy

服务器配置

如仓库的 .env.example 文件所示，设置服务器变量：SERVER_TYPE、SERVER_PORT、SERVER_URL 以及语言。

.env

SERVER_NAME=evolution
SERVER_TYPE=http
SERVER_PORT=80
# Your application's URL: https://<subdomain>.squareweb.app, or your custom domain
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE=en
# Other variables below...

Evolution API 从 SERVER_PORT（而不是 PORT）读取端口，未设置时回退到 8080，因此请保留 SERVER_PORT=80。配置一个安全的全局 API 密钥以避免未经授权的访问非常重要。请将它替换为你自己的长随机值：示例文件中的密钥是公开的。

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

配置 Square Cloud

在项目根目录创建 squarecloud.app 文件。START 命令会生成 Prisma 客户端、构建项目并启动它；安装和构建大约需要 3072 MB 的 RAM：

squarecloud.app

DISPLAY_NAME=Evolution API
RUNTIME=nodejs
START=npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod
MEMORY=3072
VERSION=recommended
SUBDOMAIN=my-evolution-api
AUTORESTART=true

SUBDOMAIN 必须与 SERVER_URL 中的地址一致。通过控制面板上传时，请选择 “Web Publication”，设置相同的子域名，并将 START 命令粘贴为启动命令。

部署

通过控制面板

访问上传页面

访问上传页面并上传你的项目 zip 文件。

配置你的环境

上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。
如果你上传的是 Web 项目，请务必选择 “Web Publication” 并为项目设置子域名。

部署你的项目

最后，点击 “Deploy” 按钮，即可将项目托管到 Square Cloud。
部署完成后，你可以在控制面板中监控项目的状态和日志。

确认你的应用已上线

首次部署通常在一分钟内完成。在控制面板中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。
如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

通过 CLI

要使用此方法，你的项目根目录中需要有一个名为 squarecloud.app 的配置文件。它告诉 Square Cloud 如何运行你的应用。

配置文件指南

了解如何创建定义你应用环境的 squarecloud.app 配置文件。

安装 CLI

安装 Square Cloud CLI。如果你已经安装，运行同一条命令即可更新：

curl -fsSL https://cli.squarecloud.app/install | bash

npm install -g @squarecloud/cli@latest

运行下面的命令。它会打开你的浏览器：在浏览器中批准登录后，CLI 即可使用。无需复制任何 API 密钥。如需在脚本和 CI 中使用，请参阅 CLI 身份验证。

squarecloud auth login

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip（排除 squarecloud.ignore 中列出的内容）并上传：

squarecloud upload

要上传你自己创建的 zip，请通过 --file 传入：

squarecloud upload --file <path/to/zip>

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

squarecloud app status
squarecloud app logs

如果你部署的是网站或 API，请在浏览器中打开 https://<your-subdomain>.squareweb.app，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。

应用无法启动？请参见故障排除指南，了解最常见的原因和解决方法。

附加信息

首次运行后，你可以将 RAM 降低到 1536MB 或 2048MB，并将启动命令仅设置为：

npm run start:prod

缓存系统

你可以在 Evolution API 中配置缓存系统。为此，你需要一个 Redis 数据库，你同样可以在 Square Cloud 上托管它。
要配置它，你还需要下载证书并设置连接 URL。请注意 rediss:// 协议：Square Cloud 数据库只接受 TLS 连接。

.env

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="rediss://default:MySecurePassword@square-cloud-db-ID.squareweb.app:7170"
CACHE_REDIS_TTL=604800
# Prefix serves to differentiate data from one installation to another that are using the same redis
CACHE_REDIS_PREFIX_KEY=evolution
# Enabling this variable will save the connection information in Redis and not in the database.
CACHE_REDIS_SAVE_INSTANCES=false

故障排查

自定义域名

若要使用自定义域名（例如 mysite.com）来代替默认 URL mysite.squareweb.app，你需要 Standard 计划或更高等级。默认 URL 由配置文件中的 SUBDOMAIN 字段决定。要连接你的域名，请参阅如何设置自己的域名。

最低内存要求

网站和 API 的最低要求为 512MB RAM，足以在静态运行时上托管静态构建产物。对于在服务器上渲染页面的应用（Next.js、Nuxt、Angular SSR 等），我们建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

找不到此站点。

请检查子域名/域名是否与 SUBDOMAIN 字段或自定义域名设置中配置的内容一致。如果你刚上传站点，请等待最多 60 秒，让 Square 启用首次访问。

站点响应超时……

你的服务器必须监听端口 80 和主机 0.0.0.0。Square Cloud 会在你的应用中设置 PORT（80）和 HOST（0.0.0.0）环境变量：请在代码中读取它们，而不要硬编码其他值。只监听 localhost 或 127.0.0.1 的服务器永远收不到请求。

后续步骤

托管数据库

创建 Evolution API 所需的 PostgreSQL 数据库。

数据库连接错误

修复 SSL/TLS 和连接错误。

WhatsApp 机器人

使用 whatsapp-web.js 或 Baileys 构建单个 WhatsApp 机器人。

联系我们

如果你仍然遇到技术问题，我们的专业支持团队可以为你提供帮助。联系我们，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud 4.9/5 评分（共 402 条评价）（Google 与 Trustpilot）的重要原因之一。

Bots

网站

API 与后端

数据库

自托管应用

指南

迁移指南

部署 Evolution API（WhatsApp API）

简介

前置条件

为什么使用 Evolution API？

搭建项目

数据库配置

服务器配置

配置 Square Cloud

部署

通过控制面板

通过 CLI

配置文件指南

附加信息

缓存系统

故障排查

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

后续步骤

托管数据库

数据库连接错误

WhatsApp 机器人

联系我们

​简介

​前置条件

​为什么使用 Evolution API？

​搭建项目

​数据库配置

​服务器配置

​配置 Square Cloud

​部署

​通过控制面板

​通过 CLI

配置文件指南

​附加信息

​缓存系统

​故障排查

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​后续步骤

托管数据库

数据库连接错误

WhatsApp 机器人

​联系我们

简介

前置条件

为什么使用 Evolution API？

搭建项目

数据库配置

服务器配置

配置 Square Cloud

部署

通过控制面板

通过 CLI

附加信息

缓存系统

故障排查

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

后续步骤

联系我们