@wanghaopeng1148/deskpet 2.0.5 → 2.0.6

package/dist/node/server/main.js

@@ -171,11 +171,38 @@ async function main() {
     // 监听地址允许用环境变量临时覆盖。
     // 为什么需要：dev-all.mjs 会读 DESKPET_PORT 去等端口，而后端原先只认 settings.json，
     // 两边取值来源不一致 —— 一旦设了环境变量，就成了「后端其实起来了，启动脚本却一直等不到」。
-    // 顺带也让同机并行跑第二个实例（调试用）成为可能。
     const envPort = Number(process.env.DESKPET_PORT);
     const serverHost = process.env.DESKPET_HOST?.trim() || config.get('server.host');
     const serverPort = Number.isInteger(envPort) && envPort > 0 ? envPort : config.get('server.port');
-    const httpServer = await listen(expressApp, serverPort, serverHost);
+    // ── 单实例：拿不到锁就**拒绝启动** ─────────────────────────
+    // 需求是「这台机器上只允许跑一个 DeskPet」。此处必须早于 listen 和任何写库动作：
+    //   · 同一端口的重复启动，listen 那一步本来就会 EADDRINUSE（实测 Windows 同样如此），
+    //     但那条错误信息只说「端口被占用」，容易被当成别的程序占着；
+    //   · 真正需要这道锁兜的是**换了端口**的第二次启动 —— 端口不冲突，
+    //     它会一路跑到底并注册一遍定时任务，同一条 cron 就被执行两次（部署类脚本尤其危险）。
+    // 所以这里直接拒绝，而不是「起来了但不抢任务」。
+    const instanceLock = acquireInstanceLock();
+    if (!instanceLock.acquired) {
+        // 用**配置文件**里的端口报地址：本次进程可能带着 --port 覆盖，那个端口属于它自己，
+        // 而正在运行的那一个用的通常是配置端口
+        const runningUrl = dashboardUrl(config.get('server.host'), config.get('server.port'));
+        console.error('[deskpet] 已经有另一个 DeskPet 实例在运行，本次不再启动。');
+        console.error(`          数据目录：${getDataRoot()}`);
+        console.error(`          那个实例的管理台：${runningUrl}`);
+        console.error('          （它若启动时用 --port 指定过端口，以它自己的为准）');
+        console.error('          想停掉它：结束它的进程，或删掉启动文件夹里的 DeskPet.vbs 后重新登录');
+        console.error('          确实要并行跑第二个（例如调试）：换个数据目录即可 ——' +
+            ' DESKPET_HOME=<另一个目录> npx deskpet --port 3400');
+        process.exit(1);
+    }
+    let httpServer;
+    try {
+        httpServer = await listen(expressApp, serverPort, serverHost);
+    }
+    catch (err) {
+        instanceLock.release();
+        throw err;
+    }
     wsHub.attach(httpServer);
     const dashUrl = dashboardUrl(serverHost, serverPort);
     console.log(`[deskpet] 管理台: ${dashUrl}`);
@@ -197,28 +224,12 @@ async function main() {
     // 复位，并给未结束的执行记录收尾。这一步是「有罪推定」——它假定
     // 「库里凡是 running 的任务，都是上个进程挂掉时留下的」。
     //
-    // 但本进程完全可能只是因为 3210 端口被占用而没抢到实例（重复启动、--watch 抖动），
-    // 而真正在跑任务的其实是另一个进程。此时若提前执行 recoverInterrupted()，
-    // 就会把对方正在执行的任务误判成「服务重启，执行被中断」——
-    // 用户看到的现象是「刚点运行不到 1 秒就报中断」，且任务日志一个字节都没产生。
-    //
-    // 因此必须等 listen() 成功之后再启动调度器。
-    //
-    // 但光靠端口还不够：Windows 上 libuv 默认给监听套接字设 SO_REUSEADDR，
-    // 允许多个进程同时绑定同一端口且都 listen 成功，EADDRINUSE 基本不会触发。
-    // 所以这里再用心跳文件判一次「是否已有实例在跑」，有的话只跳过恢复动作、
-    // 不中断对方（见 utils/instance-guard.ts）。
-    // 单实例判定改用**原子锁**（O_EXCL 一步完成「检查 + 创建」），
-    // 取代原先心跳那种「读 → 判 → 写」三步：后者在两个实例几乎同时启动时，
-    // 双方都可能读到「没有心跳 / 心跳已过期」，于是双双认定「我是唯一实例」，
-    // 双双执行 recoverInterrupted()，把对方正在跑的任务掐成「服务重启，执行被中断」。
-    const instanceLock = acquireInstanceLock();
-    if (!instanceLock.acquired) {
-        console.warn('[deskpet] 检测到已有 DeskPet 实例在运行：本次跳过「残留任务恢复」，' +
-            '不会中断对方正在执行的任务');
-    }
+    // 所以顺序很要紧：单实例锁已在上面拒绝掉「已有实例在跑」的情况，listen 又拒绝了
+    // 端口被占用的情况（包括被别的程序占用）。走到这里说明本进程确实是唯一的那个，
+    // 做残留恢复不会误伤 —— 但仍保持「listen 成功之后才启动调度器」的顺序，
+    // 免得端口冲突时白白把库里 running 的记录误收尾一遍。
     startHeartbeat();
-    scheduler.start({ recover: instanceLock.acquired });
+    scheduler.start({ recover: true });
     // 开机自启：启动时应用 + 跟随设置变化
     // removeWhenOff: false —— 启动时的同步只「确保开启时文件存在」，不删除。
     // 否则一个用默认配置（autoStart=false）起来的实例（例如临时跑一次 npx，

package/dist/node/server/utils/instance-guard.js

@@ -1,11 +1,17 @@
 /**
  * 单实例保护 —— 判定「是否已有另一个 DeskPet 实例正在运行」。
  *
- * 为什么不能只靠端口检测（main.ts 的 listen）：
- *   Node/libuv 在 Windows 上默认给监听套接字设置 SO_REUSEADDR，而 Windows 的
- *   语义与 Linux 不同 —— 它允许**多个进程同时绑定同一端口且都 listen 成功**
- *   （Linux 下会直接 EADDRINUSE）。因此「端口占用了就当已有实例」这个假设
- *   在 Windows 上基本不成立，多个实例可以并存且互不知晓。
+ * 为什么在端口检测之外还要做单实例判定：
+ *   listen 遇到端口被占用会 EADDRINUSE 并退出 —— 实测（Node 22/24、本机 Windows 验证）
+ *   第二个进程绑同一端口**同样**报 EADDRINUSE，不存在「双双监听成功」这回事，
+ *   所以「同端口重复启动」端口检测已经拦得住。
+ *
+ *   它拦不住的是另外两种情形：
+ *     · 换了端口起第二个实例（例如 --port 3400），端口不冲突；
+ *     · 极小概率的时序竞争，或端口检测因别的错误被跳过。
+ *   这两种情况下若两个实例都执行 recoverInterrupted()，就会把对方正在执行的任务掐成中断。
+ *   因此再加一道按**数据目录**的原子锁兜底 —— 注意两者作用域不同：
+ *   端口是全局的，锁是跟着 DESKPET_HOME 走的（不同数据目录互不影响）。
  *
  * 为什么这件事很要紧：
  *   每个实例启动都会执行 TaskScheduler 的残留恢复（recoverInterrupted）——
@@ -14,9 +20,12 @@
  *   新实例这一下就会把对方正在执行的任务掐掉，用户看到的现象是
  *   「刚点运行不到 1 秒就报：服务重启，执行被中断」，且任务日志一个字节都没产生。
  *
- * 判定方式：心跳文件。运行中的实例定期刷新其内容（pid + 时间戳），
- * 启动时若发现心跳足够新且对应进程真的还活着，就认定已有实例在跑，
- * 此时必须跳过破坏性的恢复动作。
+ * 判定方式有两层：
+ *   ① 原子锁（主）：O_EXCL 一步完成「检查 + 创建」，按数据目录独占，见 acquireInstanceLock()。
+ *      判断锁属主是否还活着，读的是**锁文件里的 pid**（不是心跳）
+ *   ② 心跳文件（辅）：实例定期写 pid + 时间戳，用于诊断「现在是谁在跑」，
+ *      并由 anotherInstanceAlive() 提供「心跳是否新鲜 + 进程是否存活」的判断
+ *      （该函数目前主要被单测覆盖；启动路径已改用原子锁）
  */
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wanghaopeng1148/deskpet",
   "productName": "DeskPet",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "DeskPet 2.0 — 本机任务自动化服务 + Web 管理台 (Node + Express + Vue 3 + TypeScript)",
   "type": "module",
   "author": "whp",

package/server/main.ts

@@ -182,13 +182,45 @@ async function main(): Promise<void> {
   // 监听地址允许用环境变量临时覆盖。
   // 为什么需要：dev-all.mjs 会读 DESKPET_PORT 去等端口，而后端原先只认 settings.json，
   // 两边取值来源不一致 —— 一旦设了环境变量，就成了「后端其实起来了，启动脚本却一直等不到」。
-  // 顺带也让同机并行跑第二个实例（调试用）成为可能。
   const envPort = Number(process.env.DESKPET_PORT)
   const serverHost = process.env.DESKPET_HOST?.trim() || (config.get('server.host') as string)
   const serverPort =
     Number.isInteger(envPort) && envPort > 0 ? envPort : (config.get('server.port') as number)
 
-  const httpServer: Server = await listen(expressApp, serverPort, serverHost)
+  // ── 单实例：拿不到锁就**拒绝启动** ─────────────────────────
+  // 需求是「这台机器上只允许跑一个 DeskPet」。此处必须早于 listen 和任何写库动作：
+  //   · 同一端口的重复启动，listen 那一步本来就会 EADDRINUSE（实测 Windows 同样如此），
+  //     但那条错误信息只说「端口被占用」，容易被当成别的程序占着；
+  //   · 真正需要这道锁兜的是**换了端口**的第二次启动 —— 端口不冲突，
+  //     它会一路跑到底并注册一遍定时任务，同一条 cron 就被执行两次（部署类脚本尤其危险）。
+  // 所以这里直接拒绝，而不是「起来了但不抢任务」。
+  const instanceLock = acquireInstanceLock()
+  if (!instanceLock.acquired) {
+    // 用**配置文件**里的端口报地址：本次进程可能带着 --port 覆盖，那个端口属于它自己，
+    // 而正在运行的那一个用的通常是配置端口
+    const runningUrl = dashboardUrl(
+      config.get('server.host') as string,
+      config.get('server.port') as number
+    )
+    console.error('[deskpet] 已经有另一个 DeskPet 实例在运行，本次不再启动。')
+    console.error(`          数据目录：${getDataRoot()}`)
+    console.error(`          那个实例的管理台：${runningUrl}`)
+    console.error('          （它若启动时用 --port 指定过端口，以它自己的为准）')
+    console.error('          想停掉它：结束它的进程，或删掉启动文件夹里的 DeskPet.vbs 后重新登录')
+    console.error(
+      '          确实要并行跑第二个（例如调试）：换个数据目录即可 ——' +
+        ' DESKPET_HOME=<另一个目录> npx deskpet --port 3400'
+    )
+    process.exit(1)
+  }
+
+  let httpServer: Server
+  try {
+    httpServer = await listen(expressApp, serverPort, serverHost)
+  } catch (err) {
+    instanceLock.release()
+    throw err
+  }
   wsHub.attach(httpServer)
 
   const dashUrl = dashboardUrl(serverHost, serverPort)
@@ -213,30 +245,12 @@ async function main(): Promise<void> {
   // 复位，并给未结束的执行记录收尾。这一步是「有罪推定」——它假定
   // 「库里凡是 running 的任务，都是上个进程挂掉时留下的」。
   //
-  // 但本进程完全可能只是因为 3210 端口被占用而没抢到实例（重复启动、--watch 抖动），
-  // 而真正在跑任务的其实是另一个进程。此时若提前执行 recoverInterrupted()，
-  // 就会把对方正在执行的任务误判成「服务重启，执行被中断」——
-  // 用户看到的现象是「刚点运行不到 1 秒就报中断」，且任务日志一个字节都没产生。
-  //
-  // 因此必须等 listen() 成功之后再启动调度器。
-  //
-  // 但光靠端口还不够：Windows 上 libuv 默认给监听套接字设 SO_REUSEADDR，
-  // 允许多个进程同时绑定同一端口且都 listen 成功，EADDRINUSE 基本不会触发。
-  // 所以这里再用心跳文件判一次「是否已有实例在跑」，有的话只跳过恢复动作、
-  // 不中断对方（见 utils/instance-guard.ts）。
-  // 单实例判定改用**原子锁**（O_EXCL 一步完成「检查 + 创建」），
-  // 取代原先心跳那种「读 → 判 → 写」三步：后者在两个实例几乎同时启动时，
-  // 双方都可能读到「没有心跳 / 心跳已过期」，于是双双认定「我是唯一实例」，
-  // 双双执行 recoverInterrupted()，把对方正在跑的任务掐成「服务重启，执行被中断」。
-  const instanceLock = acquireInstanceLock()
-  if (!instanceLock.acquired) {
-    console.warn(
-      '[deskpet] 检测到已有 DeskPet 实例在运行：本次跳过「残留任务恢复」，' +
-        '不会中断对方正在执行的任务'
-    )
-  }
+  // 所以顺序很要紧：单实例锁已在上面拒绝掉「已有实例在跑」的情况，listen 又拒绝了
+  // 端口被占用的情况（包括被别的程序占用）。走到这里说明本进程确实是唯一的那个，
+  // 做残留恢复不会误伤 —— 但仍保持「listen 成功之后才启动调度器」的顺序，
+  // 免得端口冲突时白白把库里 running 的记录误收尾一遍。
   startHeartbeat()
-  scheduler.start({ recover: instanceLock.acquired })
+  scheduler.start({ recover: true })
 
   // 开机自启：启动时应用 + 跟随设置变化
   // removeWhenOff: false —— 启动时的同步只「确保开启时文件存在」，不删除。

package/server/utils/instance-guard.ts

@@ -1,11 +1,17 @@
 /**
  * 单实例保护 —— 判定「是否已有另一个 DeskPet 实例正在运行」。
  *
- * 为什么不能只靠端口检测（main.ts 的 listen）：
- *   Node/libuv 在 Windows 上默认给监听套接字设置 SO_REUSEADDR，而 Windows 的
- *   语义与 Linux 不同 —— 它允许**多个进程同时绑定同一端口且都 listen 成功**
- *   （Linux 下会直接 EADDRINUSE）。因此「端口占用了就当已有实例」这个假设
- *   在 Windows 上基本不成立，多个实例可以并存且互不知晓。
+ * 为什么在端口检测之外还要做单实例判定：
+ *   listen 遇到端口被占用会 EADDRINUSE 并退出 —— 实测（Node 22/24、本机 Windows 验证）
+ *   第二个进程绑同一端口**同样**报 EADDRINUSE，不存在「双双监听成功」这回事，
+ *   所以「同端口重复启动」端口检测已经拦得住。
+ *
+ *   它拦不住的是另外两种情形：
+ *     · 换了端口起第二个实例（例如 --port 3400），端口不冲突；
+ *     · 极小概率的时序竞争，或端口检测因别的错误被跳过。
+ *   这两种情况下若两个实例都执行 recoverInterrupted()，就会把对方正在执行的任务掐成中断。
+ *   因此再加一道按**数据目录**的原子锁兜底 —— 注意两者作用域不同：
+ *   端口是全局的，锁是跟着 DESKPET_HOME 走的（不同数据目录互不影响）。
  *
  * 为什么这件事很要紧：
  *   每个实例启动都会执行 TaskScheduler 的残留恢复（recoverInterrupted）——
@@ -14,9 +20,12 @@
  *   新实例这一下就会把对方正在执行的任务掐掉，用户看到的现象是
  *   「刚点运行不到 1 秒就报：服务重启，执行被中断」，且任务日志一个字节都没产生。
  *
- * 判定方式：心跳文件。运行中的实例定期刷新其内容（pid + 时间戳），
- * 启动时若发现心跳足够新且对应进程真的还活着，就认定已有实例在跑，
- * 此时必须跳过破坏性的恢复动作。
+ * 判定方式有两层：
+ *   ① 原子锁（主）：O_EXCL 一步完成「检查 + 创建」，按数据目录独占，见 acquireInstanceLock()。
+ *      判断锁属主是否还活着，读的是**锁文件里的 pid**（不是心跳）
+ *   ② 心跳文件（辅）：实例定期写 pid + 时间戳，用于诊断「现在是谁在跑」，
+ *      并由 anotherInstanceAlive() 提供「心跳是否新鲜 + 进程是否存活」的判断
+ *      （该函数目前主要被单测覆盖；启动路径已改用原子锁）
  */
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'