@computesdk/upstash (帮助)
计算SDK的 Upstash Box 提供商 - 在云沙盒中执行代码,并拥有完整的文件系统访问, shell 命令,快照,并预览 URL.
安装
npm install @computesdk/upstash
设置
- 获取您的 Upstash Box API 密钥 控制台.upstash.com
- 设置环境变量 :
export UPSTASH_BOX_API_KEY=your_api_key_here
快速启动
import { upstash } from '@computesdk/upstash';
const compute = upstash({ apiKey: process.env.UPSTASH_BOX_API_KEY });
const sandbox = await compute.instances.create();
const result = await sandbox.runCommand(`python - <<'PY'
import pandas as pd
print(pd.__version__)
PY`);
console.log(result.stdout);
await sandbox.destroy();
配置
环境变量
export UPSTASH_BOX_API_KEY=your_api_key_here
配置选项
interface UpstashConfig {
/** Upstash Box API key - if not provided, will use UPSTASH_BOX_API_KEY env var */
apiKey?: string;
/** Default runtime environment (e.g. 'node', 'python') */
runtime?: string;
/** Execution timeout in milliseconds (default: 600000) */
timeout?: number;
}
特征
- 命令执行 - 在沙盒中运行 shell 命令( Python/ Node.js 可用)
- 文件系统操作 - 完整文件系统访问
- 预览 URL - 为运行服务获取可公开获取的URL
- 抓图 - 保存并恢复沙盒状态
API 参考
命令执行
// Run Python code via heredoc
const result = await sandbox.runCommand(`python - <<'PY'
import json
data = {"message": "Hello from Python"}
print(json.dumps(data))
PY`);
// Run Node.js code via heredoc
const result = await sandbox.runCommand(`node - <<'JS'
const data = { message: "Hello from Node.js" };
console.log(JSON.stringify(data));
JS`);
```typescript
// List files
const result = await sandbox.runCommand('ls -la');
// Install packages
const result = await sandbox.runCommand('pip install requests');
// Run with environment variables
const result = await sandbox.runCommand('echo $MY_VAR', {
env: { MY_VAR: 'hello' },
});
// Run with working directory
const result = await sandbox.runCommand('ls', { cwd: '/workspace/home/myproject' });
// Run in background
const result = await sandbox.runCommand('node server.js', { background: true });
文件系统操作
// Write file
await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello World")');
// Read file
const content = await sandbox.filesystem.readFile('/tmp/hello.py');
// Create directory
await sandbox.filesystem.mkdir('/tmp/data');
// List directory contents
const files = await sandbox.filesystem.readdir('/tmp');
// Check if file exists
const exists = await sandbox.filesystem.exists('/tmp/hello.py');
// Remove file or directory
await sandbox.filesystem.remove('/tmp/hello.py');
预览 URL
// Get a publicly accessible URL for a running service
const url = await sandbox.getUrl({ port: 3000 });
console.log(url); // https://<box-id>-3000.box.upstash.io
抓图
import { upstash } from '@computesdk/upstash';
const compute = upstash({ apiKey: process.env.UPSTASH_BOX_API_KEY });
// Create a snapshot of a running sandbox
const snapshot = await compute.snapshot.create(sandbox.id, {
name: 'my-checkpoint',
});
console.log(snapshot.id, snapshot.metadata);
// Restore from a snapshot
const restored = await compute.instances.create({
snapshotId: snapshot.id,
});
沙盒管理
// Get sandbox info
const info = await sandbox.getInfo();
console.log(info.id, info.status, info.createdAt);
// Reconnect to existing sandbox
const existing = await compute.instances.getById('box-id');
// List all sandboxes
const sandboxes = await compute.instances.list();
// Destroy sandbox
await sandbox.destroy();
处理错误
import { upstash } from '@computesdk/upstash';
try {
const compute = upstash({ apiKey: process.env.UPSTASH_BOX_API_KEY });
const sandbox = await compute.instances.create();
const result = await sandbox.runCommand('invalid code');
} catch (error) {
if (error.message.includes('Missing Upstash Box API key')) {
console.error('Set UPSTASH_BOX_API_KEY environment variable');
} else if (error.message.includes('authentication failed')) {
console.error('Check your Upstash Box API key');
} else if (error.message.includes('quota exceeded')) {
console.error('Upstash usage limits reached');
}
}
实例
数据科学工作流程
import { upstash } from '@computesdk/upstash';
const compute = upstash({ apiKey: process.env.UPSTASH_BOX_API_KEY });
const sandbox = await compute.instances.create();
// Create project structure
await sandbox.filesystem.mkdir('/analysis/data');
await sandbox.filesystem.mkdir('/analysis/output');
// Write input data
const csvData = `name,age,city
Alice,25,New York
Bob,30,San Francisco
Charlie,35,Chicago`;
await sandbox.filesystem.writeFile('/analysis/data/people.csv', csvData);
// Process data with Python
const result = await sandbox.runCommand(`python - <<'PY'
import pandas as pd
import matplotlib.pyplot as plt
# Read data
df = pd.read_csv('/analysis/data/people.csv')
print("Data loaded:")
print(df)
# Calculate statistics
avg_age = df['age'].mean()
print(f"\\nAverage age: {avg_age}")
# Create visualization
plt.figure(figsize=(8, 6))
plt.bar(df['name'], df['age'])
plt.title('Age by Person')
plt.savefig('/analysis/output/age_chart.png')
print("\\nChart saved!")
PY`);
console.log(result.stdout);
await sandbox.destroy();
带预览 URL 的 Web 服务器
import { upstash } from '@computesdk/upstash';
const compute = upstash({ apiKey: process.env.UPSTASH_BOX_API_KEY });
const sandbox = await compute.instances.create();
// Write a simple server
await sandbox.filesystem.writeFile('/server.js', `
const http = require('http');
const server = http.createServer((req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json' });
res.end(JSON.stringify({ status: 'ok' }));
});
server.listen(3000, () => console.log('Server running on port 3000'));
`);
// Start server in background
await sandbox.runCommand('node /server.js', { background: true });
// Get the public URL
const url = await sandbox.getUrl({ port: 3000 });
console.log('Server available at:', url);
await sandbox.destroy();
最佳做法
- 资源管理: 完成释放资源时总是销毁沙盒
- 处理错误: 使用试捕取区块进行稳健的错误处理
- 超时: 为长期任务设定适当的超时( 默认为10分钟)
- 文件路径: 所有路径都相对
/workspace/home - 抓图: 使用快照保存并恢复可复制环境的沙盒状态
- API 密钥安全: 从不向版本控制输入 API 密钥
限制
- 文件路径: 所有文件系统操作范围都在
/workspace/home - 内存限制: 受Upstash Box资源限制
- 抓图删除: 快照删除需要框上下文
- 模板支持: 使用快照而不是模板来保存框状态
支助
许可证
麻省理工学院