# @earendil-works/gondolin 中文文档

规范地址：https://npmcn.com/package/%40earendil-works/gondolin/

版本：0\.14\.0
npm 元数据更新时间：2026-10-22T08:11:55.629Z
中文译文更新时间：2026-11-13T03:36:31.965Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.1 MB，407 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：3 个
- 首次发布：2026-02-04T22:30:52.042Z
- 最新版本发布：2026-10-22T08:11:55.249Z
- 近 30 天下载量：215959（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

Alpine Linux 沙盒,用于运行未信任的密码,并带有受控文件系统和网络访问

## 安装

```sh
npm install @earendil-works/gondolin
```

也可以使用：`pnpm add @earendil-works/gondolin`、`yarn add @earendil-works/gondolin`、`bun add @earendil-works/gondolin`

## README

# 贡多林

**具有完全可编程网络堆栈和文件系统的本地Linux微VM.**

Gondolin在您的 Mac 或 Linux 机上运行轻量级微VMs( QEMU by 默认, 可选 `krun` 后端). 网络堆栈和虚拟文件系统是 在 TypeScript 中执行,使您能够完全控制什么 沙盒可以访问 和它可以使用的秘密.

## 所需资源

您需要安装 QEMU 来运行微VM( 默认后端) :

| 马科斯 | Linux (德文/乌本图) |
| --- | --- |
| `brew install qemu` | `sudo apt install qemu-system-arm` |

可选的实验后端 :

-   `libkrun` + 键 `host/krun-runner` (单位:千美元)`sandbox.vmm = "krun"`(中文(简体) )
-   `make krun-runner` 从地上恢复根相依赖并构建跑道
    -   在MacOS上,它也给跑者签上 `com.apple.security.hypervisor`
    -   Gondolin自动探测这个本地跑者 `--vmm krun`
-   `@earendil-works/gondolin` 为所支持的目标出版针对特定平台的可选跑道套件(`darwin-arm64`, (中文(简体) ), `linux-x64`(中文(简体) )
-   krun 启动资产通过图像清单提供(`assets.krunKernel` 编号 : `assets.krunInitrd`(单位:千美元) `gondolin build` 并发布图像
-   `gondolin bash --vmm krun` 选择每个命令的后端
-   `GONDOLIN_VMM=krun` 仍然是全球默认值
-   后端等同矩阵 : [文件/后端](https://npmcn.com/package/%40earendil-works/docs/backends.md)

Linux 的先决条件 `make krun-runner` (乌班图/德比安):

```bash
sudo apt install \
  build-essential curl git make pkg-config clang lld xz-utils \
  libclang-dev llvm-dev libcap-ng-dev

# libkrun needs current stable Rust (edition2024 crates)
curl https://sh.rustup.rs -sSf | sh -s -- -y --profile minimal
. "$HOME/.cargo/env"

# install Zig 0.17.0 for your Linux architecture
```

-   节点.js 22.19

> **说明:** 运行时验证目前在ARM64(Apple Silicon,Linux arch64)上最强. Linux x86 64 目前正在测试烟雾 `make krun-runner` 在中央情报局.

## 安装

```bash
npm install @earendil-works/gondolin
```

## 快速启动( CLI)

```bash
npx @earendil-works/gondolin bash
```

您也可以从另一个终端中发现并重新附加运行 VMS :

```bash
# List running sessions
npx @earendil-works/gondolin list

# Attach a second shell to a running VM by UUID/prefix
npx @earendil-works/gondolin attach <session-id>

# Snapshot a running VM session (stops that session)
npx @earendil-works/gondolin snapshot <session-id>

# Resume from snapshot id/path
npx @earendil-works/gondolin bash --resume <snapshot-id-or-path>
```

来宾图像(~200MB)在首通运行时自动解析 `builtin-image-registry.json` 缓存于 `~/.cache/gondolin/images/`。 。 。 . 如果没有提供明确的图像,贡多林将使用 `GONDOLIN_DEFAULT_IMAGE` (默认 : `alpine-base:latest`) (中文(简体) ).

## 哈罗世界

```ts
import { VM, createHttpHooks, MemoryProvider } from "@earendil-works/gondolin";

const { httpHooks, env } = createHttpHooks({
  allowedHosts: ["api.github.com"],
  secrets: {
    GITHUB_TOKEN: {
      hosts: ["api.github.com"],
      value: process.env.GITHUB_TOKEN!,
    },
  },
});

const vm = await VM.create({
  httpHooks,
  env,
  vfs: {
    mounts: { "/workspace": new MemoryProvider() },
  },
});

// NOTE:
// - `vm.exec("...")` runs via `/bin/sh -lc "..."` (shell features work)
// - `vm.exec([cmd, ...argv])` executes `cmd` directly and does not search `$PATH`
//   so `cmd` must be an absolute path
const cmd = `
  curl -sS -f \
    -H "Accept: application/vnd.github+json" \
    -H "Authorization: Bearer $GITHUB_TOKEN" \
    https://api.github.com/user
`;

// You can pass a string to `vm.exec(...)` as shorthand for `/bin/sh -lc "..."`.
const result = await vm.exec(cmd);

console.log("exitCode:", result.exitCode);
console.log("stdout:\n", result.stdout);
console.log("stderr:\n", result.stderr);

await vm.close();
```

客人从不看真正的秘密价值 它只得到占位符. 默认( E)`secretPlaceholderMode: "shared"`那些占位符看起来像 `<random-marker>.<normalized_secret_name>`,所有产生的秘密共享 一个随机标记. `secretPlaceholderMode: "unique"` 而不是每个秘密 完全随机的占位符 `GONDOLIN_SECRET_<random>`。 。 。 . 位置符由主机在输出的 HTTP 信头中替换, 包括 `Authorization: Basic …` (基数64的符号在 `username:password` 现予替换).

默认情况下, URL 查询参数中的占位符不会被替换 。 你们可以 选择使用 `replaceSecretsInQuery: true`,但这会增加反射 风险,只应在必要时使用.

> **说明:** 避免挂起一个 `MemoryProvider` 时间 `/` 除非您还提供了 系统 CA 捆绑。 贡多林在 `/etc/gondolin/mitm/ca.crt`, (中文(简体) ), 但是,如果你的根挂载隐藏 Distro CA 文件,那么公开的 TLS 校验可以 仍然失败(例如:. `curl: (60)`) (中文(简体) ).

## 外出 SSH 主机授权列表

SSH egress 可以使用一个明确的主机授权列表:

```ts
const vm = await VM.create({
  dns: {
    mode: "synthetic",
    syntheticHostMapping: "per-host",
  },
  ssh: {
    allowedHosts: ["github.com"],

    // Upstream host key verification
    //
    // If `hostVerifier` is not provided, gondolin verifies upstream host keys using
    // OpenSSH known_hosts (by default: ~/.ssh/known_hosts and /etc/ssh/ssh_known_hosts).
    // You can override this with `knownHostsFile`.
    // knownHostsFile: "/path/to/known_hosts",

    // Option A: use an ssh-agent (recommended for encrypted keys)
    agent: process.env.SSH_AUTH_SOCK,

    // Option B: provide a raw private key
    credentials: {
      "github.com": {
        username: "git",
        privateKey: process.env.GITHUB_DEPLOY_KEY!,
      },
    },
  },
});
```

`syntheticHostMapping: "per-host"` 需要这样,主机就可以向外映射 端口上的 TCP 连接 `22` 返回预定主机名.

当证书或 SSH 代理配置时, 主机终止 SSH 的来宾 届会和代理 `exec` 请求(包括 Git smart- protocol 命令) 到 真实的上游主机使用主机侧认证 。 私钥从不 可见于来宾.

如果未为主机配置匹配证书, 则无 `ssh.agent` 设定了 SSH流量被屏蔽(直接通过不支持).

由于这是SSH终止,客人看到主机提供的SSH主机密钥; 配置来宾 `known_hosts` (或按需要禁止严格检查).

上游 SSH 主机密钥对照 OpenSSH 进行校验 `known_hosts` 默认. 如果缺少上游主机(或密钥更改),则代理的 SSH 请求 将失败.

## 许可证和链接

-   [文档](https://earendil-works.github.io/gondolin/)
-   [问题跟踪器](https://github.com/earendil-works/gondolin/issues)
-   许可证 : [阿帕奇 - 2.0](https://github.com/earendil-works/gondolin/blob/main/LICENSE)

## 常见问题

### @earendil-works/gondolin 是什么？

Alpine Linux 沙盒,用于运行未信任的密码,并带有受控文件系统和网络访问

### 如何安装 @earendil-works/gondolin？

在项目目录运行 npm install @earendil-works/gondolin，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gondolin，可以用 npx gondolin 直接运行。

### @earendil-works/gondolin 支持 TypeScript 吗？

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

### @earendil-works/gondolin 支持 ESM 还是 CommonJS？

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

### @earendil-works/gondolin 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @earendil-works/gondolin 可以商用吗？

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

### @earendil-works/gondolin 的下载量有多少？

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

### @earendil-works/gondolin 还在维护吗？

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