@kne/fastify-app-manager 0.1.14 → 0.1.15

package/README.md

@@ -126,6 +126,7 @@ deploy(versionId)
 | 版本上传 | Zip Slip 防护、条目数/体积上限、解压丢弃任意层级 `node_modules`、Fullstack 包格式校验、server 生产依赖安装 |
 | 短部署 | `deploy` / `start` / `restart` 立即返回 `deploying`，后台按 PM2 真实状态 + healthCheck 写回 `running`/`error`/`stopped` |
 | 部署进度 | `deploy` 按「准备部署包 → 校验环境变量 → SQL 迁移 → 启动进程 → 等待就绪」上报阶段，经 `GET .../app/deploy/stream` SSE 推送（含下载 / 解压 / 安装依赖等子阶段） |
+| 部署记录 | 每次部署（含父应用启动时补回部署目录）落库：状态 `running`/`success`/`failed`、阶段事件、部署日志（依赖安装输出、就绪失败时进程 `err.log` 末尾）；父应用重启后未结束的标为中断；`GET .../app/deploy/list`、`.../app/deploy/detail` 查询 |
 | 生命周期 | `start` / `stop` / `restart` / `remove`；父应用重启后异步 `syncAllStatuses` 对齐 PM2 |
 | 双通道访问 | 自定义域名透明反代 + `/app/{name}` 剥前缀反代 |
 | 日志 | PM2 落盘 + 历史分页（`beforeLine` 上滚、每页最多 100 行）+ SSE（含回放行与心跳） |
@@ -213,6 +214,9 @@ await fastify.listen({ port: 3000 });
 | `maxZipSize` | number | 否 | `209715200` | zip 最大字节（200MB）；同步 multipart 限制 |
 | `maxZipEntries` | number | 否 | `20000` | zip 最大条目数（不含被丢弃的 `node_modules` 条目） |
 | `npmInstallTimeoutMs` | number | 否 | `600000` | `server` 目录 `npm install` 超时 |
+| `deployRecordKeep` | number | 否 | `20` | 每个应用保留的部署记录条数 |
+| `deployLogMaxLines` | number | 否 | `2000` | 单次部署日志最多保留行数（超出丢弃最早的） |
+| `deployErrorLogTailLines` | number | 否 | `50` | 就绪失败时附加到部署日志的进程 `err.log` 末尾行数 |
 | `sseReplayLines` | number | 否 | `100` | SSE 连接时回放最近行数 |
 | `sseHeartbeatMs` | number | 否 | `15000` | SSE 心跳间隔 |
 | `logMaxSize` | number | 否 | `52428800` | 单日志文件上限（50MB），达到即切分；`0` 关闭按大小切分 |
@@ -459,7 +463,7 @@ await fastify.listen({ port: 3000 });
 
 ##### GET `{prefix}/app/deploy/stream`
 
-SSE 部署进度。连接时先推送 `snapshot`（该应用最近一次部署中匹配 `progressId` 的已有事件，便于断线重连），之后每个阶段变化推送 `progress`。每个应用只在内存中保留最近一次部署的事件。
+SSE 部署进度。连接时先推送 `snapshot`（该次部署已有事件，便于断线重连；内存中没有时从部署记录回放，`deploy` 为该部署记录含最近 `sseReplayLines` 行日志，无记录为 `null`），之后每个阶段变化推送 `progress`，每行部署日志推送 `log`（`{ progressId, line }`）。
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
@@ -480,7 +484,7 @@ SSE 部署进度。连接时先推送 `snapshot`（该应用最近一次部署
 
 ```text
 event: snapshot
-data: {"steps":["package","env","migrate","start","ready"],"events":[]}
+data: {"steps":["package","env","migrate","start","ready"],"events":[],"deploy":null}
 
 event: progress
 data: {"progressId":"p-1","step":"package","status":"running","detail":"download","message":null,"at":"2026-10-10T10:00:00.000Z"}
@@ -489,6 +493,27 @@ event: progress
 data: {"progressId":"p-1","step":"ready","status":"done","detail":null,"message":null,"at":"2026-10-10T10:00:05.000Z"}
 ```
 
+##### 部署记录
+
+每次部署（含父应用启动时补回部署目录，`source: 'restore'`）都会落库，每个应用保留最近 `deployRecordKeep` 条。父应用重启时，未结束的记录标为 `failed`（`message: deploy interrupted: app manager restarted`）。应用详情返回 `deployment`（进行中的部署，无则 `null`）与 `lastDeployment`（最近一次部署记录摘要）。
+
+| 方法 | 路径 | 参数 | 说明 |
+|------|------|------|------|
+| GET | `{prefix}/app/deploy/list` | `name`, `perPage?`, `currentPage?` | 部署记录分页（不含日志与事件），按开始时间倒序 |
+| GET | `{prefix}/app/deploy/detail` | `name`, `progressId?`, `logLines?` | 部署记录详情；`progressId` 为空取最近一次；`logLines` 只取最后 N 行（`0` 全部） |
+
+部署记录字段：
+
+| 字段 | 说明 |
+|------|------|
+| `progressId` / `versionId` / `version` | 部署标识与版本 |
+| `source` | `deploy` 手动部署 / `restore` 启动时补回部署目录 |
+| `status` | `running` / `success` / `failed` |
+| `step` / `message` | 最后到达的阶段 / 失败原因 |
+| `startedAt` / `finishedAt` | 起止时间 |
+| `events` | 阶段事件（仅详情） |
+| `log` / `logTotalLines` | 部署日志：各阶段结果、依赖安装输出、就绪失败时进程 `err.log` 末尾（仅详情） |
+
 ##### 版本迁移脚本管理
 
 管理某版本的 `.sql` 文件。脚本内容存于版本记录（数据库），版本目录不在磁盘时也可查看和编辑；目录在磁盘上（当前版本）时同步写入 `server/{migrationPath}`，部署时以数据库为准覆盖。执行状态读写应用库的 `_fs_sql_migrations`（与 `@kne/fastify-sequelize` 共用，按文件名记账；共享库中不同应用的同名脚本会互相影响）。文件名须匹配 `[A-Za-z0-9_-.]+\.sql`。
@@ -547,6 +572,8 @@ data: {"progressId":"p-1","step":"ready","status":"done","detail":null,"message"
 |--------|------|------|------|
 | name | string | 是 | 应用 slug |
 
+返回脱敏后的应用对象，另带 `deployment`：最近一次部署尚未结束（未出错、就绪阶段未完成）时为 `{ progressId, versionId, version, startedAt, step, detail }`，否则为 `null`。准备部署包阶段应用仍是旧的 `status` 与 `currentVersionId`，用它判断哪个版本正在部署。`app/list` 的每个元素同样带该字段。
+
 ##### POST `{prefix}/app/start` | `stop` | `restart` | `remove`
 
 | 参数名 | 类型 | 必填 | 说明 |
@@ -731,7 +758,11 @@ data: {"name":"demo","ts":1791456608533,...}
 | `restoreMissingArtifacts()` | 当前版本目录（`artifactPath/server`）缺失时，按版本 `fileId` 经 `resolveVersionFile` 取回 zip 重建并恢复 `current` 链接（不跑 SQL 迁移）；返回 `[{ name, version, action: 'restored' \| 'skipped' \| 'failed', reason? }]`，无 `fileId` 的记 `skipped` |
 | `listVersions({ name, perPage, currentPage })` | 版本列表 |
 | `deploy({ name, versionId, version, runMigration, migrations?, progressId? })` | 部署；版本目录缺失时先从宿主文件重建，启动后清理其它版本目录；立即 `deploying`，后台 `syncRealStatus`；各阶段进度写入 `getDeployProgress()` |
-| `getDeployProgress()` | 部署进度中心：`emitter`（事件名 `deploy:{name}`）、`snapshot(name)` 返回最近一次部署 `{ progressId, events }` |
+| `getDeployProgress()` | 部署进度中心：`emitter`（事件名 `deploy:{name}`、日志 `deploy-log:{name}`）、`snapshot(name)` 返回最近一次部署 `{ progressId, status, events, ... }`、`active(name)` 进行中的部署 |
+| `deployList({ name, perPage?, currentPage? })` | 同 `GET .../app/deploy/list` |
+| `deployDetail({ name, progressId?, logLines? })` | 同 `GET .../app/deploy/detail` |
+| `lastDeployment(name)` | 最近一次部署记录摘要（无日志），无记录为 `null` |
+| `markInterruptedDeploys()` | 把库里仍 `running`、但本进程未在跟踪的部署记录标为 `failed`（启动时自动调用），返回条数 |
 | `waitDeployProgress({ name, progressId, timeoutMs? })` | 等到该次部署出错或 `ready` 结束（默认超时 120000ms），返回 `{ progressId, ok, timedOut, events }`；供 MCP 等同步调用方使用 |
 | `getEnvDeclaration({ name, versionId? })` | 同 `GET .../app/env/schema` |
 | `listInjectedEnvKeys(app)` | 应用中心注入（或在其它页签维护）的变量名 `Set`，环境变量声明中不展示 |

package/index.js

@@ -23,6 +23,12 @@ module.exports = fp(
         maxZipSize: 200 * 1024 * 1024,
         maxZipEntries: 20000,
         npmInstallTimeoutMs: 10 * 60 * 1000,
+        /** 每个应用保留的部署记录条数 */
+        deployRecordKeep: 20,
+        /** 单次部署日志最多保留的行数（超出丢弃最早的） */
+        deployLogMaxLines: 2000,
+        /** 就绪失败时附加到部署日志的进程错误日志行数 */
+        deployErrorLogTailLines: 50,
         logRetentionMaxRows: 10000,
         sseReplayLines: 100,
         sseHeartbeatMs: 15000,

package/libs/controllers/app.js

@@ -277,25 +277,77 @@ module.exports = fp(async (fastify, options) => {
     async (request, reply) => {
       const { name, progressId } = request.query;
       await services.app.detail({ name });
-      const sse = createSseReply(reply, { heartbeatMs: options.sseHeartbeatMs });
       const progress = services.app.getDeployProgress();
       const matches = event => !progressId || event.progressId === progressId;
-      const snapshot = progress.snapshot(name);
+      const memory = progress.snapshot(name);
+      let record = null;
+      if (progressId && (!memory || memory.progressId !== progressId)) {
+        // 不在本进程内（已结束被新部署覆盖或主进程重启过）：从部署记录回放
+        record = await services.app.deployDetail({ name, progressId, logLines: options.sseReplayLines }).catch(() => null);
+      } else if (memory) {
+        record = await services.app.deployDetail({ name, progressId: memory.progressId, logLines: options.sseReplayLines }).catch(() => null);
+      }
+      const sse = createSseReply(reply, { heartbeatMs: options.sseHeartbeatMs });
       sse.writeEvent('snapshot', {
         steps: DEPLOY_STEPS,
-        events: snapshot ? snapshot.events.filter(matches) : []
+        events: record ? (record.events || []).filter(matches) : memory ? memory.events.filter(matches) : [],
+        deploy: record ? Object.assign({}, record, { events: undefined }) : null
       });
 
       const onProgress = event => matches(event) && sse.writeEvent('progress', event);
+      const onLog = event => matches(event) && sse.writeEvent('log', event);
       const eventName = `deploy:${name}`;
+      const logEventName = `deploy-log:${name}`;
       progress.emitter.on(eventName, onProgress);
+      progress.emitter.on(logEventName, onLog);
       request.raw.on('close', () => {
         progress.emitter.off(eventName, onProgress);
+        progress.emitter.off(logEventName, onLog);
         sse.close();
       });
     }
   );
 
+  fastify.get(
+    `${options.prefix}/app/deploy/list`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '部署记录列表（不含日志）',
+        query: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            perPage: { type: 'number', default: 20 },
+            currentPage: { type: 'number', default: 1 }
+          }
+        }
+      }
+    },
+    async request => services.app.deployList(request.query)
+  );
+
+  fastify.get(
+    `${options.prefix}/app/deploy/detail`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '部署记录详情（含阶段事件与部署日志）；progressId 为空取最近一次',
+        query: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            progressId: { type: 'string' },
+            logLines: { type: 'number', default: 0, description: '只返回最后 N 行日志；0 返回全部' }
+          }
+        }
+      }
+    },
+    async request => services.app.deployDetail(request.query)
+  );
+
   fastify.get(
     `${options.prefix}/app/list`,
     {

package/libs/models/appDeploy.js

@@ -0,0 +1,71 @@
+module.exports = ({ DataTypes }) => {
+  return {
+    name: 'appDeploy',
+    model: {
+      appName: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        comment: '所属应用 name'
+      },
+      progressId: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        comment: '部署进度 id，与 SSE 进度订阅一致'
+      },
+      versionId: {
+        type: DataTypes.STRING,
+        allowNull: true,
+        comment: '部署的版本 id'
+      },
+      version: {
+        type: DataTypes.STRING,
+        allowNull: true,
+        comment: '部署的版本号'
+      },
+      source: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        defaultValue: 'deploy',
+        comment: 'deploy 手动部署 | restore 启动时补回部署目录'
+      },
+      status: {
+        type: DataTypes.STRING,
+        allowNull: false,
+        defaultValue: 'running',
+        comment: 'running | success | failed'
+      },
+      step: {
+        type: DataTypes.STRING,
+        allowNull: true,
+        comment: '最后到达的阶段'
+      },
+      message: {
+        type: DataTypes.TEXT,
+        allowNull: true,
+        comment: '失败原因'
+      },
+      events: {
+        type: DataTypes.JSON,
+        allowNull: true,
+        comment: '进度事件 [{ step, status, detail, message, at }]'
+      },
+      log: {
+        type: DataTypes.TEXT,
+        allowNull: true,
+        comment: '部署日志（依赖安装输出、各阶段结果、启动失败时的进程错误日志）'
+      },
+      startedAt: {
+        type: DataTypes.DATE,
+        allowNull: true
+      },
+      finishedAt: {
+        type: DataTypes.DATE,
+        allowNull: true
+      }
+    },
+    options: {
+      comment: '应用部署记录',
+      indexes: [{ fields: ['app_name'] }, { unique: true, fields: ['progress_id'] }]
+    }
+  };
+};

package/libs/services/app.js

@@ -265,7 +265,7 @@ module.exports = fp(async (fastify, options) => {
 
   const detail = async ({ name }) => {
     const app = await getByName(name);
-    return Object.assign(toPublicApp(app), { deployment: deployProgress.active(app.name) });
+    return Object.assign(toPublicApp(app), { deployment: deployProgress.active(app.name), lastDeployment: await lastDeployment(app.name) });
   };
 
   const versionSqlDir = ver => path.join(ver.artifactPath, 'server', ver.migrationPath || options.sqlPath || 'sql');
@@ -486,7 +486,150 @@ module.exports = fp(async (fastify, options) => {
 
   /** 同一 app 并发同步合并为一次，避免 restart/reconcile 竞态 */
   const statusSyncInflight = new Map();
-  const deployProgress = createDeployProgress();
+
+  const pruneDeployRecords = async appName => {
+    const stale = await models.appDeploy.findAll({
+      where: { appName },
+      attributes: ['id'],
+      order: [['createdAt', 'DESC']],
+      offset: options.deployRecordKeep
+    });
+    if (stale.length) {
+      await models.appDeploy.destroy({ where: { id: stale.map(row => row.id) } });
+    }
+  };
+
+  const persistDeploy = async state => {
+    const values = {
+      appName: state.name,
+      progressId: state.progressId,
+      versionId: state.versionId,
+      version: state.version,
+      source: state.source,
+      status: state.status,
+      step: state.step,
+      message: state.message,
+      events: state.events,
+      log: state.logs.join('\n'),
+      startedAt: state.startedAt,
+      finishedAt: state.finishedAt
+    };
+    const record = await models.appDeploy.findOne({ where: { progressId: state.progressId } });
+    if (record) {
+      await record.update(values);
+      return;
+    }
+    await models.appDeploy.create(values);
+    await pruneDeployRecords(state.name);
+  };
+
+  const deployProgress = createDeployProgress({
+    persist: persistDeploy,
+    logMaxLines: options.deployLogMaxLines,
+    onPersistError: (err, state) => fastify.log.warn({ err, app: state.name, progressId: state.progressId }, 'persist deploy record failed')
+  });
+
+  const tailLines = (lines, n) => (n > 0 && lines.length > n ? lines.slice(-n) : lines);
+
+  /** 部署记录：进程内仍在跟踪的以内存为准（日志更新），否则读库 */
+  const toDeployRecord = (row, { withLog = false, logLines = 0 } = {}) => {
+    const memory = deployProgress.snapshot(row.appName);
+    const live = memory && memory.progressId === row.progressId ? memory : null;
+    const base = live || {
+      name: row.appName,
+      progressId: row.progressId,
+      versionId: row.versionId,
+      version: row.version,
+      source: row.source,
+      status: row.status,
+      step: row.step,
+      message: row.message,
+      startedAt: row.startedAt ? new Date(row.startedAt).toISOString() : null,
+      finishedAt: row.finishedAt ? new Date(row.finishedAt).toISOString() : null,
+      events: Array.isArray(row.events) ? row.events : []
+    };
+    const record = Object.assign({}, base, { name: row.appName });
+    if (!withLog) {
+      delete record.events;
+      return record;
+    }
+    const lines = live ? deployProgress.logsOf(row.appName, row.progressId) || [] : row.log ? row.log.split('\n') : [];
+    return Object.assign(record, { logTotalLines: lines.length, log: tailLines(lines, logLines).join('\n') });
+  };
+
+  const deployList = async ({ name, perPage = 20, currentPage = 1 } = {}) => {
+    const app = await getByName(name);
+    const { rows, count } = await models.appDeploy.findAndCountAll({
+      where: { appName: app.name },
+      attributes: { exclude: ['log', 'events'] },
+      offset: perPage * (currentPage - 1),
+      limit: perPage,
+      order: [['createdAt', 'DESC']]
+    });
+    return { pageData: rows.map(row => toDeployRecord(row)), totalCount: count };
+  };
+
+  /** progressId 为空取最近一次；logLines 为 0 返回全部已保存日志 */
+  const deployDetail = async ({ name, progressId, logLines = 0 } = {}) => {
+    const app = await getByName(name);
+    const where = { appName: app.name };
+    if (progressId) {
+      where.progressId = progressId;
+    }
+    let row = await models.appDeploy.findOne({ where, order: [['createdAt', 'DESC']] });
+    const memory = deployProgress.snapshot(app.name);
+    // 刚开始的部署可能还没落库
+    if (memory && (progressId ? memory.progressId === progressId : !row || row.progressId !== memory.progressId)) {
+      row = { appName: app.name, progressId: memory.progressId };
+    }
+    if (!row) {
+      httpError(404, 'deploy record not found');
+    }
+    return toDeployRecord(row, { withLog: true, logLines: Number(logLines) || 0 });
+  };
+
+  const lastDeployment = async name => {
+    const row = await models.appDeploy.findOne({ where: { appName: name }, attributes: { exclude: ['log', 'events'] }, order: [['createdAt', 'DESC']] });
+    return row ? toDeployRecord(row) : null;
+  };
+
+  /** 父进程重启后，内存里的部署进度已丢失：库里仍 running 的记录无法再结束，标记为中断 */
+  const markInterruptedDeploys = async () => {
+    const rows = await models.appDeploy.findAll({ where: { status: 'running' } });
+    for (const row of rows) {
+      if (deployProgress.active(row.appName)?.progressId === row.progressId) {
+        continue;
+      }
+      const at = new Date();
+      const message = 'deploy interrupted: app manager restarted';
+      await row.update({
+        status: 'failed',
+        message,
+        finishedAt: at,
+        events: (Array.isArray(row.events) ? row.events : []).concat({ progressId: row.progressId, step: row.step || 'package', status: 'error', detail: null, message, at: at.toISOString() }),
+        log: [row.log, `${at.toISOString()} ${message}`].filter(Boolean).join('\n')
+      });
+    }
+    return rows.length;
+  };
+
+  /** 就绪阶段收尾：失败时把进程错误日志末尾写进部署日志，便于定位启动失败 */
+  const settleDeployReady = async (app, progress, result) => {
+    if (result?.status === 'running') {
+      progress.report('ready', 'done');
+      return;
+    }
+    try {
+      const lines = await readLastLines(currentLogFile(app, 'err'), options.deployErrorLogTailLines, { timezone: options.logTimezone });
+      if (lines.length) {
+        progress.log(`---- ${app.name} err.log (last ${lines.length} lines) ----`);
+        lines.forEach(item => progress.log(item.content));
+      }
+    } catch (e) {
+      progress.log(`read err.log failed: ${e.message}`);
+    }
+    progress.report('ready', 'error', { message: result?.message || result?.status || null });
+  };
 
   /**
    * 根据 PM2 真实进程状态 + HTTP 健康检查，异步写回 DB status。
@@ -840,7 +983,7 @@ module.exports = fp(async (fastify, options) => {
   const canResolveFile = ver => !!ver.fileId && typeof options.resolveVersionFile === 'function';
 
   /** 版本目录不在磁盘时按 fileId 取回 zip 解压并装依赖；再以数据库中的 SQL 覆盖目录内 .sql */
-  const materializeArtifact = async (app, ver, { onProgress } = {}) => {
+  const materializeArtifact = async (app, ver, { onProgress, onLog } = {}) => {
     if (await hasArtifact(ver)) {
       onProgress && onProgress('reuse');
     } else {
@@ -860,7 +1003,8 @@ module.exports = fp(async (fastify, options) => {
           sqlPath: options.sqlPath,
           // 老版本可能没有 env.schema.json：照常还原目录，由启动前的环境变量校验给出提示
           requireEnvSchema: false,
-          onProgress
+          onProgress,
+          onLog
         });
         await fs.move(stagingPath, ver.artifactPath, { overwrite: true });
       } catch (e) {
@@ -901,20 +1045,27 @@ module.exports = fp(async (fastify, options) => {
     return results;
   };
 
-  /** 补回当前版本目录并恢复 current 链接；不跑 SQL 迁移 */
-  const restoreArtifact = async ({ app, ver }) => {
+  /** 补回当前版本目录并恢复 current 链接；不跑 SQL 迁移。progress 存在时记录到部署记录 */
+  const restoreArtifact = async ({ app, ver, progress }) => {
     if (!canResolveFile(ver)) {
       fastify.log.warn({ app: app.name, version: ver.version }, 'current version artifact missing and cannot be restored without fileId');
+      progress && progress.report('package', 'error', { message: 'current version artifact missing and cannot be restored without fileId' });
       return { name: app.name, version: ver.version, action: 'skipped', reason: 'no fileId' };
     }
     try {
-      await materializeArtifact(app, ver);
+      progress && progress.report('package', 'running');
+      await materializeArtifact(app, ver, {
+        onProgress: progress ? detail => progress.report('package', 'running', { detail }) : undefined,
+        onLog: progress ? progress.log : undefined
+      });
       await linkCurrent(app, ver.artifactPath);
+      progress && progress.report('package', 'done');
       fastify.log.info({ app: app.name, version: ver.version }, 'current version artifact restored from file');
-      return { name: app.name, version: ver.version, action: 'restored' };
+      return Object.assign({ name: app.name, version: ver.version, action: 'restored' }, progress ? { progressId: progress.progressId } : {});
     } catch (e) {
       fastify.log.warn({ err: e, app: app.name, version: ver.version }, 'restore current version artifact failed');
-      return { name: app.name, version: ver.version, action: 'failed', reason: e.message };
+      progress && progress.report('package', 'error', { message: e.message });
+      return Object.assign({ name: app.name, version: ver.version, action: 'failed', reason: e.message }, progress ? { progressId: progress.progressId } : {});
     }
   };
 
@@ -942,7 +1093,7 @@ module.exports = fp(async (fastify, options) => {
     let step = 'package';
     progress.report(step, 'running');
     try {
-      await materializeArtifact(app, ver, { onProgress: detail => progress.report('package', 'running', { detail }) });
+      await materializeArtifact(app, ver, { onProgress: detail => progress.report('package', 'running', { detail }), onLog: progress.log });
     } catch (e) {
       progress.report(step, 'error', { message: e.message });
       httpError(400, e.message);
@@ -962,15 +1113,15 @@ module.exports = fp(async (fastify, options) => {
     }
     progress.report(step, 'done');
 
-    await app.update({
-      status: 'deploying',
-      currentVersionId: String(ver.id),
-      message: null
-    });
+    try {
+      await app.update({
+        status: 'deploying',
+        currentVersionId: String(ver.id),
+        message: null
+      });
 
-    await linkCurrent(app, ver.artifactPath);
+      await linkCurrent(app, ver.artifactPath);
 
-    try {
       step = 'migrate';
       if (runMigration && options.migrateBeforeStart && ver.hasMigration) {
         progress.report(step, 'running');
@@ -1027,7 +1178,13 @@ module.exports = fp(async (fastify, options) => {
       progress.report(step, 'running');
       scheduleStatusSync(app.id, {
         beforeTables: beforeForReady,
-        onSettled: result => (result?.status === 'running' ? progress.report('ready', 'done') : progress.report('ready', 'error', { message: result?.message || result?.status || null }))
+        onSettled: result =>
+          settleDeployReady(app, progress, result).catch(err => {
+            fastify.log.warn({ err, app: app.name }, 'settle deploy ready failed');
+            if (!progress.finished()) {
+              progress.report('ready', 'error', { message: err.message });
+            }
+          })
       });
       await pruneVersionArtifacts(app).catch(err => fastify.log.warn({ err, app: app.name }, 'prune version artifacts failed'));
       return {
@@ -1300,6 +1457,11 @@ module.exports = fp(async (fastify, options) => {
       getLoadStore,
       getDeployProgress: () => deployProgress,
       waitDeployProgress: ({ name, progressId, timeoutMs }) => deployProgress.wait(name, progressId, { timeoutMs }),
+      deployList,
+      deployDetail,
+      lastDeployment,
+      markInterruptedDeploys,
+      settleDeployReady,
       getEnvDeclaration,
       listInjectedEnvKeys,
       toPublicApp,

package/libs/services/bootstrap.js

@@ -1,5 +1,6 @@
 const fp = require('fastify-plugin');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const { EventEmitter } = require('node:events');
 const pm2Util = require('../utils/pm2');
@@ -136,17 +137,28 @@ module.exports = fp(async (fastify, options) => {
     const { services } = fastify[options.name];
     const results = [];
     for (const item of missing) {
-      const result = await services.app.restoreArtifact(item);
+      const { app, ver } = item;
+      const progress = services.app.getDeployProgress().begin(app.name, crypto.randomUUID(), { versionId: String(ver.id), version: ver.version, source: 'restore' });
+      const result = await services.app.restoreArtifact(Object.assign({}, item, { progress }));
       results.push(result);
-      const { app } = item;
       const wasActive = app.status === 'running' || app.status === 'deploying';
       try {
         const synced = await services.app.syncStatus({ name: app.name, recoverIfMissing: result.action === 'restored' && wasActive });
         if (result.action !== 'restored' && wasActive && synced?.status !== 'running') {
           await app.update({ status: 'error', message: `current version artifact missing: ${result.reason}` });
         }
+        if (!progress.finished()) {
+          if (!wasActive) {
+            progress.report('ready', 'skipped');
+          } else {
+            await services.app.settleDeployReady(app, progress, synced);
+          }
+        }
       } catch (e) {
         fastify.log.warn({ err: e, app: app.name }, 'sync status after artifact restore failed');
+        if (!progress.finished()) {
+          progress.report('ready', 'error', { message: e.message });
+        }
       }
     }
     return results;
@@ -154,6 +166,7 @@ module.exports = fp(async (fastify, options) => {
 
   const recoverOnStartup = async () => {
     const { services } = fastify[options.name];
+    await services.app.markInterruptedDeploys().catch(err => fastify.log.warn({ err }, 'mark interrupted deploys failed'));
     const missing = await services.app.listMissingArtifacts();
     // 两路并行：部署目录完好的应用不必等其它应用重装依赖
     const [reconciled, restored] = await Promise.all([

package/libs/utils/deployProgress.js

@@ -3,37 +3,125 @@ const { EventEmitter } = require('node:events');
 /** 部署阶段，按顺序推进：准备部署包 → 校验环境变量 → SQL 迁移 → 启动进程 → 等待就绪 */
 const DEPLOY_STEPS = ['package', 'env', 'migrate', 'start', 'ready'];
 
+const isFinished = event => event.status === 'error' || (event.step === 'ready' && event.status !== 'running');
+
+const toPublicState = state => ({
+  name: state.name,
+  progressId: state.progressId,
+  versionId: state.versionId,
+  version: state.version,
+  source: state.source,
+  status: state.status,
+  step: state.step,
+  message: state.message,
+  startedAt: state.startedAt,
+  finishedAt: state.finishedAt,
+  events: state.events.slice()
+});
+
 /**
  * 每个应用只保留最近一次部署的进度事件，供 SSE 订阅与断线重连回放。
  * 事件：{ progressId, step, status: 'running' | 'done' | 'skipped' | 'error', detail?, message?, at }
+ * persist(state)：每次状态变化后按 progressId 串行调用，state 含 logs（日志行数组）；日志变化合并 flushDelayMs 再写
  */
-const createDeployProgress = () => {
+const createDeployProgress = ({ persist = null, logMaxLines = 2000, flushDelayMs = 1000, onPersistError = null } = {}) => {
   const emitter = new EventEmitter();
   emitter.setMaxListeners(0);
   const latest = new Map();
 
-  const begin = (name, progressId, { versionId = null, version = null } = {}) => {
-    const state = { progressId, versionId, version, startedAt: new Date().toISOString(), events: [] };
+  const begin = (name, progressId, { versionId = null, version = null, source = 'deploy' } = {}) => {
+    const state = {
+      name,
+      progressId,
+      versionId,
+      version,
+      source,
+      status: 'running',
+      step: null,
+      message: null,
+      startedAt: new Date().toISOString(),
+      finishedAt: null,
+      events: [],
+      logs: []
+    };
     latest.set(name, state);
+
+    let chain = Promise.resolve();
+    let timer = null;
+    const flush = () => {
+      clearTimeout(timer);
+      timer = null;
+      if (!persist) {
+        return chain;
+      }
+      const data = Object.assign(toPublicState(state), { logs: state.logs.slice() });
+      chain = chain.then(() => persist(data)).catch(err => onPersistError && onPersistError(err, data));
+      return chain;
+    };
+    const scheduleFlush = () => {
+      if (timer || !persist) {
+        return;
+      }
+      timer = setTimeout(flush, flushDelayMs);
+      timer.unref && timer.unref();
+    };
+
+    const log = text => {
+      if (text === undefined || text === null) {
+        return;
+      }
+      const at = new Date().toISOString();
+      String(text)
+        .split(/\r?\n/)
+        .filter(line => line.trim())
+        .forEach(line => {
+          state.logs.push(`${at} ${line}`);
+          emitter.emit(`deploy-log:${name}`, { progressId, line: `${at} ${line}` });
+        });
+      if (state.logs.length > logMaxLines) {
+        state.logs.splice(0, state.logs.length - logMaxLines);
+      }
+      scheduleFlush();
+    };
+
     const report = (step, status, { detail = null, message = null } = {}) => {
       const event = { progressId, step, status, detail, message, at: new Date().toISOString() };
       state.events.push(event);
+      state.step = step;
+      log(`[${step}] ${status}${detail ? ` ${detail}` : ''}${message ? `: ${message}` : ''}`);
+      if (state.status === 'running' && isFinished(event)) {
+        state.status = event.status === 'error' ? 'failed' : 'success';
+        state.message = message;
+        state.finishedAt = event.at;
+      }
       emitter.emit(`deploy:${name}`, event);
+      flush();
       return event;
     };
-    return { progressId, report };
+
+    const finished = () => state.status !== 'running';
+
+    flush();
+    return { progressId, report, log, finished, flush };
   };
 
-  const snapshot = name => latest.get(name) || null;
+  const snapshot = name => {
+    const state = latest.get(name);
+    return state ? toPublicState(state) : null;
+  };
 
-  const clear = name => latest.delete(name);
+  /** 当前进程内某次部署的日志行（含时间戳前缀） */
+  const logsOf = (name, progressId) => {
+    const state = latest.get(name);
+    return state && state.progressId === progressId ? state.logs.slice() : null;
+  };
 
-  const isFinished = event => event.status === 'error' || (event.step === 'ready' && event.status !== 'running');
+  const clear = name => latest.delete(name);
 
   /** 尚未结束的最近一次部署；准备部署包阶段应用仍是旧状态与旧版本，需靠它判断哪个版本正在部署 */
   const active = name => {
     const state = latest.get(name);
-    if (!state || state.events.some(isFinished)) {
+    if (!state || state.status !== 'running') {
       return null;
     }
     const last = state.events[state.events.length - 1];
@@ -41,6 +129,7 @@ const createDeployProgress = () => {
       progressId: state.progressId,
       versionId: state.versionId,
       version: state.version,
+      source: state.source,
       startedAt: state.startedAt,
       step: last ? last.step : null,
       detail: last ? last.detail : null
@@ -74,10 +163,11 @@ const createDeployProgress = () => {
       timer = setTimeout(() => finish(true), timeoutMs);
     });
 
-  return { emitter, begin, snapshot, active, clear, wait };
+  return { emitter, begin, snapshot, logsOf, active, clear, wait };
 };
 
 module.exports = {
   DEPLOY_STEPS,
+  isFinished,
   createDeployProgress
 };

package/libs/utils/version.js

@@ -4,7 +4,7 @@ const { spawn } = require('node:child_process');
 const { extractZipSafe, resolvePackageRoot } = require('./zip');
 const { validatePackageRoot, listSqlFiles } = require('./validatePackage');
 
-const runNpmInstall = (cwd, timeoutMs) =>
+const runNpmInstall = (cwd, timeoutMs, onLog) =>
   new Promise((resolve, reject) => {
     const child = spawn('npm', ['install', '--production', '--no-fund', '--no-audit'], {
       cwd,
@@ -12,8 +12,12 @@ const runNpmInstall = (cwd, timeoutMs) =>
       stdio: ['ignore', 'pipe', 'pipe']
     });
     let stderr = '';
+    child.stdout?.on('data', chunk => {
+      onLog && onLog(chunk.toString());
+    });
     child.stderr.on('data', chunk => {
       stderr += chunk.toString();
+      onLog && onLog(chunk.toString());
     });
     const timer = setTimeout(() => {
       child.kill('SIGKILL');
@@ -34,7 +38,7 @@ const runNpmInstall = (cwd, timeoutMs) =>
   });
 
 /** install=false 时只解压校验，不装依赖（用于不常驻磁盘的版本上传） */
-const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath, install = true, requireEnvSchema = true, onProgress }) => {
+const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath, install = true, requireEnvSchema = true, onProgress, onLog }) => {
   await fs.emptyDir(artifactPath);
   onProgress && onProgress('extract');
   const extractDir = path.join(artifactPath, '_extract');
@@ -64,7 +68,7 @@ const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, max
   const serverDir = path.join(artifactPath, 'server');
   if (install) {
     onProgress && onProgress('install');
-    await runNpmInstall(serverDir, npmInstallTimeoutMs);
+    await runNpmInstall(serverDir, npmInstallTimeoutMs, onLog);
   }
 
   const sqlDir = path.join(serverDir, sqlPath || 'sql');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-app-manager",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Fastify 单机应用市场插件：版本上传、PM2 托管、路径/域名反代与日志 SSE",
   "main": "index.js",
   "scripts": {