@kne/fastify-app-manager 0.1.9 → 0.1.11

package/README.md

@@ -22,7 +22,7 @@ npm i --save @kne/fastify-app-manager
 
 适用场景：内网/堡垒机上的业务应用集中托管；不负责多机编排、硬磁盘配额或 WebSocket 升级。
 
-> **关键设计**：子应用前端通过部署时注入的 `runtimePublicUrl` / `runtimeApiUrl` 感知对外前缀；网关对路径模式剥前缀反代，并改写 Location / Cookie / 文本 body 兜底。Scheme B（子进程挂 `APP_BASE_PATH`）已弃用。
+> **关键设计**：子应用前端通过部署时注入的 `runtimePublicUrl` / `runtimeApiUrl` 感知对外前缀；网关对路径模式剥前缀反代，并改写 Location / Cookie / 文本 body 兜底（JS 脚本不改写，避免与 runtimeApiUrl 重复拼前缀）。Scheme B（子进程挂 `APP_BASE_PATH`）已弃用。
 >
 > **存储隔离**：同时注入 `window.__LOCAL_STORAGE_PREFIX="<应用名>"`，`@kne/local-storage`（≥0.1.2，`@kne/token-storage` 底层依赖）读到后自动给 key 加 `<应用名>:` 前缀，避免同源挂载的子应用与宿主、其它子应用互相覆盖登录 token 等本地存储。
 
@@ -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 |
 
 ##### 状态机
@@ -106,7 +108,7 @@ deploy(versionId)
 | `save-env` patch | `null` 删除键；`********` 对 secret 键表示保持原值 |
 | 显式密钥 | 存于 `options.secretEnvKeys`；`save-env` 可传 `secretEnvKeys` 将普通键标为密钥；响应顶层回传合并后的键名列表（不含明文） |
 | 默认托管库 | `defaultAppDb`（默认 `appsRoot/_shared/apps-data.sqlite`），与宿主主库强制分离；应用未配 `DB_*` 时注入 |
-| 应用自有库 | 应用 `env` 含完整 `DB_*` 时为独享库（`dbScope=dedicated`） |
+| 应用自有库 | 应用 `env` 含完整 `DB_*` 且 `DB_DEDICATED` 不为 `false` 时为独享库（`dbScope=dedicated`）；`DB_DEDICATED=false` 保留配置但回落共享库。`dbScope` 始终由 env 推导，与启动注入的连接一致；独享库若带 `DB_TABLE_PREFIX`（与其它系统共用库）只认该前缀的表 |
 | 共享库表前缀 | 启动时注入 `DB_TABLE_PREFIX=t_{appName}_` 并由系统写回应用 env（接口不返回、不可修改）；子应用 sequelize 须读取该变量建表 |
 | 表归属 | `options.ownedTables`；共享库启动就绪后按前缀自动认领，亦可 `sync-owned` 扫描；运维仅限归属表 |
 
@@ -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（含回放行与心跳） |
@@ -191,6 +194,10 @@ await fastify.listen({ port: 3000 });
 | `pathPrefix` | string | 否 | `'/app'` | 路径访问前缀（无尾斜杠亦可） |
 | `passthroughEnvKeys` | array | 否 | `[]` | 允许注入子进程的宿主 env 键名 |
 | `secretEnvKeyPattern` | RegExp | 否 | `/(SECRET\|PASSWORD\|TOKEN\|KEY\|PRIVATE)/i` | 按键名正则脱敏；与显式 `secretEnvKeys` 取并集 |
+| `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` 覆盖 |
@@ -253,11 +260,12 @@ await fastify.listen({ port: 3000 });
 | description | string | 否 | - | 描述 |
 | category | object / string | 否 | - | 应用分类（应用中心分组用），写入 `options.category`；推荐传 fastify-group 分组对象，对象只保留 `{ code, name }`，字符串原样保存 |
 | isPublic | boolean | 否 | `true` | 是否在公开应用中心展示，写入 `options.isPublic`；未设置视为公开 |
+| entries | array | 否 | `[]` | 应用入口 `[{ label, path }]`，写入 `options.entries`；`path` 相对应用根（缺前导 `/` 自动补），缺 `label` 或 `path` 的项丢弃，同 `path` 只保留第一项 |
 | env | object | 否 | `{}` | 应用自有环境变量 |
 | pm2Config | object | 否 | `{}` | PM2 覆盖项 |
 | options | object | 否 | `{}` | 扩展字段；可含 `secretEnvKeys: string[]` 显式密钥键名 |
 
-返回脱敏后的应用对象（含 `port`、`pathUrl`、`category`、`passthroughEnvKeys`、`secretEnvKeys`、`status: 'idle'` 等）。
+返回脱敏后的应用对象（含 `port`、`pathUrl`、`category`、`entries`（每项附 `url` = 挂载前缀 + `path`）、`passthroughEnvKeys`、`secretEnvKeys`、`status: 'idle'` 等）。
 
 ##### POST `{prefix}/app/save`
 
@@ -269,6 +277,7 @@ await fastify.listen({ port: 3000 });
 | label / domain / icon / description / env / pm2Config / options | - | 否 | 传入的字段才更新；`env` 按 patch 语义合并 |
 | category | object / string / null | 否 | 合并写入 `options.category`（对象只保留 `{ code, name }`），不影响 `options` 其它键；传空值清除分类 |
 | isPublic | boolean | 否 | 合并写入 `options.isPublic`，不影响 `options` 其它键 |
+| entries | array / null | 否 | 整体替换 `options.entries`（规则同创建），不影响 `options` 其它键；传 `[]` / `null` 清空入口 |
 
 ##### POST `{prefix}/app/save-env`
 
@@ -318,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`
 
@@ -356,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` 的版本目录（只保留当前版本）。
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -367,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`：
 
@@ -383,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`。
 
 | 方法 | 路径 | 参数 | 说明 |
 |------|------|------|------|
@@ -426,7 +480,11 @@ await fastify.listen({ port: 3000 });
       "description": "d",
       "category": { "code": "tools", "name": "工具" },
       "isPublic": true,
-      "pathUrl": "/app/demo/"
+      "pathUrl": "/app/demo/",
+      "entries": [
+        { "label": "PC", "path": "/", "url": "/app/demo/" },
+        { "label": "移动端", "path": "/mobile", "url": "/app/demo/mobile" }
+      ]
     }
   ],
   "totalCount": 1
@@ -618,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 })` | 列出日志文件 |
@@ -663,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` 且进程缺失时尝试拉起 |
 
 #### 数据模型
 
@@ -685,7 +754,7 @@ data: {"name":"demo","ts":1791456608533,...}
 | description | string / null | 描述 |
 | env | object | 自有环境变量 |
 | pm2Config | object | PM2 覆盖 |
-| options | object | 扩展字段；`secretEnvKeys` 为显式密钥键名列表，`category` 为应用分类，`isPublic` 为是否公开（未设置视为公开） |
+| options | object | 扩展字段；`secretEnvKeys` 为显式密钥键名列表，`category` 为应用分类，`isPublic` 为是否公开（未设置视为公开），`entries` 为应用入口 `[{ label, path }]` |
 | port | number | 分配端口 |
 | status | string | `idle` / `deploying` / `running` / `stopped` / `error` |
 | currentVersionId | string / null | 当前部署版本 id |
@@ -706,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)`。
 
@@ -775,7 +846,7 @@ rename 为 {stream}-{起始时间}.log ──→ pm2 reloadLogs ──→ gzip
 ##### 环境合并顺序
 
 ```
-pickHostEnv(passthroughEnvKeys) → app.env → PORT=分配端口（强制）
+pickHostEnv(passthroughEnvKeys) → app.env → PORT=分配端口（强制） → resolveSystemEnv 返回值（覆盖）
 ```
 
 API 响应脱敏：`secretEnvKeyPattern` ∪ `options.secretEnvKeys`；明文密钥不回传，顶层 `secretEnvKeys` 只暴露键名。

package/index.js

@@ -36,6 +36,14 @@ module.exports = fp(
         loadSampleIntervalMs: 5000,
         loadHistoryMinutes: 10,
         passthroughEnvKeys: [],
+        /** 宿主维护的系统变量：接口不返回、不可外部修改，resolveSystemEnv 返回的同名键会持久化 */
+        systemEnvKeys: [],
+        /** async ({ app, version, serverDir }) => env | null，每次启动进程前调用，返回值覆盖应用变量 */
+        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) => {
@@ -26,6 +28,10 @@ module.exports = fp(async (fastify, options) => {
             description: { type: 'string' },
             category: { type: ['object', 'string', 'null'] },
             isPublic: { type: 'boolean' },
+            entries: {
+              type: ['array', 'null'],
+              items: { type: 'object', properties: { label: { type: 'string' }, path: { type: 'string' } } }
+            },
             env: { type: 'object' },
             pm2Config: { type: 'object' },
             options: { type: 'object' }
@@ -53,6 +59,10 @@ module.exports = fp(async (fastify, options) => {
             description: { type: 'string' },
             category: { type: ['object', 'string', 'null'] },
             isPublic: { type: 'boolean' },
+            entries: {
+              type: ['array', 'null'],
+              items: { type: 'object', properties: { label: { type: 'string' }, path: { type: 'string' } } }
+            },
             env: { type: 'object' },
             pm2Config: { type: 'object' },
             options: { type: 'object' }
@@ -109,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 });
     }
   );
 
@@ -155,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`,
     {
@@ -169,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 处理',
@@ -188,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/controllers/gateway.js

@@ -1,6 +1,6 @@
 const fp = require('fastify-plugin');
 const { Readable } = require('node:stream');
-const { rewriteLocation, rewriteSetCookiePath, shouldRewriteBody, rewriteBody } = require('../utils/pathRewrite');
+const { rewriteLocation, rewriteSetCookiePath, shouldRewriteBody, rewriteBody, tagEtag, restoreConditionalHeaders } = require('../utils/pathRewrite');
 const { wantsHtml, renderUnavailablePage, getStatusText } = require('../utils/unavailablePage');
 
 module.exports = fp(async (fastify, options) => {
@@ -41,13 +41,16 @@ module.exports = fp(async (fastify, options) => {
         reply.send(error);
       },
       rewriteRequestHeaders: (req, headers) => {
-        const next = { ...headers };
+        const next = stripPrefix ? restoreConditionalHeaders(headers) : { ...headers };
         delete next['content-length'];
         return next;
       },
       rewriteHeaders: headers => {
         const next = { ...headers };
         if (stripPrefix) {
+          if (next.etag) {
+            next.etag = tagEtag(next.etag);
+          }
           if (next.location) {
             next.location = rewriteLocation(next.location, mountPrefix);
           }

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: {