# @computesdk/northflank 中文文档

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

版本：1\.1\.21
npm 元数据更新时间：2026-11-06T13:39:41.625Z
中文译文更新时间：2026-11-10T14:26:30.229Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：140 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-05-29T14:47:20.892Z
- 最新版本发布：2026-11-06T13:39:41.418Z
- 近 30 天下载量：10005（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

计算SDK的Northflank供应商 - 在Northflank的集装箱平台上部署和管理计算工作量

## 安装

```sh
npm install @computesdk/northflank
```

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

## README

# @ computesdk/ 北风

计算SDK的Northflank供应商.

每个沙盒都是你Northflank计划中的部署服务. 通过Northflank的Exec API在容器中运行的指令;端口通过服务的公共DNS被曝光.

## 安装

```bash
npm install @computesdk/northflank
```

## 设置

1.  获取您的 API 令牌 : **团队设置 → API → 托肯斯 → 创建 API 令牌**
2.  创建( 或选择) Northflank 项目
3.  设置环境变量 :

```bash
export NORTHFLANK_TOKEN=your_api_token_here
export NORTHFLANK_PROJECT_ID=your_project_id
```

## 快速启动

```ts
import { northflank } from '@computesdk/northflank';

const compute = northflank({
  token: process.env.NORTHFLANK_TOKEN!,
  projectId: process.env.NORTHFLANK_PROJECT_ID!,
  runtime: 'node',
});

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

const result = await sandbox.runCommand(`node -e "console.log('hello from northflank')"`);
console.log(result.stdout);

await sandbox.destroy();
```

## 配置

```ts
interface NorthflankConfig {
  /** Northflank API token */
  token: string;
  /** Project ID (slug, e.g. "my-project") */
  projectId: string;
  /** Team ID — required for organization API tokens */
  teamId?: string;
  /** API host — defaults to https://api.northflank.com */
  host?: string;
  /** Service name prefix used to identify managed sandboxes — defaults to "computesdk-" */
  servicePrefix?: string;
  /** Container image — overrides the default for the runtime */
  image?: string;
  /** Default runtime label when none is passed to create() — any string; defaults to "node". "node" and "python" map to built-in image defaults; anything else needs `image` or `internalDeployment` */
  runtime?: string;
  /** Northflank deployment plan — defaults to "nf-compute-50" */
  deploymentPlan?: string;
  /** Default ports to expose on every sandbox */
  ports?: { name: string; internalPort: number; public?: boolean; protocol?: 'HTTP' | 'HTTP/2' | 'TCP' | 'UDP' }[];
  /** Budget in ms for the first exec to retry while the container starts (default: 120000) */
  timeout?: number;
  /** Deploy from a Northflank build service instead of an external image */
  internalDeployment?: { id: string; branch?: string; buildSHA?: string };
  /** Ephemeral storage per container in MB (e.g. 5120 for 5 GiB) */
  ephemeralStorageSize?: number;
}
```

## 内部部署(建议生产)

默认情况下, 沙盒拉 `node:20-slim` 编号 : `python:3.11-slim` (或你的电话) `image`)来自外部登记册。 关于生产工作量,我们建议从 **北岸建筑服务** 在同一项目中——内部部署被优化,以更快地冷起而不用依赖外部注册.

```ts
const compute = northflank({
  token: process.env.NORTHFLANK_TOKEN!,
  projectId: process.env.NORTHFLANK_PROJECT_ID!,
  internalDeployment: {
    id: 'my-build-service',   // build service ID in the same project
    branch: 'main',           // optional — defaults to "main"
    buildSHA: 'latest',       // optional — defaults to "latest"
  },
});
```

也可以通过 `internalDeployment` 以每盒为单位 `create()`;它覆盖了配置级别值。 外部图像继续工作—— `internalDeployment` 只是推荐的路径.

## 每盒选项

`create()` 在标准选项之上接受这些针对提供者的选项:

```ts
await compute.instances.create({
  runtime: 'python',                    // overrides config.runtime
  image: 'my-registry/custom:tag',      // overrides config.image and the runtime default
  ports: [{ name: 'app', internalPort: 3000 }], // overrides config.ports
  deploymentPlan: 'nf-compute-200',     // overrides config.deploymentPlan
  timeout: 180000,                      // overrides config.timeout
  envs: { LOG_LEVEL: 'debug' },         // merged into runtimeEnvironment
  name: 'my-sandbox',                   // service name (auto-prefixed)
  ephemeralStorageSize: 5120,           // 5 GiB ephemeral storage per container
});
```

内建图像默认值 : `node` → `node:20-slim`, (中文(简体) ), `python` → `python:3.11-slim`。任何其他运行时标签都被接受,但您必须提供 `image` 或者说 `internalDeployment` ——没有默认退后.

## 运行代码

没有 `runCode` ——直接通过运行时间 `runCommand`数字 :

```ts
// Python
const py = await sandbox.runCommand(`python -c "import json; print(json.dumps({'hello': 'world'}))"`);

// Node.js
const js = await sandbox.runCommand(`node -e "console.log(JSON.stringify({hello: 'world'}))"`);
```

对于多行脚本,请先写出文件后再引用:

```ts
await sandbox.filesystem.writeFile('/tmp/script.py', `
import pandas as pd
print(pd.__version__)
`);
const result = await sandbox.runCommand('python /tmp/script.py');
```

## 图标

```ts
// Simple command
await sandbox.runCommand('ls -la');

// Working directory
await sandbox.runCommand('npm install', { cwd: '/app' });

// Environment variables
await sandbox.runCommand('echo $MY_VAR', { env: { MY_VAR: 'hello' } });

// Background execution
await sandbox.runCommand('python server.py', { background: true });
```

## 文件系统

```ts
await sandbox.filesystem.writeFile('/tmp/hello.txt', 'hello world');
const content = await sandbox.filesystem.readFile('/tmp/hello.txt');

await sandbox.filesystem.mkdir('/tmp/data');
const entries = await sandbox.filesystem.readdir('/tmp');

const exists = await sandbox.filesystem.exists('/tmp/hello.txt');
await sandbox.filesystem.remove('/tmp/hello.txt');
```

文件系统操作向exec代理发送路径作为plain argv元素(例如. `['mkdir', '-p', '--', path]`)或者通过Northflank's `fileCopy` API——没有涉及外壳剖析,因此路径不需要逃跑. 仅 `runCommand` (实际上引用了外壳) `env` 编号 : `cwd` 值它会插入.

## 沙盒管理

```ts
// List managed sandboxes (filtered by servicePrefix)
const sandboxes = await compute.instances.list();

// Look up by service ID (slug of the service name)
const sandbox = await compute.instances.getById('computesdk-1700000000-abc123');

// Inspect — refetches the live deployment status
const info = await sandbox.getInfo();
console.log(info.id, info.status, info.createdAt);

// Get the public URL for a port — exposes it dynamically if not already public
const url = await sandbox.getUrl({ port: 3000 });

await sandbox.destroy();
```

## 页:1

-   服务名称 `<servicePrefix><timestamp>-<random>` (或 `<servicePrefix><name>` 如果你通过了 `name`) (中文(简体) ). `list`, (中文(简体) ), `getById` 财务报告和审定财务报表 `destroy` 只运行于名称以前缀开头的服务.
-   `create` 在创建服务的 Northflank API 呼叫之后立即返回 **没有** 等待容器准备好。 第一个 `runCommand` 因此,(或文件系统调用)可能需要更长的时间:它重复瞬变执行失败(最多到 `timeout` ms),而吊舱完成开始. 一旦一个Exec成功,之后的电话直接运行,没有重试.
-   `list` 返回每个前缀服务,无论部署状态如何。 使用 `getInfo` 检查每个人的状态,并在必要时过滤客户端.
-   `getInfo` 从API的每通电话中重新读取服务—— `running` 表示部署状态是 `COMPLETED` 服务没有暂停; `stopped` 意味着暂停, `PENDING`,或 `IN_PROGRESS`· ; `error` 表示 `FAILED`。 。 。 .
-   `getUrl` 将补补服务端口配置, 如果尚未将请求的端口公开, 然后返回其端口 `dns`。 。 。 .

## 限制

-   **启动时间** ——Northflank拉出并启动图像;期望数十秒.
-   **内存和 CPU** - 以选定的 `deploymentPlan`。 。 。 .
-   **文件持久性** ——文件存放于容器内,服务被破坏后会丢失.

## 支助

-   [北侧文件](https://northflank.com/docs)
-   [计算SDK问题](https://github.com/computesdk/computesdk/issues)

## 许可证

麻省理工学院

## 常见问题

### @computesdk/northflank 是什么？

计算SDK的Northflank供应商 - 在Northflank的集装箱平台上部署和管理计算工作量

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

在项目目录运行 npm install @computesdk/northflank，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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