@ computesdk/ 超级服务器

Superserve 提供在孤立云中运行代码的沙盒基础设施 由烟花微VMs提供动力的环境.

安装

npm install computesdk @computesdk/superserve

设置

1. 获取您的超级服务器 API 密钥 控制台. 超级服务器.ai。 。 。 .
2. 设置环境变量 :

export SUPERSERVE_API_KEY=your_api_key_here

快速启动

import { compute } from 'computesdk';
import { superserve } from '@computesdk/superserve';

compute.setConfig({
  provider: superserve({ apiKey: process.env.SUPERSERVE_API_KEY }),
});

const sandbox = await compute.instances.create();

const result = await sandbox.runCommand('node -v');
console.log(result.stdout);

await sandbox.destroy();

或者直接给供货厂打电话:

import { superserve } from '@computesdk/superserve';

const provider = superserve({ apiKey: process.env.SUPERSERVE_API_KEY });
const sandbox = await provider.sandbox.create();

配置

superserve({
  apiKey: string,      // optional, falls back to SUPERSERVE_API_KEY
  baseUrl: string,     // optional, falls back to SUPERSERVE_BASE_URL,
                       //   then the @superserve/sdk default
  timeout: number,     // optional default auto-pause timeout (ms)
})

特征

API 参考

sandbox.create(options?)

启动一个新的微VM. 共同选项 :

await compute.instances.create({
  templateId: 'superserve/python-3.11',    // optional, defaults to superserve/base
  timeout: 60_000,                          // auto-pause timeout in ms
  envs: { API_KEY: 'value' },
  name: 'my-sandbox',
  metadata: { source: 'ci' },
});

解析模板包括: superserve/base, (中文(简体) ), superserve/python-3.11, (中文(简体) ), superserve/node-22,等等——见 超级服务器文件 完整名单.

过 snapshotId 改为 templateId 从快照启动(见 抓图) (中文(简体) ).

sandbox.runCommand(command, options?)

const result = await sandbox.runCommand('npm install', {
  cwd: '/app',
  env: { NODE_ENV: 'production' },
  timeout: 120_000,
});

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);

过 onStdout 编号 : onStderr 在命令运行时接收输出 :

await sandbox.runCommand('npm test', {
  onStdout: (data) => process.stdout.write(data),
  onStderr: (data) => process.stderr.write(data),
});

sandbox.getUrl({ port })

await sandbox.runCommand('python3 -m http.server 8000', { background: true });
const url = await sandbox.getUrl({ port: 8000 });

getUrl 发布端口并返回其预览 URL。 已公布的端口为 默认公开。 港口必须在1024至65535之间;港口49983为 保留。 对于私人预览和访问符,请使用预览 API 打开 sandbox.getInstance() ——见: 预览 URL 指南。 。 。 .

sandbox.filesystem

await sandbox.filesystem.writeFile('/app/config.json', '{"key":"value"}');
const text = await sandbox.filesystem.readFile('/app/config.json');
await sandbox.filesystem.mkdir('/app/data');
const entries = await sandbox.filesystem.readdir('/app');
const present = await sandbox.filesystem.exists('/app/config.json');
await sandbox.filesystem.remove('/app/config.json');

readFile 财务报告和审定财务报表 writeFile 直接到每个沙盒的数据平面. mkdir, (中文(简体) ), readdir, (中文(简体) ), exists,以及 remove 通过 shell 执行 运行的命令 sandbox.runCommand。 。 。 .

sandbox.getInfo() 编号 : sandbox.destroy()

const info = await sandbox.getInfo();
console.log(info.id, info.status);

await sandbox.destroy();

状态映射:超级服务器 paused 财务报告和审定财务报表 deleted 报告状态为 计算SDK的 stopped, (中文(简体) ), failed 作为 error,其他各州为 running。 。 。 .

provider.sandbox.list() 财务报告和审定财务报表 getById(id)

const items = await provider.sandbox.list();      // read-only, no side effects
const sandbox = await provider.sandbox.getById(items[0].instanceId);

list() 仅读 —— 它返回 InstanceInfo 没有打开的根 届会。 要实际操作上市条目,请打电话 getById(id)。 。 。 .

请注意: getById() 问题 POST /activate 沙盒上那个 自动复调已暂停的沙盒 并旋转他们的访问标志。 狦 仅需要只读元数据,更喜欢重复 list() 直接说.

模板

const templates = await provider.template!.list();

改为: 创建 模板,使用 @superserve/sdk 直接——模板 需要一个构建的 spec (from + 键 steps),计算SDK template.create({ name }) 形状不携带.

抓图

const snapshot = await provider.snapshot!.create(sandbox.instanceId, {
  name: 'before-upgrade',
});

// Boot a new sandbox from it; processes that were running continue.
const fork = await provider.sandbox.create({ snapshotId: snapshot.id });

const snapshots = await provider.snapshot!.list({ instanceId: sandbox.instanceId });
await provider.snapshot!.delete(snapshot.id);

一个快照可以保存沙盒的内存和磁盘,并保存到删除时,甚至 在原始沙盒消失之后。 每个沙盒列出快照:通过 instanceId 改为 list(),它返回一个没有它的空列表. snapshot.create() 首先连接到沙盒, 如果是, 沙盒会恢复它 暂停 见 示意图指南。 。 。 .

处理错误

常见错误和如何回收 :

try {
  const sandbox = await compute.instances.create();
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);

  if (msg.includes('authentication')) {
    // Bad or missing SUPERSERVE_API_KEY
  } else if (msg.includes('quota') || msg.includes('limit')) {
    // Team has hit its concurrent-sandbox cap
  } else {
    // Network or transient platform error — safe to retry with backoff
  }
}

认证失败归正为单一的用户信息 不论根本原因(HTTP 401, 缺少密钥, AuthenticationError 从SDK.

实例

一个可运行的示例 examples/basic数字 :

cd examples/basic
export SUPERSERVE_API_KEY=your_key
pnpm superserve

学多点

• 超级服务器文件
• @superserve/sdk
• 计算SDK

许可证

麻省理工学院