@ computesdk/ buddy
计算SDK的Buddy提供者.
每个沙盒都是Buddy沙盒——你Buddy项目中的Ubuntu microVM,服务于前武装的游泳池. 命令在运行时会流出输出,端口通过Buddy隧道发布,快照作为可再用的基础图像双倍.
建造在 @buddy-works/sandbox-sdkBuddy的官方TypeScript SDK(英语:TypeScript SDK).
安装
npm install @computesdk/buddy
需要20.19或22.12号节点并更新,匹配Buddy SDK(ESM和CommonJS建筑均被发运出).
设置
- 在其中创建 API 令牌 巴迪 我的身份证 访问符 与
SANDBOX_MANAGE范围 - 为您的沙盒创建( 或选择) Buddy 工程
- 设置环境变量 :
export BUDDY_TOKEN=your_api_token_here
export BUDDY_WORKSPACE=your_workspace_domain
export BUDDY_PROJECT=your_project_name
快速启动
import { buddy } from '@computesdk/buddy';
const compute = buddy();
const sandbox = await compute.instances.create();
const result = await sandbox.runCommand('echo "hello from buddy"');
console.log(result.stdout);
await sandbox.destroy();
全权证书取自环境,因此 buddy() 不需要参数。 明确通过它们以覆盖 :
const compute = buddy({
token: process.env.BUDDY_TOKEN!,
workspace: 'acme',
project: 'sandboxes',
});
配置
interface BuddyConfig {
/** API token with the `SANDBOX_MANAGE` scope. Falls back to `BUDDY_TOKEN`. */
token?: string;
/** Workspace domain. Falls back to `BUDDY_WORKSPACE`. */
workspace?: string;
/** Project the sandboxes belong to. Falls back to `BUDDY_PROJECT`. */
project?: string;
/** Base OS image — `'ubuntu:24.04'` (default) or `'ubuntu:22.04'`. */
os?: string;
/** Resource preset, `"{vCPU}x{RAM GB}"` from `1x2` to `12x24`. Buddy's own default applies when omitted. */
resources?: BuddyResources;
/** Buddy installation — `'US'` (default) or `'EU'`. */
region?: BuddyRegion;
/** Sandbox lifetime in milliseconds, after which Buddy stops it. Defaults to 1 hour. */
timeout?: number;
/** Ports to expose on every sandbox this provider creates. */
ports?: BuddyPortInput[];
/** API base URL. Overrides `region`, for on-premise installations. */
apiUrl?: string;
}
选择安装
Buddy在一个API范围内运行独立设施而不是区域,每个区域都有
自己的主机,账户和信使. region 选择 API 主机和位置
隧道终止 :
const compute = buddy({ region: 'EU' });
region | API 主机 |
|---|---|
US (默认) | https://api.buddy.works |
EU | https://api.eu.buddy.works |
一个装置签发的令牌对其他装置无效。 对于一个真实
安装, 设置 apiUrl 换句话说.
创建选项
除了交叉提供者的选择之外, create 接受:
await compute.instances.create({
// Expose ports up front, so getUrl needs no extra round trip
ports: [3000, { port: 443, type: 'TLS', region: 'EU' }],
// Resources — either a preset, or cpu/memory that map onto one
resources: '4x8',
// Commands run once when the sandbox first boots
firstBootCommands: 'npm ci',
// Working directory for the sandbox's apps
appDir: '/buddy/app',
tags: ['ci'],
});
snapshotId (或 templateId)从快照开始沙盒,而不是从底像开始.
显示端口
const sandbox = await compute.instances.create({ ports: [3000] });
await sandbox.runCommand('npx serve -l 3000', { background: true });
const url = await sandbox.getUrl({ port: 3000 });
getUrl 如果在创建时没有宣布端口,则按要求打开隧道,
保持任何隧道已经打开。 仅 HTTP 财务报告和审定财务报表 TLS 隧道获得公共URL;
TCP 财务报告和审定财务报表 SSH 隧道由主机和端口到达,报告于 getInfo。 。 。 .
文件系统
await sandbox.filesystem.mkdir('/buddy/app');
await sandbox.filesystem.writeFile('/buddy/app/index.js', 'console.log(1)');
await sandbox.filesystem.readFile('/buddy/app/index.js');
await sandbox.filesystem.readdir('/buddy/app');
await sandbox.filesystem.exists('/buddy/app/index.js');
await sandbox.filesystem.remove('/buddy/app');
相对路径解析 /buddy,默认值的主目录 buddy 用户.
第一个文件系统在沙盒上呼叫等待它的第一个启动设置完成. 哥们 队列 命令 对起步沙盒,但内容终点不: 设置他们要么拒绝请求,要么接受写作,一旦设定就丢弃 完成 。 等待需要几百毫秒 在一个新创造的沙盒和 之后什么都没有.
抓图
一个快照是一张从活沙盒取取的磁盘图像,作为可重复使用的底片 图像其他提供者调用模板.
const snapshot = await compute.snapshot.create(sandbox.instanceId, { name: 'with-deps' });
await compute.snapshot.list(); // the whole project
await compute.snapshot.list({ instanceId: sandbox.instanceId }); // one sandbox
await compute.snapshot.delete(snapshot.id);
// Booting from it is a normal create
const prepared = await compute.instances.create({ snapshotId: snapshot.id });
Buddy 同步创建快照 它们不会被还原 直到它们转向
CREATED这样 create 等那个再回来. metadata 已接受为
交叉提供者兼容性但不存储: Buddy只保留一个名称.
巴迪没有单独的模板实体 所以 template.list 财务报告和审定财务报表 template.delete 别名
即时方法和 template.create 掷出,指向 snapshot.create。 。 。 .
倒在巴迪SDK
getInstance() 返回提供者工作过的控件,包括活的 SDK
客户端和文件系统,所以Buddy在计算SDK表面外的特性仍然可以达到
不建立第二个客户端 :
const { client, fs, sandboxId } = sandbox.getInstance();
await client.getSandboxAppLogs({ path: { sandbox_id: sandboxId, app_id: 'web' } });
手柄 fs 财务报告和审定财务报表 client 直接拨打 API, 无需提供者的第一启动等: 在刚刚创建的沙盒上, 制作一个 sandbox.filesystem 呼叫( 偶数) exists在上传之前.
支助业务
| 方法 | 支助 | 页:1 |
|---|---|---|
create | ✅ | 一个请求; 在沙盒仍在启动时返回, 因为命令队列反对它 . |
getById | ✅ | 回返 null 当沙盒不复存在时. |
list | ✅ | 在配置的项目中列出沙盒. |
destroy | ✅ | 对服务器错误进行检索; 如果沙盒已经丢失, 则不开放 . |
runCommand | ✅ | 一次往返 exec 用于普通调用; 当调用通过时, 流输出 。 真正的退出代码 无论是哪种方式. |
getInfo | ✅ | 报告 巴迪自己的状态和设置状态, 加上每一个隧道,在 metadata。 。 。 . |
getUrl | ✅ | 如果端口尚未打开, 则打开一条隧道, 保留已有的隧道 . |
filesystem | ✅ | 通过Buddy的原生端点传输文件内容,没有命令行内容限制. 读取先用本地命令解析并链接;只有在验证其类型后才接受已存在的目录. |
snapshot | ✅ | create 编号 : list 编号 : delete· ; create 等待到快照恢复. |
template | ⚠️ | Buddy没有模板实体 —— list编号 :delete 别名快照, create 投出一个提示. |
页:1
create不等待沙盒到达RUNNING。Buddy队列对起步沙盒提交命令,所以等待只会给第一个命令增加延迟。 有同样的原因 供应商称SDK'sBuddyApiClient直接代替Sandbox.create()民意测验准备时间.runCommand(cmd)没有流回调或atimeout运行在巴迪的同步exec端点: 一个请求, 将 stdout, stderr 和退出代码一起返回 。 这样的命令没有留下 进入沙盒的命令历史。 服务器最多等待60 s; 过去调用返回退出码 124, 服务器的消息输入stderr,该过程会一直运行在沙盒中。 通过 atimeout对于可能运行更长或必须停止的命令.runCommand(cmd, { onStdout, onStderr }), (中文(简体) ),streamCommand, (中文(简体) ),background: true和任何timeout使用同步键execs而不是资源,所以输出会随着它的产生而到来,命令会出现在历史中,一个超时会杀死它. 它的日志没有显示 stdout 从 stderr, 所以所有输出都到stdout财务报告和审定财务报表onStdout· ;onStderr没有叫。 Buddy最多3个这样的命令,每个成员一次在一个沙盒里,每个工作空间10个,runCommand抛出——90分钟后停止,包括background这些.runCommand(cmd, { background: true })当Buddy在命令中排入队列时返回,而不读取其输出.runCommand(cmd, { timeout })返回超时结果并终止命令.- 无法选择安装中的沙盒放置;
region选择安装和隧道位置.
许可证
麻省理工学院