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

# 在线扩容 Sandbox

> 使用 PPIO SDK 或 CLI 扩容运行中的 Sandbox，查看各项资源结果，查询当前资源与配额。

使用 `resize` 可以在不重启 Sandbox 的情况下增加 CPU、内存和磁盘。参数表示目标**总量**，不是新增量。启动前配置资源请参阅[创建 Sandbox](https://ppio.com/docs/sandbox/sandbox.md#指定-cpu内存和磁盘)。

本功能要求所使用的 SDK（JavaScript/TypeScript 或 Python）或 CLI 版本为 2.1.4+。

> [!NOTE]
>
> 已有进程可能需要重启或调整自身配置，才能使用新增资源。例如，JVM 通过 `-Xmx` 设置的堆内存上限，以及启动时设定大小的固定线程池，不一定会随扩容自动增大。

## 扩容运行中的 Sandbox

至少指定一项资源，未传字段保持不变。请替换为运行中的 Sandbox ID，并根据[当前资源与配额](#查询当前资源与配额)选择目标值。

```python Python theme={null}
from ppio_sandbox import Sandbox

sandbox = Sandbox.connect("YOUR_SANDBOX_ID")
result = sandbox.resize(cpu=4, memory_gib=8)

for name, item in result.items():
    print(name, item["status"], item.get("current"))
    if item["status"] in ("failed", "unknown"):
        print(name, item.get("reason") or item.get("message"))
```

```typescript JavaScript & TypeScript theme={null}
import { Sandbox } from 'ppio-sandbox'

const result = await Sandbox.resize(
  'YOUR_SANDBOX_ID',
  { cpu: 4, memoryGiB: 8 },
)

for (const [name, item] of Object.entries(result)) {
  if (!item) continue
  console.log(name, item.status, item.current)
  if (item.status === 'failed' || item.status === 'unknown') {
    console.error(name, item.reason ?? item.message)
  }
}
```

```bash CLI theme={null}
ppio sandbox resize <sandboxID> --cpu 4 --memory-gib 8

# 磁盘目标总量需在配额范围内；JSON 输出便于脚本逐项检查。
ppio sandbox resize <sandboxID> --disk-gib 40 --output json
```

## 资源取值与单位

| 资源 | JavaScript | Python | CLI | 目标单位 |
| - | - | - | - | - |
| CPU | `cpu` | `cpu` | `--cpu` | vCPU，仅支持 1、2、4、8、16、32，不支持 3、5 等其他取值 |
| 内存 | `memoryGiB` | `memory_gib` | `--memory-gib` | GiB |
| 磁盘 | `diskGiB` | `disk_gib` | `--disk-gib` | GiB |

* 所有值必须为正数且表示绝对总量。例如 `memoryGiB: 8` 表示总计 8 GiB，不是增加 8 GiB。
* CPU 与内存配比支持 2c1g（CPU:内存为 1:0.5），最大配比为 1:2。
* 资源只能增加，不能缩小。目标等于当前值时返回 `skipped`；目标小于当前值时该项失败。
* 扩容后的内存和磁盘总量必须是整数 GiB。保持已有非整数 GiB 规格不变时，可以使用精确对应整数 MiB 的值。

## 处理部分成功

每项资源独立返回结果。例如 CPU 扩容成功时，内存仍可能失败。失败项**不会回滚**已成功的资源。

> [!WARNING]
>
> 必须逐项检查 `status` 和 `current`。SDK 调用正常返回或 CLI 退出码为 0，都不表示所有资源已扩容成功。

SDK 结果包含所请求资源的条目（`cpu`、`memory`、`disk`）。CLI 使用 `--output json` 时，各项结果位于 `resources` 对象中。`requested`、`previous` 和 `current` 分别是目标总量、调用前总量和调用后总量；CPU 单位为核，内存和磁盘为 GiB。

| status | 含义与处理方式 |
| - | - |
| `applied` | 目标总量已生效。 |
| `skipped` | 原本已是该总量，无需变更。 |
| `failed` | 该项未扩容，查看 `reason` 和 `message`。 |
| `unknown` | 结果尚未确认，稍后[查询 Sandbox 详情](#查询当前资源与配额)，不要将返回的总量视为最终结果。 |

对于失败项，检查目标值是否满足[资源取值要求](#资源取值与单位)和[配额限制](https://ppio.com/docs/sandbox/quota-limits.md)。请求级错误仍可能抛出 SDK 异常或使 CLI 以非零退出码结束。

## 查询当前资源与配额

Sandbox 详情与列表中的 CPU 单位为核，内存和磁盘单位为 **MiB**，与扩容参数及结果中的 **GiB** 不同。选择目标值前，请先查询当前资源与配额。

```python Python theme={null}
from ppio_sandbox import Sandbox

sandbox = Sandbox.connect("YOUR_SANDBOX_ID")
info = sandbox.get_info()
print(info.cpu_count)     # 核
print(info.memory_mb)     # MiB
print(info.disk_size_mb)  # MiB

quota = Sandbox.get_quota()
print(quota.limit.max_vcpu, quota.usage.concurrent_vcpu)
```

```typescript JavaScript & TypeScript theme={null}
import { Sandbox } from 'ppio-sandbox'

const info = await Sandbox.getInfo('YOUR_SANDBOX_ID')
console.log(info.cpuCount)   // 核
console.log(info.memoryMB)   // MiB
console.log(info.diskSizeMB) // MiB

const quota = await Sandbox.getQuota()
console.log(quota.limit.maxVcpu, quota.usage.concurrentVcpu)
```

```bash CLI theme={null}
ppio sandbox info <sandboxID>
ppio sandbox list
ppio sandbox quota
```

## 计费说明

CPU 和内存扩容生效后，从生效时刻起按新的规格计费。磁盘在 Sandbox 运行期间不收取费用；暂停后，存储费用按扩容后的磁盘容量计算。

## 常见问题

### 必须新建 Template 才能修改资源吗？

不需要。创建时可以通过 `resources` 指定资源；对于已运行的 Sandbox，可以使用 `resize` 扩容。前者未传的字段采用 Template 默认值，后者未传的字段保持当前值。

### 命令没有报错，为什么内存仍未增加？

请查看内存项的 `status`。`failed` 时根据 `reason` 和 `message` 排查，`unknown` 时稍后查询详情确认。不要仅通过 CLI 退出码判断是否全部成功。

### 返回 400、403、404、409 或 412 时如何处理？

结合错误信息排查，不要直接重复提交相同请求：

* `400`：请求参数或资源值不合法。检查是否至少指定一项资源，以及目标值、单位和格式是否符合[资源取值要求](#资源取值与单位)。
* `403`：请求被拒绝。检查账号或 API Key 对实例的访问权限，并按返回的错误信息处理；若错误明确提示配额不足，再检查[配额](https://ppio.com/docs/sandbox/quota-limits.md)或申请提高配额。
* `404`：实例不存在或当前不可用。核对 Sandbox ID，确认实例仍然存在且当前账号可访问。
* `409`：请求与另一个操作冲突。[查询 Sandbox 详情](#查询当前资源与配额)，确认实例处于运行状态，并在冲突操作结束后重试。
* `412`：前置状态条件不满足。[查询 Sandbox 详情](#查询当前资源与配额)，确认实例处于可扩容的运行状态后再重试。

### 扩容失败后，实例和资源会怎样？

某个资源返回 `failed` 时，不会停止实例，也不会回滚已经扩容成功的资源；失败资源保持原规格。对于请求级错误或 `unknown` 结果，请[查询 Sandbox 详情](#查询当前资源与配额)，确认当前实例状态和资源规格。

### 支持缩容吗？为什么磁盘不能调小？

不支持。`resize` 只允许增加资源，CPU、内存和磁盘都不能缩小。如果需要更小的磁盘，请[新建 Sandbox 并指定合适的磁盘容量](https://ppio.com/docs/sandbox/sandbox.md#指定-cpu内存和磁盘)，目标容量仍需满足 Template 最小规格和配额限制。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.