DM-recovery

dsh-plugin-dm-recovery-readiness

达梦 DM8 数据库可恢复能力评估插件。按 16 个恢复场景逐项对照「要求 vs 本库实际」，回答能恢复到哪一点、要丢什么，生成 HTML 报告。

单实例与共享存储集群（DMDSC 两节点）都已完成真机验证；文档里的地址与账号均做过替换，非真实环境。

目录

• 功能
• 环境要求
• 安装
• 使用
• 配置
• 报告
• OS 访问（可选）
• 注意事项
• 卸载
• 目录结构
• 开发
• 许可证

功能

• 16 个恢复场景，分三组覆盖：逻辑损坏 5 项（单条记录误删误改、整表误 DROP / TRUNCATE、整表批量误 UPDATE、schema 被 DROP、表结构误改）、物理损坏 8 项（单数据页、单数据文件、控制文件、联机日志、归档日志、备份集、整机与存储、表空间）、集群容灾 3 项（DMDSC 单节点故障、全集群故障、站点级灾难）
• 每个场景给出五档能力判定：可恢复 / 仅能粗粒度恢复 / 不可恢复 / 无法判定 / 不适用，并附一张「要求 vs 本库实际」条件表，只对未满足的条件给建议
• 回答「能恢复到哪一点」：归档链逐段核对（逐段验 next.ARCH_LSN === prev.CLSN + 1，再看并集有无洞）、未归档尾部、可回溯窗口的时间起点、时间 ↔ LSN 双向夹逼
• 备份可用性核对：库里有哪些备份集、能恢复到哪一点、备份本身可不可信，并核对调用方自行提供的备份位置。校验目标按「账本 → 磁盘上找到的备份集 → 调用方给的 backupPath」三档取；一个都取不到时也出结论（说明三个来源为何都不可用），不静默省略这一节 —— 备份集在 ASM 上时 find 本来就够不到，backupPath 是账本为空时唯一的位置线索
• 支持 DMDSC 逐节点核对：节点间参数配置差异、坏页归属、归档目录自足性（实测交叉配置下两个归档目录各自都不自足）。集群口径上还有两点：①「本节点备份日志里没有 N corrupted pages during backup」属正常形态（全备只由其中一个节点发起），别的节点已给出裁决时判提示而非警告；② ARCH_HANG_FLAG 的解读同时覆盖 LOCAL 与 REMOTE 目标 —— REMOTE 取 0 意味着对端不可达时静默放弃投递，那份归档冗余会悄悄失效
• 可选的主机侧只读核验（SSH）：dmrman CHECK BACKUPSET、备份日志的全库逐页裁决、备份文件查找
• 输出单文件 HTML 报告，同目录另存一份内容相同的 findings.json
• 库内 SQL 均为查询语句，主机侧只执行 3 类只读命令。不扫描、不修复、不改配置

分级的依据是「哪个场景救不了」，不是「哪个参数没设」—— 参数齐全但救不了，仍然是严重问题。

环境要求

安装

1. 安装插件

dsh plugin --profile web add github:Shiyuedong-Jade/DM-recovery

从本地目录安装：

dsh plugin --profile web add file:/path/to/dsh-plugin-dm-recovery-readiness

file: 安装时绝对路径不能含空格：dsh plugin 会转发给 pnpm，参数在空格处断开。

2. 放置达梦 JDBC 驱动

驱动 jar 是达梦的商业组件，不随插件分发。把达梦安装目录下的 dmdbms/drivers/jdbc/DmJdbcDriver8.jar 复制到工作目录的 drivers/ 下：

插件加载时会自动建好工作目录（drivers/、java/、runtime/）。工作目录可用插件配置 home 修改，见配置。

3. 重启

首次安装后重启 dsh web，并刷新已打开的页面。

使用

在会话里调用 dm_recovery_readiness。目标、账号、口令都能在设置卡片里预先填好，也可以每次调用时填。

工具有一个必填参数 action，共六个动作：

工具返回分级结论（严重 / 警告 / 提示 / 未取到）、稳定 ID 的结论项与报告路径。同一个结论跨次运行 ID 不变，可直接做对比。

调用参数

取值优先级：本次调用参数 > 插件配置。

配置

写在 profile 的 cordis.patch.yml 中该插件那一行上，也可以在设置界面里修改：

- insert:
    - id: dm-recovery-readiness
      name: 'dsh-plugin-dm-recovery-readiness'
      config:
        host: '10.0.0.61'                  # 默认目标；多节点用调用参数 targets
        port: 7236
        user: 'SYSDBA'
        home: 'D:\dm-recovery-home'        # 工作目录，默认 ~/.dsh/dm-recovery-readiness
        credentialRef: 'DM_RECOVERY_PASSWORD'
        driverJar: ''                      # 直接指定驱动 jar 时填
        javaHome: ''                       # 需要 javac 编译桥时填
        timeoutSec: 120
        sshUser: 'dmdba'                   # 以下全部为空时不做任何主机侧命令
        plinkPath: 'plink'
        dmrmanPath: 'dmrman'

口令的另外两种来源

本项目的约定是每次运行在设置卡片里手输、用完即弃 —— 插件不保存、不写配置文件。要用凭据库则设置 credentialRef：

export DM_RECOVERY_PASSWORD='数据库口令'

或写入 ~/.dsh/.credentials.yaml 的 refs，键名与 credentialRef 一致。

取值顺序：调用参数 password > 配置里的 password > credentialRef 指向的凭据库。

报告

report 动作落两份同名不同后缀的文件：

dm-recovery-<库名>-<时间戳>.html            ← 给人看：正文按恢复场景组织
dm-recovery-<库名>-<时间戳>.findings.json   ← 给机器用：信封去掉正文

报告按「恢复场景」组织，而不是按「插件能查到什么」分章：

1. 封面信息带：评估对象、数据库与实例、形态与版本、采集账号、生成时间、报告编号与总体等级色标
2. 目录：封面之后、第 1 节之前。点条目跳到对应章节，每节末尾可跳回目录；打印时隐藏
3. 评估概况：定义式面板，以及版本与实例信息（库与实例、服务版本、形态与节点、归档模式、归档链、未归档尾部、可回溯起点、备份账本、坏页记录、时间 ↔ LSN 精度、OS 级实测）
4. 结论摘要：KPI、分布条、「等级 / 条数 / 判定含义」表、分级明细、场景能力分布
5. 最要紧的几件事：按严重度排序，指向下方建议编号
6. 该改的 N 件事：建议按要改的东西去重，每件事只说一次，并列出它影响哪些场景
7. 逐场景条件对照：16 个场景 ×「要求 vs 本库实际」，建议只给指针
8. 场景能力汇总、场景判定的实测依据
9. OS 级实测：按本次实际跑到的条数连续编号
10. 附录 A~F：处置能力体检、坏页清单、归档空间、备份可用性、部署与节点核对、输出词表

版式与同族的《达梦数据库安全评估报告》一致：深蓝封面信息带、编号小节徽章、定义式信息面板、结论看板；计数为 0 的档位照常显示、只是变淡；带 A4 打印样式，导出 PDF 时表格与卡片不被切断。

DMDSC 多节点时报告里会多出节点核对的内容；报告默认输出到插件工作目录下的 dm-recovery-reports，不是 dsh 进程的启动目录。

README 与插件市场里展示的报告截图（assets/screenshot-*.png）由 node tools/shots.mjs 从一份真实报告生成：先脱敏、再出图；脱敏后若还残留真实 IP、账号或内部文档引用，工具会拒绝出图。截图清单见 screenshots.json。

OS 访问（可选）：三条只读命令

不给 sshHost 时插件是纯 JDBC 只读的，一次主机命令都不执行。给了之后，它会在数据库主机上执行三条固定形态的只读命令，把库内查不到的东西取回来：

边界写死在代码里，不靠自觉：

• 命令只能由 lib/ossh.js 的三个构造函数产生，没有任何接受任意命令字符串的入口。
• 路径参数走 safeArg 逐字符校验，允许的字符集故意很窄；引号、分号、管道、重定向、$、反引号、空格、换行、括号一律抛错。所以「把用户输入拼进命令」这条路在类型上就不存在。
• 三条命令全是只读，没有 RESTORE / RECOVER / 任何写命令，也不进 dmrman 交互模式（一律用 CTLSTMT= 一次性执行）。

scan-backup-log.sh 要先手工拷到数据库主机（插件没有上传通道），路径由 sshScriptPath 指定，默认 <sshLogDir>/scan-backup-log.sh。

注意事项

• 所有库内 SQL 都是查询语句，主机侧只执行 3 类只读命令（dmrman CHECK BACKUPSET、sh scan-backup-log.sh、find 找备份文件），不修改数据库与主机配置。
• 不主动扫描坏页，这是配置语义决定的：达梦 PAGE_CHECK_POLICY=1 下读到坏页会让实例 HALT。想发现未被碰到的坏页就得去读那些页，读到坏页库就 HALT —— 所以「扫描去发现坏页」在 PAGE_CHECK_POLICY=1 的环境上不该存在，本插件在实现层面就不提供。
• 不执行修复：SF_PRIMARY_PAGE_REPAIR 是拿备库的干净页覆盖主库坏页。备库不同步时，覆盖上去的可能是旧页 —— 把「一个坏页」换成「一个陈旧但校验通过」的页，更隐蔽。
• V$ERROR_PAGE 只记录被访问到的坏页，「未发现」不等于「没有坏页」。真机模拟实验（2026-10-13）实测：零化一页后读取，实例报 page check error 与 SYSTEM SHUTDOWN ABORT，而 V$ERROR_PAGE 始终 0 行；全备照样成功、日志里写 0 corrupted pages during backup。真正抓到它的是 dmdbchk。
• 对象定位依赖 DBA_EXTENTS。同一次实验里它在该页上返回 0 行（该页 DBA_EXTENTS 只报 1 个区 / 5 块，DBA_SEGMENTS 是 197 区 / 3152 块），所以定位结果一律按「可能没定位到」看待。
• 备份历史来自 V$BACKUPSET，只反映当前控制文件记得的备份集。账本为空不等于没有备份 —— 这一态判「无法判定」，不判「没有备份」。
• 「时间点 → LSN」的映射只能借归档文件的 CREATE_TIME，精度等于一个归档文件的跨度（低负载库一个文件能横跨几十小时），因此不承诺精确到秒的 PITR。夹逼区间跨过判定线时结论是「无法判定」，不猜一个。
• 没有 RTO 判定：恢复耗时取决于磁盘吞吐、并行度、是否异机，库内查不出来。插件不会拿假设的吞吐量估一个「预计分钟数」。
• 主机侧核验需要先把 assets/shell/scan-backup-log.sh 手工拷到数据库主机上；插件没有上传通道。
• 非交互地向 plink 传口令时，口令会出现在 plink 的进程参数里 —— 这是已知弱点。要规避就改用密钥登录（ssh -i），那样插件配置里根本不需要 SSH 口令。
• 数据守护（主备）形态尚未在真机验证。
• 以下环境未验证：DM9、Windows 上的达梦、ARM 架构（鲲鹏 / 飞腾）。
• 报告包含主机名、账号、目录路径与实测发现，不要提交到公开仓库或公共渠道。
• 口令在调用卡片中填写，插件不保存、不落盘；宿主的会话日志会记录调用参数，这一点插件无法避免。
• 开发时注意：宿主加载的是 profile 目录下的安装副本（$DSH_HOME/profiles/web/node_modules/dsh-plugin-dm-recovery-readiness），仓库源码改了不会自动生效。流程是先推送，再 dsh plugin --profile web update dsh-plugin-dm-recovery-readiness 更新副本，最后重启 dsh web。这个 profile 虽然声明了 patchReload: live，但那只覆盖补丁文件，插件代码没有热重载通道，原因见 DESIGN §48。
• Java 8 下首次运行会编译桥接器，产物在 home/runtime/classes；删除 home/runtime/ 可清空，下次运行自动重建。

卸载

dsh plugin --profile web remove dsh-plugin-dm-recovery-readiness

再删除工作目录（其中包含驱动 jar）：

目录结构

├── package.json              插件清单
├── cordis.patch.yml          作为 bundle 的插入清单
├── screenshots.json          报告截图清单（插件市场详情页用）
├── lib/
│   ├── index.js              插件入口：注册 dm_recovery_readiness 工具、解析参数与口令
│   ├── bridge.js             Node 与 Java 之间的只读桥
│   ├── queries.js            全部只读 SQL，跨版本差异都带降级链
│   ├── analyze.js            判定逻辑（纯函数，可离线单测）
│   ├── archive.js            归档空间参数检查
│   ├── backup.js             备份可用性：账本解析、覆盖度、归档链逐段核对、时间 ↔ LSN 夹逼
│   ├── dsc.js                DMDSC 多节点：目标解析、节点一致性、覆盖度、坏页归属
│   ├── scenarios.js          恢复场景引擎：16 个场景判定、条件表、建议
│   ├── vocab.js              唯一词表：分级、场景能力、条件满足
│   ├── format.js             四层输出骨架
│   ├── result.js             结果信封与稳定 ID
│   ├── report.js             HTML 报告渲染
│   └── ossh.js               可选的主机侧只读采集，命令只能由本模块的构造函数产生
├── assets/
│   ├── java/DmQuery.java     只读查询桥源码
│   ├── screenshot-*.png      报告截图，由 tools/shots.mjs 生成
│   └── shell/
│       ├── scan-backup-log.sh  日志扫描：备份证据与全库逐页裁决（插件会调用）
│       └── find-dm-logs.sh     日志发现（人工执行；插件当前不用它）
├── .github/workflows/
│   ├── ci.yml                离线自检（不连库、不装依赖）
│   └── peer-range.yml        每周核对 peer 范围是否落后于 registry（需联网）
└── tools/                    开发与自检脚本

开发

node tools/smoke.mjs                  # 离线自检：契约形状、安全边界、报告版式；不连库、不需要驱动（条数自己打印）
node tools/triage.mjs selftest        # 判定逻辑自检（含时间比对、反复损坏检测）
node tools/peer-range.mjs             # 核对 peer 范围是否还覆盖 registry 上已发布的版本（需联网）
node tools/check-backup.mjs           # 连真实库跑一次 backup 动作
node tools/run-action.mjs             # 任意 action 的真机运行器，支持 --out-dir、--dmrman-dcr-ini
node tools/live-check.mjs report      # 连真实库打印信封本体与正文
node tools/live-smoke.mjs             # 真机回归：六个 action × 信封不变量 × 交付物形状 × 口令不落盘
node tools/page-chain-check.mjs       # 坏页链路真机半验证，18 项断言（注入页 × 真机数据）
node tools/shots.mjs                  # 从 reports/ 下的报告生成 assets/screenshot-*.png（本机需 Edge / Chrome）

真机脚本的口令只从环境变量读，不进命令行：DM_HOST、DM_USER、DM_PASSWORD，DMDSC 另给 DM_TARGETS；主机侧核验另给 SSH_HOST、SSH_USER、SSH_PASSWORD、SSH_HOST_KEY、DMRMAN_DCR_INI、SSH_LOG_DIR。live-smoke.mjs 的退出码：0 通过、1 断言失败、2 环境不可用。

改 peerDependencies 时留意 @deepseek-ai/* 的预发布版本：node-semver 只在范围里存在与该版本同元组、且自身带预发布标签的比较符时才放行，写得太宽或太窄都会静默漏掉版本，用户装的时候才会看到 peer 告警。范围里是一条条枚举（覆盖 0.1.0~0.1.7 每个元组），宿主发新元组就会静默失效 —— 所以改完跑一次 node tools/peer-range.mjs（它把 registry 上已发布的版本逐个比一遍）；.github/workflows/peer-range.yml 每周也会自动跑一次。

许可证

MIT