@kne/fastify-app-manager 0.1.10 → 0.1.12

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', 'envSchema']) {
+      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 }
   });
 });

package/libs/services/migration.js

@@ -1,12 +1,10 @@
 const fp = require('fastify-plugin');
-const path = require('node:path');
-const fs = require('fs-extra');
-const { listSqlFiles } = require('../utils/validatePackage');
 const { isValidSqlFileName, readExecutedMigrations, recordMigration, removeMigrationRecord } = require('../utils/migrate');
 
 module.exports = fp(async (fastify, options) => {
   const { models } = fastify[options.name];
   const getDbops = () => fastify[options.name].services.dbops;
+  const getAppService = () => fastify[options.name].services.app;
 
   const httpError = (statusCode, message) => {
     if (fastify.httpErrors) {
@@ -27,8 +25,7 @@ module.exports = fp(async (fastify, options) => {
     if (!ver || ver.appName !== name) {
       httpError(404, 'version not found');
     }
-    const sqlDir = path.join(ver.artifactPath, 'server', ver.migrationPath || options.sqlPath);
-    return { app, ver, sqlDir };
+    return { app, ver };
   };
 
   const assertFileName = file => {
@@ -37,25 +34,20 @@ module.exports = fp(async (fastify, options) => {
     }
   };
 
-  const assertFileExists = async (sqlDir, file) => {
+  const getFiles = ver => getAppService().getMigrationFiles(ver);
+
+  const findFile = async (ver, file) => {
     assertFileName(file);
-    const filePath = path.join(sqlDir, file);
-    if (!(await fs.pathExists(filePath))) {
+    const item = (await getFiles(ver)).find(f => f.name === file);
+    if (!item) {
       httpError(404, `sql file ${file} not found`);
     }
-    return filePath;
-  };
-
-  const syncHasMigration = async (ver, sqlDir) => {
-    const hasMigration = (await listSqlFiles(sqlDir)).length > 0;
-    if (ver.hasMigration !== hasMigration) {
-      await ver.update({ hasMigration });
-    }
+    return item;
   };
 
   const list = async ({ name, versionId }) => {
-    const { app, ver, sqlDir } = await resolveVersion({ name, versionId });
-    const files = await listSqlFiles(sqlDir);
+    const { app, ver } = await resolveVersion({ name, versionId });
+    const files = await getFiles(ver);
     let executedMap = new Map();
     let dbError = null;
     try {
@@ -63,18 +55,13 @@ module.exports = fp(async (fastify, options) => {
     } catch (e) {
       dbError = e.message;
     }
-    const pageData = await Promise.all(
-      files.map(async file => {
-        const stat = await fs.stat(path.join(sqlDir, file));
-        return {
-          name: file,
-          size: stat.size,
-          updatedAt: stat.mtime,
-          executed: dbError ? null : executedMap.has(file),
-          executedAt: executedMap.get(file) || null
-        };
-      })
-    );
+    const pageData = files.map(item => ({
+      name: item.name,
+      size: Buffer.byteLength(item.content || '', 'utf8'),
+      updatedAt: item.updatedAt || null,
+      executed: dbError ? null : executedMap.has(item.name),
+      executedAt: executedMap.get(item.name) || null
+    }));
     return {
       versionId: String(ver.id),
       version: ver.version,
@@ -87,32 +74,33 @@ module.exports = fp(async (fastify, options) => {
   };
 
   const content = async ({ name, versionId, file }) => {
-    const { sqlDir } = await resolveVersion({ name, versionId });
-    const filePath = await assertFileExists(sqlDir, file);
-    return { name: file, content: await fs.readFile(filePath, 'utf8') };
+    const { ver } = await resolveVersion({ name, versionId });
+    const item = await findFile(ver, file);
+    return { name: file, content: item.content || '' };
   };
 
   const save = async ({ name, versionId, file, content: sql }) => {
     assertFileName(file);
-    const { ver, sqlDir } = await resolveVersion({ name, versionId });
-    await fs.ensureDir(sqlDir);
-    await fs.writeFile(path.join(sqlDir, file), sql || '', 'utf8');
-    await syncHasMigration(ver, sqlDir);
+    const { ver } = await resolveVersion({ name, versionId });
+    const files = (await getFiles(ver)).filter(f => f.name !== file);
+    files.push({ name: file, content: sql || '', updatedAt: new Date().toISOString() });
+    await getAppService().saveMigrationFiles(ver, files);
     return { name: file };
   };
 
   const remove = async ({ name, versionId, file }) => {
-    const { ver, sqlDir } = await resolveVersion({ name, versionId });
-    const filePath = await assertFileExists(sqlDir, file);
-    await fs.remove(filePath);
-    await syncHasMigration(ver, sqlDir);
+    const { ver } = await resolveVersion({ name, versionId });
+    await findFile(ver, file);
+    await getAppService().saveMigrationFiles(
+      ver,
+      (await getFiles(ver)).filter(f => f.name !== file)
+    );
     return { name: file };
   };
 
   const execute = async ({ name, versionId, file }) => {
-    const { app, sqlDir } = await resolveVersion({ name, versionId });
-    const filePath = await assertFileExists(sqlDir, file);
-    const sql = await fs.readFile(filePath, 'utf8');
+    const { app, ver } = await resolveVersion({ name, versionId });
+    const { content: sql } = await findFile(ver, file);
     const dbops = getDbops();
     let beforeTables = [];
     let afterTables = [];
@@ -131,8 +119,8 @@ module.exports = fp(async (fastify, options) => {
   };
 
   const mark = async ({ name, versionId, file }) => {
-    const { app, sqlDir } = await resolveVersion({ name, versionId });
-    await assertFileExists(sqlDir, file);
+    const { app, ver } = await resolveVersion({ name, versionId });
+    await findFile(ver, file);
     await getDbops().withSequelize(app, sequelize => recordMigration(sequelize, file));
     return { name: file, executed: true };
   };

package/libs/utils/deployProgress.js

@@ -0,0 +1,66 @@
+const { EventEmitter } = require('node:events');
+
+/** 部署阶段，按顺序推进：准备部署包 → 校验环境变量 → SQL 迁移 → 启动进程 → 等待就绪 */
+const DEPLOY_STEPS = ['package', 'env', 'migrate', 'start', 'ready'];
+
+/**
+ * 每个应用只保留最近一次部署的进度事件，供 SSE 订阅与断线重连回放。
+ * 事件：{ progressId, step, status: 'running' | 'done' | 'skipped' | 'error', detail?, message?, at }
+ */
+const createDeployProgress = () => {
+  const emitter = new EventEmitter();
+  emitter.setMaxListeners(0);
+  const latest = new Map();
+
+  const begin = (name, progressId) => {
+    const state = { progressId, events: [] };
+    latest.set(name, state);
+    const report = (step, status, { detail = null, message = null } = {}) => {
+      const event = { progressId, step, status, detail, message, at: new Date().toISOString() };
+      state.events.push(event);
+      emitter.emit(`deploy:${name}`, event);
+      return event;
+    };
+    return { progressId, report };
+  };
+
+  const snapshot = name => latest.get(name) || null;
+
+  const clear = name => latest.delete(name);
+
+  const isFinished = event => event.status === 'error' || (event.step === 'ready' && event.status !== 'running');
+
+  /** 等到该次部署出错或就绪阶段结束（或超时）；返回 { progressId, ok, timedOut, events } */
+  const wait = (name, progressId, { timeoutMs = 120000 } = {}) =>
+    new Promise(resolve => {
+      const collect = () => {
+        const state = latest.get(name);
+        return state && state.progressId === progressId ? state.events.slice() : [];
+      };
+      let timer = null;
+      const listener = event => {
+        if (event.progressId === progressId && isFinished(event)) {
+          finish(false);
+        }
+      };
+      const finish = timedOut => {
+        clearTimeout(timer);
+        emitter.off(`deploy:${name}`, listener);
+        const events = collect();
+        resolve({ progressId, ok: !timedOut && !events.some(event => event.status === 'error'), timedOut, events });
+      };
+      if (collect().some(isFinished)) {
+        finish(false);
+        return;
+      }
+      emitter.on(`deploy:${name}`, listener);
+      timer = setTimeout(() => finish(true), timeoutMs);
+    });
+
+  return { emitter, begin, snapshot, clear, wait };
+};
+
+module.exports = {
+  DEPLOY_STEPS,
+  createDeployProgress
+};

package/libs/utils/env.js

@@ -194,6 +194,7 @@ module.exports = {
   pickHostEnv,
   hasAppDbConfig,
   DB_DEDICATED_KEY,
+  DB_CONNECTION_KEYS,
   isAppDbEnabled,
   buildDefaultAppDbEnv,
   resolveAppDbEnv,

package/libs/utils/envSchema.js

@@ -0,0 +1,105 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const Ajv = require('ajv');
+
+const ENV_SCHEMA_FILE = 'env.schema.json';
+
+// 与 @fastify/env（env-schema）一致：类型转换、填充默认值，separator 为其内置关键字
+const createAjv = () => {
+  const ajv = new Ajv({ allErrors: true, coerceTypes: true, useDefaults: true, allowUnionTypes: true });
+  ajv.addKeyword('separator');
+  return ajv;
+};
+
+/** 检查 schema 是否符合规范：顶层 object、有 properties、required 中的键都已声明、能被 ajv 编译 */
+const checkEnvSchema = schema => {
+  const errors = [];
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return ['env.schema.json must be a JSON object'];
+  }
+  if (schema.type !== 'object') {
+    errors.push('env.schema.json: "type" must be "object"');
+  }
+  if (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties)) {
+    errors.push('env.schema.json: "properties" must be an object');
+  }
+  if (schema.required !== undefined) {
+    if (!Array.isArray(schema.required) || schema.required.some(key => typeof key !== 'string')) {
+      errors.push('env.schema.json: "required" must be an array of strings');
+    } else if (schema.properties && typeof schema.properties === 'object') {
+      const undeclared = schema.required.filter(key => !Object.prototype.hasOwnProperty.call(schema.properties, key));
+      if (undeclared.length) {
+        errors.push(`env.schema.json: required keys not declared in properties: ${undeclared.join(', ')}`);
+      }
+    }
+  }
+  if (!errors.length) {
+    try {
+      createAjv().compile(schema);
+    } catch (e) {
+      errors.push(`env.schema.json: ${e.message}`);
+    }
+  }
+  return errors;
+};
+
+/** 读取 server/env.schema.json；文件缺失、JSON 非法或不符合规范时抛错 */
+const readEnvSchema = async serverDir => {
+  const file = path.join(serverDir, ENV_SCHEMA_FILE);
+  if (!(await fs.pathExists(file))) {
+    throw new Error(`missing server/${ENV_SCHEMA_FILE}`);
+  }
+  let schema;
+  try {
+    schema = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`server/${ENV_SCHEMA_FILE} is not valid JSON: ${e.message}`);
+  }
+  const errors = checkEnvSchema(schema);
+  if (errors.length) {
+    throw new Error(errors.join('; '));
+  }
+  return schema;
+};
+
+const formatError = error => {
+  const { keyword, params = {} } = error;
+  if (keyword === 'required') {
+    return { key: params.missingProperty, message: '必填，未配置' };
+  }
+  const key = String(error.instancePath || '')
+    .replace(/^\//, '')
+    .split('/')[0];
+  if (keyword === 'type') {
+    return { key, message: `类型应为 ${params.type}` };
+  }
+  if (keyword === 'enum') {
+    return { key, message: `取值应为 ${(params.allowedValues || []).join(' / ')}` };
+  }
+  if (keyword === 'pattern') {
+    return { key, message: `格式应匹配 ${params.pattern}` };
+  }
+  return { key, message: error.message };
+};
+
+/** 按 schema 校验环境变量；空字符串视为未配置。返回 [{ key, message }]，空数组表示通过 */
+const validateEnv = (schema, env = {}) => {
+  const data = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (value != null && value !== '') {
+      data[key] = value;
+    }
+  }
+  const validate = createAjv().compile(schema);
+  if (validate(data)) {
+    return [];
+  }
+  return (validate.errors || []).map(formatError);
+};
+
+module.exports = {
+  ENV_SCHEMA_FILE,
+  checkEnvSchema,
+  readEnvSchema,
+  validateEnv
+};

package/libs/utils/validatePackage.js

@@ -1,9 +1,11 @@
 const path = require('node:path');
 const fs = require('fs-extra');
+const { readEnvSchema } = require('./envSchema');
 
 const ENTRY_CANDIDATES = ['index.html', 'entry.html', 'entry-prod.html'];
 
-const validatePackageRoot = async rootDir => {
+/** requireEnvSchema=false 时缺少 / 非法的 env.schema.json 不算错误，envSchema 返回 null（用于从宿主文件还原老版本） */
+const validatePackageRoot = async (rootDir, { requireEnvSchema = true } = {}) => {
   const errors = [];
   const rootPkg = path.join(rootDir, 'package.json');
   const serverPkg = path.join(rootDir, 'server', 'package.json');
@@ -28,9 +30,19 @@ const validatePackageRoot = async rootDir => {
     }
   }
 
+  let envSchema = null;
+  try {
+    envSchema = await readEnvSchema(path.join(rootDir, 'server'));
+  } catch (e) {
+    if (requireEnvSchema) {
+      errors.push(e.message);
+    }
+  }
+
   return {
     ok: errors.length === 0,
     errors,
+    envSchema,
     hasMigration: await hasSqlMigrations(path.join(rootDir, 'server', 'sql'))
   };
 };

package/libs/utils/version.js

@@ -33,13 +33,15 @@ const runNpmInstall = (cwd, timeoutMs) =>
     });
   });
 
-const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath }) => {
+/** install=false 时只解压校验，不装依赖（用于不常驻磁盘的版本上传） */
+const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath, install = true, requireEnvSchema = true, onProgress }) => {
   await fs.emptyDir(artifactPath);
+  onProgress && onProgress('extract');
   const extractDir = path.join(artifactPath, '_extract');
   await extractZipSafe(zipBuffer, extractDir, { maxZipSize, maxZipEntries });
   const packageRoot = await resolvePackageRoot(extractDir);
 
-  const validation = await validatePackageRoot(packageRoot);
+  const validation = await validatePackageRoot(packageRoot, { requireEnvSchema });
   if (!validation.ok) {
     await fs.remove(artifactPath);
     throw new Error(`invalid package: ${validation.errors.join('; ')}`);
@@ -60,14 +62,18 @@ const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, max
   });
 
   const serverDir = path.join(artifactPath, 'server');
-  await runNpmInstall(serverDir, npmInstallTimeoutMs);
+  if (install) {
+    onProgress && onProgress('install');
+    await runNpmInstall(serverDir, npmInstallTimeoutMs);
+  }
 
   const sqlDir = path.join(serverDir, sqlPath || 'sql');
   const sqlFiles = await listSqlFiles(sqlDir);
   return {
     hasMigration: sqlFiles.length > 0,
     migrationPath: sqlPath || 'sql',
-    sqlFiles
+    sqlFiles,
+    envSchema: validation.envSchema
   };
 };
 

package/libs/utils/versionSql.js

@@ -0,0 +1,33 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const { listSqlFiles } = require('./validatePackage');
+
+/** 读取目录内的 .sql 为 [{ name, content, updatedAt }] */
+const readSqlDir = async sqlDir => {
+  const files = [];
+  for (const name of await listSqlFiles(sqlDir)) {
+    const filePath = path.join(sqlDir, name);
+    const [content, stat] = await Promise.all([fs.readFile(filePath, 'utf8'), fs.stat(filePath)]);
+    files.push({ name, content, updatedAt: stat.mtime.toISOString() });
+  }
+  return files;
+};
+
+/** 以 files 为准覆盖目录内的 .sql：删掉多余的，写入全部 */
+const writeSqlDir = async (sqlDir, files) => {
+  await fs.ensureDir(sqlDir);
+  const keep = new Set(files.map(item => item.name));
+  for (const name of await listSqlFiles(sqlDir)) {
+    if (!keep.has(name)) {
+      await fs.remove(path.join(sqlDir, name));
+    }
+  }
+  for (const item of files) {
+    await fs.writeFile(path.join(sqlDir, item.name), item.content || '', 'utf8');
+  }
+};
+
+module.exports = {
+  readSqlDir,
+  writeSqlDir
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-app-manager",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Fastify 单机应用市场插件：版本上传、PM2 托管、路径/域名反代与日志 SSE",
   "main": "index.js",
   "scripts": {
@@ -69,6 +69,7 @@
     "@fastify/reply-from": "^12.6.5",
     "@kne/ensure-slash": "^0.1.0",
     "adm-zip": "^0.6.0",
+    "ajv": "^8.17.1",
     "fs-extra": "^11.4.0",
     "jsdom": "^29.1.1",
     "lodash": "^4.18.1",