@kne/fastify-app-manager 0.1.9 → 0.1.11

package/libs/services/app.js

@@ -10,7 +10,8 @@ const { ensureLogFiles, readLogTail, readLastLines, appendLog, countLines } = re
 const { currentFileName, isCurrentFileName, resolveLogFile, listLogFiles } = require('../utils/logRotate');
 const { toIsoInTz, convertLogText } = require('../utils/logTime');
 const { runSqlMigrations, MIGRATION_ACTIONS } = require('../utils/migrate');
-const { listSqlFiles } = require('../utils/validatePackage');
+const { readSqlDir, writeSqlDir } = require('../utils/versionSql');
+const { createDeployProgress } = require('../utils/deployProgress');
 const pm2Util = require('../utils/pm2');
 
 const NAME_RE = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
@@ -45,6 +46,27 @@ module.exports = fp(async (fastify, options) => {
     }
     return category.code ? { code: category.code, name: category.name || category.code } : null;
   };
+  // 应用入口：label + 相对应用根的 path；去空、补前导 /、按 path 去重
+  const normalizeEntries = entries => {
+    const seen = new Set();
+    return (Array.isArray(entries) ? entries : []).reduce((result, item) => {
+      const label = String(item?.label || '').trim();
+      const rawPath = String(item?.path || '').trim();
+      if (!label || !rawPath) {
+        return result;
+      }
+      const entryPath = rawPath.startsWith('/') ? rawPath : `/${rawPath}`;
+      if (!seen.has(entryPath)) {
+        seen.add(entryPath);
+        result.push({ label, path: entryPath });
+      }
+      return result;
+    }, []);
+  };
+  const resolveEntries = appLike => {
+    const base = mountPrefix(appLike.name);
+    return normalizeEntries(appLike.options?.entries).map(entry => Object.assign({}, entry, { url: `${base}${entry.path}` }));
+  };
 
   const toPublicApp = app => {
     if (!app) {
@@ -59,6 +81,7 @@ module.exports = fp(async (fastify, options) => {
     json.pathUrl = `${mountPrefix(json.name)}/`;
     json.category = json.options?.category || null;
     json.isPublic = isAppPublic(json);
+    json.entries = resolveEntries(json);
     return json;
   };
 
@@ -71,7 +94,7 @@ module.exports = fp(async (fastify, options) => {
   };
 
   const create = async data => {
-    const { name, label, domain, icon, description, category, isPublic, env, pm2Config, options: appOptions } = data;
+    const { name, label, domain, icon, description, category, isPublic, entries, env, pm2Config, options: appOptions } = data;
     if (!name || !NAME_RE.test(name)) {
       httpError(400, 'invalid name: use lowercase slug [a-z0-9-]');
     }
@@ -111,6 +134,9 @@ module.exports = fp(async (fastify, options) => {
     if (isPublic !== undefined) {
       normalizedOptions.isPublic = !!isPublic;
     }
+    if (entries !== undefined) {
+      normalizedOptions.entries = normalizeEntries(entries);
+    }
 
     const app = await models.app.create({
       name,
@@ -118,7 +144,7 @@ module.exports = fp(async (fastify, options) => {
       domain: domain || null,
       icon: icon || null,
       description: description || null,
-      env: omitSystemEnv(env),
+      env: omitSystemEnv(env, options.systemEnvKeys),
       pm2Config: pm2Config || {},
       options: normalizedOptions,
       port,
@@ -130,7 +156,7 @@ module.exports = fp(async (fastify, options) => {
     return toPublicApp(app);
   };
 
-  const save = async ({ name, category, isPublic, ...data }) => {
+  const save = async ({ name, category, isPublic, entries, ...data }) => {
     const app = await getByName(name);
     const omit = ['name', 'port', 'rootPath', 'pm2Name', 'status', 'currentVersionId'];
     const patch = {};
@@ -161,6 +187,9 @@ module.exports = fp(async (fastify, options) => {
     if (isPublic !== undefined) {
       patch.options = Object.assign({}, patch.options || app.options || {}, { isPublic: !!isPublic });
     }
+    if (entries !== undefined) {
+      patch.options = Object.assign({}, patch.options || app.options || {}, { entries: normalizeEntries(entries) });
+    }
     await app.update(patch);
     return toPublicApp(app);
   };
@@ -170,7 +199,7 @@ module.exports = fp(async (fastify, options) => {
     // 密钥类型不可撤销，只随变量删除而移除
     const secretEnvKeys = normalizeSecretKeys([...resolveSecretEnvKeys(app), ...(nextSecretKeys || [])]);
     const nextEnv = applyEnvPatch(app.env || {}, env || {}, Object.assign({}, options, { secretEnvKeys }));
-    const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key) && Object.prototype.hasOwnProperty.call(nextEnv, key));
+    const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key, options.systemEnvKeys) && Object.prototype.hasOwnProperty.call(nextEnv, key));
     await app.update({
       env: nextEnv,
       options: Object.assign({}, app.options || {}, { secretEnvKeys: cleanedSecrets })
@@ -211,7 +240,8 @@ module.exports = fp(async (fastify, options) => {
         description: app.description,
         category: app.options?.category || null,
         isPublic: isAppPublic(app),
-        pathUrl: `${mountPrefix(app.name)}/`
+        pathUrl: `${mountPrefix(app.name)}/`,
+        entries: resolveEntries(app)
       }));
     return { pageData, totalCount: pageData.length };
   };
@@ -221,7 +251,42 @@ module.exports = fp(async (fastify, options) => {
     return toPublicApp(app);
   };
 
-  const uploadVersion = async ({ name, version, label, zipBuffer }) => {
+  const versionSqlDir = ver => path.join(ver.artifactPath, 'server', ver.migrationPath || options.sqlPath || 'sql');
+
+  const hasArtifact = ver => fs.pathExists(path.join(ver.artifactPath, 'server'));
+
+  /** SQL 以数据库为准；旧版本行（migrationFiles 为空）首次访问时从版本目录回填 */
+  const getMigrationFiles = async ver => {
+    if (Array.isArray(ver.migrationFiles)) {
+      return ver.migrationFiles;
+    }
+    if (!(await hasArtifact(ver))) {
+      return [];
+    }
+    const files = await readSqlDir(versionSqlDir(ver));
+    await ver.update({ migrationFiles: files, hasMigration: files.length > 0 });
+    return files;
+  };
+
+  /** 写库，版本目录在磁盘上时同步覆盖其 .sql */
+  const saveMigrationFiles = async (ver, files) => {
+    const sorted = [...files].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    await ver.update({ migrationFiles: sorted, hasMigration: sorted.length > 0 });
+    if (await hasArtifact(ver)) {
+      await writeSqlDir(versionSqlDir(ver), sorted);
+    }
+    return sorted;
+  };
+
+  const toPublicVersion = (row, files = row.migrationFiles) => {
+    const { migrationFiles, ...json } = row.toJSON();
+    if (Array.isArray(files) && files.length) {
+      json.sqlFiles = files.map(item => item.name);
+    }
+    return json;
+  };
+
+  const uploadVersion = async ({ name, version, label, zipBuffer, fileId }) => {
     if (!version) {
       httpError(400, 'version is required');
     }
@@ -241,7 +306,10 @@ module.exports = fp(async (fastify, options) => {
     // Prepare outside the version table so failed or in-progress uploads never appear in the version list.
     const versionsDir = path.join(app.rootPath, 'versions');
     const stagingPath = path.join(versionsDir, `.staging-${crypto.randomUUID()}`);
+    // 有宿主文件的版本只校验不常驻磁盘，部署时再解压；没有的只能保留目录
+    const keepArtifact = !fileId;
     let prepared;
+    let migrationFiles;
     try {
       prepared = await prepareVersionArtifact({
         zipBuffer,
@@ -249,8 +317,10 @@ module.exports = fp(async (fastify, options) => {
         maxZipSize: options.maxZipSize,
         maxZipEntries: options.maxZipEntries,
         npmInstallTimeoutMs: options.npmInstallTimeoutMs,
-        sqlPath: options.sqlPath
+        sqlPath: options.sqlPath,
+        install: keepArtifact
       });
+      migrationFiles = await readSqlDir(path.join(stagingPath, 'server', prepared.migrationPath));
     } catch (e) {
       await fs.remove(stagingPath).catch(() => {});
       httpError(400, e.message);
@@ -258,26 +328,34 @@ module.exports = fp(async (fastify, options) => {
 
     let artifactPath = null;
     try {
-      return await models.appVersion.sequelize.transaction(async transaction => {
+      const result = await models.appVersion.sequelize.transaction(async transaction => {
         const versionRow = await models.appVersion.create(
           {
             appName: name,
             version,
             label: label || null,
             artifactPath: stagingPath,
-            hasMigration: prepared.hasMigration,
-            migrationPath: prepared.migrationPath
+            hasMigration: migrationFiles.length > 0,
+            migrationPath: prepared.migrationPath,
+            fileId: fileId ? String(fileId) : null,
+            migrationFiles
           },
           { transaction }
         );
         artifactPath = path.join(versionsDir, String(versionRow.id));
-        await fs.move(stagingPath, artifactPath);
+        if (keepArtifact) {
+          await fs.move(stagingPath, artifactPath);
+        }
         await versionRow.update({ artifactPath }, { transaction });
-        return versionRow.toJSON();
+        return toPublicVersion(versionRow);
       });
+      if (!keepArtifact) {
+        await fs.remove(stagingPath).catch(() => {});
+      }
+      return result;
     } catch (e) {
       await fs.remove(stagingPath).catch(() => {});
-      if (artifactPath) {
+      if (artifactPath && keepArtifact) {
         await fs.remove(artifactPath).catch(() => {});
       }
       if (e.name === 'SequelizeUniqueConstraintError') {
@@ -297,16 +375,52 @@ module.exports = fp(async (fastify, options) => {
     });
     const pageData = await Promise.all(
       rows.map(async row => {
-        const json = row.toJSON();
-        if (json.hasMigration) {
-          json.sqlFiles = await listSqlFiles(path.join(json.artifactPath, 'server', json.migrationPath || 'sql'));
-        }
-        return json;
+        const files = await getMigrationFiles(row);
+        return toPublicVersion(row, files);
       })
     );
     return { pageData, totalCount: count };
   };
 
+  const listArtifactFiles = async (root, dir = '') => {
+    const files = [];
+    for (const entry of await fs.readdir(path.join(root, dir), { withFileTypes: true })) {
+      const rel = dir ? `${dir}/${entry.name}` : entry.name;
+      // 部署时装的依赖与复制进 server 的 build 都不属于原始包
+      if (rel === 'server/node_modules' || rel === 'server/build') {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        files.push(...(await listArtifactFiles(root, rel)));
+      } else if (entry.isFile()) {
+        files.push(rel);
+      }
+    }
+    return files;
+  };
+
+  /** 有 fileId 时返回原始 zip；否则从版本目录还原包内容（不含 server/node_modules、server/build） */
+  const resolveVersionPackage = async ({ name, versionId }) => {
+    await getByName(name);
+    const ver = await models.appVersion.findByPk(versionId);
+    if (!ver || ver.appName !== name) {
+      httpError(404, 'version not found');
+    }
+    const fileName = `${name}-${ver.version}.zip`;
+    if (ver.fileId && typeof options.resolveVersionFile === 'function') {
+      try {
+        const buffer = await options.resolveVersionFile({ fileId: ver.fileId, name, version: ver.version });
+        return { fileName, buffer };
+      } catch (e) {
+        fastify.log.warn({ err: e, app: name, version: ver.version }, 'resolve version file failed, fallback to artifact');
+      }
+    }
+    if (!(await fs.pathExists(path.join(ver.artifactPath, 'server')))) {
+      httpError(404, 'version package not found');
+    }
+    return { fileName, artifactPath: ver.artifactPath, files: await listArtifactFiles(ver.artifactPath) };
+  };
+
   const healthCheck = async (port, { timeoutMs, intervalMs, healthPath }) => {
     const started = Date.now();
     const url = `http://127.0.0.1:${port}${healthPath || '/'}`;
@@ -336,6 +450,7 @@ module.exports = fp(async (fastify, options) => {
 
   /** 同一 app 并发同步合并为一次，避免 restart/reconcile 竞态 */
   const statusSyncInflight = new Map();
+  const deployProgress = createDeployProgress();
 
   /**
    * 根据 PM2 真实进程状态 + HTTP 健康检查，异步写回 DB status。
@@ -430,11 +545,14 @@ module.exports = fp(async (fastify, options) => {
 
   const finishDeployAsync = async appId => syncRealStatus(appId, { recoverIfMissing: false });
 
-  const scheduleStatusSync = (appId, opts) => {
+  const scheduleStatusSync = (appId, { onSettled, ...opts } = {}) => {
     setImmediate(() => {
-      syncRealStatus(appId, opts).catch(err => {
-        fastify.log.warn({ err, appId }, 'syncRealStatus failed');
-      });
+      syncRealStatus(appId, opts)
+        .catch(err => {
+          fastify.log.warn({ err, appId }, 'syncRealStatus failed');
+          return { status: 'error', message: err.message };
+        })
+        .then(result => onSettled && onSettled(result));
     });
   };
 
@@ -443,14 +561,18 @@ module.exports = fp(async (fastify, options) => {
     return syncRealStatus(app.id, { recoverIfMissing });
   };
 
-  const syncAllStatuses = async ({ recoverIfMissing = true } = {}) => {
+  const syncAllStatuses = async ({ recoverIfMissing = true, excludeIds = [] } = {}) => {
     const apps = await models.app.findAll({
       where: {
         status: ['running', 'deploying', 'stopped', 'error']
       }
     });
+    const excluded = new Set(excludeIds.map(String));
     const results = [];
     for (const app of apps) {
+      if (excluded.has(String(app.id))) {
+        continue;
+      }
       const shouldRecover = recoverIfMissing && (app.status === 'running' || app.status === 'deploying');
       results.push(await syncRealStatus(app.id, { recoverIfMissing: shouldRecover }));
     }
@@ -480,6 +602,26 @@ module.exports = fp(async (fastify, options) => {
       await app.reload();
     }
 
+    if (typeof options.resolveSystemEnv === 'function') {
+      const systemEnv = await options.resolveSystemEnv({ app, version, serverDir });
+      if (systemEnv && typeof systemEnv === 'object') {
+        const persisted = {};
+        for (const [key, value] of Object.entries(systemEnv)) {
+          if (value == null) {
+            continue;
+          }
+          env[key] = String(value);
+          if ((options.systemEnvKeys || []).includes(key) && app.env?.[key] !== env[key]) {
+            persisted[key] = env[key];
+          }
+        }
+        if (Object.keys(persisted).length) {
+          await app.update({ env: Object.assign({}, app.env || {}, persisted) });
+          await app.reload();
+        }
+      }
+    }
+
     const pathBase = mountPrefix(app.name);
     // Domain-first: inject `/` so custom Host SPA works; path mode then relies on gateway rewrite fallback.
     // Path-only: inject `/app/{name}` so runtime* matches strip-prefix gateway.
@@ -502,7 +644,117 @@ module.exports = fp(async (fastify, options) => {
     });
   };
 
-  const deploy = async ({ name, versionId, version, runMigration = true, migrations }) => {
+  const linkCurrent = async (app, artifactPath) => {
+    const currentLink = path.join(app.rootPath, 'current');
+    await fs.remove(currentLink).catch(() => {});
+    await fs.symlink(artifactPath, currentLink).catch(async () => {
+      // Windows fallback: copy marker file
+      await fs.writeFile(path.join(app.rootPath, 'current-path.txt'), artifactPath);
+    });
+  };
+
+  /** 只做 fs 检查：返回当前版本目录（artifactPath/server）缺失的应用 */
+  const listMissingArtifacts = async () => {
+    const { Op } = fastify.sequelize.Sequelize;
+    const apps = await models.app.findAll({ where: { currentVersionId: { [Op.ne]: null } } });
+    const missing = [];
+    for (const app of apps) {
+      const ver = await models.appVersion.findByPk(app.currentVersionId);
+      if (ver && !(await fs.pathExists(path.join(ver.artifactPath, 'server')))) {
+        missing.push({ app, ver });
+      }
+    }
+    return missing;
+  };
+
+  const canResolveFile = ver => !!ver.fileId && typeof options.resolveVersionFile === 'function';
+
+  /** 版本目录不在磁盘时按 fileId 取回 zip 解压并装依赖；再以数据库中的 SQL 覆盖目录内 .sql */
+  const materializeArtifact = async (app, ver, { onProgress } = {}) => {
+    if (await hasArtifact(ver)) {
+      onProgress && onProgress('reuse');
+    } else {
+      if (!canResolveFile(ver)) {
+        throw new Error(`version ${ver.version} artifact missing and cannot be restored without fileId`);
+      }
+      const stagingPath = path.join(app.rootPath, 'versions', `.staging-${crypto.randomUUID()}`);
+      try {
+        onProgress && onProgress('download');
+        const zipBuffer = await options.resolveVersionFile({ fileId: ver.fileId, name: app.name, version: ver.version });
+        await prepareVersionArtifact({
+          zipBuffer,
+          artifactPath: stagingPath,
+          maxZipSize: options.maxZipSize,
+          maxZipEntries: options.maxZipEntries,
+          npmInstallTimeoutMs: options.npmInstallTimeoutMs,
+          sqlPath: options.sqlPath,
+          onProgress
+        });
+        await fs.move(stagingPath, ver.artifactPath, { overwrite: true });
+      } catch (e) {
+        await fs.remove(stagingPath).catch(() => {});
+        throw e;
+      }
+    }
+    await writeSqlDir(versionSqlDir(ver), await getMigrationFiles(ver));
+  };
+
+  /** 删除非当前版本中可从宿主文件重建的目录；删前先把 SQL 回填进库 */
+  const pruneVersionArtifacts = async app => {
+    const versions = await models.appVersion.findAll({ where: { appName: app.name } });
+    const removed = [];
+    for (const ver of versions) {
+      if (String(ver.id) === String(app.currentVersionId) || !canResolveFile(ver) || !(await fs.pathExists(ver.artifactPath))) {
+        continue;
+      }
+      await getMigrationFiles(ver);
+      await fs.remove(ver.artifactPath);
+      removed.push(ver.version);
+    }
+    if (removed.length) {
+      fastify.log.info({ app: app.name, versions: removed }, 'pruned non-current version artifacts');
+    }
+    return removed;
+  };
+
+  const pruneAllVersionArtifacts = async () => {
+    const results = [];
+    for (const app of await models.app.findAll()) {
+      try {
+        results.push({ name: app.name, removed: await pruneVersionArtifacts(app) });
+      } catch (e) {
+        fastify.log.warn({ err: e, app: app.name }, 'prune version artifacts failed');
+      }
+    }
+    return results;
+  };
+
+  /** 补回当前版本目录并恢复 current 链接；不跑 SQL 迁移 */
+  const restoreArtifact = async ({ app, ver }) => {
+    if (!canResolveFile(ver)) {
+      fastify.log.warn({ app: app.name, version: ver.version }, '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);
+      await linkCurrent(app, ver.artifactPath);
+      fastify.log.info({ app: app.name, version: ver.version }, 'current version artifact restored from file');
+      return { name: app.name, version: ver.version, action: 'restored' };
+    } 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 };
+    }
+  };
+
+  const restoreMissingArtifacts = async () => {
+    const results = [];
+    for (const item of await listMissingArtifacts()) {
+      results.push(await restoreArtifact(item));
+    }
+    return results;
+  };
+
+  const deploy = async ({ name, versionId, version, runMigration = true, migrations, progressId }) => {
     const app = await getByName(name);
     let ver = null;
     if (versionId) {
@@ -514,21 +766,29 @@ module.exports = fp(async (fastify, options) => {
       httpError(404, 'version not found');
     }
 
+    const progress = deployProgress.begin(app.name, progressId || crypto.randomUUID());
+    let step = 'package';
+    progress.report(step, 'running');
+    try {
+      await materializeArtifact(app, ver, { onProgress: detail => progress.report('package', 'running', { detail }) });
+    } catch (e) {
+      progress.report(step, 'error', { message: e.message });
+      httpError(400, e.message);
+    }
+    progress.report(step, 'done');
+
     await app.update({
       status: 'deploying',
       currentVersionId: String(ver.id),
       message: null
     });
 
-    const currentLink = path.join(app.rootPath, 'current');
-    await fs.remove(currentLink).catch(() => {});
-    await fs.symlink(ver.artifactPath, currentLink).catch(async () => {
-      // Windows fallback: copy marker file
-      await fs.writeFile(path.join(app.rootPath, 'current-path.txt'), ver.artifactPath);
-    });
+    await linkCurrent(app, ver.artifactPath);
 
     try {
+      step = 'migrate';
       if (runMigration && options.migrateBeforeStart && ver.hasMigration) {
+        progress.report(step, 'running');
         const env = mergeEnv({
           passthroughEnvKeys: options.passthroughEnvKeys,
           appEnv: app.env,
@@ -563,6 +823,9 @@ module.exports = fp(async (fastify, options) => {
         } catch (e) {
           // ignore ownership merge failures
         }
+        progress.report(step, 'done');
+      } else {
+        progress.report(step, 'skipped');
       }
 
       if (runMigration === false) {
@@ -570,18 +833,29 @@ module.exports = fp(async (fastify, options) => {
         app.env = Object.assign({}, app.env, { RUN_SQL_ON_SYNC: 'false' });
       }
 
+      step = 'start';
+      progress.report(step, 'running');
       const beforeForReady = await snapshotTablesSafe(app);
       await startProcess(app);
-      scheduleStatusSync(app.id, { beforeTables: beforeForReady });
+      progress.report(step, 'done');
+      step = 'ready';
+      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 }))
+      });
+      await pruneVersionArtifacts(app).catch(err => fastify.log.warn({ err, app: app.name }, 'prune version artifacts failed'));
       return {
         name: app.name,
         status: 'deploying',
         versionId: String(ver.id),
+        progressId: progress.progressId,
         port: app.port,
         pathUrl: `${mountPrefix(app.name)}/`,
         domain: app.domain
       };
     } catch (e) {
+      progress.report(step, 'error', { message: e.message });
       await app.update({ status: 'error', message: e.message });
       httpError(400, e.message);
     }
@@ -663,9 +937,18 @@ module.exports = fp(async (fastify, options) => {
       }
     }
 
+    const snapshot = app.toJSON();
     await models.appVersion.destroy({ where: { appName: name } });
     await fs.remove(app.rootPath).catch(() => {});
+    deployProgress.clear(app.name);
     await app.destroy();
+    if (typeof options.onAppRemoved === 'function') {
+      try {
+        await options.onAppRemoved({ app: snapshot });
+      } catch (e) {
+        fastify.log.warn({ err: e, appName: name }, 'onAppRemoved hook failed');
+      }
+    }
     return {
       removed: true,
       export: exportResult,
@@ -801,6 +1084,14 @@ module.exports = fp(async (fastify, options) => {
       syncStatus,
       syncAllStatuses,
       remove,
+      resolveVersionPackage,
+      listMissingArtifacts,
+      restoreArtifact,
+      restoreMissingArtifacts,
+      pruneVersionArtifacts,
+      pruneAllVersionArtifacts,
+      getMigrationFiles,
+      saveMigrationFiles,
       logs,
       logFiles,
       resolveAppLogFile,
@@ -808,6 +1099,7 @@ module.exports = fp(async (fastify, options) => {
       removeLogFiles,
       load,
       getLoadStore,
+      getDeployProgress: () => deployProgress,
       toPublicApp,
       mountPrefix,
       findByHost,

package/libs/services/bootstrap.js

@@ -35,8 +35,28 @@ module.exports = fp(async (fastify, options) => {
     return models.app.findOne({ where: { pm2Name } });
   };
 
+  /** 宿主 sync() 不会给已有表加列：老库升级时补齐后续新增的可空列 */
+  const ensureSchema = async () => {
+    const { models } = fastify[options.name];
+    const model = models.appVersion;
+    const queryInterface = model.sequelize.getQueryInterface();
+    const table = model.getTableName();
+    const columns = await queryInterface.describeTable(table);
+    for (const name of ['fileId', 'migrationFiles']) {
+      const attr = model.rawAttributes[name];
+      if (!columns[attr.field]) {
+        await queryInterface.addColumn(table, attr.field, { type: attr.type, allowNull: true, comment: attr.comment });
+      }
+    }
+  };
+
   const onReady = async () => {
     await fsEnsureAppsRoot();
+    try {
+      await ensureSchema();
+    } catch (e) {
+      fastify.log.warn({ err: e }, 'ensure app-manager schema failed');
+    }
     try {
       await pm2Util.connect();
       connected = true;
@@ -87,9 +107,9 @@ module.exports = fp(async (fastify, options) => {
       loadTimer.unref?.();
     }
 
-    // 父应用重启后不阻塞 ready：后台按 PM2 真实状态异步对齐 DB
+    // 父应用重启后不阻塞 ready：后台按 PM2 真实状态对齐 DB，缺部署目录的应用另行补回后再拉起
     setImmediate(() => {
-      reconcile().catch(err => {
+      recoverOnStartup().catch(err => {
         fastify.log.warn({ err }, 'async reconcile/sync statuses failed');
       });
       rotateLogs().catch(err => fastify.log.warn({ err }, 'log rotation failed'));
@@ -103,14 +123,57 @@ module.exports = fp(async (fastify, options) => {
     await fs.ensureDir(options.appsRoot);
   };
 
-  const reconcile = async () => {
+  const reconcile = async ({ excludeIds } = {}) => {
     const { services } = fastify[options.name];
     if (typeof services.app.syncAllStatuses === 'function') {
-      return services.app.syncAllStatuses({ recoverIfMissing: true });
+      return services.app.syncAllStatuses({ recoverIfMissing: true, excludeIds });
     }
     return [];
   };
 
+  /** 逐个补回缺失的部署目录（npm install 耗时），每补完一个就单独对齐状态并按需拉起 */
+  const restoreArtifacts = async missing => {
+    const { services } = fastify[options.name];
+    const results = [];
+    for (const item of missing) {
+      const result = await services.app.restoreArtifact(item);
+      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}` });
+        }
+      } catch (e) {
+        fastify.log.warn({ err: e, app: app.name }, 'sync status after artifact restore failed');
+      }
+    }
+    return results;
+  };
+
+  const recoverOnStartup = async () => {
+    const { services } = fastify[options.name];
+    const missing = await services.app.listMissingArtifacts();
+    // 两路并行：部署目录完好的应用不必等其它应用重装依赖
+    const [reconciled, restored] = await Promise.all([
+      reconcile({ excludeIds: missing.map(({ app }) => app.id) }).catch(err => {
+        fastify.log.warn({ err }, 'async reconcile/sync statuses failed');
+        return [];
+      }),
+      restoreArtifacts(missing).catch(err => {
+        fastify.log.warn({ err }, 'restore missing artifacts failed');
+        return [];
+      })
+    ]);
+    // 只保留当前版本目录，其余版本部署时再从宿主文件解压
+    const pruned = await services.app.pruneAllVersionArtifacts().catch(err => {
+      fastify.log.warn({ err }, 'prune version artifacts failed');
+      return [];
+    });
+    return { reconciled, restored, pruned };
+  };
+
   const runRotation = async ({ now = new Date() } = {}) => {
     const { models } = fastify[options.name];
     const apps = await models.app.findAll({ attributes: ['name', 'rootPath'] });
@@ -244,6 +307,6 @@ module.exports = fp(async (fastify, options) => {
   };
 
   Object.assign(fastify[options.name].services, {
-    bootstrap: { onReady, onClose, reconcile, rotateLogs, sampleLoad }
+    bootstrap: { onReady, onClose, ensureSchema, recoverOnStartup, reconcile, rotateLogs, sampleLoad }
   });
 });