@kne/fastify-app-manager 0.1.10 → 0.1.12

package/libs/services/app.js

@@ -3,14 +3,30 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const portPool = require('../utils/portPool');
-const { mergeEnv, maskEnvForResponse, applyEnvPatch, mergePm2Config, normalizeSecretKeys, collectSecretKeys, isSystemEnvKey, omitSystemEnv } = require('../utils/env');
+const {
+  mergeEnv,
+  maskEnvForResponse,
+  applyEnvPatch,
+  mergePm2Config,
+  normalizeSecretKeys,
+  collectSecretKeys,
+  isSystemEnvKey,
+  isSecretKey,
+  omitSystemEnv,
+  SECRET_MASK,
+  SYSTEM_ENV_KEYS,
+  DB_CONNECTION_KEYS,
+  DB_DEDICATED_KEY
+} = require('../utils/env');
+const { readEnvSchema, validateEnv, ENV_SCHEMA_FILE } = require('../utils/envSchema');
 const { prepareVersionArtifact } = require('../utils/version');
 const { injectEntryHtml } = require('../utils/entryInject');
 const { ensureLogFiles, readLogTail, readLastLines, appendLog, countLines } = require('../utils/logFiles');
 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])?$/;
@@ -197,7 +213,9 @@ module.exports = fp(async (fastify, options) => {
     const app = await getByName(name);
     // 密钥类型不可撤销，只随变量删除而移除
     const secretEnvKeys = normalizeSecretKeys([...resolveSecretEnvKeys(app), ...(nextSecretKeys || [])]);
-    const nextEnv = applyEnvPatch(app.env || {}, env || {}, Object.assign({}, options, { secretEnvKeys }));
+    // PORT 由端口池分配，启动时总会覆盖，不接受外部写入
+    const { PORT, ...envPatch } = env || {};
+    const nextEnv = applyEnvPatch(app.env || {}, envPatch, Object.assign({}, options, { secretEnvKeys }));
     const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key, options.systemEnvKeys) && Object.prototype.hasOwnProperty.call(nextEnv, key));
     await app.update({
       env: nextEnv,
@@ -250,7 +268,60 @@ 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, envSchema, ...json } = row.toJSON();
+    if (Array.isArray(files) && files.length) {
+      json.sqlFiles = files.map(item => item.name);
+    }
+    json.hasEnvSchema = !!envSchema;
+    return json;
+  };
+
+  /** schema 以数据库为准；旧版本行（envSchema 为空）且版本目录在磁盘时从目录回填 */
+  const getVersionEnvSchema = async ver => {
+    if (ver.envSchema) {
+      return ver.envSchema;
+    }
+    if (!(await hasArtifact(ver))) {
+      return null;
+    }
+    try {
+      const schema = await readEnvSchema(path.join(ver.artifactPath, 'server'));
+      await ver.update({ envSchema: schema });
+      return schema;
+    } catch (e) {
+      return null;
+    }
+  };
+
+  const uploadVersion = async ({ name, version, label, zipBuffer, fileId }) => {
     if (!version) {
       httpError(400, 'version is required');
     }
@@ -270,7 +341,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,
@@ -278,8 +352,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);
@@ -287,26 +363,35 @@ 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,
+            envSchema: prepared.envSchema
           },
           { 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') {
@@ -326,16 +411,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 || '/'}`;
@@ -365,6 +486,7 @@ module.exports = fp(async (fastify, options) => {
 
   /** 同一 app 并发同步合并为一次，避免 restart/reconcile 竞态 */
   const statusSyncInflight = new Map();
+  const deployProgress = createDeployProgress();
 
   /**
    * 根据 PM2 真实进程状态 + HTTP 健康检查，异步写回 DB status。
@@ -459,11 +581,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));
     });
   };
 
@@ -472,27 +597,27 @@ 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 }));
     }
     return results.filter(Boolean);
   };
 
-  const startProcess = async app => {
-    const version = await models.appVersion.findByPk(app.currentVersionId);
-    if (!version) {
-      throw new Error('current version missing');
-    }
+  /** 子进程最终环境变量：宿主透传 → 托管库 → 应用变量 → PORT → resolveSystemEnv；顺带持久化表前缀与系统变量 */
+  const buildProcessEnv = async (app, version) => {
     const serverDir = path.join(version.artifactPath, 'server');
-    const { outFile, errFile } = await ensureLogFiles(app.rootPath);
     const env = mergeEnv({
       passthroughEnvKeys: options.passthroughEnvKeys,
       appEnv: app.env,
@@ -511,6 +636,7 @@ module.exports = fp(async (fastify, options) => {
 
     if (typeof options.resolveSystemEnv === 'function') {
       const systemEnv = await options.resolveSystemEnv({ app, version, serverDir });
+      const injectedKeys = [];
       if (systemEnv && typeof systemEnv === 'object') {
         const persisted = {};
         for (const [key, value] of Object.entries(systemEnv)) {
@@ -518,6 +644,7 @@ module.exports = fp(async (fastify, options) => {
             continue;
           }
           env[key] = String(value);
+          injectedKeys.push(key);
           if ((options.systemEnvKeys || []).includes(key) && app.env?.[key] !== env[key]) {
             persisted[key] = env[key];
           }
@@ -527,7 +654,143 @@ module.exports = fp(async (fastify, options) => {
           await app.reload();
         }
       }
+      // 记下本次由系统注入的键，供环境变量声明接口隐藏（如未配置 ORIGIN 时由宿主补上的值）
+      const recorded = app.options?.injectedEnvKeys || [];
+      if (recorded.length !== injectedKeys.length || recorded.some(key => !injectedKeys.includes(key))) {
+        await app.update({ options: Object.assign({}, app.options || {}, { injectedEnvKeys: injectedKeys }) });
+        await app.reload();
+      }
+    }
+    return env;
+  };
+
+  const envSchemaMissingError = () => {
+    const err = new Error(`该版本缺少 server/${ENV_SCHEMA_FILE}，请补充后重新上传`);
+    err.envErrors = [];
+    return err;
+  };
+
+  /** 按版本的 env.schema.json 校验最终环境变量，不通过时抛错（err.envErrors 为 [{ key, message }]） */
+  const assertEnvValid = async (app, version, env) => {
+    const schema = await getVersionEnvSchema(version);
+    if (!schema) {
+      throw envSchemaMissingError();
+    }
+    const errors = validateEnv(schema, env);
+    if (errors.length) {
+      const injected = listInjectedEnvKeys(app);
+      const detail = errors.map(({ key, message }) => `${key}${injected.has(key) ? '（应用中心注入）' : ''} ${message}`).join('；');
+      const err = new Error(`环境变量不符合 ${ENV_SCHEMA_FILE}：${detail}`);
+      err.envErrors = errors;
+      throw err;
+    }
+  };
+
+  /** 应用中心自动注入或在其它页签维护的变量名：环境变量管理中不展示 */
+  const listInjectedEnvKeys = app =>
+    new Set([
+      'PORT',
+      ...SYSTEM_ENV_KEYS,
+      ...(options.systemEnvKeys || []),
+      ...(options.passthroughEnvKeys || []),
+      // 托管库连接由宿主注入，自有库在数据页签配置
+      ...DB_CONNECTION_KEYS,
+      DB_DEDICATED_KEY,
+      ...(app.options?.injectedEnvKeys || [])
+    ]);
+
+  const resolveDeclarationVersion = async (app, versionId) => {
+    if (versionId) {
+      const ver = await models.appVersion.findByPk(versionId);
+      if (!ver || ver.appName !== app.name) {
+        httpError(404, 'version not found');
+      }
+      return ver;
+    }
+    if (app.currentVersionId) {
+      const ver = await models.appVersion.findByPk(app.currentVersionId);
+      if (ver) {
+        return ver;
+      }
+    }
+    return models.appVersion.findOne({ where: { appName: app.name }, order: [['createdAt', 'DESC']] });
+  };
+
+  /**
+   * 环境变量声明：declared 为 schema 中需要用户填写的变量，others 为已配置但未声明的变量；
+   * 两者都不含应用中心注入的变量，密钥值掩码
+   */
+  const getEnvDeclaration = async ({ name, versionId } = {}) => {
+    const app = await getByName(name);
+    const ver = await resolveDeclarationVersion(app, versionId);
+    const schema = ver ? await getVersionEnvSchema(ver) : null;
+    const injected = listInjectedEnvKeys(app);
+    const appEnv = omitSystemEnv(app.env || {}, options.systemEnvKeys);
+    const secretOpts = Object.assign({}, options, { secretEnvKeys: resolveSecretEnvKeys(app) });
+    const isSecret = (key, prop) => !!prop?.writeOnly || isSecretKey(key, options.secretEnvKeyPattern, secretOpts.secretEnvKeys);
+    const maskValue = (key, prop) => {
+      const value = appEnv[key];
+      if (value == null || value === '') {
+        return null;
+      }
+      return isSecret(key, prop) ? SECRET_MASK : value;
+    };
+
+    const properties = schema?.properties || {};
+    const required = new Set(schema?.required || []);
+    const errorMap = new Map();
+    if (schema) {
+      const previewEnv = mergeEnv({
+        passthroughEnvKeys: options.passthroughEnvKeys,
+        appEnv: app.env,
+        port: app.port,
+        defaultAppDb: options.defaultAppDb,
+        appName: app.name
+      });
+      validateEnv(schema, previewEnv)
+        .filter(item => !injected.has(item.key))
+        .forEach(item => errorMap.set(item.key, item.message));
+    }
+
+    const declared = Object.entries(properties)
+      .filter(([key]) => !injected.has(key))
+      .map(([key, prop]) => ({
+        key,
+        type: prop?.type || null,
+        required: required.has(key),
+        default: prop?.default === undefined ? null : prop.default,
+        description: prop?.description || prop?.title || null,
+        enum: Array.isArray(prop?.enum) ? prop.enum : null,
+        secret: isSecret(key, prop),
+        configured: appEnv[key] != null && appEnv[key] !== '',
+        value: maskValue(key, prop),
+        error: errorMap.get(key) || null
+      }));
+
+    const others = Object.keys(appEnv)
+      .filter(key => !injected.has(key) && !Object.prototype.hasOwnProperty.call(properties, key))
+      .map(key => ({ key, secret: isSecret(key), value: maskValue(key) }));
+
+    return {
+      name: app.name,
+      versionId: ver ? String(ver.id) : null,
+      version: ver ? ver.version : null,
+      hasSchema: !!schema,
+      valid: !!schema && errorMap.size === 0,
+      declared,
+      others
+    };
+  };
+
+  const startProcess = async (app, { env: preparedEnv } = {}) => {
+    const version = await models.appVersion.findByPk(app.currentVersionId);
+    if (!version) {
+      throw new Error('current version missing');
     }
+    const serverDir = path.join(version.artifactPath, 'server');
+    const env = preparedEnv || (await buildProcessEnv(app, version));
+    await assertEnvValid(app, version, env);
+    const { outFile, errFile } = await ensureLogFiles(app.rootPath);
 
     const pathBase = mountPrefix(app.name);
     // Domain-first: inject `/` so custom Host SPA works; path mode then relies on gateway rewrite fallback.
@@ -551,7 +814,119 @@ 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,
+          // 老版本可能没有 env.schema.json：照常还原目录，由启动前的环境变量校验给出提示
+          requireEnvSchema: false,
+          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) {
@@ -563,21 +938,42 @@ 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');
+
+    // 变量不合规时不切换版本、不执行迁移、不启动进程
+    step = 'env';
+    progress.report(step, 'running');
+    let processEnv;
+    try {
+      processEnv = await buildProcessEnv(app, ver);
+      await assertEnvValid(app, ver, processEnv);
+    } 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,
@@ -612,25 +1008,39 @@ module.exports = fp(async (fastify, options) => {
         } catch (e) {
           // ignore ownership merge failures
         }
+        progress.report(step, 'done');
+      } else {
+        progress.report(step, 'skipped');
       }
 
       if (runMigration === false) {
         // child may honor RUN_SQL_ON_SYNC
-        app.env = Object.assign({}, app.env, { RUN_SQL_ON_SYNC: 'false' });
+        processEnv.RUN_SQL_ON_SYNC = 'false';
       }
 
+      step = 'start';
+      progress.report(step, 'running');
       const beforeForReady = await snapshotTablesSafe(app);
-      await startProcess(app);
-      scheduleStatusSync(app.id, { beforeTables: beforeForReady });
+      await startProcess(app, { env: processEnv });
+      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);
     }
@@ -647,15 +1057,28 @@ module.exports = fp(async (fastify, options) => {
     return toPublicApp(app);
   };
 
-  const start = async ({ name }) => {
-    const app = await getByName(name);
-    if (!app.currentVersionId) {
+  /** 启动 / 重启前先按 schema 校验，不通过直接报错，不改动正在运行的进程与状态 */
+  const prepareStartEnv = async app => {
+    const version = app.currentVersionId ? await models.appVersion.findByPk(app.currentVersionId) : null;
+    if (!version) {
       httpError(400, 'no version deployed');
     }
+    const env = await buildProcessEnv(app, version);
+    try {
+      await assertEnvValid(app, version, env);
+    } catch (e) {
+      httpError(400, e.message);
+    }
+    return env;
+  };
+
+  const start = async ({ name }) => {
+    const app = await getByName(name);
+    const env = await prepareStartEnv(app);
     await app.update({ status: 'deploying', message: null });
     try {
       const beforeTables = await snapshotTablesSafe(app);
-      await startProcess(app);
+      await startProcess(app, { env });
       scheduleStatusSync(app.id, { beforeTables });
       return toPublicApp(await getByName(name));
     } catch (e) {
@@ -666,6 +1089,7 @@ module.exports = fp(async (fastify, options) => {
 
   const restart = async ({ name }) => {
     const app = await getByName(name);
+    const env = await prepareStartEnv(app);
     await app.update({ status: 'deploying', message: null });
     try {
       const beforeTables = await snapshotTablesSafe(app);
@@ -675,7 +1099,7 @@ module.exports = fp(async (fastify, options) => {
       } catch (e) {
         // ignore if not running
       }
-      await startProcess(app);
+      await startProcess(app, { env });
       scheduleStatusSync(app.id, { beforeTables });
       return toPublicApp(await getByName(name));
     } catch (e) {
@@ -715,6 +1139,7 @@ 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 {
@@ -858,6 +1283,14 @@ module.exports = fp(async (fastify, options) => {
       syncStatus,
       syncAllStatuses,
       remove,
+      resolveVersionPackage,
+      listMissingArtifacts,
+      restoreArtifact,
+      restoreMissingArtifacts,
+      pruneVersionArtifacts,
+      pruneAllVersionArtifacts,
+      getMigrationFiles,
+      saveMigrationFiles,
       logs,
       logFiles,
       resolveAppLogFile,
@@ -865,6 +1298,10 @@ module.exports = fp(async (fastify, options) => {
       removeLogFiles,
       load,
       getLoadStore,
+      getDeployProgress: () => deployProgress,
+      waitDeployProgress: ({ name, progressId, timeoutMs }) => deployProgress.wait(name, progressId, { timeoutMs }),
+      getEnvDeclaration,
+      listInjectedEnvKeys,
       toPublicApp,
       mountPrefix,
       findByHost,