# @computesdk/gcp 中文文档

规范地址：https://npmcn.com/package/%40computesdk/gcp/

版本：0\.1\.12
npm 元数据更新时间：2026-11-07T03:30:18.219Z
中文译文更新时间：2026-11-10T14:32:16.387Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40computesdk/gcp
原文对照：https://npmcn.com/package/%40computesdk/gcp/?lang=original
项目主页：https://www.computesdk.com/
源码仓库：https://github.com/computesdk/computesdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：218 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-10-13T14:19:51.984Z
- 最新版本发布：2026-11-07T03:30:18.010Z
- 近 30 天下载量：9468（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

计算SDK( Cloud Run Sandboxs) 的谷歌云供应商

## 安装

```sh
npm install @computesdk/gcp
```

也可以使用：`pnpm add @computesdk/gcp`、`yarn add @computesdk/gcp`、`bun add @computesdk/gcp`

## README

# @ computesdk/ gcp (帮助)

Google 云供应商 [计算SDK](https://computesdk.com/)。每个 Google Cloud 产品是一个子路径导出:

| 子路径 | 导出 | 产品 |
| --- | --- | --- |
| `@computesdk/gcp/cloud-run` | `cloudRun` | 云跑沙盒 |

## 云运行

```typescript
import { cloudRun } from '@computesdk/gcp/cloud-run'
```

Cloud Run Sandboxs目前处于β状态,需要您的GCP项目被Cloud Run团队允许上市.

此软件包支持两种模式:

-   远程模式: 使用网关云运行服务 `npx -p @computesdk/gcp computesdk-cloud-run`,然后使用 `CLOUD_RUN_SANDBOX_URL` 财务报告和审定财务报表 `CLOUD_RUN_SANDBOX_SECRET`。 。 。 .
-   直接模式 : 在部署的 Cloud Run 服务内运行您的应用程序 `--sandbox-launcher`,然后拨打容器中沙盒CLI `/usr/local/gcp/bin/sandbox`。 。 。 .

## 安装

```bash
npm install @computesdk/gcp
```

## 设置远程网关

设置您的 GCP 项目和区域, 然后运行设置命令 :

```bash
export CLOUD_RUN_PROJECT_ID="your-gcp-project"
export CLOUD_RUN_REGION="us-central1"

npx -p @computesdk/gcp computesdk-cloud-run
```

设置命令使用 `gcloud` 改为:

-   构建一个小的计算SDK网关容器.
-   调用到云跑 `--sandbox-launcher` 财务报告和审定财务报表 `--no-cpu-throttling`。 。 。 .
-   配置低纬度沙盒执行的网关, 带有 1 CPU, 2Gi 内存, 货币 20 ()`CLOUD_RUN_CONCURRENCY`页:1.
-   允许非认证的云运行引用 `--allow-unauthenticated`。 。 。 .
-   生成网关认证的无记名符号 .
-   打印运行时环境变量 .

默认情况下,网关执行每个计算SDK命令 `sandbox do`。计算SDK沙盒对象是一个逻辑手柄,用于在呼叫之间携带环境变量和工作目录等配置。 设定 `executionMode: 'stateful'` 用于 `sandbox run`, (中文(简体) ), `sandbox exec`,以及 `sandbox delete` 用于持续沙盒会话.

执行模式控制 SDK 如何向 Cloud Run 沙盒 CLI 映射 :

| SDK 方法 | 以弗模式( 默认) | 状态模式 |
| --- | --- | --- |
| `create()` | 只创建本地逻辑控件 | 电话 `sandbox run --write --detach <id>` (闲置可写会话) |
| `create({ snapshotId })` | —— 说 | 电话 `sandbox run --write --import-tar <snapshot> --detach <id>` |
| `runCommand()` | 电话 `sandbox do -- /bin/sh -c <command>` | 电话 `sandbox exec <id> -- /bin/sh -c <command>` |
| `runCommand(cmd, { onStdout })` | 从流出 `sandbox do` | 从流出 `sandbox exec` |
| `destroy()` | 仅删除本地簿记 | 电话 `sandbox delete --force <id>` |
| `snapshot.create(id)` | —— 说 | 电话 `sandbox tar --file=<snapshot> <id>` |
| `filesystem` | 运行每个操作 `sandbox do` | 运行每个操作 `sandbox exec <id>` |

将打印值添加到您的应用环境 :

```bash
CLOUD_RUN_SANDBOX_URL=https://computesdk-sandbox-...run.app
CLOUD_RUN_SANDBOX_SECRET=...
```

先决条件:

-   您的GCP项目是允许的 云跑沙盒.
-   `gcloud` 已安装、更新和认证.
-   Cloud Build和 Cloud run API为项目启用.
-   您的组织政策允许公众云跑 引用者,或呼叫者必须提供 `CLOUD_RUN_AUTH_TOKEN`。 。 。 .

### 公共网关访问

远程网关设计为云跑地层公用并被保护 `CLOUD_RUN_SANDBOX_SECRET` 用于沙盒操作。 Public Cloud Run access 避免要求每个SDK的调用者将一个Google身份标志薄荷.

设置命令通过 `--allow-unauthenticated`。如果您的组织以 `constraints/iam.allowedPolicyMemberDomains`,部署可用IAM警告成功,但服务仍需要 Cloud Run IAM 认证. 在这种情况下,允许 `allUsers` 作为 `roles/run.invoker` 用于此网关服务或设置 `CLOUD_RUN_AUTH_TOKEN` 转到网关 URL 的 Google 签名身份标志 .

## 手动直接部署

用沙盒发射器部署您的服务已启用 :

```bash
gcloud beta run deploy my-sandbox-service \
  --image=gcr.io/$PROJECT_ID/my-sandbox-service:latest \
  --region=$REGION \
  --project=$PROJECT_ID \
  --sandbox-launcher \
  --no-cpu-throttling
```

沙盒二进制仅在 Cloud Run 容器中可用 `--sandbox-launcher` 启用 .

## 远程使用

```typescript
import { cloudRun } from '@computesdk/gcp/cloud-run'

const compute = cloudRun({
  sandboxUrl: process.env.CLOUD_RUN_SANDBOX_URL,
  sandboxSecret: process.env.CLOUD_RUN_SANDBOX_SECRET,
})

const sandbox = await compute.instances.create()

const result = await sandbox.runCommand('echo hello')
console.log(result.stdout)

await sandbox.destroy()
```

### 国家执行

远程沙盒默认为 `ephemeral`: 每个命令和文件系统操作 使用新鲜的沙盒. 使用 `executionMode: 'stateful'` 关于提供者或 `sandbox.create()` 当文件必须在呼叫之间持续时(包括 单独 `mkdir` 接下来是 `writeFile`) (中文(简体) ). A. 对工作指南的修改 贝壳 `cd` 不更改后续命令的起始目录; 设置 `workdir` 或者通过命令 `cwd` 当然.

状态沙盒是本地到网关实例,按会话亲和度排列, 如果重启, 则丢失 。 抓图保存根fs状态, 不 过程或内存,并排除 `/tmp` 和挂起的路径。 恢复为 `allowEgress: true` 在本地的"云跑"发射器中也会失败,即使相同 GCS快照在不入地还原. 超时不能证明本地 创建已停止; 已更新的网关尝试被限制删除失败 仅在网关分配该ID时才会创建精确的ID. 打电话者提供的身份证 在创建失败后从未自动删除 : `sandbox exec` 报告 "不跑"并不能证明没有本地身份证. SDK 不创建 `name` 让网关分配ID。 原始创建错误仍然 已经返回.

```typescript
import { cloudRun } from '@computesdk/gcp/cloud-run'

const compute = cloudRun({
  sandboxUrl: process.env.CLOUD_RUN_SANDBOX_URL,
  sandboxSecret: process.env.CLOUD_RUN_SANDBOX_SECRET,
  executionMode: 'stateful',
  write: true,
})

const sandbox = await compute.instances.create()
await sandbox.runCommand('echo hello > /tmp/hello.txt')
const result = await sandbox.runCommand('cat /tmp/hello.txt')
console.log(result.stdout)
await sandbox.destroy()
```

## 直接使用

```typescript
import { cloudRun } from '@computesdk/gcp/cloud-run'

const compute = cloudRun({
  persistDir: '/tmp/cloud-run-sandbox',
  write: true,
})

const sandbox = await compute.instances.create({
  envs: { NODE_ENV: 'production' },
})

const result = await sandbox.runCommand('echo hello')
console.log(result.stdout)

await sandbox.destroy()
```

## 配置

| 选项 | 新闻 var | 默认 | 说明 |
| --- | --- | --- | --- |
| `sandboxUrl` | `CLOUD_RUN_SANDBOX_URL` |  | 远程模式已部署网关服务的 URL |
| `sandboxSecret` | `CLOUD_RUN_SANDBOX_SECRET` |  | 已部署网关服务的接线符 |
| `gatewayAuthToken` | `CLOUD_RUN_AUTH_TOKEN` |  | 启用 Cloud 运行 IAM 认证时可选的 Google 身份标识符 |
| `sizeGateways` | `CLOUD_RUN_SANDBOX_URL_<SIZE>`, (中文(简体) ), `CLOUD_RUN_SANDBOX_SECRET_<SIZE>` |  | 每个标准大小的网关`xs`, (中文(简体) ), `sm`, (中文(简体) ), `md`, (中文(简体) ), `lg`, (中文(简体) ), `xl`,用于 `sizeClass` 创建; 秘密默认为 `sandboxSecret` |
| `executionMode` |  | `ephemeral` | 使用 `ephemeral` 页:1 `sandbox do` 或者说 `stateful` 页:1 `sandbox run`编号 :`exec`编号 :`delete` |
| `sandboxBinary` | `CLOUD_RUN_SANDBOX_BINARY` | `/usr/local/gcp/bin/sandbox` | 云跑沙盒 CLI 路径 |
| `mode` |  | CLI 默认 | 沙盒 CLI 模式, `local` 或者说 `container` |
| `allowEgress` |  | `false` | 允许沙盒网络进取 |
| `rootfs` |  | `/` | 接触沙盒的根文件系统 |
| `workdir` |  | CLI 默认 | 默认工作目录 |
| `template` |  |  | Cloud 运行容器模板名称 |
| `persistDir` |  |  | 用于持久文件系统状态的主机路径 |
| `overlayDir` |  |  | 可写入的覆盖目录 |
| `write` |  | `false` | 允许挂载的文件系统可写 |
| `mounts` |  | `[]` | 带子挂起 `--mount` |
| `env` |  | `{}` | 新沙盒会话的环境变量 |
| `globalArgs` |  | `[]` | 额外的 CLI 全球参数 |
| `runArgs` |  | `[]` | 额外参数 `sandbox do` 财务报告和审定财务报表 `sandbox run` |
| `execArgs` |  | `[]` | 额外参数 `sandbox exec` 状态模式 |

## 页:1

命令使用电平 `sandbox do` 默认执行。 只有当您的 Cloud Run sandbox CLI 配置支持主机支持的持久性( 如) 时, 文件系统才会保存 `--persist-dir`启用 `executionMode: 'stateful'` 当您需要脱去的沙盒会话时 `sandbox run` 并重新使用 `sandbox exec`。 。 。 .

### 沙盒图像

沙盒以网关图像为根文件系统,以根运行. 由设置构建的图像包括 `git`, (中文(简体) ), `python3`, (中文(简体) ), `unzip`, (中文(简体) ), `curl` 和 CA 证书,并保留 apt 软件包列表,这样可以写沙盒 `apt-get install` 再来 沙盒不能切换用户,所以将下载作为 root 和 `sudo` 是直接运行命令的shim。 网络访问`git clone`, (中文(简体) ), `apt-get`, (中文(简体) ), `curl`需求 `allowEgress: true`。 。 。 .

### 抓图

`compute.snapshot.create(sandboxId)` 导出状态沙盒的可写 rootf 覆盖 `sandbox tar`· ; `compute.sandbox.create({ snapshotId })` 从它开始一个新的状态沙盒。 源出相续. 下方的文件 `/tmp` 财务报告和审定财务报表 `--mount` 路径不包含,运行的过程和内存也不保存. 快照存储在 `gs://$CLOUD_RUN_SNAPSHOT_BUCKET/computesdk-snapshots/` 当网关有 `CLOUD_RUN_SNAPSHOT_BUCKET` 设置( 设置创建桶并授予服务运行时间服务账户) `roles/storage.objectAdmin`),否则在捕捉到它们的网关实例上.

### 网关实例

一个精致的沙盒 住在创建它的地方 提供商重播Cloud Run的会话配乐 所以后续呼叫到达了这个实例;亲和是最好的努力,所以保持 `--session-affinity` 备忘 `--concurrency` 在服务。 网关删除状态沙盒闲置 `CLOUD_RUN_SANDBOX_IDLE_TIMEOUT_MS` (默认一小时, `0` 禁用; 以相同的变量在部署时设置它 , 绝不在命令运行期间 。 快照,恢复和活流需要当前网关;针对这些特性之前部署的网关,快照调用失败并有重新部署提示,流出输出在命令出站时到达.

### 大小

云头 运行沙盒没有自己的CPU或内存控制:它们共享 `--cpu`编号 :`--memory` 他们运行的网关实例。 因此,每个规模都是自己的网关服务。 每个大小部署一个 `CLOUD_RUN_SIZE=<size> npx -p @computesdk/gcp computesdk-cloud-run`部署 `computesdk-sandbox-<size>` 时间 `xs` 1个vCPU/1 GiB, `sm` 1个vCPU/2 GiB, `md` 2 vCPU/4 GiB, (英语), `lg` 4 vCPU/8 GiB或 `xl` 8 vCPU/16 GiB 有1个温暖的例子和指纹 `CLOUD_RUN_SANDBOX_URL_<SIZE>`。 。 。 . `compute.sandbox.create({ sizeClass: 'lg' })` (或 `{ vcpus: 4, memoryMiB: 8192 }`然后在那个网关上运行。 网关显示其大小 `/v1/health`。没有配置网关的大小、部署在不同大小的网关,以及 `2xl` (Cloud Run express out at 8 vCPU) 全部失败 `sizeClass:` 错误而不是运行另一个大小 。 一个实例上的沙盒分享它的CPU和内存,所以使用低 `CLOUD_RUN_CONCURRENCY` 当每个沙盒需要整个尺寸.

`getUrl()` 不支持, 因为当前 Cloud run sandbox CLI 不曝光 per- sandbox 端口.

## CI 与工作量身份联合会

当Cloud Run IAM auth被启用后,CI需要为网关URL提供由Google签名的ID标志. 一些联邦证书无法使用 `gcloud auth print-identity-token` 直接; 使用 IAM 证书 `generateIdToken` 带有联邦访问标志:

```bash
ACCESS_TOKEN="$(gcloud auth print-access-token)"
SERVICE_URL="$(gcloud run services describe computesdk-sandbox --region=$CLOUD_RUN_REGION --project=$CLOUD_RUN_PROJECT_ID --format='value(status.url)')"

CLOUD_RUN_AUTH_TOKEN="$(node -e '
const [accessToken, audience, serviceAccount] = process.argv.slice(1)
fetch(`https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${serviceAccount}:generateIdToken`, {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({ audience, includeEmail: true }),
}).then(r => r.json()).then(j => process.stdout.write(j.token))
' "$ACCESS_TOKEN" "$SERVICE_URL" "$CLOUD_RUN_SERVICE_ACCOUNT")"
```

必须允许联邦校长冒充 `CLOUD_RUN_SERVICE_ACCOUNT` 和薄荷OpenID的标志.

## 常见问题

### @computesdk/gcp 是什么？

计算SDK\( Cloud Run Sandboxs\) 的谷歌云供应商

### 如何安装 @computesdk/gcp？

在项目目录运行 npm install @computesdk/gcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 computesdk-cloud-run，可以用 npx computesdk-cloud-run 直接运行。

### @computesdk/gcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @computesdk/gcp 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @computesdk/gcp 可以商用吗？

@computesdk/gcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @computesdk/gcp 的下载量有多少？

根据 npm 官方下载统计，@computesdk/gcp 在 2026/10/11 – 2026/11/09 这 30 天内被下载 9,468 次，日均约 316 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @computesdk/gcp 还在维护吗？

最新版本 0\.1\.12 发布于 2026/11/07（3 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。