@coclaw/openclaw-coclaw 0.26.2 → 0.26.3

package/src/auto-upgrade/worker-backup.js

@@ -1,33 +1,55 @@
 /**
  * worker-backup.js — 插件目录物理备份与恢复
  *
- * 使用 Node.js 内置 fs.cp()（16.7+）进行跨平台物理复制，无外部依赖。
- * 备份采用原子操作：先 cp 到 .tmp.bak，再 rename 到 .bak，
- * 避免中途失败产生不完整的备份目录。
+ * 备份目录固定在 `<state-dir>/coclaw/upgrade-backup/<pluginId>/`——必须在
+ * npm 地盘（extensions/<id>/node_modules）之外：`plugins update` 跑 npm 时
+ * 会把安装目录里的陌生 `.bak` 目录当 extraneous 修剪掉（本机实测 update 后
+ * 约 46s 消失），导致回滚时备份已无。state-dir 下的自管目录免疫 npm prune。
  *
- * 命名约束：备份目录（含临时目录）必须以 .bak 结尾。
- * OpenClaw gateway 启动时会扫描 extensions/ 下所有子目录并尝试作为插件加载，
- * 但会跳过以 .bak 结尾的目录（discovery.ts shouldIgnoreScannedDirectory）。
- * 若临时目录不以 .bak 结尾（如曾用的 .bak-tmp），在 fs.cp 期间 gateway
- * 重启会将不完整的目录当作插件加载，导致 method 重复注册或加载异常。
+ * state-dir 解析复用 state.js 的双轨通道（gateway 进程走 runtime 注入，
+ * worker 子进程走 OPENCLAW_STATE_DIR 环境变量）。
+ *
+ * 备份采用原子操作：先 cp 到 `<pluginId>.tmp`，再 rename 到 `<pluginId>`，
+ * 避免中途失败产生不完整的备份目录。恢复时备份目录与插件目录可能跨文件系统
+ * （state-dir 与 extensions 不保证同盘），rename 报 EXDEV 时退化为 cp+rm。
+ *
+ * 残留语义：interrupted 等异常分支不主动清备份——保留给人工恢复，下次备份前
+ * 覆盖；固定目录 + 升级锁保证同一插件至多一份，无累积风险。
  */
 import fs from 'node:fs/promises';
 import nodePath from 'node:path';
 
+import { resolveStateDir } from './state.js';
+
+const CHANNEL_ID = 'coclaw';
+const BACKUP_DIRNAME = 'upgrade-backup';
+
+/**
+ * 备份目录路径：`<state-dir>/coclaw/upgrade-backup/<pluginId>`
+ * @param {string} pluginId
+ * @returns {string}
+ */
+export function getBackupDir(pluginId) {
+	return nodePath.join(resolveStateDir(), CHANNEL_ID, BACKUP_DIRNAME, pluginId);
+}
+
 /**
  * 备份插件目录
  * @param {string} pluginDir - 插件安装目录
+ * @param {string} pluginId - 插件 ID（备份目录名）
  * @returns {Promise<string>} 备份目录路径
  */
-export async function createBackup(pluginDir) {
-	const backupDir = `${pluginDir}.bak`;
+export async function createBackup(pluginDir, pluginId) {
+	const backupDir = getBackupDir(pluginId);
 
-	// 若上次异常退出遗留了 .bak，先清理
+	// 若上次异常退出遗留了旧备份/临时目录，先清理
 	await fs.rm(backupDir, { recursive: true, force: true });
-
-	// 先复制到临时名，再 rename，确保原子性
-	const tmpDir = `${pluginDir}.tmp.bak`;
+	const tmpDir = `${backupDir}.tmp`;
 	await fs.rm(tmpDir, { recursive: true, force: true });
+
+	// 先复制到临时名，再 rename（同目录内必为同文件系统，rename 原子），
+	// 确保备份目录要么完整要么不存在
+	await fs.mkdir(nodePath.dirname(backupDir), { recursive: true });
 	await fs.cp(pluginDir, tmpDir, { recursive: true });
 	await fs.rename(tmpDir, backupDir);
 
@@ -37,10 +59,17 @@ export async function createBackup(pluginDir) {
 /**
  * 从备份恢复插件目录
  * @param {string} pluginDir - 插件安装目录
+ * @param {string} pluginId - 插件 ID
+ * @param {object} [opts]
+ * @param {Function} [opts.renameFn] - 测试注入（EXDEV 分支）
+ * @param {Function} [opts.rmFn] - 测试注入（EXDEV 退化路径的备份清理）
+ * @param {Function} [opts.log] - 本地日志函数（worker 进程禁 remoteLog）
  * @returns {Promise<boolean>} 是否成功恢复
  */
-export async function restoreFromBackup(pluginDir) {
-	const backupDir = `${pluginDir}.bak`;
+export async function restoreFromBackup(pluginDir, pluginId, opts) {
+	const backupDir = getBackupDir(pluginId);
+	/* c8 ignore next -- ?./?? fallback */
+	const doRename = opts?.renameFn ?? fs.rename;
 
 	try {
 		await fs.access(backupDir);
@@ -51,29 +80,37 @@ export async function restoreFromBackup(pluginDir) {
 
 	// 删除损坏的新版本
 	await fs.rm(pluginDir, { recursive: true, force: true });
-	// 恢复备份
-	await fs.rename(backupDir, pluginDir);
+	// 恢复备份：state-dir 与 extensions 可能跨文件系统，EXDEV 时退化 cp+rm
+	try {
+		await doRename(backupDir, pluginDir);
+	}
+	catch (err) {
+		if (err?.code !== 'EXDEV') throw err;
+		await fs.cp(backupDir, pluginDir, { recursive: true });
+		// cp 成功即文件态已恢复，restore 成立；残留备份目录清理失败只降级为告警——
+		// 整体抛出会让调用方误走 fallback install / 误记 rollback-failed
+		try {
+			/* c8 ignore next -- ?./?? fallback */
+			const doRm = opts?.rmFn ?? fs.rm;
+			await doRm(backupDir, { recursive: true, force: true });
+		}
+		catch (rmErr) {
+			/* c8 ignore next -- ?? fallback：err 字段缺省的兜底分支不强制覆盖 */
+			opts?.log?.(`[upgrade-worker] Backup cleanup after EXDEV restore failed (non-fatal): ${rmErr?.message ?? String(rmErr)}`);
+		}
+	}
 	return true;
 }
 
 /**
  * 删除备份目录
- * @param {string} pluginDir - 插件安装目录
+ * @param {string} pluginId - 插件 ID
  */
-export async function removeBackup(pluginDir) {
-	const backupDir = `${pluginDir}.bak`;
+export async function removeBackup(pluginId) {
+	const backupDir = getBackupDir(pluginId);
 	await fs.rm(backupDir, { recursive: true, force: true });
 }
 
-/**
- * 从 extensions 目录路径推算备份目录路径
- * @param {string} pluginDir
- * @returns {string}
- */
-export function getBackupDir(pluginDir) {
-	return `${pluginDir}.bak`;
-}
-
 /**
  * 读取指定目录下 package.json 的版本号
  * @param {string} dir

package/src/auto-upgrade/worker-verify.js

@@ -9,9 +9,10 @@
  * 执行 `plugins update` 之间 npm dist-tag 可能已指向 x+1；严格等 x 会把
  * 这种"升级到了更新版本"误判为失败并回滚。
  *
- * 磁盘 package.json 的版本仅作为诊断写入本地日志，不参与判定——openclaw 侧
- * `plugins.installs[id].installPath` 可能在 id-migration 等极端场景发生漂移，
- * 而 upgradeHealth 是 gateway 进程内"新代码真的被加载"的权威信号。
+ * 磁盘 package.json 的版本仅作为诊断写入本地日志，不参与判定——安装目录路径
+ * 取自权威记录（经 openclaw plugins inspect 读取），仍可能在 id-migration 等
+ * 极端场景发生漂移，而 upgradeHealth 返回 gateway 进程模块加载时刻钉住的版本
+ * 快照（handler 不读磁盘），是"新代码真的被加载"的权威信号。
  *
  * worker 运行在独立子进程中，禁止使用 remoteLog；诊断信息全部通过 logger
  * （本地日志）输出，由 updater 记录到 upgrade-log.jsonl。
@@ -20,21 +21,17 @@ import { execFile as nodeExecFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import nodePath from 'node:path';
 
-// 与 updater-check.js 同逻辑，worker 运行在独立子进程，不跨进程复用 gateway 模块
-function isNewerVersion(a, b) {
-	const parse = (v) => v.replace(/-.*$/, '').split('.').map(Number);
-	const pa = parse(a);
-	const pb = parse(b);
-	for (let i = 0; i < 3; i++) {
-		/* c8 ignore next 2 -- ?? fallback：正常 semver 不会有缺失段 */
-		if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
-		if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
-	}
-	// x.y.z 相同时：release > pre-release（semver 规则）
-	const aHasPre = a.includes('-');
-	const bHasPre = b.includes('-');
-	if (bHasPre && !aHasPre) return true;
-	return false;
+import { isNewerVersion } from './updater-check.js';
+
+/**
+ * 升级达标判据：实际版本等于或新于目标即达标（isNewerVersion 是严格大于，须显式加等号）。
+ * 健康轮询与 worker 的 L2 结局核对共用本函数，保证两处判据同构。
+ * @param {string} version - 实际观测到的版本
+ * @param {string} target - 目标版本
+ * @returns {boolean}
+ */
+export function isVersionReached(version, target) {
+	return version === target || isNewerVersion(version, target);
 }
 
 const CMD_TIMEOUT_MS = 30_000;
@@ -77,18 +74,22 @@ function runCmd(cmd, args, opts) {
 }
 
 /**
- * 触发一次 gateway 重启；失败不抛（后续轮询 RPC 会兜底验证 gateway 是否就绪）
+ * 触发一次 gateway 重启；失败不抛（后续轮询 RPC 会兜底验证 gateway 是否就绪）。
+ * 返回命令是否成功——回滚路径据此追加 rollback-restart-failed 诊断事件，
+ * verify 路径忽略返回值（轮询兜底）。
  * @param {object} [opts]
  * @param {Function} [opts.execFileFn]
- * @returns {Promise<void>}
+ * @returns {Promise<boolean>}
  */
 export async function triggerGatewayRestart(opts) {
 	try {
 		await runCmd('openclaw', ['gateway', 'restart'], opts);
+		return true;
 	}
 	catch {
 		// restart 命令本身失败不阻断：openclaw 可能已在重启/daemon 自恢复；
 		// 无论如何都进入后续 upgradeHealth 轮询，由它判定 gateway 最终是否可用
+		return false;
 	}
 }
 
@@ -166,7 +167,7 @@ export async function pollUpgradeHealth(toVersion, opts) {
 		const result = await callUpgradeHealthOnce(opts);
 		if (result.ok) {
 			// 等于或更新均视为成功，覆盖"升级窗口期 dist-tag 前移"的情形
-			if (result.version === toVersion || isNewerVersion(result.version, toVersion)) {
+			if (isVersionReached(result.version, toVersion)) {
 				return {
 					ok: true,
 					version: result.version,