luckytri 1.2.1 → 1.2.2

package/scripts/service-supervisor.js

@@ -1,17 +1,9 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { processAlive } from "../server/runtime/update-manager.js";
-
-const ACTIVE_UPDATE = new Set([
-  "queued",
-  "downloading",
-  "checking",
-  "stopping",
-  "backup",
-  "restarting",
-  "verifying",
-  "restoring",
-]);
+import {
+  processAlive,
+  isUpdateFinished,
+} from "../server/runtime/update-manager.js";
 
 function readJob(home) {
   try {
@@ -34,7 +26,10 @@ export async function updatedServerAfterExit(
   while (true) {
     const job = read();
     if (!job || job.parent !== parentPid) return { matched: false, pid: null };
-    if (!ACTIVE_UPDATE.has(job.status))
+    // This supervisor can outlive its installed release. A future worker may
+    // introduce stages this older process does not know; only explicit terminal
+    // states permit handover while the worker is still alive.
+    if (isUpdateFinished(job.status))
       return { matched: true, pid: alive(job.childPid) ? job.childPid : null };
     if (!alive(job.workerPid))
       return { matched: true, pid: alive(job.childPid) ? job.childPid : null };

package/scripts/start-server.js

@@ -30,7 +30,12 @@ else console.log("未检测到系统代理，外部 API 请求将直连。");
 let currentPid;
 for (const signal of ["SIGINT", "SIGTERM"])
   process.on(signal, () => {
-    if (currentPid) process.kill(currentPid, signal);
+    if (currentPid)
+      try {
+        process.kill(currentPid, signal);
+      } catch (error) {
+        if (error.code !== "ESRCH") throw error;
+      }
   });
 
 async function start(root) {
@@ -71,6 +76,7 @@ try {
     } else {
       await waitForProcessExit(tracked.pid);
     }
+    currentPid = undefined;
 
     const update = await updatedServerAfterExit(paths.home, tracked.pid);
     if (!update.matched) break;
@@ -80,6 +86,7 @@ try {
       // after rollback). Keep this foreground process alive so systemd does not
       // kill that process or any still-running update work in the same cgroup.
       tracked = { pid: update.pid };
+      currentPid = update.pid;
       direct = false;
       continue;
     }

package/scripts/update-instance.js

@@ -5,6 +5,7 @@ import {
   writeFileSync,
   readFileSync,
   realpathSync,
+  writeSync,
 } from "node:fs";
 import { dirname, join, delimiter } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -23,6 +24,21 @@ import {
   writeUpdateJob,
 } from "../server/runtime/update-manager.js";
 import { updateRoot } from "../server/runtime/installation.js";
+import {
+  npmFailureCode,
+  updateError,
+} from "../server/runtime/update-errors.js";
+
+export function requireUpdateNode(version = process.versions.node) {
+  const [major, minor] = String(version).split(".").map(Number);
+  if (
+    !Number.isInteger(major) ||
+    !Number.isInteger(minor) ||
+    major < 24 ||
+    (major === 24 && minor < 5)
+  )
+    throw updateError("NODE_UNSUPPORTED");
+}
 
 export function installEnvironment(env) {
   const kept = {};
@@ -35,11 +51,11 @@ export function installEnvironment(env) {
       kept[key] = value;
   return kept;
 }
-export function findNpmCli(env = process.env) {
+export function findNpmCli(env = process.env, execPath = process.execPath) {
   const candidates = [
     env.npm_execpath,
-    join(dirname(process.execPath), "node_modules/npm/bin/npm-cli.js"),
-    join(dirname(process.execPath), "../lib/node_modules/npm/bin/npm-cli.js"),
+    join(dirname(execPath), "node_modules/npm/bin/npm-cli.js"),
+    join(dirname(execPath), "../lib/node_modules/npm/bin/npm-cli.js"),
     ...String(env.PATH || env.Path || "")
       .split(delimiter)
       .flatMap((dir) => [
@@ -60,31 +76,73 @@ export function findNpmCli(env = process.env) {
       /* Try the next native Node/npm installation location. */
     }
   }
-  throw Error("未找到 npm");
+  throw updateError("NPM_NOT_FOUND");
 }
-function command(args, { cwd, env = process.env, timeout = 600000, log } = {}) {
+export function runUpdateCommand(
+  args,
+  {
+    cwd,
+    env = process.env,
+    timeout = 600000,
+    log,
+    failureCode = "STEP_FAILED",
+    npmInstall = false,
+  } = {},
+) {
   return new Promise((resolve, reject) => {
     const fd = log ? openSync(log, "a", 0o600) : null;
-    const child = spawn(process.execPath, args, {
-      cwd,
-      env,
-      windowsHide: true,
-      stdio: fd === null ? "ignore" : ["ignore", fd, fd],
-    });
-    if (fd !== null) closeSync(fd);
-    let timedOut = false;
-    const timer = setTimeout(() => {
+    let timer,
+      child,
+      settled = false,
+      timedOut = false,
+      outputError,
+      tail = "";
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        if (fd !== null) closeSync(fd);
+      } catch (closeError) {
+        error ||= closeError;
+      }
+      if (error) reject(error);
+      else resolve();
+    };
+    try {
+      child = spawn(process.execPath, args, {
+        cwd,
+        env,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      finish(error);
+      return;
+    }
+    const capture = (chunk) => {
+      if (settled) return;
+      tail = (tail + chunk.toString("utf8")).slice(-16384);
+      try {
+        if (fd !== null) writeSync(fd, chunk);
+      } catch (error) {
+        outputError = error;
+        // Wait for exit before rollback can rename a migration database.
+        child.kill("SIGKILL");
+      }
+    };
+    child.stdout.on("data", capture);
+    child.stderr.on("data", capture);
+    timer = setTimeout(() => {
       timedOut = true;
-      child.kill();
+      child.kill("SIGKILL");
     }, timeout);
-    child.once("error", (e) => {
-      clearTimeout(timer);
-      reject(e);
-    });
-    child.once("exit", (code) => {
-      clearTimeout(timer);
-      if (timedOut) reject(Error("更新步骤超时"));
-      else code === 0 ? resolve() : reject(Error("更新程序校验失败"));
+    child.once("error", finish);
+    child.once("close", (code) => {
+      if (outputError) finish(outputError);
+      else if (timedOut) finish(updateError("STEP_TIMEOUT"));
+      else if (code === 0) finish();
+      else finish(updateError(npmInstall ? npmFailureCode(tail) : failureCode));
     });
   });
 }
@@ -94,10 +152,11 @@ export function updateExecution(paths) {
   const pause = () => new Promise((r) => setTimeout(r, 250));
   return {
     async install(slot, version) {
+      requireUpdateNode();
       const cli = findNpmCli();
       const userconfig = join(updateRoot(paths.home), "install.npmrc");
       writeFileSync(userconfig, "", { mode: 0o600 });
-      await command(
+      await runUpdateCommand(
         [
           cli,
           "install",
@@ -112,20 +171,26 @@ export function updateExecution(paths) {
           "--engine-strict",
           `luckytri@${version}`,
         ],
-        { cwd: slot, env: installEnvironment(process.env), log: paths.log },
+        {
+          cwd: slot,
+          env: installEnvironment(process.env),
+          log: paths.log,
+          npmInstall: true,
+        },
       );
     },
     async check(root, version) {
       const script = `import fs from 'node:fs';import {createRequire} from 'node:module';const p=JSON.parse(fs.readFileSync(${JSON.stringify(join(root, "package.json"))},'utf8'));if(p.version!==${JSON.stringify(version)})process.exit(1);await import(${JSON.stringify(pathToFileURL(join(root, "server/app.js")).href)});const sharp=createRequire(${JSON.stringify(pathToFileURL(join(root, "package.json")).href)})('sharp');await sharp({create:{width:1,height:1,channels:3,background:'#fff'}}).png().toBuffer();`;
-      await command(["--input-type=module", "-e", script], {
+      await runUpdateCommand(["--input-type=module", "-e", script], {
         cwd: root,
         env: installEnvironment(process.env),
         timeout: 30000,
         log: paths.log,
+        failureCode: "PACKAGE_CHECK_FAILED",
       });
     },
     async migrate(root, database, { previous, version, databaseId }) {
-      await command(
+      await runUpdateCommand(
         [
           join(root, "scripts", "migrate-instance.js"),
           database,
@@ -138,6 +203,7 @@ export function updateExecution(paths) {
           env: installEnvironment(process.env),
           timeout: 3600000,
           log: paths.log,
+          failureCode: "MIGRATION_FAILED",
         },
       );
     },

package/server/i18n/errors.js

@@ -34,6 +34,42 @@ export const ERRORS = {
     "The update did not complete. The original program and data were retained. Check the runtime log before trying again.",
   "自动恢复未完成，更新前的校验备份已保留，请查看运行日志并手动恢复。":
     "Automatic recovery did not complete. The verified pre-update backup was retained. Check the runtime log and recover manually.",
+  "Node.js 版本不满足新版本要求，请先升级 Node.js 后重试。":
+    "This Node.js version does not meet the new release requirements. Upgrade Node.js and try again.",
+  "当前服务找不到 npm，请安装 npm 并检查服务的 PATH 配置。":
+    "The service cannot find npm. Install npm and check the service PATH.",
+  "npm 暂时无法下载该版本或其运行依赖，请稍后重新检查更新。":
+    "npm cannot download this release or its runtime dependencies yet. Check for updates again later.",
+  "连接 npm 失败，请检查服务器的网络、DNS 和代理配置。":
+    "Cannot reach npm. Check the server network, DNS and proxy settings.",
+  "连接 npm 时证书校验失败，请检查服务器的证书和代理配置。":
+    "Certificate verification failed when connecting to npm. Check the server certificates and proxy settings.",
+  "npm 拒绝了下载请求，请检查服务器的网络或代理访问限制。":
+    "npm rejected the download request. Check network or proxy access restrictions.",
+  "磁盘空间不足，请为新程序、数据库快照和迁移副本留出空间。":
+    "There is not enough disk space for the new program, database snapshot and migration copy.",
+  "服务账号没有所需的读写权限，请检查实例和更新目录的权限。":
+    "The service account lacks read or write access. Check the instance and update directory permissions.",
+  "当前更新步骤超时，请检查运行日志后重试。":
+    "The update step timed out. Check the runtime log and try again.",
+  "新版本安装失败，旧实例仍在运行，请查看运行日志中的 npm 报错。":
+    "Installation failed while the previous instance remains running. Check the npm errors in the runtime log.",
+  "新程序或本机运行依赖校验失败，请查看运行日志。":
+    "The new program or its local runtime dependencies failed validation. Check the runtime log.",
+  "旧实例未能安全停止，请检查进程管理和实例端口。":
+    "The previous instance could not be stopped safely. Check process management and the instance port.",
+  "更新前的数据库快照未能完成或通过校验，请查看运行日志。":
+    "The pre-update database snapshot could not be completed or verified. Check the runtime log.",
+  "记忆与数据迁移未通过校验，请查看运行日志。":
+    "Memory and data migration failed validation. Check the runtime log.",
+  "新实例未能正常启动，请检查运行日志和端口占用。":
+    "The new instance could not start correctly. Check the runtime log and port usage.",
+  "更新进程意外退出，请检查服务管理器、进程退出记录和运行日志。":
+    "The update process exited unexpectedly. Check the service manager, process exit records and runtime log.",
+  "旧版本或数据库恢复未完成，请使用更新前的校验备份恢复。":
+    "The previous program or database could not be restored. Recover from the verified pre-update backup.",
+  "当前更新步骤未完成，请查看运行日志。":
+    "The update step did not complete. Check the runtime log.",
   "缺少候选版本的数据迁移器，已停止更新":
     "The candidate release has no data migrator. The update was stopped.",
   迁移目标不是现有的绝对路径数据库文件:

package/server/runtime/update-errors.js

@@ -0,0 +1,73 @@
+// Only these descriptions reach the management UI. Subprocess output can
+// contain local paths or credentials and belongs in the local log only.
+export const UPDATE_FAILURES = Object.freeze({
+  NODE_UNSUPPORTED: "Node.js 版本不满足新版本要求，请先升级 Node.js 后重试。",
+  NPM_NOT_FOUND: "当前服务找不到 npm，请安装 npm 并检查服务的 PATH 配置。",
+  VERSION_UNAVAILABLE:
+    "npm 暂时无法下载该版本或其运行依赖，请稍后重新检查更新。",
+  NETWORK_ERROR: "连接 npm 失败，请检查服务器的网络、DNS 和代理配置。",
+  TLS_ERROR: "连接 npm 时证书校验失败，请检查服务器的证书和代理配置。",
+  REGISTRY_ACCESS: "npm 拒绝了下载请求，请检查服务器的网络或代理访问限制。",
+  DISK_FULL: "磁盘空间不足，请为新程序、数据库快照和迁移副本留出空间。",
+  PERMISSION_DENIED: "服务账号没有所需的读写权限，请检查实例和更新目录的权限。",
+  STEP_TIMEOUT: "当前更新步骤超时，请检查运行日志后重试。",
+  INSTALL_FAILED:
+    "新版本安装失败，旧实例仍在运行，请查看运行日志中的 npm 报错。",
+  PACKAGE_CHECK_FAILED: "新程序或本机运行依赖校验失败，请查看运行日志。",
+  STOP_FAILED: "旧实例未能安全停止，请检查进程管理和实例端口。",
+  BACKUP_FAILED: "更新前的数据库快照未能完成或通过校验，请查看运行日志。",
+  MIGRATION_FAILED: "记忆与数据迁移未通过校验，请查看运行日志。",
+  START_FAILED: "新实例未能正常启动，请检查运行日志和端口占用。",
+  UPDATE_INTERRUPTED:
+    "更新进程意外退出，请检查服务管理器、进程退出记录和运行日志。",
+  RECOVERY_FAILED: "旧版本或数据库恢复未完成，请使用更新前的校验备份恢复。",
+  STEP_FAILED: "当前更新步骤未完成，请查看运行日志。",
+});
+
+export function updateError(code) {
+  const known = Object.hasOwn(UPDATE_FAILURES, code) ? code : "STEP_FAILED";
+  return Object.assign(Error(UPDATE_FAILURES[known]), { updateCode: known });
+}
+
+export function npmFailureCode(output) {
+  for (const [pattern, code] of [
+    [/\bEBADENGINE\b/, "NODE_UNSUPPORTED"],
+    [/\bENOSPC\b/, "DISK_FULL"],
+    [/\b(?:EACCES|EPERM)\b/, "PERMISSION_DENIED"],
+    [/\b(?:E404|ETARGET)\b/, "VERSION_UNAVAILABLE"],
+    [/\b(?:E401|E403)\b/, "REGISTRY_ACCESS"],
+    [
+      /\b(?:CERT_[A-Z_]+|[A-Z_]*CERTIFICATE[A-Z_]*|SELF_SIGNED_CERT_IN_CHAIN|UNABLE_TO_VERIFY_LEAF_SIGNATURE)\b/,
+      "TLS_ERROR",
+    ],
+    [
+      /\b(?:ENOTFOUND|EAI_AGAIN|ECONNRESET|ECONNREFUSED|ETIMEDOUT|ESOCKETTIMEDOUT|ENETUNREACH|EHOSTUNREACH)\b/,
+      "NETWORK_ERROR",
+    ],
+  ])
+    if (pattern.test(output)) return code;
+  return "INSTALL_FAILED";
+}
+
+export function updateFailure(error, stage) {
+  const osCode = {
+    ENOSPC: "DISK_FULL",
+    EACCES: "PERMISSION_DENIED",
+    EPERM: "PERMISSION_DENIED",
+  }[error?.code];
+  const fallback =
+    {
+      downloading: "INSTALL_FAILED",
+      checking: "PACKAGE_CHECK_FAILED",
+      stopping: "STOP_FAILED",
+      backup: "BACKUP_FAILED",
+      migrating: "MIGRATION_FAILED",
+      restarting: "START_FAILED",
+      verifying: "START_FAILED",
+      restoring: "RECOVERY_FAILED",
+    }[stage] || "STEP_FAILED";
+  const failureCode = Object.hasOwn(UPDATE_FAILURES, error?.updateCode)
+    ? error.updateCode
+    : osCode || fallback;
+  return { failureCode, detail: UPDATE_FAILURES[failureCode] };
+}

package/server/runtime/update-execution.js

@@ -15,6 +15,7 @@ import {
 } from "./update-manager.js";
 import { backupDatabase } from "../../scripts/backup.js";
 import { restoreToNewFile, verifyArchive } from "../storage/archive.js";
+import { updateFailure } from "./update-errors.js";
 
 // Executed outside the server so a large verified snapshot does not stall the
 // WebUI. Dependencies are explicit for failure, restart and rollback tests.
@@ -105,12 +106,9 @@ export async function performUpdate(
     return job;
   } catch (error) {
     const failedStage = job.status;
-    job = { ...job, failedStage };
-    console.error(
-      "更新步骤未完成：",
-      failedStage,
-      error.code || error.cause?.code || "STEP_FAILED",
-    );
+    const failure = updateFailure(error, failedStage);
+    job = { ...job, failedStage, ...failure };
+    console.error("更新步骤未完成：", failedStage, failure.failureCode, error);
     if (!stopped) {
       save("error", { error: UPDATE_FAILED, finished: Date.now() });
       return job;
@@ -150,6 +148,7 @@ export async function performUpdate(
               `${paths.database}.update-failed-${id}.migration${suffix}`,
             );
       const restored = await start(paths.package);
+      save("restoring", { childPid: restored });
       await health(restored, job.previous);
       save("error", {
         error: UPDATE_FAILED,
@@ -157,8 +156,14 @@ export async function performUpdate(
         childPid: restored,
         finished: Date.now(),
       });
-    } catch {
-      save("error", { error: UPDATE_RECOVERY_FAILED, finished: Date.now() });
+    } catch (recoveryError) {
+      const recovery = updateFailure(recoveryError, "restoring");
+      console.error("更新恢复未完成：", recovery.failureCode, recoveryError);
+      save("error", {
+        error: UPDATE_RECOVERY_FAILED,
+        recoveryCode: recovery.failureCode,
+        finished: Date.now(),
+      });
     }
     return job;
   } finally {

package/server/runtime/update-manager.js

@@ -1,6 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import {
+  updateError,
+  updateFailure,
+  UPDATE_FAILURES,
+} from "./update-errors.js";
 import {
   atomicJson,
   UPDATE_ID,
@@ -11,7 +16,7 @@ export const UPDATE_FAILED =
   "更新未完成，原程序和数据已保留，请查看运行日志后重试。";
 export const UPDATE_RECOVERY_FAILED =
   "自动恢复未完成，更新前的校验备份已保留，请查看运行日志并手动恢复。";
-const ACTIVE = new Set([
+export const UPDATE_ACTIVE_STAGES = Object.freeze([
   "queued",
   "downloading",
   "checking",
@@ -22,6 +27,12 @@ const ACTIVE = new Set([
   "verifying",
   "restoring",
 ]);
+const ACTIVE = new Set(UPDATE_ACTIVE_STAGES);
+export const isUpdateActive = (stage) => ACTIVE.has(stage);
+export const isUpdateFinished = (stage) =>
+  stage === "done" || stage === "error";
+const beforeStop = (stage) =>
+  ["queued", "downloading", "checking"].includes(stage);
 export const processAlive = (pid) => {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -70,18 +81,17 @@ export class InstanceUpdater {
       return null;
     }
     if (
-      ACTIVE.has(job.status) &&
+      isUpdateActive(job.status) &&
       job.workerPid &&
       !processAlive(job.workerPid)
     ) {
+      const failedStage = job.status;
       job = writeUpdateJob(this.paths.home, {
         ...job,
         status: "error",
-        error: ["queued", "downloading", "checking", "migrating"].includes(
-          job.status,
-        )
-          ? UPDATE_FAILED
-          : UPDATE_RECOVERY_FAILED,
+        failedStage,
+        ...updateFailure(updateError("UPDATE_INTERRUPTED"), failedStage),
+        error: beforeStop(failedStage) ? UPDATE_FAILED : UPDATE_RECOVERY_FAILED,
         finished: this.now(),
       });
     }
@@ -95,10 +105,22 @@ export class InstanceUpdater {
       finished: job.finished,
       error: job.error || "",
       restored: !!job.restored,
+      ...(isUpdateActive(job.failedStage)
+        ? { failedStage: job.failedStage }
+        : {}),
+      ...(Object.hasOwn(UPDATE_FAILURES, job.failureCode)
+        ? {
+            failureCode: job.failureCode,
+            detail: UPDATE_FAILURES[job.failureCode],
+          }
+        : {}),
+      ...(Object.hasOwn(UPDATE_FAILURES, job.recoveryCode)
+        ? { recoveryDetail: UPDATE_FAILURES[job.recoveryCode] }
+        : {}),
     };
   }
   get busy() {
-    return this.starting || ACTIVE.has(this.status()?.status);
+    return this.starting || isUpdateActive(this.status()?.status);
   }
   async install(version) {
     if (this.busy) return this.status();