离线与内网怎么装 dsh:镜像同步、npx 缓存预热与离线包校验,三条路先选对再动手别混用
内网装 dsh 的难点不在安装命令,而在「怎么把包和依赖带进去,以及带进去的东西对不对」。 三条路径按环境选一条:有内网源走镜像,只有一两台机器走离线包,机器多且要复用缓存才做预热。
dsh 离线安装前先判断你属于哪种没网
三种受限程度对应三条路径,选错会白忙一遍。 对照:
| 环境 | 可行路径 | 关键前提 |
|---|---|---|
| 能访问企业私有源 | 镜像同步 | 本体、插件、依赖都已同步 |
| 完全断网、机器少 | 离线包 | 能带 U 盘或走审批通道 |
| 完全断网、机器多 | 缓存预热 | 目标机器架构与预热机一致 |
先确认再动手。 在目标机器上跑一次 npm config get registry,能连通就是镜像路径,连不通再考虑搬包。
dsh 离线路径一:内网镜像同步
镜像路径的核心不是「改 registry」,而是「源里到底有没有这个版本和它的依赖」。 步骤:
- 在能上网的机器上确认版本存在:
npm view @deepseek-ai/dsh versions; - 让管理员把该版本同步进私有源;
- 在目标机器验证源已生效:
npm config get registry; - 在目标机器再次
npm view @deepseek-ai/dsh@<版本> version,能打印才算同步成功; - 再执行安装或
npx。
404 几乎都是同步不全引起的。 常见情况是本体同步了,插件包与传递依赖没同步,表现为「装得上 dsh、装不上插件」。
把可装范围写进内网文档。 哪个版本、哪些插件已同步,一次写清,比每个人各试一遍省事。
dsh 离线路径二:离线包
完全断网、机器只有一两台时,离线包最可靠,因为它不依赖缓存状态和源配置。 准备阶段在有网机器上执行:
npm pack @deepseek-ai/dsh@<版本>,得到一个.tgz;- 同样为每个插件执行
npm pack; - 记录每个包的版本号,写成清单;
- 把包体与清单一起拷进内网。
安装阶段在目标机器上执行:
- 确认 Node 已就绪:
node -v; - 全局安装本体:
npm install -g ./deepseek-ai-dsh-<版本>.tgz; - 用
dsh --version核对版本与清单一致; - 插件用
dsh plugin --profile web add <包体路径>安装; - 重启并确认插件出现在列表里。
离线包同样会解析依赖。 如果某个依赖不在本机缓存也不在内网源,安装仍会去联网,这就是离线包最常见的失败点;提前把依赖一并 pack 或让源覆盖依赖。
dsh 离线路径三:缓存预热
预热适合「机器多、又不允许自建源」的场景,代价是与架构和缓存结构强绑定。 步骤:
- 在有网机器执行
npm cache add @deepseek-ai/dsh@<版本>; - 用
npm cache verify确认缓存完整; - 用
npm config get cache找到缓存目录(默认在用户目录下的.npm); - 把缓存目录整体拷到目标机器同一路径;
- 在目标机器执行
npx --offline -y @deepseek-ai/dsh@<版本> web。
--offline 的作用是禁止联网,让缺包立刻报错,而不是卡住等超时。 排查时先看这条命令的输出,它比 npx 默认的静默重试有用。
原生模块是预热路径的死角。 预热机与目标机器架构不同(例如 arm64 到 x64)时,即使包在缓存里也可能装不上,需要目标机器具备编译条件。
dsh 离线传输校验与失败判据
没有校验的传输等于没传输,因为坏包和缺包的表现都是「装不上」。 校验清单:
- 包体 SHA-256 两台机器一致;
dsh --version与清单里的版本号一致;- 插件列表数量与预期一致;
- 首次启动日志没有模块解析错误;
- 发一条消息确认模型链路可用。
第一步用系统的哈希工具即可。 两端对同一文件算一次,数值不同就重新拷贝,不要尝试「先装上看看」。
校验没过时,先判断问题落在哪一段,再决定要不要重新准备。 对照:
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 安装报 404 | 源里没有该版本或依赖 | 补同步,别反复重试 |
| 安装时报网络错误 | 离线包里还有未满足的依赖 | 一并 pack 或提供源 |
| 安装成功但启动报模块缺失 | 包体不完整或架构不匹配 | 重新传输,核对架构 |
--offline 直接报缺包 | 缓存里没有该版本 | 重新预热并校验缓存 |
判据比现象重要。 「装不上」不是一个原因,上表四行对应四种完全不同的处理方式。
dsh 内网长期做法与下一步
一次性交付靠离线包,长期使用靠镜像。 建议:
- 把 dsh 与常用插件列成一份内网可装清单,跟着版本更新;
- 每次升级前先在测试机验证,再同步进源;
- 记录每台机器的 dsh 版本与安装路径;
- 不要把 DSH_HOME 一起打包分发,配置与凭据应按机器各自生成。
DSH_HOME 不属于安装包。 它默认在 ~/.dsh,装包不会带上会话与凭据,迁移数据要单独处理。
路径选完、校验通过,才算可以启动。 想看 npx 场景的镜像细节,读 npx 离线镜像;想看下载慢与源配置,读 下载慢怎么办;想看插件包完整性,读 插件包完整性;想按使用方式选最小安装,读 dsh 最小安装。
常见问题
至少三样:与目标机器架构匹配的 dsh 包体、目标环境可用的 Node 运行时、以及你要装的插件包。dsh 本体不含 Node,离线机器上没装 Node 的话,光搬包体也起不来。
内网源装 dsh 报 404,通常是因为该版本没有同步进源,或者只同步了本体没同步依赖。先用 npm view @deepseek-ai/dsh versions 在内网源上确认版本存在,再检查插件包与它们的依赖是否都在源里。
确认离线 dsh 包有没有被改坏,就在两台机器上分别对同一个 tgz 算 SHA-256 并比对,一致再安装。安装后再用 dsh --version 核对版本号,两步都过才算传输可靠。
内网装 dsh 选哪条路径,取决于机器数量:机器多、要反复装就选内网镜像,只有一两台机器一次性交付则选离线包更省事。缓存预热对原生模块不友好,架构不同的机器之间搬运容易失败。
相关术语
- 私有 registry
- 私有 registry 是企业内网自建的 npm 源,客户端把 registry 指过去后,npx 与全局安装都从它解析包。— npm 文档
- 缓存预热
- 缓存预热是一种在有网机器上先把包下载进 npm 缓存目录、再把缓存整体搬到目标机器复用的做法,避免目标机器联网。— npm 文档
- 离线包
- 离线包是用 `npm pack` 打出的 `.tgz` 文件,可以通过本地路径直接安装,不依赖任何 registry。— npm 文档:npm pack
- DSH_HOME
- DSH_HOME 是 DeepSeek Harness 的数据根目录,默认 ~/.dsh,保存配置、会话、插件与凭据,安装包不会携带它。— DeepSeek Harness 官方文档
来源
- DeepSeek Harness 官方文档· deepseek-harness
- dsh CLI README· deepseek-ai
- npm 文档:npm pack· npm