在代码中使用 Square Cloud,支持 JavaScript、Python 和 Go

Square Cloud API 的官方 SDK。在你自己的脚本中部署、重启、查看日志、编辑文件、创建快照和设置域名,运行时零依赖。

已在 GitHub 上开源,每种语言的方法和错误都完全一致。

选择语言并安装

四个官方包:三个用于 Square Cloud API,一个用于 Blob Storage。每个包只需要对应语言的运行时。

  • JavaScript 和 TypeScript

    @squarecloud/api

    Node.js 22+、Deno、Bun 和边缘运行时

    npm install @squarecloud/api

    文档源代码

  • Python

    squarecloud-api

    Python 3.11+,提供同步和异步客户端

    pip install squarecloud-api

    文档源代码

  • Go

    github.com/squarecloudofc/sdk-api-go/v3

    Go 1.22+,每次调用都接受 context

    go get github.com/squarecloudofc/sdk-api-go/v3

    文档源代码

  • Blob Storage

    @squarecloud/blob

    Node.js 20+ 和浏览器

    npm install @squarecloud/blob

    文档源代码

第一次调用

创建一个 API 密钥,将其设为 SQUARECLOUD_API_KEY 环境变量,然后运行下面任意一个程序。程序会输出你的名字,以及该密钥可以看到多少个应用。

index.mjs
import { SquareCloudAPI } from "@squarecloud/api";const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);const { user, applications } = await api.account.me();console.log(`Hi ${user.name}, you have ${applications.length} apps`);
main.py
import osfrom squarecloud import SquareCloudwith SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client:    me = client.account.me()    print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")
main.go
package mainimport (	"context"	"fmt"	"log"	"os"	"github.com/squarecloudofc/sdk-api-go/v3")func main() {	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))	me, err := c.Account.Me(context.Background())	if err != nil {		log.Fatal(err)	}	fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications))}

API 能做的一切,都能在代码中完成

JavaScript、Python 和 Go SDK 覆盖 API 参考中的所有操作,每次 CI 运行都会对照其 OpenAPI 规范进行检查。下方的方法名以 JavaScript 为例,Python 使用 snake_case,Go 使用 PascalCase。

  • 应用

    查看单个或全部应用的状态,启动、停止和重启应用,并获取日志以及 CPU、内存和网络指标。

    apps.statusAllapps.restartapps.logsapps.metrics

  • 部署

    从 zip 创建应用,向其提交新文件,关联 GitHub 仓库和分支或设置 Webhook,并列出过往部署。

    apps.createapps.commitdeploys.linkGithubApp

  • 文件与变量

    列出、读取、写入、移动和删除应用的文件,并获取、设置或替换其环境变量。

    files.writefiles.readenvs.set

  • 实时

    以可循环遍历的迭代器实时跟踪应用的日志和状态。连接中断后会自动重新建立。

    apps.realtime

  • 快照

    为应用和数据库创建、列出并恢复快照,还能以流的方式下载快照文件。

    snapshots.createsnapshots.restoredownloadSnapshot

  • 网络

    设置自定义域名,读取其 DNS 记录,清除缓存,并按时间范围查询分析、错误和性能数据。

    network.setDomainnetwork.purgeCachenetwork.analytics

  • 数据库

    创建 MongoDB、PostgreSQL、MySQL 和 Redis 数据库,调整内存,查看状态,并重置密码或证书。

    databases.createdatabases.resetCredentials

  • 工作区

    创建工作区,通过邀请码添加成员,更改成员的分组,并与团队共享应用。

    workspaces.members.addworkspaces.apps.add

  • AI

    使用同一个客户端和同一个密钥,向 Square Cloud AI Gateway 发送兼容 OpenAI 的聊天请求。

    ai.chat

在 JavaScript 中使用 Blob Storage

@squarecloud/blob 是 Blob Storage 的 SDK:上传、私有文件、分享链接、文件夹规则以及兼容 S3 的网关,可在 Node.js 和浏览器中使用。 了解 Blob Storage

  • 大文件上传

    传入文件路径、Blob 或字节即可。大文件会从磁盘流式读取,分片并行上传,最大 10 GiB。

    putlist

  • 私有文件

    私有文件没有公开 URL。你可以创建会过期的下载链接,或随时可撤销的分享链接。

    downloadUrlshares.createshares.revoke

  • 从浏览器上传

    由你的服务器创建短时有效的上传令牌,浏览器用它上传,API 密钥始终不会离开你的服务器。

    uploadTokens.create

每种语言,同样的构建方式

  • 零依赖

    每个 SDK 只使用其语言的标准库或平台自带的 fetch,不会往你的锁文件里添加任何其他内容。

  • 统一的错误类型

    所有 API、网络和本地错误都抛出同一个错误类,并附带 HTTP 状态码和 API 的错误代码。

  • 安全的重试

    每次尝试 30 秒超时,只对可以安全重复的失败进行重试,遇到 429 绝不重试。

  • 限定范围的密钥

    密钥可以只授予部分权限,并限定到特定的应用或数据库。列表只返回该密钥能看到的内容。

项目每个阶段都有合适的套餐

从小规模开始,按需扩展,无绑定合约。

4.9 分(满分 5 分)· Google + Trustpilot 上的 402 条评价Trustpilot

托管于持有以下认证的合作数据中心
Tier 3ISO 27001SOC 2 Type IIAlways-On DDoS 防护
了解我们的基础设施

关于 SDK 的常见问题

哪些语言有官方的 Square Cloud SDK?

JavaScript 和 TypeScript(@squarecloud/api)、Python(squarecloud-api)以及 Go(github.com/squarecloudofc/sdk-api-go)。Blob Storage 有单独的 JavaScript SDK:@squarecloud/blob。四个 SDK 都在 GitHub 上开源。

SDK 覆盖整个 API 吗?

是的。JavaScript、Python 和 Go SDK 覆盖 Square Cloud API 参考中的所有操作,外加快照下载,并在每次 CI 运行时对照其 OpenAPI 规范进行检查。Blob Storage 及其兼容 S3 的网关由 @squarecloud/blob 提供支持。

使用 SDK 需要哪个套餐?

SDK 本身是开源包。它们调用的 API 包含在 Square Cloud 的所有套餐中,从 Hobby 起即可使用,每分钟的请求数取决于套餐。

API 密钥应该存放在哪里?

放在 SQUARECLOUD_API_KEY 环境变量中,切勿写进源代码。每个密钥只授予它所需的权限和资源;一旦泄露,请在账户的安全设置中将其撤销。

可以在浏览器中使用 SDK 吗?

API SDK 面向服务器:Node.js、Deno、Bun、边缘运行时、Python 和 Go。在浏览器中使用会暴露 API 密钥。如需从浏览器上传,@squarecloud/blob 会使用由你的服务器创建的短时上传令牌。

我在用旧版本,有哪些变化?

当前版本经过重写:方法挂在客户端上,响应是使用 API 原有字段名的纯数据,所有失败都只有一种错误类型。每个 SDK 的文档都提供从上一个主版本迁移的指南。

SDK、CLI 还是 GitHub Action,该用哪个?

调用写在代码里时用 SDK,比如重启应用的机器人命令,或创建快照的脚本。在终端中用 CLI,每次推送都要部署时用 GitHub Action。

准备好让你的项目 扩展 了吗?

加入超过 50 万名曾使用 Square Cloud 托管项目的开发者。

  • 可预期的价格
  • 账单无惊喜
  • 秒级部署
  • 高可用性
  • 稳定扩展
  • 自动重启
  • 含 SSL 与安全防护
  • 隔离容器