# @eduwork/dsh-remote-access 中文文档

规范地址：https://npmcn.com/package/%40eduwork/dsh-remote-access/

版本：0\.1\.6
npm 元数据更新时间：2026-11-12T08:05:11.724Z
中文译文更新时间：2026-11-14T06:58:59.093Z
软件包许可：MulanPSL-2\.0 AND MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40eduwork/dsh-remote-access
原文对照：https://npmcn.com/package/%40eduwork/dsh-remote-access/?lang=original
项目主页：https://github.com/ECNU/EduWork/tree/main/packages/dsh-remote-access#readme
源码仓库：https://github.com/ECNU/EduWork

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

- 包体积（解压后）：2 MB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.22\.1
- 运行依赖：0 个
- peer 依赖：zod ^4\.4\.3，react ^18\.2\.0，@deepseek-ai/cordis ^4\.0\.5，@deepseek-ai/schemastery \>=3\.18\.5 \<3\.19\.0 \|\| 3\.19\.0，@deepseek-ai/dsh-home-paths \>=0\.2\.2-rc\.1 \<0\.3\.0-0，@deepseek-ai/dsh-api-remotes \>=0\.2\.2-rc\.1 \<0\.3\.0-0，@deepseek-ai/dsh-client-locale \>=0\.2\.2-rc\.1 \<0\.3\.0-0，@deepseek-ai/dsh-typert-protocol \>=0\.2\.2-rc\.1 \<0\.3\.0-0，@deepseek-ai/dsh-client-ui-renderer \>=0\.2\.2-rc\.1 \<0\.3\.0-0，@deepseek-ai/dsh-client-ui-settings \>=0\.2\.2-rc\.1 \<0\.3\.0-0
- 首次发布：2026-10-22T17:05:06.378Z
- 最新版本发布：2026-11-12T08:05:11.103Z
- 近 30 天下载量：2183（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

通过自办中继器对DSH主机进行端到端加密远程访问

## 安装

```sh
npm install @eduwork/dsh-remote-access
```

也可以使用：`pnpm add @eduwork/dsh-remote-access`、`yarn add @eduwork/dsh-remote-access`、`bun add @eduwork/dsh-remote-access`

## README

# 远程访问

[English](https://npmcn.com/package/%40eduwork/dsh-remote-access/README_EN.md)

`@eduwork/dsh-remote-access` 让你在手机或其他电脑的浏览器里使用另一台电脑上的 DeepSeek Harness（DSH）：查看和新建会话、继续或取消任务、审批、回答提问、查看和下载结果。连接经自托管的中继服务器转发，端到端加密，中继看不到内容。每台设备都要在电脑上核对配对码、确认后才能连接，也可以随时移除。

包里有两部分：

-   **DSH 插件**：运行在被访问的电脑上，在设置页开关远程访问、添加和移除设备。
-   **中继服务**：部署在有公网地址的服务器上，转发密文，并提供手机上打开的网页。

## 使用

### 部署中继

需要 Node.js 24.22.1 或更新版本，以及为中继域名提供 HTTPS 并转发 WebSocket 的反向代理。

```sh
RELAY_URL=https://remote.example.edu/ RELAY_ACCESS_KEYS=替换成随机Key \
  npx --yes --package=@eduwork/dsh-remote-access@0.1.2 eduwork-remote-relay
```

`RELAY_URL` 是用户访问中继的公开地址；`RELAY_ACCESS_KEYS` 是发给电脑主人的接入密钥，多个用逗号分隔。中继默认监听 `127.0.0.1:8787`，可用 `HOST`、`PORT` 修改；`<RELAY_URL>healthz` 返回 `ok`，可用于监控。

服务器推荐按 [Docker 部署指南](https://npmcn.com/package/%40eduwork/dsh-remote-access/docs/docker/README.md) 使用 Dockerfile 和 Compose，从 npm 固定版本构建后用 `docker compose up -d --build` 启动。完整的 [中继部署指南](https://npmcn.com/package/%40eduwork/dsh-remote-access/docs/DEPLOYMENT.md) 还包含 Key 生成、Windows PowerShell 命令、HTTPS/Nginx、路径前缀、systemd 常驻运行、机构登录和 iframe 集成，以及验证与排错步骤。

中继也可以部署在同域的单独路径，例如 `RELAY_URL=https://example.edu/eduwork-remote/`。反向代理须保留此前缀，电脑上填写同一个完整地址。同域路径不隔离浏览器权限，部署者须确认站点与被配对电脑处于可接受的共同信任范围（见[安全](https://npmcn.com/package/%40eduwork/dsh-remote-access/#readme-%E5%AE%89%E5%85%A8)）；作用于整个站点的 Service Worker 还须放过这段路径。

学校或企业也可以让成员凭自己的登录使用中继，不必逐个发接入密钥：`RELAY_OIDC_ISSUER` 填机构 OpenID Connect 登录的 issuer（例如 `https://sso.example.edu`），`RELAY_OIDC_CLIENT_IDS` 填桌面应用在该登录中的 client ID，多个用逗号分隔。电脑以登录得到的 ID Token 注册，中继用 issuer 公布的公钥验证，只记录用户标识，不记录 Token。Token 到期前电脑会自动换新的；到期仍未换新时，中继断开这台电脑现有的远程连接。机构登录失效、需要重新登录时，电脑停止连接中继，设置页提示重新登录。两种方式可以同时启用。

中继限制每个账号最多同时注册 5 台电脑，每台电脑每分钟最多接受 60 个设备连接，同一地址一分钟内注册被拒 10 次后要等待。中继在反向代理后面时，用 `RELAY_CLIENT_IP_HEADER` 指定代理传递客户端地址的请求头（例如 `x-real-ip`），否则所有用户共用代理的地址。

中继的网页默认不允许被其他页面嵌入。机构网站需要用 iframe 嵌入它时，用 `RELAY_FRAME_ANCESTORS` 列出允许嵌入的页面来源，多个用空格分隔：与中继同源的页面写 `self`，其他页面写它的来源，例如 `https://portal.example.edu`。命令行和 env 文件都会去掉引号，所以 `self` 与 `'self'` 等效；写多个来源时整个值加双引号，例如 `RELAY_FRAME_ANCESTORS="self https://portal.example.edu"`。iframe 不要加 `sandbox` 属性，中继网页需要运行脚本、注册 Service Worker 和下载文件。嵌入的页面应与中继属于同一站点（主域名相同，例如 `portal.example.edu` 与 `remote.example.edu`）：跨站嵌入时，Safari 等 WebKit 浏览器无法在其中加载电脑的界面。

### 在电脑上开启

在 DSH 中安装插件后重启：

```sh
dsh plugin --profile web add @eduwork/dsh-remote-access
```

打开“设置 → 远程访问”，填写中继服务器和接入密钥，勾选“允许远程访问”。显示“已连接”后即可添加设备。远程访问默认关闭。“测试连接”分别说明中继能否访问、身份能否通过，未开启时也可以测试；连接失败时可点“重试”。

机构的发行版可以预置自己的中继和登录（插件设置 `organization: { relay, oidcProfileId }`，`oidcProfileId` 是 [dsh-oidc](https://npmcn.com/package/%40eduwork/dsh-oidc/README.md) 中的机构配置）。这时设置页默认使用机构账号：显示登录状态，未登录时可直接登录，登录后勾选“允许远程访问”即可，退出登录后远程访问随之停止。中继由发行版决定，设置页不显示也不能修改。用户也可以改选“使用自己的中继服务器”，填写中继和接入密钥。

机构登录模式还要求宿主安装提供 `identityToken(profileID)` 接口的 `@eduwork/dsh-oidc@0.3.1` 或后续兼容版本；旧版 `0.3.0` 不包含该接口。使用接入密钥的独立部署不依赖 OIDC 插件。

### 添加和移除设备

1.  在电脑上点“添加设备”，出现二维码和链接。链接 10 分钟内有效，只能用一次。
2.  在手机上扫码或打开链接，填写设备名称，点“开始配对”。
3.  确认手机和电脑上显示的 6 位配对码一致后，在电脑上点“允许”。

之后在这台设备上打开中继地址就会连接到电脑；断线后自动重连。iPhone 和 iPad 上请先把页面添加到主屏幕，从主屏幕打开后再粘贴配对链接：只在 Safari 里配对的设备，7 天不用会丢失配对。

在电脑的“已配对设备”里点“移除”，该设备立即断开，之后不能再连接。

## 远程设备能做什么

可以选择已有工作区，查看或新建会话，继续和取消任务，审批或回答提问，查看和下载结果；宿主已安装相应插件时，还可以使用 Studio 成果和日历。

手机上看到的就是 DSH 自己的界面。DSH 0.2.2 起自带手机布局：会话列表从左上角以抽屉打开，选中会话或面板后自动收起；设置铺满屏幕，各分区排成一行标签。设置在远程设备上只能查看。对话中的耗时、重试、审批和提问与电脑上一致。

远端不能直接调用打开本机窗口、程序或发出通知的接口，不能注册或删除工作区、修改设置、管理账号、插件、凭据、技能、记忆或远程访问本身，也不能直接使用终端与代码执行接口。**通过 Agent 发起的任务仍可能执行命令，沿用该会话的权限与审批规则**；禁止直接调用终端接口不等于禁止 Agent 使用工具。完整清单见 [src/gate/gate.ts](https://npmcn.com/package/%40eduwork/dsh-remote-access/src/gate/gate.ts)，未列出的接口一律拒绝。

## 安全

-   电脑和设备之间端到端加密，中继只转发密文。配对链接固定了电脑的公钥，中继无法冒充电脑。
-   设备密钥由浏览器生成且不可导出，电脑只保存设备公钥。每次连接都要用设备密钥签名。
-   接入密钥和机构登录只决定谁能使用这台中继，不能用来连接别人的电脑。接入密钥保存在 DSH 的凭据里（`EDUWORK_REMOTE_ACCESS_KEY`），不写进插件设置；机构登录的 ID Token 只发给发行版预置的中继，设置页不能更改这个地址。
-   手机上打开的网页由中继提供，部署中继的人可以修改它。请只使用你信任的中继。
-   手机上显示的 DSH 界面由所连的电脑提供，与中继网页同源。浏览器按来源（协议、主机、端口）而非路径隔离数据，因此一台电脑提供的界面能使用此浏览器与其他电脑的配对去连接它们。请只与自己的电脑配对。
-   同理，中继与其他网站同源时，那些网站的脚本能使用这里的配对连接电脑；任何一台被配对的电脑提供的界面，也能以用户的身份访问那些网站及脚本可访问的浏览器数据。独立域名能缩小信任范围；若选择同域路径集成，需要接受这项共同信任边界，路径前缀和普通 iframe 均不提供隔离。
-   允许其他页面嵌入中继的网页后，那些页面能把它显示在自己的页面里并加以遮挡，诱导用户点击（例如批准命令）。只允许你信任的页面嵌入。

协议细节见[协议文档](https://npmcn.com/package/%40eduwork/dsh-remote-access/docs/PROTOCOL.md)。

## 贡献来源

本插件由 [@JunieXD](https://github.com/JunieXD) 在 [#192](https://github.com/ECNU/EduWork/pull/192) 中实现，承接了 [@Paraso42](https://github.com/Paraso42) 在 [#180](https://github.com/ECNU/EduWork/pull/180) 中的远程访问原型贡献：DSH 宿主接入点梳理、接口白名单与拒绝原因、设备信任与撤销模型，以及断线重连、避免重复执行和跨网络部署的验收场景。@Paraso42 是远程访问功能的合作贡献者；当前协议与实现以 #192 为准。

## 开发

在本包目录运行：

```sh
npm ci
npm run check
node scripts/check-web.ts
```

`check-web.ts` 在 Chromium 和 WebKit 中走完配对、加载、请求、断线重连和移除设备，需要本机已安装 Playwright 的浏览器，不在 CI 中运行。

[包维护与发布](https://github.com/ecnu/EduWork/blob/main/docs/PACKAGES.md) · [变更记录](https://npmcn.com/package/%40eduwork/dsh-remote-access/CHANGELOG.md) · [代码许可](https://npmcn.com/package/%40eduwork/dsh-remote-access/LICENSE) · [第三方声明](https://npmcn.com/package/%40eduwork/dsh-remote-access/THIRD_PARTY_NOTICES.md)

## 常见问题

### @eduwork/dsh-remote-access 是什么？

通过自办中继器对DSH主机进行端到端加密远程访问

### 如何安装 @eduwork/dsh-remote-access？

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

### @eduwork/dsh-remote-access 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eduwork\_\_dsh-remote-access 是否存在。

### @eduwork/dsh-remote-access 支持 ESM 还是 CommonJS？

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

### @eduwork/dsh-remote-access 需要什么版本的 Node\.js？

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

### @eduwork/dsh-remote-access 可以商用吗？

@eduwork/dsh-remote-access 使用 MulanPSL-2\.0 AND MIT 许可。声明的许可为 MulanPSL-2\.0 AND MIT，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @eduwork/dsh-remote-access 的下载量有多少？

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

### @eduwork/dsh-remote-access 还在维护吗？

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