Skip to main content

简介

  • 本指南假设你已在 top.gg 上拥有一个已通过审核的机器人,并且你的项目使用 Node.js 或 Python。
  • 接下来,你需要在 Square Cloud 上创建一个账户,这可以通过注册页面完成。你可以使用你的电子邮件来创建账户。
  • 最后,你的账户需要有一个有效方案。请比较可用方案,并根据你的需求选择一个。

设置环境

  1. 在开始之前,请确保你的系统上已安装 Node.js 和 npm。如果你还没有安装,可以从 Node.js 官方网站下载。
  2. 使用以下命令启动一个新的 Node.js 项目并启用 import 语法:
Terminal
这些命令会在当前目录中创建一个 package.json 文件。
  1. 安装 Express:
Terminal

设置项目

1. 获取你的 webhook 密钥:
  • 选择你的应用程序在 Square Cloud 上使用的子域名(配置文件中的 SUBDOMAIN 字段),例如 mysite。这样你的 webhook URL 就是 https://mysite.squareweb.app/topgg。
  • 在 Top.gg 上打开你项目的控制面板,进入 Webhooks。
  • 粘贴 webhook URL 并保存。随后 Top.gg 会生成一个以 whs_ 开头的 webhook 密钥:复制它并妥善保密。你的代码会从 TOPGG_WEBHOOK_SECRET 环境变量中读取它。
Top.gg 会用 x-topgg-signature 请求头为每个请求签名,格式为 t=<timestamp>,v1=<signature>,其中签名是用你的密钥对 <timestamp>.<raw body> 计算的 HMAC SHA-256。下面的代码会重新计算签名,并拒绝任何不匹配的请求,这样其他人就无法向你的 URL 发送伪造的投票。详情请参见 Top.gg webhook 文档。
本指南使用 Top.gg v1 webhook。旧版 v0 webhook 会在 Authorization 请求头中发送密码,且负载格式不同,这里不作介绍。
2. 实现 webhook 监听器: 以下部分提供了 Javascript 和 Python 两种代码示例:
该示例使用 Node 内置的 crypto 模块验证签名,因此不需要任何 Top.gg 包。这里没有使用 @top-gg/sdk 4.0.0 的 Webhook 类:在我们的测试中,它的监听器会对有效的投递返回超时错误,导致 Top.gg 重试这些投递。
index.js

创建 squarecloud 配置文件

在你的项目文件夹中创建一个 squarecloud.app 文件。将 SUBDOMAIN 设置为你在第 1 步中选择的子域名:
SUBDOMAIN 会将监听器发布在 https://mysite.squareweb.app,而 Web 应用至少需要 MEMORY=512。代码监听 PORT 环境变量中的端口(Square Cloud 将其设为 80)和主机 0.0.0.0。

了解:如何为 Square Cloud 创建配置文件。

squarecloud.app 文件是一个配置文件,用于配置你的应用程序;它将用于定义名称、描述、版本、主文件等内容。

将你的应用程序上传到 Square Cloud

完成所有步骤后,你的项目文件夹中应包含你的代码、依赖文件(package.json 或 requirements.txt)以及配置文件。如果要通过控制面板上传,请将它们放入一个 .zip 文件中。 如果你的应用程序是 Node.js 项目,请查看我们关于 Node.js 的文章。 如果你的应用程序是 Python 项目,请查看我们关于 Python 的文章。

通过控制面板

1

访问上传页面

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

配置你的环境

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

部署你的项目

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

确认你的应用已上线

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

通过 CLI

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

配置文件指南

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

安装 CLI

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

登录

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

上传你的项目

在项目文件夹中运行下面的命令。CLI 会将当前文件夹打包为 zip(排除 squarecloud.ignore 中列出的内容)并上传:
要上传你自己创建的 zip,请通过 --file 传入:
4

确认你的应用已上线

首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志:
如果你部署的是网站或 API,请在浏览器中打开 https://<your-subdomain>.squareweb.app,你应该能看到应用正常响应。如果你部署的是机器人,发送一条命令确认它已上线。
应用无法启动?请参见故障排除指南,了解最常见的原因和解决方法。

设置 webhook 密钥

通过以下任一方式,将你的 whs_ 密钥添加为应用程序的 TOPGG_WEBHOOK_SECRET 环境变量:
  • 控制面板:在上传页面打开 Advanced configuration,在部署前添加该变量。对于已部署的应用程序,请在其 Environment Variables 页面添加。
  • CLI:在项目文件夹中,使用 squarecloud app env set 设置它并重启应用程序:
应用程序在启动时读取环境变量,因此每次修改后都要重启它。在设置密钥之前,代码会以 401 Unauthorized 拒绝所有请求。管理环境变量的其他方式请参阅环境变量。

开始测试

如果你正确地完成了所有操作,请在浏览器中打开 https://mysite.squareweb.app/topgg(将 mysite 替换为你的子域名)。如果出现 “Cannot GET /topgg”(Node.js)或 “Method Not Allowed”(Python),说明一切正常:该路由只接受 Top.gg 发送的 POST 请求。
  • 对于我们使用 app.post("/topgg", ...) 创建的 JavaScript 代码,接收投票的路由是 “/topgg”。因此,如果你的网站是 mysite.squareweb.app,Webhook URL 就是 https://mysite.squareweb.app/topgg。
  • 对于我们使用 @app.route("/topgg", methods=["POST"]) 创建的 Python 代码,接收投票的路由同样是 “/topgg”。因此,Webhook URL 也是相同的 https://mysite.squareweb.app/topgg。
最后,回到 Top.gg 上你项目的 Webhooks 页面,点击 “Send Test” 按钮。之后,检查应用程序的日志。如果一切顺利,你在 console.log 或 print 中定义的消息应该会出现在日志中。
Top.gg webhook 发送测试示例
这样,如果一切都配置正确,你的 webhook 就准备好在你的机器人在 top.gg 上收到投票时发送通知了。

故障排除

自定义域名

若要使用自定义域名(例如 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 的服务器永远收不到请求。

后续步骤

Discord 机器人

托管接收投票的机器人。

环境变量

管理你的 webhook 密钥和其他密钥。

应用无法启动

修复端口冲突、缺少模块和其他启动失败问题。

联系我们

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