@kne/fastify-app-manager 0.1.10 → 0.1.11

package/README.md

@@ -51,18 +51,20 @@ Client / Admin UI
 | Path gateway | `/app/{name}` 剥前缀；改写绝对路径 Location、Cookie Path、文本类 body |
 | 未运行兜底 | 应用存在但未 `running` 时，网关返回 503 状态页（已停止 / 启动中 / 异常 / 未部署），接口请求返回 JSON，不再落到宿主 404；`/app/{name}` 下应用不存在时返回 404「应用不存在」页 |
 | PM2 | 每应用一进程，名 `app-manager__{name}`；stdout/stderr 由 PM2 落 `appsRoot/{name}/logs`，插件按大小/按天切分归档 |
-| Bootstrap | `onReady` 连接 PM2、挂 log bus（只推 SSE）、启动日志切分与负载采样定时器；**异步**对托管应用做 `syncAllStatuses`（不阻塞父应用 ready） |
+| Bootstrap | `onReady` 连接 PM2、挂 log bus（只推 SSE）、启动日志切分与负载采样定时器；**异步**并行：目录完好的托管应用立即 `syncAllStatuses`，缺当前版本目录的应用按版本 `fileId` 逐个补回后再单独拉起，最后清理非当前版本目录（均不阻塞父应用 ready） |
 
 ##### 部署时序
 
 ```
-uploadVersion (zip)
+uploadVersion (zip / fileId)
        ↓
- 校验包格式 → 解压 → npm install --production（server）
+ 校验包格式 → SQL 写入版本记录；multipart 解压并 npm install 后保留目录，fileId 不保留目录
        ↓
 deploy(versionId)
        ↓
- status=deploying → 可选 SQL 迁移 → inject entryHtml → pm2.start
+ 目录缺失则按 fileId 解压 + npm install → 数据库 SQL 覆盖写回
+       ↓
+ status=deploying → 可选 SQL 迁移 → inject entryHtml → pm2.start → 清理其它版本目录
        ↓（立即返回）
  后台 healthCheck → running / error
 ```
@@ -74,7 +76,7 @@ deploy(versionId)
 | 概念 | 说明 |
 |------|------|
 | **App** | 元信息、分配端口、env、pm2Config、状态机；落盘目录 `appsRoot/{name}` |
-| **AppVersion** | 一次 zip 上传产物；`artifactPath` 存解压后的包；部署时按 id 或 version 选择 |
+| **AppVersion** | 一次 zip 上传产物；`artifactPath` 为解压目录（有 `fileId` 的版本只在当前部署时常驻磁盘），SQL 脚本存于 `migrationFiles`；部署时按 id 或 version 选择 |
 | **端口池** | 默认 `4000–7999`，创建时分配未占用端口；`PORT` 强制写入子进程 env |
 
 ##### 状态机
@@ -120,6 +122,7 @@ deploy(versionId)
 |------|------|
 | 版本上传 | Zip Slip 防护、条目数/体积上限、解压丢弃任意层级 `node_modules`、Fullstack 包格式校验、server 生产依赖安装 |
 | 短部署 | `deploy` / `start` / `restart` 立即返回 `deploying`，后台按 PM2 真实状态 + healthCheck 写回 `running`/`error`/`stopped` |
+| 部署进度 | `deploy` 按「准备部署包 → SQL 迁移 → 启动进程 → 等待就绪」上报阶段，经 `GET .../app/deploy/stream` SSE 推送（含下载 / 解压 / 安装依赖等子阶段） |
 | 生命周期 | `start` / `stop` / `restart` / `remove`；父应用重启后异步 `syncAllStatuses` 对齐 PM2 |
 | 双通道访问 | 自定义域名透明反代 + `/app/{name}` 剥前缀反代 |
 | 日志 | PM2 落盘 + 历史分页（`beforeLine` 上滚、每页最多 100 行）+ SSE（含回放行与心跳） |
@@ -194,6 +197,7 @@ await fastify.listen({ port: 3000 });
 | `systemEnvKeys` | array | 否 | `[]` | 宿主维护的系统变量键名，与内置 `DB_TABLE_PREFIX` 合并：接口不返回，create / save / saveEnv 不可新增、修改或删除 |
 | `resolveSystemEnv` | function | 否 | `null` | `async ({ app, version, serverDir }) => env \| null`，每次启动进程（deploy / start / restart / 恢复）前调用；返回值覆盖应用变量注入子进程，值为 `null` / `undefined` 的键忽略，属于 `systemEnvKeys` 的键持久化到 `app.env` |
 | `onAppRemoved` | function | 否 | `null` | `async ({ app }) => void`，应用删除成功后调用，`app` 为删除前快照（含 `env`）；数据清理未完成而未删除时不调用，钩子报错只记 warn 日志 |
+| `resolveVersionFile` | function | 否 | `null` | `async ({ fileId, name, version, request }) => Buffer`，版本上传传 `fileId`（而非 multipart 文件）时调用，返回 zip 内容；未配置时传 `fileId` 返回 400。版本记录保存 `fileId`；这类版本只在当前部署时常驻磁盘，部署非当前版本或启动时当前版本目录缺失会再次调用以重建 |
 | `defaultAppDb` | object | 否 | `appsRoot/_shared/apps-data.sqlite` | 托管应用默认库（须与宿主主库分离） |
 | `dbQueryMaxRows` | number | 否 | `500` | 只读 query SQL 最大返回行数 |
 | `pm2Defaults` | object | 否 | 见下表 | 全局 PM2 默认；可被应用 `pm2Config` 覆盖 |
@@ -323,16 +327,17 @@ await fastify.listen({ port: 3000 });
 
 ##### POST `{prefix}/app/version/upload`
 
-`multipart/form-data` 上传 zip。
+`multipart/form-data` 上传 zip；或 JSON 传 `fileId`，由 `resolveVersionFile` 读取宿主文件（如文件管理中已上传的 zip）。
 
 | 字段名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
-| file | file | 是 | zip 二进制（字段名任意 file part） |
+| file | file | 否 | zip 二进制（字段名任意 file part）；与 `fileId` 二选一，同时存在时以 `file` 为准 |
+| fileId | string | 否 | 宿主文件 id，交给 `resolveVersionFile` 读取；与 `file` 二选一 |
 | name | string | 是 | 应用 slug（须已 create） |
 | version | string | 是 | 版本号；同应用内唯一 |
 | label | string | 否 | 版本说明 |
 
-成功返回 `appVersion` 记录（含 `artifactPath`、`hasMigration` 等）。包在临时目录完成解压、校验与 `npm install` 后才写入版本表，上传中或失败的包不会出现在版本列表；包非法或 npm 失败时清理临时目录并返回 400。版本号已存在返回 409；同版本号仅残留软删除记录时会先彻底清除再写入。
+成功返回 `appVersion` 记录（含 `artifactPath`、`hasMigration`、`fileId`、`sqlFiles` 等）。包中 `server/{sqlPath}/*.sql` 的内容写入版本记录（数据库）。传 `fileId` 时只解压校验、不装依赖，也不保留版本目录（部署时再从宿主文件解压）；multipart 上传无处重建，解压并 `npm install` 后保留目录。包在临时目录处理完才写入版本表，上传中或失败的包不会出现在版本列表；包非法或 npm 失败时清理临时目录并返回 400。版本号已存在返回 409；同版本号仅残留软删除记录时会先彻底清除再写入。
 
 ##### GET `{prefix}/app/version/list`
 
@@ -361,9 +366,20 @@ await fastify.listen({ port: 3000 });
 
 `hasMigration` 为 true 时额外附带 `sqlFiles` 列表。
 
+##### GET `{prefix}/app/version/download`
+
+下载版本部署包，文件名 `{name}-{version}.zip`。
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| name | string | 是 | 应用 slug |
+| versionId | string | 是 | 版本 id；不属于该应用返回 404 |
+
+版本有 `fileId` 且配置了 `resolveVersionFile` 时返回原始 zip；否则（或读取失败时）由版本目录流式打包，排除部署时生成的 `server/node_modules` 与 `server/build`。版本目录也不存在时返回 404。
+
 ##### POST `{prefix}/app/deploy`
 
-选择版本部署。立即返回 `deploying`，后台做健康检查。
+选择版本部署。版本目录不在磁盘时先经 `resolveVersionFile` 取回 zip 解压并 `npm install`（耗时，取不回返回 400 且不改应用状态），再以数据库中的 SQL 覆盖目录内 `.sql`；随后立即返回 `deploying`，后台做健康检查。进程启动后删除该应用其它有 `fileId` 的版本目录（只保留当前版本）。
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -372,6 +388,7 @@ await fastify.listen({ port: 3000 });
 | version | string | 否 | - | 版本号 |
 | runMigration | boolean | 否 | `true` | false 时向 app.env 写入 `RUN_SQL_ON_SYNC=false`；预跑 SQL 仍受 `migrateBeforeStart` 约束 |
 | migrations | array | 否 | - | `[{ name, action }]` 逐个指定**待执行**脚本的处理方式；未列出的按 `execute`。仅在 `runMigration` 且 `migrateBeforeStart` 时生效 |
+| progressId | string | 否 | 随机 UUID | 进度标识；前端先用它连 `GET .../app/deploy/stream` 再发起部署，可收到完整进度 |
 
 `migrations[].action`：
 
@@ -388,15 +405,47 @@ await fastify.listen({ port: 3000 });
   "name": "demo",
   "status": "deploying",
   "versionId": "354173577374729216",
+  "progressId": "c0a8...",
   "port": 4001,
   "pathUrl": "/app/demo/",
   "domain": null
 }
 ```
 
+##### GET `{prefix}/app/deploy/stream`
+
+SSE 部署进度。连接时先推送 `snapshot`（该应用最近一次部署中匹配 `progressId` 的已有事件，便于断线重连），之后每个阶段变化推送 `progress`。每个应用只在内存中保留最近一次部署的事件。
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| name | string | 是 | 应用 slug |
+| progressId | string | 否 | 只推送该次部署的事件；不传则推送该应用所有部署事件 |
+
+阶段（`steps`，依次推进）：
+
+| step | 说明 | `detail`（`status=running` 时） |
+|------|------|------|
+| `package` | 准备版本目录 | `reuse` 目录已在磁盘 / `download` 取回 zip / `extract` 解压 / `install` 安装依赖 |
+| `migrate` | 预跑 SQL 迁移；未开启 `runMigration`、`migrateBeforeStart` 或版本无脚本时为 `skipped` | - |
+| `start` | PM2 拉起进程 | - |
+| `ready` | 健康检查；通过为 `done`，否则 `error`（`message` 为原因，如 `health check timeout`） | - |
+
+`status`：`running` / `done` / `skipped` / `error`。任一阶段 `error` 即部署失败；`ready` 为 `done` / `error` 时部署结束，前端可断开连接。
+
+```text
+event: snapshot
+data: {"steps":["package","migrate","start","ready"],"events":[]}
+
+event: progress
+data: {"progressId":"p-1","step":"package","status":"running","detail":"download","message":null,"at":"2026-10-10T10:00:00.000Z"}
+
+event: progress
+data: {"progressId":"p-1","step":"ready","status":"done","detail":null,"message":null,"at":"2026-10-10T10:00:05.000Z"}
+```
+
 ##### 版本迁移脚本管理
 
-管理某版本 `server/{migrationPath}` 下的 `.sql` 文件，执行状态读写应用库的 `_fs_sql_migrations`（与 `@kne/fastify-sequelize` 共用，按文件名记账；共享库中不同应用的同名脚本会互相影响）。文件名须匹配 `[A-Za-z0-9_-.]+\.sql`。
+管理某版本的 `.sql` 文件。脚本内容存于版本记录（数据库），版本目录不在磁盘时也可查看和编辑；目录在磁盘上（当前版本）时同步写入 `server/{migrationPath}`，部署时以数据库为准覆盖。执行状态读写应用库的 `_fs_sql_migrations`（与 `@kne/fastify-sequelize` 共用，按文件名记账；共享库中不同应用的同名脚本会互相影响）。文件名须匹配 `[A-Za-z0-9_-.]+\.sql`。
 
 | 方法 | 路径 | 参数 | 说明 |
 |------|------|------|------|
@@ -627,12 +676,21 @@ data: {"name":"demo","ts":1791456608533,...}
 | `saveEnv({ name, env, secretEnvKeys? })` | 同 save-env |
 | `list({ filter, perPage, currentPage })` | 列表 |
 | `detail({ name })` | 详情（脱敏） |
-| `uploadVersion({ name, version, label, zipBuffer })` | 上传版本 |
+| `uploadVersion({ name, version, label, zipBuffer, fileId? })` | 上传版本；`fileId` 记入版本记录供后续重建 |
+| `resolveVersionPackage({ name, versionId })` | 下载用：返回 `{ fileName, buffer }`（原始 zip）或 `{ fileName, artifactPath, files }`（版本目录内待打包的相对路径） |
+| `getMigrationFiles(ver)` | 读取版本 SQL `[{ name, content, updatedAt }]`；旧版本记录为空时从版本目录回填 |
+| `saveMigrationFiles(ver, files)` | 写入版本 SQL 并同步 `hasMigration`，版本目录在磁盘上时同步覆盖 `.sql` |
+| `pruneVersionArtifacts(app)` | 删除该应用非当前、且有 `fileId` 的版本目录（删前回填 SQL），返回被删版本号 |
+| `pruneAllVersionArtifacts()` | 对所有应用执行 `pruneVersionArtifacts` |
+| `restoreMissingArtifacts()` | 当前版本目录（`artifactPath/server`）缺失时，按版本 `fileId` 经 `resolveVersionFile` 取回 zip 重建并恢复 `current` 链接（不跑 SQL 迁移）；返回 `[{ name, version, action: 'restored' \| 'skipped' \| 'failed', reason? }]`，无 `fileId` 的记 `skipped` |
 | `listVersions({ name, perPage, currentPage })` | 版本列表 |
-| `deploy({ name, versionId, version, runMigration, migrations? })` | 部署；立即 `deploying`，后台 `syncRealStatus` |
+| `deploy({ name, versionId, version, runMigration, migrations?, progressId? })` | 部署；版本目录缺失时先从宿主文件重建，启动后清理其它版本目录；立即 `deploying`，后台 `syncRealStatus`；各阶段进度写入 `getDeployProgress()` |
+| `getDeployProgress()` | 部署进度中心：`emitter`（事件名 `deploy:{name}`）、`snapshot(name)` 返回最近一次部署 `{ progressId, events }` |
 | `start` / `stop` / `restart` | 生命周期；`start`/`restart` 立即 `deploying`，后台按 PM2+health 写回真实状态 |
 | `syncStatus({ name, recoverIfMissing? })` | 同步单个应用真实状态并返回公开对象 |
-| `syncAllStatuses({ recoverIfMissing? })` | 批量同步（父应用启动 reconcile 使用） |
+| `syncAllStatuses({ recoverIfMissing?, excludeIds? })` | 批量同步（父应用启动 reconcile 使用）；`excludeIds` 中的应用跳过 |
+| `listMissingArtifacts()` | 列出当前版本目录（`artifactPath/server`）缺失的应用：`[{ app, ver }]` |
+| `restoreArtifact({ app, ver })` | 补回单个应用的当前版本目录，返回同 `restoreMissingArtifacts` 的单项 |
 | `remove({ name, exportBeforeRemove?, cleanupData?, ... })` | 删除；默认可导出+清理所属表 |
 | `logs({ name, stream, file?, perPage, currentPage, beforeLine? })` | 读当前日志或指定归档 |
 | `logFiles({ name })` | 列出日志文件 |
@@ -672,11 +730,13 @@ data: {"name":"demo","ts":1791456608533,...}
 
 | 方法签名 | 说明 |
 |----------|------|
-| `onReady()` | 连接 PM2、挂 log bus、启动日志切分与负载采样定时器，并 **setImmediate** 异步 `reconcile`、一次 `rotateLogs` 与一次 `sampleLoad`（不阻塞父应用 ready） |
+| `onReady()` | `ensureSchema` 后连接 PM2、挂 log bus、启动日志切分与负载采样定时器，并 **setImmediate** 异步执行 `recoverOnStartup`，以及一次 `rotateLogs` 与一次 `sampleLoad`（不阻塞父应用 ready） |
+| `ensureSchema()` | 宿主 `sync()` 不给已有表加列：为老库补齐后续新增的可空列（当前为 `appVersion.fileId`、`appVersion.migrationFiles`），可重复执行 |
+| `recoverOnStartup()` | 两路并行：部署目录完好的应用立即 `reconcile`；目录缺失的应用逐个 `restoreArtifact`（需重装依赖，较慢），每补完一个即单独 `syncStatus` 并按需拉起；补不回且原为 `running`/`deploying` 的标记 `error`；两路结束后 `pruneAllVersionArtifacts`。返回 `{ reconciled, restored, pruned }` |
 | `onClose()` | 停止切分与采样定时器并等待进行中的任务，断开 bus / PM2（由插件 `onClose` 调用） |
 | `rotateLogs({ now? })` | 立即执行一轮切分 + 压缩 + 保留清理；返回本轮切分的 `[{ name, stream, fileName, reason }]`，`reason` 为 `size` / `daily` |
 | `sampleLoad({ now? })` | 立即采样一轮：每个应用一条样本写入负载缓冲并推送 SSE，返回样本数组；PM2 未连接时返回 `[]` |
-| `reconcile()` | 调用 `app.syncAllStatuses({ recoverIfMissing: true })`：按 PM2 真实状态写回 DB；`running`/`deploying` 且进程缺失时尝试拉起 |
+| `reconcile({ excludeIds? })` | 调用 `app.syncAllStatuses({ recoverIfMissing: true, excludeIds })`：按 PM2 真实状态写回 DB；`running`/`deploying` 且进程缺失时尝试拉起 |
 
 #### 数据模型
 
@@ -715,6 +775,8 @@ data: {"name":"demo","ts":1791456608533,...}
 | artifactPath | string | 解压目录 |
 | hasMigration | boolean | 是否存在 sql 文件 |
 | migrationPath | string | 相对 server 的 sql 目录，默认 `sql` |
+| fileId | string / null | 宿主文件 id（经 `fileId` 上传时写入）；版本目录据此按需重建，非当前版本不常驻磁盘 |
+| migrationFiles | json / null | SQL 迁移脚本 `[{ name, content, updatedAt }]`，接口不返回（列表只给 `sqlFiles` 文件名） |
 
 唯一约束：`(app_name, version)`。
 

package/index.js

@@ -42,6 +42,8 @@ module.exports = fp(
         resolveSystemEnv: null,
         /** async ({ app }) => void，应用删除成功后调用，app 为删除前快照；报错只记日志 */
         onAppRemoved: null,
+        /** async ({ fileId, name, version, request }) => Buffer，版本上传传 fileId 时读取宿主文件 */
+        resolveVersionFile: null,
         secretEnvKeyPattern: /(SECRET|PASSWORD|TOKEN|KEY|PRIVATE)/i,
         sqlPath: 'sql',
         migrateBeforeStart: false,

package/libs/controllers/app.js

@@ -1,7 +1,9 @@
 const fp = require('fastify-plugin');
+const path = require('node:path');
 const fs = require('fs-extra');
 const yazl = require('yazl');
 const { createSseReply } = require('../utils/logStream');
+const { DEPLOY_STEPS } = require('../utils/deployProgress');
 const { formatInTz } = require('../utils/logTime');
 
 module.exports = fp(async (fastify, options) => {
@@ -117,29 +119,36 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: auth(),
       schema: {
-        summary: '上传应用版本 zip'
+        summary: '上传应用版本 zip（multipart 传 file，或 JSON 传宿主文件 fileId）'
       }
     },
     async request => {
-      const parts = request.parts();
-      let name;
-      let version;
-      let label;
+      let { name, version, label, fileId } = request.isMultipart() ? {} : request.body || {};
       let zipBuffer;
-      for await (const part of parts) {
-        if (part.type === 'file') {
-          zipBuffer = await part.toBuffer();
-        } else {
-          const val = part.value;
-          if (part.fieldname === 'name') name = val;
-          if (part.fieldname === 'version') version = val;
-          if (part.fieldname === 'label') label = val;
+      if (request.isMultipart()) {
+        for await (const part of request.parts()) {
+          if (part.type === 'file') {
+            zipBuffer = await part.toBuffer();
+          } else {
+            const val = part.value;
+            if (part.fieldname === 'name') name = val;
+            if (part.fieldname === 'version') version = val;
+            if (part.fieldname === 'label') label = val;
+            if (part.fieldname === 'fileId') fileId = val;
+          }
         }
       }
-      if (!zipBuffer) {
-        throw fastify.httpErrors.badRequest('file is required');
+      if (zipBuffer) {
+        return services.app.uploadVersion({ name, version, label, zipBuffer });
+      }
+      if (!fileId) {
+        throw fastify.httpErrors.badRequest('file or fileId is required');
       }
-      return services.app.uploadVersion({ name, version, label, zipBuffer });
+      if (typeof options.resolveVersionFile !== 'function') {
+        throw fastify.httpErrors.badRequest('fileId upload is not supported: resolveVersionFile is not configured');
+      }
+      zipBuffer = await options.resolveVersionFile({ fileId, name, version, request });
+      return services.app.uploadVersion({ name, version, label, zipBuffer, fileId });
     }
   );
 
@@ -163,6 +172,39 @@ module.exports = fp(async (fastify, options) => {
     async request => services.app.listVersions(request.query)
   );
 
+  fastify.get(
+    `${options.prefix}/app/version/download`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '下载版本部署包（有 fileId 返回原始 zip，否则由版本目录打包）',
+        query: {
+          type: 'object',
+          required: ['name', 'versionId'],
+          properties: {
+            name: { type: 'string' },
+            versionId: { type: 'string' }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      const { fileName, buffer, artifactPath, files } = await services.app.resolveVersionPackage(request.query);
+      reply.header('Content-Type', 'application/zip');
+      reply.header('Content-Disposition', `attachment; filename="${encodeURIComponent(fileName)}"; filename*=UTF-8''${encodeURIComponent(fileName)}`);
+      if (buffer) {
+        reply.header('Content-Length', buffer.length);
+        return reply.send(buffer);
+      }
+      const zipFile = new yazl.ZipFile();
+      for (const file of files) {
+        zipFile.addFile(path.join(artifactPath, file), file);
+      }
+      zipFile.end();
+      return reply.send(zipFile.outputStream);
+    }
+  );
+
   fastify.post(
     `${options.prefix}/app/deploy`,
     {
@@ -177,6 +219,7 @@ module.exports = fp(async (fastify, options) => {
             versionId: { type: 'string' },
             version: { type: 'string' },
             runMigration: { type: 'boolean', default: true },
+            progressId: { type: 'string', description: '进度标识；先用它订阅 deploy/stream 再发起部署' },
             migrations: {
               type: 'array',
               description: '逐个指定待执行脚本的处理方式；未列出的待执行脚本按 execute 处理',
@@ -196,6 +239,44 @@ module.exports = fp(async (fastify, options) => {
     async request => services.app.deploy(request.body)
   );
 
+  fastify.get(
+    `${options.prefix}/app/deploy/stream`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: 'SSE 部署进度',
+        query: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            progressId: { type: 'string' }
+          }
+        }
+      }
+    },
+    async (request, reply) => {
+      const { name, progressId } = request.query;
+      await services.app.detail({ name });
+      const sse = createSseReply(reply, { heartbeatMs: options.sseHeartbeatMs });
+      const progress = services.app.getDeployProgress();
+      const matches = event => !progressId || event.progressId === progressId;
+      const snapshot = progress.snapshot(name);
+      sse.writeEvent('snapshot', {
+        steps: DEPLOY_STEPS,
+        events: snapshot ? snapshot.events.filter(matches) : []
+      });
+
+      const onProgress = event => matches(event) && sse.writeEvent('progress', event);
+      const eventName = `deploy:${name}`;
+      progress.emitter.on(eventName, onProgress);
+      request.raw.on('close', () => {
+        progress.emitter.off(eventName, onProgress);
+        sse.close();
+      });
+    }
+  );
+
   fastify.get(
     `${options.prefix}/app/list`,
     {

package/libs/models/appVersion.js

@@ -33,6 +33,16 @@ module.exports = ({ DataTypes }) => {
         allowNull: true,
         defaultValue: 'sql',
         comment: '相对 server 的 sql 目录'
+      },
+      fileId: {
+        type: DataTypes.STRING,
+        allowNull: true,
+        comment: '宿主文件 id；版本目录缺失时经 resolveVersionFile 重建'
+      },
+      migrationFiles: {
+        type: DataTypes.JSON,
+        allowNull: true,
+        comment: 'SQL 迁移文件 [{ name, content, updatedAt }]；版本目录可随时删除，部署时写回磁盘'
       }
     },
     options: {

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])?$/;
@@ -250,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');
     }
@@ -270,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,
@@ -278,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);
@@ -287,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') {
@@ -326,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 || '/'}`;
@@ -365,6 +450,7 @@ module.exports = fp(async (fastify, options) => {
 
   /** 同一 app 并发同步合并为一次，避免 restart/reconcile 竞态 */
   const statusSyncInflight = new Map();
+  const deployProgress = createDeployProgress();
 
   /**
    * 根据 PM2 真实进程状态 + HTTP 健康检查，异步写回 DB status。
@@ -459,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));
     });
   };
 
@@ -472,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 }));
     }
@@ -551,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) {
@@ -563,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,
@@ -612,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) {
@@ -619,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);
     }
@@ -715,6 +940,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 +1084,14 @@ module.exports = fp(async (fastify, options) => {
       syncStatus,
       syncAllStatuses,
       remove,
+      resolveVersionPackage,
+      listMissingArtifacts,
+      restoreArtifact,
+      restoreMissingArtifacts,
+      pruneVersionArtifacts,
+      pruneAllVersionArtifacts,
+      getMigrationFiles,
+      saveMigrationFiles,
       logs,
       logFiles,
       resolveAppLogFile,
@@ -865,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 }
   });
 });

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,37 @@
+const { EventEmitter } = require('node:events');
+
+/** 部署阶段，按顺序推进：准备部署包 → SQL 迁移 → 启动进程 → 等待就绪 */
+const DEPLOY_STEPS = ['package', '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);
+
+  return { emitter, begin, snapshot, clear };
+};
+
+module.exports = {
+  DEPLOY_STEPS,
+  createDeployProgress
+};

package/libs/utils/version.js

@@ -33,8 +33,10 @@ 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, 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);
@@ -60,7 +62,10 @@ 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);

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.11",
   "description": "Fastify 单机应用市场插件：版本上传、PM2 托管、路径/域名反代与日志 SSE",
   "main": "index.js",
   "scripts": {