# @zhangzhian/dsh-tunnel-core 中文文档

规范地址：https://npmcn.com/package/%40zhangzhian/dsh-tunnel-core/

版本：0\.3\.1
npm 元数据更新时间：2026-11-03T00:22:40.368Z
中文译文更新时间：2026-11-03T00:36:25.591Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40zhangzhian/dsh-tunnel-core
原文对照：https://npmcn.com/package/%40zhangzhian/dsh-tunnel-core/?lang=original
源码仓库：https://codeup.aliyun.com/67617ae720a07de19c7c1633/dsh-plugins

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

- 包体积（解压后）：1 MB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ~4\.0\.4，@deepseek-ai/schemastery ~3\.18\.4，@deepseek-ai/dsh-api-gateway ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-locale ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-slots ^0\.2\.0-rc\.2，@deepseek-ai/dsh-typert-protocol ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-renderer ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-settings ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-primitives ^0\.2\.0-rc\.2，@deepseek-ai/dsh-api-terminal-controller ^0\.2\.0-rc\.2，@deepseek-ai/dsh-client-ui-sidebar-right ^0\.2\.0-rc\.2
- 首次发布：2026-10-20T03:13:49.900Z
- 最新版本发布：2026-11-03T00:22:40.138Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

dsh-tunnel的组件包:把本机sshd通过Cloudflare快速隧道暴露出去(主机半+设置页面板)

## 安装

```sh
npm install @zhangzhian/dsh-tunnel-core
```

也可以使用：`pnpm add @zhangzhian/dsh-tunnel-core`、`yarn add @zhangzhian/dsh-tunnel-core`、`bun add @zhangzhian/dsh-tunnel-core`

## README

[英语](https://npmcn.com/package/%40zhangzhian/dsh-tunnel-core/#readme-english) | 简体中文

# @zhangzhian / dsh-tunnel-core

**开发工具（`@zhangzhian/dsh-devtools`）的隧道组件**：主机；主机；主机； （远程API）+“。

不要单独装它 —— 装清单包 `@zhangzhian/dsh-devtools`，它会作为依赖自动拉下来， 在插件页上表现为「开发工具」卡片里的一行（**不是**另一张卡片）。

> 2026-10：原来有一个独立的清单包 `@zhangzhian/dsh-tunnel`（插件页上单独一张 「远程接入」卡片）。用户反馈「远程接入没和开发工具在一起」，于是把它并进了 `dsh-devtools` 【中文翻译】

## 安装

```bash
dsh plugin --profile web add @zhangzhian/dsh-devtools
```

## 提供什么

-   **`dshTunnel` 远程控制** —— `status` / `startSsh` / `stopSsh` / `startWeb` / `stopWeb` / `start` / `stop` / `probe` / `sshd` / `sshdEnablePlan` / `runSshdEnable` / `recipe` / `settings` / `updateSettings` / `installService` / `uninstallService` / `serviceState` / `doctor` / `credential` / `rotateCredential` / `setCredential`，两端类型打通。 ⚠️ `probe` / `doctor` / `installService` / `uninstallService` / `serviceState` **不在面板上**：它们是排查和运维用的。能力在、有测试，只是没有界面入口。
-   **隧道生命周期** —— 解析 `cloudflared`（显式路径 → `PATH` → 常见安装位置 → 按固定 版本下载）、带 `--protocol http2` 快速隧道 (1)、(1)、(1)、(1)、(1)、(1)、(1)。
-   **两条隧道各自独立** ——SSH`phase`Web Web`webPhase`）各有自己的 阶段、域名、句柄、开关和风险确认；`exposeWeb` 是"用户想不想开"的期望态，`webPhase` 才是"现在到底开没开"。
-   **公网入口凭据** 【中文译文】`credential` / `rotateCredential` / **`setCredential`**，落盘在 `access-code`，升级前那种"只有一行 【中文翻译】：【中文翻译】；【中文翻译 `?token=账号:密码`。随机那一份是默认（8 位账号 + 24 位密码），也**可以换成用户自己 填的**1 .主机：`validateCredential`，账号和密码里都不许有冒号 —— 直达链接 靠第一个冒号切分）。
-   **端口纪律** —— 客户端端口永远落在 2201–2299，而且对同一台宿主机是稳定的，所以 dsh-电子
-   **三平台服务定义** —— `plistFor`(LaunchAgent),`unitFor`（systemd）； `taskXmlFor`（计划任务）都是纯函数，所以虽然这里只能跑其中一个，转义规则在每个平台 上都有单测守着。
-   **零依赖二维码编码器** ——包 `require` 平台提供的 9 个种子模块， 所以 `qr.ts` 是自己写的字节模式编码器，八个掩码都对着参考实现验证过。
-   **「还没开启远程登录」的引导** 【翻译】：【翻译**本平台确切**的 macOS `systemsetup -setremotelogin on`Linux; `systemctl enable --now ssh` / `sshd` / `ssh.socket`， Windows `Add-WindowsCapability` + `Set-Service sshd` + `Start-Service sshd`），逐条可复制。 主按钮「在终端里执行」把命令**预填**【参考译文】`TerminalView.write()`，不带 换行），用户在**自己的终端**里按回车、输密码 —— 插件不提权、不碰 `sshd_config`， 无头服务器上照样能用。DSH / / / / / / / / / / **已经在监听时这块不出现**（笨笨笨笨，笨笨笨笨）
-   **设置面板** —— **三个页签**：**dsh Web**【翻译】： **配置**（）。页签条**通栏**、吸顶在 中文：1、2px 1、2px 1。碟子网 **二维码**（扫一下 【中文翻译】：【中文翻译】、【中文翻译 （域名、命令、脚本、四步说明 —— 平台按浏览器自动判断，没有切换控件，也没有二维码）； 配置那条就是四个端口 / 路径字段（一份草稿 + 一个保存）。两条隧道各一张卡片（各自的 状态轮询与开关）、各一份独立的开启前风险确认。体检 / 自检 / 服务 / 诊断包**不在面板上** （见上）。

## 要求

-   **Node.js 20+。** 主机 `node:child_process`、`node:fs/promises`、`node:dgram` 【翻译 `AbortController` —— 没有原生模块，所以 Linux / macOS / Windows。
-   **这就是我的意思**，其客户端半身提供那 9 个种子模块（`react`、`react/jsx-runtime`、 `@deepseek-ai/dsh-client-ui-primitives` 等）。【中文译文】
-   **`cloudflared`** —— 在 `PATH` 【中文翻译】、【中文翻译】、【中文翻译 `$DSH_HOME/dsh-tunnel/bin`。
-   **这是一个很好的例子**，最好只允许密钥登录。没开的话面板会给出本平台的开启命令， 并在终端里预填好（见上）；各系统的开法另见 `@zhangzhian/dsh-devtools` 自述。

* * *

## 英语

# @zhangzhian / dsh-tunnel-core

这个 **隧道组件** 开发工具(`@zhangzhian/dsh-devtools`)：主机一半(隧道生命周期； sshd检查，系统服务，远程API)加上“远程访问”设置页面。

不要单独安装它——安装bundle包，它会把它作为 依赖。

## 安装

```bash
dsh plugin --profile web add @zhangzhian/dsh-devtools
```

## 它提供了什么

-   **`dshTunnel` 远程名称空间** - - - - - - `status` / `startSsh` / `stopSsh` / `startWeb` / `stopWeb` / `start` / `stop` / `probe` / `sshd` / `sshdEnablePlan` / `runSshdEnable` / `recipe` / `settings` / `updateSettings` / `installService` / `uninstallService` / `serviceState` / `doctor` / `credential` / `rotateCredential` / `setCredential`，全部首尾相连。 ⚠️ `probe` / `doctor` / `installService` / `uninstallService` / `serviceState` 是 **不在面板上**：用于故障处理和操作。的功能 它们只是没有UI入口点。
-   **隧道的生命周期** ——解决 `cloudflared` (显式路径→ `PATH` →普通安装 位置→固定下载)，刷出它 `--protocol http2`，解析快速隧道 从JSON-lines日志文件中取出主机名，并持久化每个状态更改，以便面板 在DSH重启后存活。
-   **两条独立隧道** - SSH隧道(`phase`)及深水网隧道 （`webPhase`)，每个都有自己的阶段、主机名、进程句柄、开/关按钮和风险 确认; `exposeWeb` 是期望状态， `webPhase` 是正在播放的节目。
-   **公众入场凭据** -一个用户名和一个密码坐在隧道B的前面 代理(`credential` / `rotateCredential` / **`setCredential`**坚持，坚持 `access-code`； 保存单个明文密码的升级前文件仍然是 可读)。浏览器保存一个cookie 30天，直接链接将继续保存 `?token=<user>:<pass>`.随机对是默认的(一个8个字符的用户名和一个 24个字符的密码)，并且它 **可以用一种用户类型代替吗**: 验证驻留在主机的一半(`validateCredential`，用户名和 密码可以包含一个冒号（直接链接在第一个冒号上分开）。
-   **港口纪律** -客户端端口号总是来自2201-2299，它是稳定的 一个给定的主机，所以dsh-electron只需要配置一次。
-   **平台服务** - - - - - - `plistFor` (LaunchAgent), `unitFor` （系统用户单元）和 `taskXmlFor` （Task Scheduler）是纯函数，因此它们的转义规则是单位的 在每个平台上都测试过，尽管只有一个可以在这里运行。
-   **一个独立的QR编码器** -客户端包只能 `require` 平台的 九个种子模块，所以 `qr.ts` 是否对自包含的字节模式编码器进行验证 所有八个掩码的参考实现。
-   **“SSH尚未启用”指南** -当sshd不监听时，SSH选项卡打印 这个平台（macOS）的精确命令 `systemsetup -setremotelogin on`； Linux `systemctl enable --now ssh` / `sshd` / `ssh.socket`，从发行版中挑选，是否 套接字激活正在使用；窗户 `Add-WindowsCapability` + `Set-Service sshd` + `Start-Service sshd`)，每个都是可复制的。主按钮将命令置于dsh的前面 自己的终端(`TerminalView.write()`（没有尾随换行符），所以用户按Enter和 输入密码 **在他们自己的终端** -插件永远不会提升，永远不会 触摸 `sshd_config`，它也可以在无头服务器上运行。只有一个“现在启用”按钮 当DSH本身是根/管理员时出现。积木会 **不** 出现SSHD时 已经在监听（标准是读取SSH横幅，而不是“用户是否单击”）。
-   **设置面板** - - - - - - **三个选项卡**： **首先是DSH网络隧道** (这是默认值 视图)、SSH隧道和 **配置** (两个隧道都使用的端口和cloudflare路径， 最后)。选项卡栏横跨整个宽度，固定在页眉下方，并标记 选择TAB，加2px下划线。dsh web选项卡保存URL加a **二维码** （扫描它，你在-链接携带凭据）和一个可编辑的用户名和 密码;SSH选项卡仅保存客户端配方（主机名、命令、脚本等） 步骤-平台自动检测，无切换器，无二维码)；config选项卡 保存四个端口/路径字段（一个草稿，一个保存）。每个隧道都有自己的卡片 （它自己的状态轮询和切换）和它自己的风险确认。检查, 自检、服务和诊断包是 **不在面板上** (见上图)。

## 要求

-   **node . js 20 +。** 主机只使用一半 `node:child_process`， `node:fs/promises`， `node:dgram` （自检的直接DNS查询）和 `AbortController` -没有本地人 模块，所以它在Linux， macOS和Windows上工作相同。
-   **安装DSH** 它的客户端提供了九个种子模块(`react`， `react/jsx-runtime`， `@deepseek-ai/dsh-client-ui-primitives`,……)。其他的都是 在构建时捆绑。
-   **`cloudflared`** -发现于 `PATH`，或在公共安装位置下载 （SHA-256验证） `$DSH_HOME/dsh-tunnel/bin`.
-   **一个听筒**最好只有钥匙。如果它是关闭的，面板打印每个操作系统 命令和前缀在终端中（见上文）；README包含的包 同样的理由。

## 常见问题

### @zhangzhian/dsh-tunnel-core 是什么？

dsh-tunnel的组件包:把本机sshd通过Cloudflare快速隧道暴露出去\(主机半\+设置页面板\)

### 如何安装 @zhangzhian/dsh-tunnel-core？

在项目目录运行 npm install @zhangzhian/dsh-tunnel-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（~4\.0\.4）、@deepseek-ai/schemastery（~3\.18\.4）、@deepseek-ai/dsh-api-gateway（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-locale（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-slots（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-typert-protocol（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-renderer（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-settings（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-primitives（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-api-terminal-controller（^0\.2\.0-rc\.2）、@deepseek-ai/dsh-client-ui-sidebar-right（^0\.2\.0-rc\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @zhangzhian/dsh-tunnel-core 支持 TypeScript 吗？

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

### @zhangzhian/dsh-tunnel-core 支持 ESM 还是 CommonJS？

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

### @zhangzhian/dsh-tunnel-core 可以商用吗？

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

### @zhangzhian/dsh-tunnel-core 还在维护吗？

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