前言¶

DeepSeek Harness（dsh）发布节奏快，候选版本常出；cordis.patch.yml 里多一行、少一行，都可能让实例起不来。手工改 settings.yaml、profile 补丁、agent preset 或 AGENTS.md 时，也很难在出事时快速回到「上次能正常启动」的状态。

下面介绍社区插件 dsh-plugin-safe-upgrade（维护者 devopsfortunato，分类 admin-security）。它通过 Git 记录关键配置变更、在升级前做校验与空闲检查、失败时自动恢复安装与配置，并可选地在每次启动后标记 known-good 配置。插件为非官方社区作品，仅使用 dsh 公开插件接口，与 DeepSeek / dsh 团队无隶属或背书关系；问题应在本仓库 Issues 反馈，而非 dsh 主项目。

这是什么¶

dsh-plugin-safe-upgrade 面向以 systemd 运行、且通过 npm 安装 dsh 的 Linux 环境，提供：

• 启动相关配置文件的自动版本历史（含密钥写入前的拦截）；
• 每次启动后的健康检查与 good-<time> 标记；
• Web UI 命令 /upgrade、/rollback 及 CLI dsh-safe-upgrade，用于受控升级与回滚。

当前 package 版本为 0.4.0（MIT 许可证）。插件自身无额外 npm 依赖。

核心功能¶

配置历史（Config history）¶

对决定 dsh 能否启动的文件（settings.yaml、profile 补丁与 manifest、agent preset、AGENTS.md 等）的每次修改，会在 $DSH_HOME 下的 Git 仓库中于数秒后自动提交；后续新建的 profile、preset 目录也会被纳入跟踪。会话、凭据、缓存与 node_modules 不纳入跟踪；若文件内容含字面量密钥，secret guard 会拒绝写入 Git。

配置历史与不依赖 systemd 的启动健康检查，可在无 systemd 场景下单独使用；升级与回滚需要 systemd。

Known-good 启动标记¶

每次启动后，插件检查插件加载器中的失败插件、未完成加载的插件以及损坏的 preset。若启动干净，会为当前配置与当前 dsh 版本打上 good-<time> 标签（每个配置与版本组合仅一次）。

/upgrade：侧载安装、校验后再切换¶

升级流程不在最后一刻之前动正在运行的服务：新版本安装到旁路目录，在临时拷贝的 $DSH_HOME 中对每个 profile 执行 dsh --dump-config 做校验；再次确认空闲后停止 dsh、交换安装目录并启动。若新版本无法恢复健康，会自动恢复先前的安装与配置。停机时间主要为目录交换加一次启动（README 描述为数秒量级）。

说明：dsh --dump-config 并非只读（例如 0.1.7 会改写 profile 的 cordis.yml 等），因此校验始终在配置副本上进行，live $DSH_HOME 不会被 dry run 或被拒绝的升级写入。

会话连续性检查¶

停机前，插件会用当前与新版本 dsh 分别打开每一份已存会话的副本。若「今天仍能打开」的会话在升级后将无法打开，则中止升级。若会话绑定的 agent preset 在新版本中已不存在，插件会尝试以 legacy 名称写入默认 preset 的副本，以便继续对话。回滚时会对「在新版本上继续的会话在旧版本上可能消失」给出警告。

Web UI 检查（可选 Chromium）¶

新版本启动后，在无头 Chromium 中加载真实 Web 应用；若出现 dsh 的 “Failed to load plugins” 界面，则触发回滚，以捕获服务端未必能感知的浏览器侧插件失败。未安装 Chromium/Chrome 时跳过该步骤并记为 warning。

警告与 failOnWarnings¶

升级、dry run、回滚会报告在新版本中不再匹配的 patch，以及未导致失败但已记录的插件错误。开启 failOnWarnings 可将这些视为失败：dry run 失败、升级在动 dsh 前停止（配置警告）或启动后回滚（启动警告）；手动回滚可被撤销。自动恢复不会因 warning 被撤销。

/rollback¶

可回到任意 known-good 启动标记或近期配置快照；目标配置在停止 dsh 前先做校验。若标记对应另一 dsh 版本且该版本的安装目录仍存在，会一并换回对应安装。

Boot guard（可选）¶

通过 systemd drop-in 在每次启动前校验配置；若 dsh 连续三次启动失败，会恢复本机可回到的最新 known-good 配置并再次启动。同一账户运行，且每 15 分钟内最多执行一次，避免循环。也可捕获非升级导致的手改损坏。

可选 Telegram 告警¶

升级、回滚与恢复事件可配置 Telegram 通知（细节见仓库文档）。

环境要求¶

• dsh 0.1.5 及以上，npm 安装（node_modules 中含 @deepseek-ai/dsh），以 systemd 服务（系统或用户单元）运行。
• Linux，需 git、npm、cp、systemd-run；Node.js ≥ 22。
• 会话检查会拷贝 $DSH_HOME/sessions，需 $DSH_HOME 旁有足够磁盘空间。
• Web UI 检查可选 Chromium/Chrome。

安装与启用¶

安装命令以仓库 README 为准（勿自行拼接 dsh plugin add github:owner/repo）：

git clone https://github.com/MovieMaker93/dsh-plugin-safe-upgrade ~/.dsh/plugins/safe-upgrade
dsh plugin --profile web add link:$HOME/.dsh/plugins/safe-upgrade
sudo systemctl restart dsh          # or whatever your unit is called

dsh plugin add 将包注册为 profile bundle，插入 safe-upgrade 行。首次启动时会开始配置历史，并将本次启动标为 good。

可选启动守卫（以拥有该 unit 的用户执行一次）：

node ~/.dsh/plugins/safe-upgrade/bin/dsh-safe-upgrade.mjs install-guard --unit dsh

安全提示：插件以当前 dsh 进程权限运行，可读写 $DSH_HOME、执行升级与 Git 操作。安装前请阅读源码与 MIT 许可证，确认符合你的运维与合规要求。

典型用法¶

Web UI¶

在 Web UI 中输入命令并回车：

任务结束后会有浏览器通知（若已授权）或页面 toast。

CLI¶

dsh-safe-upgrade status
dsh-safe-upgrade upgrade latest --dry-run
dsh-safe-upgrade upgrade 0.1.7-rc.2
dsh-safe-upgrade rollback good-20260928-190522
dsh-safe-upgrade check-ui        # does the web UI actually load right now?
dsh-safe-upgrade sessions        # which sessions fail to open, and which can't be continued
dsh-safe-upgrade sessions --fix-presets   # add legacy presets for sessions whose preset is gone
dsh-safe-upgrade install-guard --unit dsh [--remove]

sessions 在 $DSH_HOME/sessions 的副本上运行，不修改真实会话；--fix-presets 会用运行中的 dsh 合成 legacy preset 后写入 profile 的 cordis.patch.yml（patchReload: live 的 profile 可热加载）。

升级流程概览¶

README 中的流程可概括为：Web UI /upgrade 在 dsh 内检查空闲与无运行 job → 通过 systemd-run 启动 supervisor（在 dsh 重启后仍存活）→ 加锁、打 pre-upgrade-* 快照 → 复制安装目录、pin @deepseek-ai/* 并 npm install → 在临时 $DSH_HOME 上逐 profile dump-config → 双版本会话打开检查 → 等待空闲 → 停服、交换 install → 写 legacy preset（如有）→ 启动 → 等待 HTTP 与健康标记 → 无头浏览器检查 Web UI → 收集 journal 警告；任一步失败则停服、恢复 install.prev 与 pre-upgrade 配置并启动验证。

适用场景与注意¶

适合：长期用 systemd 托管 dsh、需要跟 latest/next 又担心配置或 RC 把实例打挂的运维或自托管开发者；希望配置变更有 Git 留档、并能一键回到 known-good 点的环境。

不适合或需额外准备：未用 systemd 的部署（无法用 /upgrade//rollback，仅历史与健康检查可用）；无法提供会话拷贝所需磁盘；不接受插件对安装目录与 $DSH_HOME 做自动 Git 与回滚操作的环境。

DSH 生态强调「一切皆插件」；社区目录站点与 DeepSeek / 幻方无官方从属关系，本插件同样为社区独立维护。

结尾¶

dsh-plugin-safe-upgrade 把「配置可回溯、升级可验证、失败可回滚」做成一套与 dsh 启动路径绑定的流程，减轻 RC 频繁发布与 patch 误配带来的停机风险。进一步了解可访问目录页与 GitHub 仓库（安装步骤以 README 中的 clone 地址为准）。

• 目录页：https://www.skillhub.cn/plugins/devopsfortunato/dsh-plugin-safe-upgrade
• GitHub：https://github.com/devopsfortunato/dsh-plugin-safe-upgrade