Go SDK：管理应用

本页的所有方法都位于 c.Apps 上，第一个参数为 ctx，其次是应用 ID。appID 也可以是通过 workspace 共享的应用的组合 ID <appId>-<workspaceId>。下面的每个代码片段都可以在这个程序中单独运行：每次将一个片段粘贴到 main 中，然后运行 goimports（参见运行示例）。

package main

import (
	"context"
	"os"

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

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}

要列出你的应用，请使用 c.Account.Me：它的 Applications 切片包含该密钥可见的所有应用。

获取应用

app, err := c.Apps.Get(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(app.ID, app.Name, app.Language, app.RAM, app.Cluster, app.CreatedAt)

字段	类型	说明
`ID`（`id`）	`string`	应用 ID
`Name`（`name`）	`string`	显示名称
`Description`（`desc`）	`string`	描述，未设置时为 `""`
`Owner`（`owner`）	`string`	所有者的用户 ID
`Cluster`（`cluster`）	`string`	应用运行所在的集群
`RAM`（`ram`）	`int`	分配的 RAM（MB）
`Language`（`language`）	`string`	运行时语言
`Domain`（`domain`）	`*string`	默认的 `<subdomain>.squareweb.app` 主机；非 Web 应用为 `nil`
`Custom`（`custom`）	`*string`	自定义域名；未设置时为 `nil`
`CreatedAt`（`created_at`）	`time.Time`	创建日期

状态

Status(ctx, appID) 返回带有格式化值的实时状态：

status, err := c.Apps.Status(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(status.Status)  // e.g. "running", "exited"
fmt.Println(status.Running) // true
fmt.Println(status.CPU)     // "0.5%"
fmt.Println(status.RAM)     // "120.4MB" (RAM in use)
fmt.Println(status.Storage, status.Network.Total, status.Network.Now)
if status.Uptime != nil {
	fmt.Println(*status.Uptime) // Unix ms of the last start; nil when stopped
}

StatusRaw(ctx, appID) 则返回数字（CPU 为百分比，RAM 为 MB，Storage 为字节，Network.Total 和 Network.Now 为 [in, out] 字节对）：

raw, err := c.Apps.StatusRaw(ctx, appID)
if err != nil {
	log.Fatal(err)
}

fmt.Println(raw.CPU, raw.RAM, raw.Network.Total) // 0.5 120.4 [1024 2048]

Uptime 是一个时间戳（应用启动的时刻），而不是持续时长。使用 time.Since(time.UnixMilli(*status.Uptime)) 计算它已运行了多久。

所有应用的状态

StatusAll(ctx, workspaceID) 在单个请求中为该密钥可见的每个应用返回一份摘要。传入 "" 表示所有应用，或者传入某个 workspace 的 ID，只获取该 workspace 的应用。CPU 和 RAM 仅在应用运行时才有值（不为 ""）。

items, err := c.Apps.StatusAll(ctx, "")
if err != nil {
	log.Fatal(err)
}
for _, it := range items {
	if it.Running {
		fmt.Println(it.ID, it.CPU, it.RAM)
	} else {
		fmt.Println(it.ID, "stopped")
	}
}

启动、停止和重启

if err := c.Apps.Start(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Stop(ctx, appID); err != nil {
	log.Fatal(err)
}
if err := c.Apps.Restart(ctx, appID); err != nil {
	log.Fatal(err)
}

服务器会保持这些调用的连接直到容器执行完动作，因此在 ctx 没有截止时间的情况下，它们至少等待 2 分钟才会超时。当平台拒绝该操作时，调用会返回 *APIError，状态为 409，带有 Code 和空的 Message：

代码	含义
`CONTAINER_ALREADY_STARTED`	对正在运行的应用执行 `start`
`CONTAINER_ALREADY_STOPPED`	对已停止的应用执行 `stop`
`CONTAINER_TEMPORARILY_SUSPENDED`	应用已被暂停
`CONTAINER_NOT_FOUND`	容器在集群上不存在
`CONTAINER_INSUFFICIENT_DISK_SPACE`	磁盘空间不足，无法启动
`CONTAINER_NETWORK_CONFLICT`	集群上存在网络冲突
`ACTION_FAILED`	集群无法执行该操作

“已启动”和“已停止”同样是错误。如果对你而言它们意味着成功，请自行处理：

err := c.Apps.Start(ctx, appID)

var apiErr *squarecloud.APIError
if err != nil && !(errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeContainerAlreadyStarted) {
	log.Fatal(err)
}

日志

Logs(ctx, appID) 以单个字符串返回最新的控制台输出（没有输出时为 ""）。

logs, err := c.Apps.Logs(ctx, appID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(logs)

如需实时日志流，请使用实时。

指标

Metrics(ctx, appID) 返回最近 24 小时的数据，每 5 分钟一个数据点，最新的在前。

points, err := c.Apps.Metrics(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(points) > 0 {
	latest := points[0]
	fmt.Println(latest.Date, latest.CPU, latest.RAM, latest.Net)
}

域名和负载均衡器

Domains(ctx) 列出每个应用的默认主机名和自定义主机名。LoadBalancers(ctx) 列出由多个应用共享的域名，以及你的套餐限额。

domains, err := c.Apps.Domains(ctx)
if err != nil {
	log.Fatal(err)
}
for _, d := range domains {
	fmt.Println(d.AppID, d.Hostname, d.Type) // Type: "subdomain" | "custom"
}

lb, err := c.Apps.LoadBalancers(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(lb.Limit)
for _, balancer := range lb.Balancers {
	ids := make([]string, 0, len(balancer.Apps))
	for _, app := range balancer.Apps {
		ids = append(ids, app.ID)
	}
	fmt.Println(balancer.Hostname, ids)
}

要设置自定义域名，请参见网络。

删除应用

if err := c.Apps.Delete(ctx, appID); err != nil {
	log.Fatal(err)
}

删除是永久性的。如果你可能还需要这些文件，请先创建一个 snapshot。

后续步骤

Commit 与上传

用 zip 创建应用，或向应用发送文件。

应用 API 参考

这些方法背后的 REST 端点。

用 CLI 管理应用

在终端中完成同样的操作。

CLI

VS Code

SDKs

获取应用

状态

所有应用的状态

启动、停止和重启

日志

指标

域名和负载均衡器

删除应用

后续步骤

Commit 与上传

应用 API 参考

用 CLI 管理应用

​获取应用

​状态

​所有应用的状态

​启动、停止和重启

​日志

​指标

​域名和负载均衡器

​删除应用

​后续步骤

Commit 与上传

应用 API 参考

用 CLI 管理应用

获取应用

状态

所有应用的状态

启动、停止和重启

日志

指标

域名和负载均衡器

删除应用

后续步骤