@kne/fastify-app-manager 0.1.5 → 0.1.7

package/README.md

@@ -49,6 +49,7 @@ Client / Admin UI
 | Management API | 创建应用、上传版本、部署、启停、日志；均走 `createAuthenticate` |
 | Domain gateway | Host 精确匹配且状态为 `running` 时透明反代，不改写路径 |
 | Path gateway | `/app/{name}` 剥前缀；改写绝对路径 Location、Cookie Path、文本类 body |
+| 未运行兜底 | 应用存在但未 `running` 时，网关返回 503 状态页（已停止 / 启动中 / 异常 / 未部署），接口请求返回 JSON，不再落到宿主 404；`/app/{name}` 下应用不存在时返回 404「应用不存在」页 |
 | PM2 | 每应用一进程，名 `app-manager__{name}`；stdout/stderr 落 `appsRoot/{name}/logs` |
 | Bootstrap | `onReady` 连接 PM2、挂 log bus；**异步**对托管应用做 `syncAllStatuses`（不阻塞父应用 ready） |
 
@@ -350,6 +351,15 @@ await fastify.listen({ port: 3000 });
 | versionId | string | 否 | - | 版本主键；与 `version` 二选一 |
 | version | string | 否 | - | 版本号 |
 | runMigration | boolean | 否 | `true` | false 时向 app.env 写入 `RUN_SQL_ON_SYNC=false`；预跑 SQL 仍受 `migrateBeforeStart` 约束 |
+| migrations | array | 否 | - | `[{ name, action }]` 逐个指定**待执行**脚本的处理方式；未列出的按 `execute`。仅在 `runMigration` 且 `migrateBeforeStart` 时生效 |
+
+`migrations[].action`：
+
+| 值 | 行为 |
+|----|------|
+| `execute` | 执行脚本并写入 `_fs_sql_migrations` |
+| `skip` | 不执行，只写入执行记录（之后部署和子应用 sync 都不会再执行） |
+| `hold` | 本次不执行也不记账，保持待执行；子应用若启用 `@kne/fastify-sequelize` 的 `runSqlOnSync`，启动时仍可能执行 |
 
 返回示例：
 
@@ -364,6 +374,18 @@ await fastify.listen({ port: 3000 });
 }
 ```
 
+##### 版本迁移脚本管理
+
+管理某版本 `server/{migrationPath}` 下的 `.sql` 文件，执行状态读写应用库的 `_fs_sql_migrations`（与 `@kne/fastify-sequelize` 共用，按文件名记账；共享库中不同应用的同名脚本会互相影响）。文件名须匹配 `[A-Za-z0-9_-.]+\.sql`。
+
+| 方法 | 路径 | 参数 | 说明 |
+|------|------|------|------|
+| GET | `{prefix}/app/version/migration/list` | `name`, `versionId` | 脚本列表：`name`、`size`、`updatedAt`、`executed`、`executedAt`；另返回 `migrateBeforeStart`，库连接失败时 `dbError` 有值且 `executed` 为 null |
+| GET | `{prefix}/app/version/migration/content` | `name`, `versionId`, `file` | 返回 `{ name, content }` |
+| POST | `{prefix}/app/version/migration/save` | `name`, `versionId`, `file`, `content` | 新增或覆盖脚本文件，并同步版本 `hasMigration` |
+| POST | `{prefix}/app/version/migration/remove` | `name`, `versionId`, `file` | 删除脚本文件（不改执行记录），并同步 `hasMigration` |
+| POST | `{prefix}/app/version/migration/action` | `name`, `versionId`, `file`, `action` | `execute` 立即执行并记账（执行后按表差异合并归属表）；`mark` 只记账；`unmark` 删除执行记录 |
+
 ##### GET `{prefix}/app/list`
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
@@ -449,14 +471,14 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 | `detail({ name })` | 详情（脱敏） |
 | `uploadVersion({ name, version, label, zipBuffer })` | 上传版本 |
 | `listVersions({ name, perPage, currentPage })` | 版本列表 |
-| `deploy({ name, versionId, version, runMigration })` | 部署；立即 `deploying`，后台 `syncRealStatus` |
+| `deploy({ name, versionId, version, runMigration, migrations? })` | 部署；立即 `deploying`，后台 `syncRealStatus` |
 | `start` / `stop` / `restart` | 生命周期；`start`/`restart` 立即 `deploying`，后台按 PM2+health 写回真实状态 |
 | `syncStatus({ name, recoverIfMissing? })` | 同步单个应用真实状态并返回公开对象 |
 | `syncAllStatuses({ recoverIfMissing? })` | 批量同步（父应用启动 reconcile 使用） |
 | `remove({ name, exportBeforeRemove?, cleanupData?, ... })` | 删除；默认可导出+清理所属表 |
 | `logs({ name, stream, perPage, currentPage })` | 读日志文件 |
-| `findByHost(host)` | 网关：按 domain + `running` 查找 |
-| `findByPathName(name)` | 网关：按 name + `running` 查找 |
+| `findByHost(host, { running? })` | 网关：按 domain 查找；默认只查 `running`，`running: false` 时不限状态 |
+| `findByPathName(name, { running? })` | 网关：按 name 查找；默认只查 `running`，`running: false` 时不限状态 |
 | `appendAppLog(appName, stream, content)` | 追加日志并 emit hub 事件 |
 | `readLastLines(name, stream, n)` | SSE 回放用 |
 | `getLogHub()` | 获取 EventEmitter |
@@ -471,6 +493,16 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 | `runQuery({ name, sql, replacements? })` | 只读 SQL |
 | `exportData` / `cleanup` | 导出与清理 |
 
+##### services.migration
+
+| 方法签名 | 说明 |
+|----------|------|
+| `list({ name, versionId })` | 版本脚本及执行状态 |
+| `content({ name, versionId, file })` | 读脚本内容 |
+| `save({ name, versionId, file, content })` / `remove({ name, versionId, file })` | 新增覆盖 / 删除脚本文件 |
+| `execute` / `mark` / `unmark`（`{ name, versionId, file }`） | 执行并记账 / 只记账 / 删除记录 |
+| `action({ name, versionId, file, action })` | 按 `action` 分发到上面三个方法 |
+
 ##### services.bootstrap
 
 | 方法签名 | 说明 |
@@ -526,6 +558,8 @@ data: {"appName":"demo","stream":"out","content":"...","line":1}
 | 机制 | 说明 |
 |------|------|
 | 路由优先级 | 管理 API（`prefix`）不进网关；先 domain 匹配，再 path 前缀匹配 |
+| 应用未运行 | 命中已存在但非 `running` 的应用时返回 503（`Cache-Control: no-store`、`Retry-After`）：浏览器 `GET`/`HEAD` 且 `Accept` 含 `text/html` 返回状态说明页（`deploying` 每 5 秒自动刷新），其余请求返回 JSON `{ statusCode, error, message, appName, appStatus }` |
+| 应用不存在 | `/app/{name}` 下找不到应用时返回 404「应用不存在」页（带返回首页）或 JSON（`appStatus: 'missing'`）；`pathPrefix` 之外以及未绑定的域名仍交给宿主路由 |
 | Location | 相对路径前缀补上 `/app/{name}` |
 | Set-Cookie | `Path=/` 改为 `Path=/app/{name}` |
 | Body | 对文本类 Content-Type，将 `"/static/`、`"/api/`、`"/account/` 等前缀改写；有 `content-encoding` 时跳过 |

package/libs/controllers/app.js

@@ -139,7 +139,19 @@ module.exports = fp(async (fastify, options) => {
             name: { type: 'string' },
             versionId: { type: 'string' },
             version: { type: 'string' },
-            runMigration: { type: 'boolean', default: true }
+            runMigration: { type: 'boolean', default: true },
+            migrations: {
+              type: 'array',
+              description: '逐个指定待执行脚本的处理方式；未列出的待执行脚本按 execute 处理',
+              items: {
+                type: 'object',
+                required: ['name', 'action'],
+                properties: {
+                  name: { type: 'string' },
+                  action: { type: 'string', enum: ['execute', 'skip', 'hold'] }
+                }
+              }
+            }
           }
         }
       }

package/libs/controllers/gateway.js

@@ -1,5 +1,7 @@
 const fp = require('fastify-plugin');
+const { Readable } = require('node:stream');
 const { rewriteLocation, rewriteSetCookiePath, shouldRewriteBody, rewriteBody } = require('../utils/pathRewrite');
+const { wantsHtml, renderUnavailablePage, getStatusText } = require('../utils/unavailablePage');
 
 module.exports = fp(async (fastify, options) => {
   const ns = options.name;
@@ -20,6 +22,12 @@ module.exports = fp(async (fastify, options) => {
     const dest = `http://127.0.0.1:${app.port}${targetPath}`;
     const mountPrefix = `${pathPrefix}/${app.name}`;
 
+    // The gateway runs in onRequest, before body parsing; reply-from only forwards request.body,
+    // so hand it the raw stream or POST/PUT bodies reach the app empty.
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      request.body = request.raw;
+    }
+
     return reply.from(dest, {
       rewriteRequestHeaders: (req, headers) => {
         const next = { ...headers };
@@ -51,13 +59,43 @@ module.exports = fp(async (fastify, options) => {
           }
           const buf = Buffer.concat(chunks.map(c => (Buffer.isBuffer(c) ? c : Buffer.from(c))));
           const text = rewriteBody(buf.toString('utf8'), mountPrefix);
-          return reply.send(text);
+          // A stream payload keeps host onSend hooks that wrap string bodies (e.g. response envelopes) from altering app responses.
+          return reply.send(Readable.from([Buffer.from(text)], { objectMode: false }));
         }
         return reply.send(res.stream);
       }
     });
   };
 
+  // Not running (503) or unknown under the path prefix (404): answer here instead of falling through to the host's 404.
+  const replyUnavailable = (request, reply, app) => {
+    const missing = app.status === 'missing';
+    const statusCode = missing ? 404 : 503;
+    reply.code(statusCode).header('cache-control', 'no-store');
+    if (!missing) {
+      reply.header('retry-after', app.status === 'deploying' ? '5' : '60');
+    }
+    if (wantsHtml(request)) {
+      return reply.type('text/html; charset=utf-8').send(Readable.from([Buffer.from(renderUnavailablePage(app))], { objectMode: false }));
+    }
+    const payload = {
+      statusCode,
+      error: missing ? 'Not Found' : 'Service Unavailable',
+      message: getStatusText(app.status).title,
+      appName: app.name,
+      appStatus: app.status
+    };
+    return reply.type('application/json; charset=utf-8').send(Readable.from([Buffer.from(JSON.stringify(payload))], { objectMode: false }));
+  };
+
+  const decodeName = raw => {
+    try {
+      return decodeURIComponent(raw);
+    } catch (e) {
+      return raw;
+    }
+  };
+
   // Domain + path gateway: run early, but skip management API and let other routes try first for non-matches.
   fastify.addHook('onRequest', async (request, reply) => {
     const url = request.raw.url || '';
@@ -71,18 +109,19 @@ module.exports = fp(async (fastify, options) => {
     }
 
     const host = request.headers.host;
-    const byHost = await services.app.findByHost(host);
+    const byHost = await services.app.findByHost(host, { running: false });
     if (byHost) {
-      return proxyToApp(request, reply, byHost, { stripPrefix: false });
+      return byHost.status === 'running' ? proxyToApp(request, reply, byHost, { stripPrefix: false }) : replyUnavailable(request, reply, byHost);
     }
 
     const match = url.match(new RegExp(`^${pathPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/?#]+)`));
     if (match) {
-      const appName = match[1];
-      const app = await services.app.findByPathName(appName);
+      const appName = decodeName(match[1]);
+      const app = await services.app.findByPathName(appName, { running: false });
       if (app) {
-        return proxyToApp(request, reply, app, { stripPrefix: true });
+        return app.status === 'running' ? proxyToApp(request, reply, app, { stripPrefix: true }) : replyUnavailable(request, reply, app);
       }
+      return replyUnavailable(request, reply, { name: appName, status: 'missing' });
     }
   });
 });

package/libs/controllers/migration.js

@@ -0,0 +1,97 @@
+const fp = require('fastify-plugin');
+
+module.exports = fp(async (fastify, options) => {
+  const { services } = fastify[options.name];
+  const auth = () => options.createAuthenticate();
+
+  const versionProps = {
+    name: { type: 'string' },
+    versionId: { type: 'string' }
+  };
+
+  fastify.get(
+    `${options.prefix}/app/version/migration/list`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '版本迁移脚本列表（含执行状态）',
+        query: {
+          type: 'object',
+          required: ['name', 'versionId'],
+          properties: versionProps
+        }
+      }
+    },
+    async request => services.migration.list(request.query)
+  );
+
+  fastify.get(
+    `${options.prefix}/app/version/migration/content`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '读取迁移脚本内容',
+        query: {
+          type: 'object',
+          required: ['name', 'versionId', 'file'],
+          properties: Object.assign({}, versionProps, { file: { type: 'string' } })
+        }
+      }
+    },
+    async request => services.migration.content(request.query)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/version/migration/save`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '新增或覆盖迁移脚本',
+        body: {
+          type: 'object',
+          required: ['name', 'versionId', 'file', 'content'],
+          properties: Object.assign({}, versionProps, {
+            file: { type: 'string' },
+            content: { type: 'string' }
+          })
+        }
+      }
+    },
+    async request => services.migration.save(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/version/migration/remove`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '删除迁移脚本文件（不改执行记录）',
+        body: {
+          type: 'object',
+          required: ['name', 'versionId', 'file'],
+          properties: Object.assign({}, versionProps, { file: { type: 'string' } })
+        }
+      }
+    },
+    async request => services.migration.remove(request.body)
+  );
+
+  fastify.post(
+    `${options.prefix}/app/version/migration/action`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '执行 / 标记已执行 / 撤销执行记录',
+        body: {
+          type: 'object',
+          required: ['name', 'versionId', 'file', 'action'],
+          properties: Object.assign({}, versionProps, {
+            file: { type: 'string' },
+            action: { type: 'string', enum: ['execute', 'mark', 'unmark'] }
+          })
+        }
+      }
+    },
+    async request => services.migration.action(request.body)
+  );
+});

package/libs/services/app.js

@@ -7,7 +7,7 @@ const { mergeEnv, maskEnvForResponse, applyEnvPatch, mergePm2Config, normalizeSe
 const { prepareVersionArtifact } = require('../utils/version');
 const { injectEntryHtml } = require('../utils/entryInject');
 const { ensureLogFiles, readLogTail, readLastLines, appendLog } = require('../utils/logFiles');
-const { runSqlMigrations } = require('../utils/migrate');
+const { runSqlMigrations, MIGRATION_ACTIONS } = require('../utils/migrate');
 const { listSqlFiles } = require('../utils/validatePackage');
 const pm2Util = require('../utils/pm2');
 
@@ -458,7 +458,7 @@ module.exports = fp(async (fastify, options) => {
     });
   };
 
-  const deploy = async ({ name, versionId, version, runMigration = true }) => {
+  const deploy = async ({ name, versionId, version, runMigration = true, migrations }) => {
     const app = await getByName(name);
     let ver = null;
     if (versionId) {
@@ -499,11 +499,18 @@ module.exports = fp(async (fastify, options) => {
         } catch (e) {
           beforeTables = [];
         }
+        const actions = {};
+        for (const item of Array.isArray(migrations) ? migrations : []) {
+          if (item?.name && MIGRATION_ACTIONS.includes(item.action)) {
+            actions[item.name] = item.action;
+          }
+        }
         await runSqlMigrations({
           serverDir: path.join(ver.artifactPath, 'server'),
           sqlPath: ver.migrationPath || options.sqlPath,
           env,
-          Sequelize: fastify.sequelize.Sequelize
+          Sequelize: fastify.sequelize.Sequelize,
+          actions
         });
         try {
           const afterTables = await dbops.withSequelize(app, async sequelize => dbops.listAllTables(sequelize));
@@ -628,16 +635,16 @@ module.exports = fp(async (fastify, options) => {
     return readLogTail(file, { perPage, currentPage, beforeLine });
   };
 
-  const findByHost = async host => {
+  const findByHost = async (host, { running = true } = {}) => {
     if (!host) {
       return null;
     }
     const hostname = String(host).split(':')[0].toLowerCase();
-    return models.app.findOne({ where: { domain: hostname, status: 'running' } });
+    return models.app.findOne({ where: Object.assign({ domain: hostname }, running ? { status: 'running' } : {}) });
   };
 
-  const findByPathName = async name => {
-    return models.app.findOne({ where: { name, status: 'running' } });
+  const findByPathName = async (name, { running = true } = {}) => {
+    return models.app.findOne({ where: Object.assign({ name }, running ? { status: 'running' } : {}) });
   };
 
   Object.assign(fastify[options.name].services, {

package/libs/services/migration.js

@@ -0,0 +1,166 @@
+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 httpError = (statusCode, message) => {
+    if (fastify.httpErrors) {
+      if (statusCode === 404) throw fastify.httpErrors.notFound(message);
+      if (statusCode === 400) throw fastify.httpErrors.badRequest(message);
+    }
+    const err = new Error(message);
+    err.statusCode = statusCode;
+    throw err;
+  };
+
+  const resolveVersion = async ({ name, versionId }) => {
+    const app = await models.app.findOne({ where: { name } });
+    if (!app) {
+      httpError(404, `app ${name} not found`);
+    }
+    const ver = versionId ? await models.appVersion.findByPk(versionId) : null;
+    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 };
+  };
+
+  const assertFileName = file => {
+    if (!isValidSqlFileName(file)) {
+      httpError(400, 'invalid sql file name: use [A-Za-z0-9_-.] and end with .sql');
+    }
+  };
+
+  const assertFileExists = async (sqlDir, file) => {
+    assertFileName(file);
+    const filePath = path.join(sqlDir, file);
+    if (!(await fs.pathExists(filePath))) {
+      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 });
+    }
+  };
+
+  const list = async ({ name, versionId }) => {
+    const { app, ver, sqlDir } = await resolveVersion({ name, versionId });
+    const files = await listSqlFiles(sqlDir);
+    let executedMap = new Map();
+    let dbError = null;
+    try {
+      executedMap = await getDbops().withSequelize(app, sequelize => readExecutedMigrations(sequelize));
+    } 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
+        };
+      })
+    );
+    return {
+      versionId: String(ver.id),
+      version: ver.version,
+      migrationPath: ver.migrationPath || options.sqlPath,
+      migrateBeforeStart: !!options.migrateBeforeStart,
+      dbError,
+      pageData,
+      totalCount: pageData.length
+    };
+  };
+
+  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 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);
+    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);
+    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 dbops = getDbops();
+    let beforeTables = [];
+    let afterTables = [];
+    await dbops.withSequelize(app, async sequelize => {
+      beforeTables = await dbops.listAllTables(sequelize).catch(() => []);
+      await sequelize.query(sql);
+      await recordMigration(sequelize, file);
+      afterTables = await dbops.listAllTables(sequelize).catch(() => []);
+    });
+    try {
+      await dbops.mergeOwnedTablesFromDiff(app, beforeTables, afterTables);
+    } catch (e) {
+      fastify.log.warn({ err: e, app: name, file }, 'merge owned tables after migration failed');
+    }
+    return { name: file, executed: true };
+  };
+
+  const mark = async ({ name, versionId, file }) => {
+    const { app, sqlDir } = await resolveVersion({ name, versionId });
+    await assertFileExists(sqlDir, file);
+    await getDbops().withSequelize(app, sequelize => recordMigration(sequelize, file));
+    return { name: file, executed: true };
+  };
+
+  const unmark = async ({ name, versionId, file }) => {
+    assertFileName(file);
+    const { app } = await resolveVersion({ name, versionId });
+    await getDbops().withSequelize(app, sequelize => removeMigrationRecord(sequelize, file));
+    return { name: file, executed: false };
+  };
+
+  const action = async ({ action: type, ...props }) => {
+    if (type === 'execute') return execute(props);
+    if (type === 'mark') return mark(props);
+    if (type === 'unmark') return unmark(props);
+    httpError(400, `unknown action ${type}`);
+  };
+
+  Object.assign(fastify[options.name].services, {
+    migration: {
+      list,
+      content,
+      save,
+      remove,
+      execute,
+      mark,
+      unmark,
+      action
+    }
+  });
+});

package/libs/utils/migrate.js

@@ -3,44 +3,80 @@ const fs = require('fs-extra');
 const { listSqlFiles } = require('./validatePackage');
 
 const SQL_MIGRATIONS_TABLE = '_fs_sql_migrations';
+const MIGRATION_ACTIONS = ['execute', 'skip', 'hold'];
+const SQL_FILE_NAME_RE = /^[A-Za-z0-9_\-.]+\.sql$/;
+
+const isValidSqlFileName = name => typeof name === 'string' && SQL_FILE_NAME_RE.test(name) && !name.includes('..');
+
+const ensureMigrationsTable = sequelize =>
+  // TIMESTAMP is portable across sqlite / postgres / mysql (avoid DATETIME — missing on PG)
+  sequelize.query(
+    `CREATE TABLE IF NOT EXISTS ${SQL_MIGRATIONS_TABLE} (
+        name VARCHAR(255) PRIMARY KEY,
+        executed_at TIMESTAMP
+      )`
+  );
+
+const readExecutedMigrations = async sequelize => {
+  await ensureMigrationsTable(sequelize);
+  const [rows] = await sequelize.query(`SELECT name, executed_at FROM ${SQL_MIGRATIONS_TABLE}`);
+  return new Map((rows || []).map(r => [r.name, r.executed_at || null]));
+};
+
+const recordMigration = async (sequelize, name) => {
+  await ensureMigrationsTable(sequelize);
+  await sequelize.query(`DELETE FROM ${SQL_MIGRATIONS_TABLE} WHERE name = ?`, { replacements: [name] });
+  await sequelize.query(`INSERT INTO ${SQL_MIGRATIONS_TABLE} (name, executed_at) VALUES (?, ?)`, {
+    replacements: [name, new Date().toISOString()]
+  });
+};
+
+const removeMigrationRecord = async (sequelize, name) => {
+  await ensureMigrationsTable(sequelize);
+  await sequelize.query(`DELETE FROM ${SQL_MIGRATIONS_TABLE} WHERE name = ?`, { replacements: [name] });
+};
 
 /**
  * Run .sql files under server/{sqlPath} with the same tracking semantics as @kne/fastify-sequelize.
+ * actions: { [file]: 'execute' | 'skip' | 'hold' } for pending files; missing entries default to 'execute'.
+ * skip records the file as executed without running it (so the child app won't run it on sync either);
+ * hold leaves it pending.
  */
-const runSqlMigrations = async ({ serverDir, sqlPath = 'sql', env = {}, Sequelize: SequelizeCtor } = {}) => {
+const runSqlMigrations = async ({ serverDir, sqlPath = 'sql', env = {}, Sequelize: SequelizeCtor, actions = {} } = {}) => {
   const sqlDir = path.join(serverDir, sqlPath);
   const files = await listSqlFiles(sqlDir);
   if (!files.length) {
-    return { executed: [], skipped: true };
+    return { executed: [], marked: [], held: [], skipped: true };
   }
 
   const sequelize = createSequelizeFromEnv(env, SequelizeCtor);
   try {
     await sequelize.authenticate();
-    // TIMESTAMP is portable across sqlite / postgres / mysql (avoid DATETIME — missing on PG)
-    await sequelize.query(
-      `CREATE TABLE IF NOT EXISTS ${SQL_MIGRATIONS_TABLE} (
-        name VARCHAR(255) PRIMARY KEY,
-        executed_at TIMESTAMP
-      )`
-    );
-
-    const [rows] = await sequelize.query(`SELECT name FROM ${SQL_MIGRATIONS_TABLE}`);
-    const done = new Set((rows || []).map(r => r.name));
+    const done = await readExecutedMigrations(sequelize);
     const executed = [];
+    const marked = [];
+    const held = [];
 
     for (const file of files) {
       if (done.has(file)) {
         continue;
       }
+      const action = actions[file] || 'execute';
+      if (action === 'hold') {
+        held.push(file);
+        continue;
+      }
+      if (action === 'skip') {
+        await recordMigration(sequelize, file);
+        marked.push(file);
+        continue;
+      }
       const sql = await fs.readFile(path.join(sqlDir, file), 'utf8');
       await sequelize.query(sql);
-      await sequelize.query(`INSERT INTO ${SQL_MIGRATIONS_TABLE} (name, executed_at) VALUES (?, ?)`, {
-        replacements: [file, new Date().toISOString()]
-      });
+      await recordMigration(sequelize, file);
       executed.push(file);
     }
-    return { executed, skipped: false };
+    return { executed, marked, held, skipped: false };
   } finally {
     await sequelize.close();
   }
@@ -70,6 +106,12 @@ const createSequelizeFromEnv = (env, SequelizeCtor) => {
 
 module.exports = {
   SQL_MIGRATIONS_TABLE,
+  MIGRATION_ACTIONS,
+  isValidSqlFileName,
+  ensureMigrationsTable,
+  readExecutedMigrations,
+  recordMigration,
+  removeMigrationRecord,
   runSqlMigrations,
   createSequelizeFromEnv
 };

package/libs/utils/unavailablePage.js

@@ -0,0 +1,77 @@
+const STATUS_TEXT = {
+  stopped: { title: '应用已停止', desc: '该应用当前处于停止状态，请联系管理员启动后再访问。' },
+  deploying: { title: '应用正在启动', desc: '应用正在部署或启动中，页面将自动刷新。' },
+  error: { title: '应用运行异常', desc: '应用启动失败或运行异常，请联系管理员处理。' },
+  idle: { title: '应用尚未部署', desc: '该应用还没有部署任何版本，请联系管理员部署后再访问。' },
+  missing: { title: '应用不存在', desc: '没有找到这个应用，请检查访问地址是否正确。' }
+};
+
+const STATUS_COLOR = {
+  deploying: { background: '#e6f4ff', color: '#1677ff' },
+  error: { background: '#fff1f0', color: '#f5222d' },
+  missing: { background: '#f2f3f5', color: '#8f959e' },
+  default: { background: '#fff7e6', color: '#fa8c16' }
+};
+
+const escapeHtml = value => String(value == null ? '' : value).replace(/[&<>"']/g, ch => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+
+const getStatusText = status => STATUS_TEXT[status] || STATUS_TEXT.stopped;
+
+const wantsHtml = request => {
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return false;
+  }
+  if (request.headers['x-requested-with']) {
+    return false;
+  }
+  return String(request.headers.accept || '').includes('text/html');
+};
+
+/** app: { name, label?, status } — status `missing` renders the not-found variant. */
+const renderUnavailablePage = app => {
+  const { title, desc } = getStatusText(app.status);
+  const { background, color } = STATUS_COLOR[app.status] || STATUS_COLOR.default;
+  const label = escapeHtml(app.label || app.name);
+  const autoRefresh = app.status === 'deploying' ? '<meta http-equiv="refresh" content="5">' : '';
+  const action = app.status === 'missing' ? `<a class="btn" href="/">返回首页</a>` : `<button type="button" class="btn" onclick="location.reload()">刷新页面</button>`;
+  return `<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${autoRefresh}
+<title>${escapeHtml(title)} - ${label}</title>
+<style>
+  * { box-sizing: border-box; }
+  body { margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; padding: 24px;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+    background: #f5f7fa; color: #1f2329; }
+  .card { width: 100%; max-width: 440px; padding: 40px 32px; text-align: center; background: #fff; border-radius: 12px;
+    box-shadow: 0 4px 24px rgba(31, 35, 41, 0.08); }
+  .icon { width: 56px; height: 56px; margin: 0 auto 20px; border-radius: 50%; display: flex; align-items: center; justify-content: center;
+    background: ${background}; color: ${color}; font-size: 28px; font-weight: 600; }
+  h1 { margin: 0 0 8px; font-size: 20px; font-weight: 600; }
+  .app { margin: 0 0 16px; color: #646a73; font-size: 14px; word-break: break-all; }
+  .desc { margin: 0 0 28px; color: #8f959e; font-size: 14px; line-height: 1.7; }
+  .btn { display: inline-block; padding: 8px 24px; border: 0; border-radius: 6px; background: #1677ff; color: #fff; font-size: 14px;
+    text-decoration: none; cursor: pointer; }
+  .btn:hover { background: #4096ff; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div class="icon">${app.status === 'deploying' ? '&#8635;' : app.status === 'missing' ? '?' : '!'}</div>
+    <h1>${escapeHtml(title)}</h1>
+    <p class="app">${label}</p>
+    <p class="desc">${escapeHtml(desc)}</p>
+    ${action}
+  </div>
+</body>
+</html>`;
+};
+
+module.exports = {
+  getStatusText,
+  wantsHtml,
+  renderUnavailablePage
+};

package/package.json

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