# @dbx-tools/lakebox 中文文档

规范地址：https://npmcn.com/package/%40dbx-tools/lakebox/

版本：0\.9\.206
npm 元数据更新时间：2026-11-10T19:18:28.032Z
中文译文更新时间：2026-11-11T18:09:39.327Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dbx-tools/lakebox
原文对照：https://npmcn.com/package/%40dbx-tools/lakebox/?lang=original
项目主页：https://github.com/reggie-db/dbx-tools#readme
源码仓库：https://github.com/reggie-db/dbx-tools

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

- 包体积（解压后）：384 kB，31 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-10-15T08:39:31.107Z
- 最新版本发布：2026-11-10T19:18:27.610Z
- 近 30 天下载量：5704（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：54（近 12 个月 54 个）

## 中文简介

Databricks Lakebox REST、集合式SSH运输以及确定用户路线

## 安装

```sh
npm install @dbx-tools/lakebox
```

也可以使用：`pnpm add @dbx-tools/lakebox`、`yarn add @dbx-tools/lakebox`、`bun add @dbx-tools/lakebox`

## README

# @ dbx 工具/ lakebox

在 Databricks Lakeboxs 上连接、提供和运行命令.

## 提供湖箱

```ts
import { client as authClient } from "@dbx-tools/auth";
import { LakeboxClient } from "@dbx-tools/lakebox/rest";
import { ensureLakeboxRunning } from "@dbx-tools/lakebox/lifecycle";

const auth = await authClient.createAuthClient({ profile: "MY-PROFILE" });
const api = new LakeboxClient({
  host: auth.host,
  ...(auth.workspaceId ? { workspaceId: auth.workspaceId } : {}),
  authenticate: async (headers) => {
    for (const [name, value] of Object.entries(await auth.headers())) {
      headers.set(name, value);
    }
  },
});
const entry = await api.create();
await api.setIdleTimeout(entry.sandboxId, 3_600);
const running = await ensureLakeboxRunning(api, entry);
```

`LakeboxClient` 接受任何证书对象 `host` 财务报告和审定财务报表 `authenticate(headers)`. AppKit和Databricks SDK `WorkspaceClient.config` 直接履行合同。 示例适应 `@dbx-tools/auth` 以明确本地概况。 使用应用程序服务主机 用于在 Databricks App 中的生命周期呼叫.

## 连接并运行命令

创建或装入 SSH 密钥, 在工作空间注册, 验证网关 主机密钥, 当工作结束时关闭会话 :

```ts
import { SshKeyStore } from "@dbx-tools/lakebox/key-store";
import type { LakeboxClient, LakeboxEntry } from "@dbx-tools/lakebox/rest";
import { SshSession } from "@dbx-tools/lakebox/session";

export async function runCommand(
  api: LakeboxClient,
  running: LakeboxEntry,
  user: { name: string; home: string },
): Promise<void> {
  const owner = "my-service";
  const keys = new SshKeyStore();
  const key = await keys.ensureRegistered(api, owner);
  const gatewayHost = running.gatewayHost ?? key.gatewayHost;
  if (!gatewayHost) {
    throw new Error("The Lakebox API did not return an SSH gateway host");
  }

  const gatewayPort = 2_222;
  const scope = await api.workspaceScope();
  const knownHost = await keys.knownHost(scope, owner, gatewayHost, gatewayPort);
  const session = new SshSession({
    host: gatewayHost,
    port: gatewayPort,
    username: running.sandboxId,
    privateKey: key.privateKey,
    privateKeyPath: key.privateKeyPath,
    knownHostsPath: keys.knownHostsPath(scope, owner, gatewayHost, gatewayPort),
    connectTimeoutMs: 30_000,
    sshTransport: "auto",
    ssh2Patch: "auto",
    ...(knownHost ? { knownHost } : {}),
    rememberHost: (fingerprint, hostKey) =>
      keys.rememberHost(scope, owner, gatewayHost, gatewayPort, fingerprint, hostKey),
  });

  try {
    await session.connect();
    const command = session.execute("sh", ["-lc", "uname -a"], {
      user,
      timeoutMs: 30_000,
    });
    const result = await command.result;
    if (!result.success) {
      throw new Error(result.stderr || `Command exited with ${result.exitCode}`);
    }
  } finally {
    await session.close();
  }
}
```

每个命令清除继承的 Databricks 证书和 SSH 代理变量 在它运行之前. `execute()` 返回一个活字 `SshCommand`。 。 `stdout` 财务报告和审定财务报表 `stderr` 字段是协同可移动的,等待命令返回其数字 退出代码,和 `result` 返回抓取的输出和计时元数据.

低等包不创建Linux用户. 通过一个账户已经 存在于湖框中. `@dbx-tools/appkit-lakebox` 创建和隔离 程序用户账户在运行其命令前 .

`forwardOut(host, port)` 通过单独的池来打开转发的 TCP 流. 长寿的HTTP和WebSocket流不会消耗温暖的命令 连接.

## 停止或删除湖框

需要等待终止状态时使用生命周期趋同:

```ts
import { ensureLakeboxStopped } from "@dbx-tools/lakebox/lifecycle";
import type { LakeboxClient, LakeboxEntry } from "@dbx-tools/lakebox/rest";

export async function stopAndDelete(api: LakeboxClient, running: LakeboxEntry): Promise<void> {
  const stopped = await ensureLakeboxStopped(api, running);
  await api.delete(stopped.sandboxId);
}
```

`stop()` 保留持久的Lakebox文件系统. `delete()` 永久 删除"湖箱"及其数据.

## 配置

| 外地 | 数值 | 默认 |
| --- | --- | --- |
| `sshTransport` | `auto`, (中文(简体) ), `openssh`, (中文(简体) ), `ssh2` | `auto` 倾向于使用 SOCKS5 的本地 OpenSSH |
| `ssh2Patch` | `auto`, (中文(简体) ), `true`, (中文(简体) ), `false` | `auto` 只在开发中补丁 |

`SshSessionOptions` 还需要网关主机和端口,Lakebox ID作为 SSH 用户名、 私有密钥材料、 密钥和已知主机路径以及连接 暂停 . `SshKeyStore` 将密钥和网关指纹保存在 `~/.dbx-tools/lakebox` 除非你通过另一个根.

## 了解生命周期和运输限制

-   `ensureLakeboxRunning()` 财务报告和审定财务报表 `ensureLakeboxStopped()` 5人以下的民意调查 几分钟.
-   REST 客户端不映射用户,不坚持应用资源身份,也不管理 服务。 使用 [@dbx-工具/appkit-lakebox](https://npmcn.com/package/%40dbx-tools/appkit-lakebox/README.md) 页:1 这些应用层面的能力.
-   指挥池保持一个测试的连接温度 并增长到10 连接。 转发使用一个单独的没有最小值的池.
-   每个被借用的SSH资源处理一个操作,然后被销毁 命令或转发流。 发送失败的打开重试, 一次带新的 资源。 既定的流和命令没有被重放.
-   `auto` 在可用时选择本地 OpenSSH 并选择 ssh2 否则。 它在运行时间故障后不会切换运输.
-   `close()` 取消活动命令、关闭传输池并等待一个 正在进行中的连接试图解决.

## 常见问题

### @dbx-tools/lakebox 是什么？

Databricks Lakebox REST、集合式SSH运输以及确定用户路线

### 如何安装 @dbx-tools/lakebox？

在项目目录运行 npm install @dbx-tools/lakebox，或使用 pnpm add / yarn add / bun add。

### @dbx-tools/lakebox 支持 TypeScript 吗？

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

### @dbx-tools/lakebox 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dbx-tools/lakebox 可以商用吗？

@dbx-tools/lakebox 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @dbx-tools/lakebox 的下载量有多少？

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

### @dbx-tools/lakebox 还在维护吗？

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