# @dbx-tools/appkit-lakebox 中文文档

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

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

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

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

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

- 包体积（解压后）：652 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2026-10-15T08:42:51.487Z
- 最新版本发布：2026-11-10T19:19:47.230Z
- 近 30 天下载量：4955（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

AppKit 插件, 用户服务, 路由, 度量衡, 和 Mastra 工具用于一个应用 Lakebox

## 安装

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

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

## README

# @dbx-工具/appkit-lakebox

给每个经过认证的Databricks App用户一个持久的Linux家,终端, 桌面、 OCI 图像服务、 代理工具、 以及共享的机器度量衡 数据砖湖盒.

## 注册插件

```ts
import { createApp, lakebase, server } from "@databricks/appkit";
import { lakebox, LakeboxRuntime } from "@dbx-tools/appkit-lakebox";
import { resolveLakeboxPluginConfig } from "@dbx-tools/appkit-lakebox/config";

const runtime = new LakeboxRuntime(resolveLakeboxPluginConfig({ idleTimeoutSeconds: 1_800 }));

await createApp({
  plugins: [server(), lakebase(), lakebox({ runtime })],
});
```

Lakebase 坚持使用 Databricks 指派的 Lakebox ID, 序列化的首次创建 并保留最后观察到的服务定义,同时 机器已经停止了。 注册应用程序 `lakebase()` 用户前的插件 进入Lakebox线路.

## 连接 Mastra 到同一运行时间

传出同样的 `LakeboxRuntime` 到 AppKit 插件和 Mastra 沙盒。 这个 将命令、服务、路线、度量衡和用户账户保持在同一位置 湖边:

```ts
import { createApp, lakebase, server } from "@databricks/appkit";
import { lakebox, LakeboxRuntime } from "@dbx-tools/appkit-lakebox";
import { resolveLakeboxPluginConfig } from "@dbx-tools/appkit-lakebox/config";
import { lakeboxSkillMounts } from "@dbx-tools/appkit-lakebox/skills";
import { lakeboxWorkspaceSandbox } from "@dbx-tools/appkit-lakebox/workspace";
import { agents, mastra } from "@dbx-tools/appkit-mastra";

const runtime = new LakeboxRuntime(resolveLakeboxPluginConfig());
const analyst = agents.createAgent({
  name: "Analyst",
  instructions: "Use the workspace when the task requires files or commands.",
});

await createApp({
  plugins: [
    server(),
    lakebase(),
    lakebox({ runtime }),
    mastra({
      agents: { analyst },
      sandbox: lakeboxWorkspaceSandbox(runtime),
      localSkillMounts: lakeboxSkillMounts(),
    }),
  ],
});
```

沙盒解决每个请求的认证 Mastra 用户 。 没有 在代理注册时创建计算。 第一个命令或服务开始 湖边 `auto` 已启用.

## 将"湖箱UI"渲染

注册后端插件,然后将 React 软件包制成相同的 应用程序 :

```tsx
import { LakeboxIndicator, LakeboxPanel } from "@dbx-tools/ui-lakebox/react";

export function LakeboxPage() {
  return (
    <>
      <LakeboxIndicator />
      <LakeboxPanel />
    </>
  );
}
```

在您的 AppKit 用户界面主题后导入软件包样式表 :

```css
@import "@dbx-tools/ui-lakebox/styles.css";
```

组件从插件已发布的客户端读取 API 基础路径 配置 。 不需要复制路由字符串或通过 Databricks 证书到浏览器.

## 创建服务

特工打电话来 `create_lakebox_service`. REST 客户端发送 `POST /api/lakebox/services`数字 :

```json
{
  "name": "hello",
  "image": "docker.io/library/python:3.12-alpine",
  "command": ["sh", "-lc", "python -m http.server \"$SERVICE_PORT\" --bind 127.0.0.1"],
  "mounts": [{ "source": "data", "target": "/data" }]
}
```

服务后调用返回 。 运行时间注入 `SERVICE_NAME`, (中文(简体) ), `SERVICE_PATH`, (中文(简体) ), `SERVICE_PORT`,以及 `PORT`. 线路服务 必须听 `127.0.0.1:$SERVICE_PORT`上山源相对 用户的家.

这是受限的容器API,而不是多克CLI. 没有守护进程, 端口发布,特权模式,设备访问,或桥梁网络. 一个湖盒 停止并启动从已保存定义中重新启动服务。 进程内存 不恢复.

## 使用代理工具

| 工具 | 效果 |
| --- | --- |
| `get_lakebox` | 返回状态, 当前用户的账户, 和不创建 Lakebox 的服务 . |
| `execute_lakebox_command` | 运行一个命令作为用户账户 . |
| `list_lakebox_services` | 列出用户服务. |
| `create_lakebox_service` | 创建或替换一个图像服务并等待到准备好 . |
| `start_lakebox_service`, (中文(简体) ), `stop_lakebox_service` | 开始或停止保存的服务, `terminal`,或 `desktop`。 。 。 . |
| `remove_lakebox_service` | 删除已保存的服务 。 须经批准. |
| `get_lakebox_service_logs` | 读取限定的服务日志 . |

插件为命令和服务变异创建或启动 Lakebox 何时 `auto` 已启用。 列表和状态操作不会创建.

## 了解生命周期

应用服务校长拥有Lakebox生命周期电话. 一个半用户 身份选择用户的 Linux 账户并授权路由, 但从未 创建、启动、停止或删除 Databricks 资源.

生命周期行为是:

1.  第一个明确的启动、命令、服务突变或路由请求 当不存在时创建应用程序的"湖盒".
2.  运行时间启动"湖盒"并恢复被保存的服务定义.
3.  每张认证身份地图到一个锁定的非苏多账户,其中有一个 持续的家用和私人服务港口.
4.  Databricks平台在配置的闲置期后停止了Lakebox.
5.  后一请又起. 用户文件和保存的服务定义 持续,但过程内存没有.

`runtime.stop()` 停止每个用户共享的湖箱. `runtime.delete()` 永久删除"湖盒"和每个用户的文件. 普通 AppKit 关闭 关闭 SSH 会话并转发桥接, 但将闲置的关机留给 平台.

## 配置

| 选项 | 默认 | 说明 |
| --- | --- | --- |
| `application` | `DBX_TOOLS_LAKEBOX_APPLICATION`, (中文(简体) ), `DATABRICKS_APP_NAME`,或项目目录 | 持续存在的 Lakebox 资源标识的稳定密钥 . |
| `idleTimeoutSeconds` | `3600` | 平台闲置超时,60至86400秒. |
| `auto` | `true` | 按需要创建或启动 Lakebox . |
| `routePrefix` | `/lakebox` | 服务路线的 AppKit 根 . |
| `metricsIntervalSeconds` | `5` | 客户端观察度量衡时的样本间隔 . |
| `sshTransport` | `auto` | `auto`, (中文(简体) ), `openssh`,或 `ssh2`。 。 。 . |
| `ssh2Patch` | `auto` | 应用 Ssh2 缺失 - 执行 - 备份工作 只在开发, 永远, 或永远. |
| `gatewayPort` | `2222` | 湖口SSH网关端口. |
| `connectTimeoutMs` | `30000` | SSH 连接超时. |
| `commandTimeoutMs` | `120000` | 默认命令超时 . |
| `keyDirectory` | `~/.dbx-tools/lakebox` | 可选服务器侧 SSH 密钥和已知主机存储根 . |

## 交互式测试

`test/cli.ts` 作为任何用户运行工作空间配置的实时运行 :

```bash
bun packages/js/node/appkit-lakebox/test/cli.ts --profile <profile> --user a@example.com status
bun packages/js/node/appkit-lakebox/test/cli.ts --profile <profile> --user b@example.com exec id
bunx tsx packages/js/node/appkit-lakebox/test/cli.ts --profile <profile> --user a@example.com serve
```

`serve` 启动该用户的终端和桌面并代理其路径 [http://127.0.0.1:8787 (中文(简体) )](http://127.0.0.1:8787/)。 。 。 .

明确传递配置配置 。 在这个绳子上, 特征特征 代理应用服务校长.

## 了解安全和运行时间限制

-   每个应用程序最多有一个管理好的"湖箱". 用户共享机器,但不共享 Linux 账户,家园,或服务端口.
-   命令和服务不接受 Databricks 环境变量, 转发证书、饼干或 SSH 代理访问.
-   当一个非启动请求没有认证时, 服务线路失败 身份证明.
-   图像服务与私人 PID, IPC, Mount, 和用户名空间运行. 他们 共享主机网络, 并且只必须绑定到被注入回路端口 .
-   量子覆盖了机器CPU,内存,持续存储,以及网络计数器. 它们不披露过程数据,只在客户端观看时进行采样.
-   Lakebase是应用软件资源识别、复制式聚合以及 最后已知的服务定义.

## 常见问题

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

AppKit 插件, 用户服务, 路由, 度量衡, 和 Mastra 工具用于一个应用 Lakebox

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

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

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

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

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

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

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

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

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

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

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

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