如何在 Square Cloud 上部署 Evolution API

简介

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

前置条件

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

为什么使用 Evolution API？

Evolution API 提供了一种更简单的方式，将众多工具集成在一处，整合了 n8n、chatwoot 等工具。该项目允许你快速创建并通过它或它的 API 连接实例，在一处管理多个机器人实例。

搭建项目

首先，你需要从某个来源获取项目。你可以从官方仓库获取，或从我们的仓库获取，后者的 releases 中已经包含了部署所需的文件。

数据库配置

要开始搭建，我们需要一个数据库。如果你拥有 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

设置好环境变量和证书后，你需要在数据库上应用迁移。为此，你需要在项目文件夹中放置 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
# Change the SERVER_URL to your actual server URL.
# you change it to your app url, selected when creating the app
# or when set a domain
SERVER_URL="https://my-evolution-api.squareweb.app"
LANGUAGE=en
# Other variables below...

配置一个安全的全局 API 密钥以避免未经授权的访问非常重要。

.env

# Other variables...
AUTHENTICATION_API_KEY=MySuperSecureAPIKEY

部署

要在 Square Cloud 上部署它，你只需要设置启动命令并发布到 web。为了安装和构建，我们建议使用 3096MB 的 RAM。

startup command

npx prisma generate --schema prisma/postgresql-schema.prisma && npm run build && npm run start:prod

通过控制面板

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

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

通过 CLI

要使用此方法，你需要在项目根目录中创建一个名为 squarecloud.app 的配置文件。该文件将包含项目所需的配置。

配置文件指南

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

安装 CLI

首先，你的环境中需要已安装 CLI。如果尚未安装，请在终端中运行以下命令：

npm install -g @squarecloud/cli

如果你已经安装，我们建议对其进行更新。为此，请在终端中运行以下命令：

Windows
Linux、macOS 和 WSL

squarecloud update

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

进行身份验证

现在，要进行身份验证并使用其他 CLI 命令，你可以在此处点击 “Request API Key” 找到你的授权密钥。获取授权密钥后，运行以下命令：

squarecloud auth login

上传你的项目

最后，要使用 CLI 将应用部署到 Square Cloud，你需要运行以下命令：

squarecloud upload

或者，如果你手动创建了 zip 文件，可以使用：

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。

.env

CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI="redis://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 计划或更高等级。子域名由配置文件中的 SUBDOMAIN 字段定义。

最低内存要求

简单网站/API 的最低要求为 512MB RAM。对于使用框架的站点（Next.JS、React、Vue、Angular 等），我们始终建议至少 1GB RAM。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。

找不到此站点。

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

站点响应超时……

请检查你是否在应用中正确配置了端口 80 和主机 0.0.0.0。我们建议使用 Square 强制注入的环境变量：来自 .env 文件的 PORT 和 HOST。

联系我们

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

教程

Bots

现成项目

数据库

APIs

网站

迁移指南

如何在 Square Cloud 上部署 Evolution API

简介

前置条件

为什么使用 Evolution API？

搭建项目

数据库配置

服务器配置

部署

通过控制面板

通过 CLI

配置文件指南

附加信息

缓存系统

故障排查

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

联系我们

​简介

​前置条件

​为什么使用 Evolution API？

​搭建项目

​数据库配置

​服务器配置

​部署

​通过控制面板

​通过 CLI

配置文件指南

​附加信息

​缓存系统

​故障排查

​自定义域名

​最低内存要求

​找不到此站点。

​站点响应超时……

​联系我们

简介

前置条件

为什么使用 Evolution API？

搭建项目

数据库配置

服务器配置

部署

通过控制面板

通过 CLI

附加信息

缓存系统

故障排查

自定义域名

最低内存要求

找不到此站点。

站点响应超时……

联系我们