从旧安装迁移到新安装:命令、插件与 DSH_HOME 三处对齐清单,每一步都留回滚点,缺一不可
迁移不是「重新装一遍」,而是把命令、插件、数据三处对齐。 只做其中一处,结果通常是「命令能跑但没有会话」或「会话还在但插件全丢」。
dsh 迁移第一步:停服务与对齐命令
先停再迁,是所有步骤的前置条件。 操作:
- 找到正在运行的 dsh 进程并正常停止(SIGINT 或 SIGTERM 会触发资源释放);
- 确认端口已释放:
lsof -i :3080无输出; - 记录当前版本:
dsh --version; - 记录 DSH_HOME 实际路径:
echo $DSH_HOME,空值时默认~/.dsh; - 整目录备份 DSH_HOME,命名带日期。
边跑边拷是迁移里最常见的自伤。 运行中的 profile 会写配置与插件依赖,复制出来的目录可能处于半写状态。
备份要整目录,不要只挑配置。 会话、日志与凭据都在里面,漏一处就会在迁移后表现为「某些东西莫名消失」。
服务停稳、备份就位之后,第一处要动手对齐的是命令入口。
命令对齐要回答三个问题:新入口叫什么、旧入口还在不在、PATH 先命中谁。 步骤:
- 按新方式安装,全局装完执行
dsh --version确认可用; - 执行
which -a dsh,看是否出现多条路径; - 若有多条,确认 shell 实际执行的是新的那一条;
- 检查是否有旧别名或脚本仍写死旧命令;
- 把脚本、定时任务、桌面快捷方式里的命令一并替换。
旧入口不一定报错,它可能只是「还能跑但版本旧」。 这类问题最难发现,所以第 3 步不能省。
新旧并存期间不要两边都启动。 两个进程写同一个 DSH_HOME,可能出现锁冲突与版本不一致。
dsh 迁移对齐二:插件与 profile
插件是跟着 profile 走的,不是跟着机器走的。 步骤:
- 在旧环境记录每个 profile 下的插件列表;
- 确认新环境使用的 profile 名称与旧的一致;
- 用同一个包名与版本重新安装:
dsh plugin --profile <名称> add <包名>; - 重启后确认列表数量与旧环境对得上;
- 逐个确认入口是否出现,必要时看日志。
「插件列表少了一半」几乎都是 profile 名称不一致。 web、headless、sdk 各自独立,装进 web 的插件不会出现在 headless 里。
插件版本不要顺手升级。 迁移的目标是恢复到迁移前的可用状态,升级应该作为独立步骤,出问题时才能区分是迁移导致的还是升级导致的。
dsh 迁移对齐三:数据与 DSH_HOME
数据对齐只做一件事:让新环境指向旧数据,而不是把数据复制进安装目录。 步骤:
- 确认新环境的 DSH_HOME 指向哪个目录;
- 把备份的 DSH_HOME 恢复到该目录,或迁移后把 DSH_HOME 指回备份位置;
- 检查权限:目录与文件只对本用户可读写;
- 启动一次,确认会话列表能看到历史;
- 确认凭据仍可用,发一条消息验证。
不要把 DSH_HOME 放进安装目录。 安装目录会随升级被替换,数据放进去等于每次升级都在赌运气。
凭据文件与配置文件是分开的。 只恢复配置不恢复凭据,表现是「界面正常但模型调不通」,容易被误判成网络问题。
dsh 迁移路线与迁移后验收
路线不同,重点也不同。 npx 换全局,重点看 PATH 是否命中新命令;CLI 换桌面端,重点防两个进程同时写同一个 DSH_HOME;旧机器换新机器,重点对齐 Node 版本、原生模块与目录权限。
桌面端与 CLI 共享 DSH_HOME 时要格外小心。 桌面端使用保留的 profile 名称,CLI 会拒绝针对它的启动与配置操作;两边同时用同一份数据,容易互相干扰。
换机器时先对齐 Node 版本。 版本跨度太大,插件可能因运行时差异加载失败,而这和迁移本身无关。
无论走哪条路线,验收看的都不是「能启动」,而是三件事是否都在。 清单:
- 会话:历史会话能列出,点开有内容;
- 插件:数量与旧环境一致,入口可用;
- 模型:发一条消息成功,错误码可读;
- 日志:新生成的日志落在新的 DSH_HOME 下;
- 版本:
dsh --version与预期一致。
三项里缺任何一项,都说明只对齐了一部分。 先定位缺的是哪一处,再回退对应步骤,不要整体重来。
dsh 迁移回滚点与常见错位
每一步动手前留一个回滚点,成本很低,收益很大。 建议:
- 停服务后备份 DSH_HOME,命名
<日期>-pre-migrate; - 安装新方式前记录旧命令与旧版本号;
- 改 PATH 或别名前,把原配置文件复制一份;
- 改完一处就验收一次,不要全部改完再测。
回滚顺序是:停新服务 → 恢复 DSH_HOME → 回到旧命令。 数据优先,因为命令回滚只是换入口,数据回滚才能救回会话与凭据。
确认新环境稳定运行一段时间后再删备份。 过早删除,等于把唯一的退路也删了。
而迁移后的异常,几乎都能归到下面这三处:命令找不到是 PATH 未刷新,能启动但无历史是 DSH_HOME 指向了空目录,插件变少是 profile 名称不一致,消息发不出是凭据没一起恢复。 先确定是哪一处,再只修那一处,别整体重装。
dsh 迁移下一步
三处都对齐,才算迁移完成。 想清理迁移后残留的旧安装,读 dsh 安装占用与清理;想按 profile 更新插件,读 按 profile 更新插件;想固定版本避免再次漂移,读 固定版本安装;想找回误删的会话,读 会话恢复。
常见问题
从 npx 换成全局安装后,dsh 的会话和插件不会自动丢,但也不会自动对齐。会话、插件与配置都在 DSH_HOME(默认 ~/.dsh)下,与安装方式解耦;换安装方式后仍指向同一个 DSH_HOME,所以数据还在,插件也会随 profile 一起被识别。
运行中的 profile 会持有配置与插件依赖的写锁,边跑边拷贝可能得到半写的文件。先停服务再迁移,能避免复制出来的数据无法加载,也避免新旧两份同时写同一个目录。
先确认新入口使用的 profile 名称与旧的一致,再看插件是否装在另一个 profile 里。profile 之间依赖独立,装错 profile 就不会出现在列表里;确认后用同一条 dsh plugin --profile <名称> add 补装。
先停新服务,再把 DSH_HOME 换回迁移前备份的那一份,最后回到旧安装方式启动。数据回滚优先于命令回滚,因为命令错了只是找不到入口,数据错了会丢会话与凭据。
相关术语
- 迁移
- 迁移是把命令入口、profile 插件与 DSH_HOME 数据从一套安装搬到另一套的过程,并保证三者版本与路径互相对应。— dsh CLI 行为参考
- profile
- profile 是 DeepSeek Harness 的具名组装环境,位于 $DSH_HOME/profiles/<名称>,各自维护独立依赖与 patch 文件。— dsh CLI README
- DSH_HOME
- DSH_HOME 是 DeepSeek Harness 的数据根目录,默认 ~/.dsh,保存 profile、配置、会话、日志与凭据。— dsh CLI 行为参考
- 回滚点
- 回滚点是在每个迁移步骤前保留的可恢复状态,通常是目录备份加一条已记录的原命令,用来在失败时退回上一步。— DeepSeek Harness 官方文档
来源
- dsh CLI 行为参考· deepseek-ai
- dsh CLI README· deepseek-ai
- DeepSeek Harness 官方文档· deepseek-harness