> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理应用

> 通过 Applications 接口查看、控制和操作应用 —— 状态、日志、指标、生命周期（启动、停止、重启）和删除。

本页的每个操作都位于 `rest.Rest` 客户端上：

```go theme={null}
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()

api := rest.New(client)
```

## 获取应用

`api.GetApplication(appID)` 返回完整的 `squarecloud.Application` 记录。

```go theme={null}
app, err := api.GetApplication("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(app.ID, app.Name, app.Cluster, app.CreatedAt)
```

### 应用属性

| 字段            | 类型        | 说明                                                                                                                          |
| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
| `ID`          | `string`  | 应用 ID（24 位十六进制字符）                                                                                                           |
| `Name`        | `string`  | 显示名称                                                                                                                        |
| `Description` | `string`  | 来自配置文件的描述                                                                                                                   |
| `Owner`       | `string`  | 所有者用户 ID                                                                                                                    |
| `Cluster`     | `string`  | 应用运行所在的集群                                                                                                                   |
| `RAM`         | `int`     | 分配的 RAM（MB）                                                                                                                 |
| `Language`    | `string`  | `javascript` \| `typescript` \| `python` \| `java` \| `elixir` \| `go` \| `rust` \| `ruby` \| `php` \| `dotnet` \| `static` |
| `Domain`      | `*string` | 默认的 `<subdomain>.squareweb.app` 主机名 —— 非网站应用为 `nil`                                                                         |
| `Custom`      | `*string` | 绑定到应用的自定义域名 —— 未配置时为 `nil`                                                                                                  |
| `CreatedAt`   | `string`  | 创建日期                                                                                                                        |

`Domain` 和 `Custom` 是指针 —— 解引用前务必进行 nil 检查：

```go theme={null}
if app.Domain != nil {
	fmt.Println("running at", *app.Domain)
}
```

## 获取应用状态

`api.GetApplicationStatus(appID)` 返回实时运行状态，其值为**人类可读格式**。

```go theme={null}
status, err := api.GetApplicationStatus("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "running" | "starting" | "restarting" | "exited" | "created" | "deleting"
fmt.Println(status.Running) // bool
fmt.Println(status.CPU)     // "0.50%"
fmt.Println(status.RAM)     // "120/512MB"
fmt.Println(status.Network) // formatted totals
fmt.Println(status.Storage) // e.g. "0B"

if status.Uptime != nil {
	fmt.Println(time.UnixMilli(*status.Uptime)) // started at
}
```

`Uptime` 是一个 `*int64`，保存以 Unix 毫秒表示的启动时间戳 —— 应用停止时为 `nil`。

### 原始状态

`api.GetApplicationStatusRaw(appID)` 以 `?rawData=true` 调用同一个 endpoint，返回**数值**而非格式化字符串 —— CPU/RAM 为数字，网络为 `[in, out]` 字节对。当你想要计算或绘图而非打印时使用它。

```go theme={null}
raw, err := api.GetApplicationStatusRaw("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(raw.CPU)     // 0.5
fmt.Println(raw.RAM)     // 120
fmt.Println(raw.Network) // { Total: [in, out], Now: [in, out] } in bytes
```

<Note>
  格式化状态便于展示（`"120/512MB"`）；原始状态适用于仪表盘、告警或任何算术运算 —— 将格式化字符串解析回数字是脆弱的做法。
</Note>

### 每个应用的摘要状态

为避免每个应用发一次请求，调用 `api.GetApplicationListStatus()`：

```go theme={null}
list, err := api.GetApplicationListStatus()
if err != nil {
	panic(err)
}

for _, summary := range list {
	fmt.Printf("%s → running=%v\n", summary.ID, summary.Running)
}
```

CPU 和 RAM 数值仅在应用当前处于运行中时才会出现。

## 获取日志

`api.GetApplicationLogs(appID)` 返回最近的日志输出。

```go theme={null}
logs, err := api.GetApplicationLogs("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(logs.Logs) // string
```

## 获取指标

`api.GetApplicationMetrics(appID)` 返回过去 24 小时的 CPU、RAM 和网络采样（最多 **288 个点**，每 5 分钟一个），类型为 `[]squarecloud.MetricPoint`。

```go theme={null}
metrics, err := api.GetApplicationMetrics("abc123def456abc123def456")
if err != nil {
	panic(err)
}

fmt.Println(len(metrics), "data points")
for _, point := range metrics {
	fmt.Println(point.Date, point.CPU, point.RAM, point.Net)
}
```

## 生命周期

`api.PostApplicationSignal(appID, signal)` 启动、停止或重启应用。信号是 `squarecloud.ApplicationSignal*` 常量之一：

```go theme={null}
err := api.PostApplicationSignal("abc123def456abc123def456", squarecloud.ApplicationSignalStart)
if err != nil {
	panic(err)
}

// squarecloud.ApplicationSignalStop
// squarecloud.ApplicationSignalRestart
```

## 删除应用

<Warning>
  `DeleteApplication` 会永久移除应用。除非你有 [snapshot](/zh/sdks/go/snapshots)，否则数据**无法恢复**。
</Warning>

```go theme={null}
err := api.DeleteApplication("abc123def456abc123def456")
if err != nil {
	panic(err)
}
```