@kne/fastify-app-manager 0.1.9 → 0.1.10

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 等本地存储。
 
@@ -106,7 +106,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` 扫描；运维仅限归属表 |
 
@@ -191,6 +191,9 @@ 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 日志 |
 | `defaultAppDb` | object | 否 | `appsRoot/_shared/apps-data.sqlite` | 托管应用默认库（须与宿主主库分离） |
 | `dbQueryMaxRows` | number | 否 | `500` | 只读 query SQL 最大返回行数 |
 | `pm2Defaults` | object | 否 | 见下表 | 全局 PM2 默认；可被应用 `pm2Config` 覆盖 |
@@ -253,11 +256,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 +273,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`
 
@@ -426,7 +431,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
@@ -685,7 +694,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 |
@@ -775,7 +784,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,12 @@ module.exports = fp(
         loadSampleIntervalMs: 5000,
         loadHistoryMinutes: 10,
         passthroughEnvKeys: [],
+        /** 宿主维护的系统变量：接口不返回、不可外部修改，resolveSystemEnv 返回的同名键会持久化 */
+        systemEnvKeys: [],
+        /** async ({ app, version, serverDir }) => env | null，每次启动进程前调用，返回值覆盖应用变量 */
+        resolveSystemEnv: null,
+        /** async ({ app }) => void，应用删除成功后调用，app 为删除前快照；报错只记日志 */
+        onAppRemoved: null,
         secretEnvKeyPattern: /(SECRET|PASSWORD|TOKEN|KEY|PRIVATE)/i,
         sqlPath: 'sql',
         migrateBeforeStart: false,

package/libs/controllers/app.js

@@ -26,6 +26,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 +57,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' }

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/services/app.js

@@ -45,6 +45,27 @@ module.exports = fp(async (fastify, options) => {
     }
     return category.code ? { code: category.code, name: category.name || category.code } : null;
   };
+  // 应用入口：label + 相对应用根的 path；去空、补前导 /、按 path 去重
+  const normalizeEntries = entries => {
+    const seen = new Set();
+    return (Array.isArray(entries) ? entries : []).reduce((result, item) => {
+      const label = String(item?.label || '').trim();
+      const rawPath = String(item?.path || '').trim();
+      if (!label || !rawPath) {
+        return result;
+      }
+      const entryPath = rawPath.startsWith('/') ? rawPath : `/${rawPath}`;
+      if (!seen.has(entryPath)) {
+        seen.add(entryPath);
+        result.push({ label, path: entryPath });
+      }
+      return result;
+    }, []);
+  };
+  const resolveEntries = appLike => {
+    const base = mountPrefix(appLike.name);
+    return normalizeEntries(appLike.options?.entries).map(entry => Object.assign({}, entry, { url: `${base}${entry.path}` }));
+  };
 
   const toPublicApp = app => {
     if (!app) {
@@ -59,6 +80,7 @@ module.exports = fp(async (fastify, options) => {
     json.pathUrl = `${mountPrefix(json.name)}/`;
     json.category = json.options?.category || null;
     json.isPublic = isAppPublic(json);
+    json.entries = resolveEntries(json);
     return json;
   };
 
@@ -71,7 +93,7 @@ module.exports = fp(async (fastify, options) => {
   };
 
   const create = async data => {
-    const { name, label, domain, icon, description, category, isPublic, env, pm2Config, options: appOptions } = data;
+    const { name, label, domain, icon, description, category, isPublic, entries, env, pm2Config, options: appOptions } = data;
     if (!name || !NAME_RE.test(name)) {
       httpError(400, 'invalid name: use lowercase slug [a-z0-9-]');
     }
@@ -111,6 +133,9 @@ module.exports = fp(async (fastify, options) => {
     if (isPublic !== undefined) {
       normalizedOptions.isPublic = !!isPublic;
     }
+    if (entries !== undefined) {
+      normalizedOptions.entries = normalizeEntries(entries);
+    }
 
     const app = await models.app.create({
       name,
@@ -118,7 +143,7 @@ module.exports = fp(async (fastify, options) => {
       domain: domain || null,
       icon: icon || null,
       description: description || null,
-      env: omitSystemEnv(env),
+      env: omitSystemEnv(env, options.systemEnvKeys),
       pm2Config: pm2Config || {},
       options: normalizedOptions,
       port,
@@ -130,7 +155,7 @@ module.exports = fp(async (fastify, options) => {
     return toPublicApp(app);
   };
 
-  const save = async ({ name, category, isPublic, ...data }) => {
+  const save = async ({ name, category, isPublic, entries, ...data }) => {
     const app = await getByName(name);
     const omit = ['name', 'port', 'rootPath', 'pm2Name', 'status', 'currentVersionId'];
     const patch = {};
@@ -161,6 +186,9 @@ module.exports = fp(async (fastify, options) => {
     if (isPublic !== undefined) {
       patch.options = Object.assign({}, patch.options || app.options || {}, { isPublic: !!isPublic });
     }
+    if (entries !== undefined) {
+      patch.options = Object.assign({}, patch.options || app.options || {}, { entries: normalizeEntries(entries) });
+    }
     await app.update(patch);
     return toPublicApp(app);
   };
@@ -170,7 +198,7 @@ module.exports = fp(async (fastify, options) => {
     // 密钥类型不可撤销，只随变量删除而移除
     const secretEnvKeys = normalizeSecretKeys([...resolveSecretEnvKeys(app), ...(nextSecretKeys || [])]);
     const nextEnv = applyEnvPatch(app.env || {}, env || {}, Object.assign({}, options, { secretEnvKeys }));
-    const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key) && Object.prototype.hasOwnProperty.call(nextEnv, key));
+    const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key, options.systemEnvKeys) && Object.prototype.hasOwnProperty.call(nextEnv, key));
     await app.update({
       env: nextEnv,
       options: Object.assign({}, app.options || {}, { secretEnvKeys: cleanedSecrets })
@@ -211,7 +239,8 @@ module.exports = fp(async (fastify, options) => {
         description: app.description,
         category: app.options?.category || null,
         isPublic: isAppPublic(app),
-        pathUrl: `${mountPrefix(app.name)}/`
+        pathUrl: `${mountPrefix(app.name)}/`,
+        entries: resolveEntries(app)
       }));
     return { pageData, totalCount: pageData.length };
   };
@@ -480,6 +509,26 @@ module.exports = fp(async (fastify, options) => {
       await app.reload();
     }
 
+    if (typeof options.resolveSystemEnv === 'function') {
+      const systemEnv = await options.resolveSystemEnv({ app, version, serverDir });
+      if (systemEnv && typeof systemEnv === 'object') {
+        const persisted = {};
+        for (const [key, value] of Object.entries(systemEnv)) {
+          if (value == null) {
+            continue;
+          }
+          env[key] = String(value);
+          if ((options.systemEnvKeys || []).includes(key) && app.env?.[key] !== env[key]) {
+            persisted[key] = env[key];
+          }
+        }
+        if (Object.keys(persisted).length) {
+          await app.update({ env: Object.assign({}, app.env || {}, persisted) });
+          await app.reload();
+        }
+      }
+    }
+
     const pathBase = mountPrefix(app.name);
     // Domain-first: inject `/` so custom Host SPA works; path mode then relies on gateway rewrite fallback.
     // Path-only: inject `/app/{name}` so runtime* matches strip-prefix gateway.
@@ -663,9 +712,17 @@ module.exports = fp(async (fastify, options) => {
       }
     }
 
+    const snapshot = app.toJSON();
     await models.appVersion.destroy({ where: { appName: name } });
     await fs.remove(app.rootPath).catch(() => {});
     await app.destroy();
+    if (typeof options.onAppRemoved === 'function') {
+      try {
+        await options.onAppRemoved({ app: snapshot });
+      } catch (e) {
+        fastify.log.warn({ err: e, appName: name }, 'onAppRemoved hook failed');
+      }
+    }
     return {
       removed: true,
       export: exportResult,

package/libs/services/dbops.js

@@ -4,7 +4,7 @@ const fs = require('fs-extra');
 const AdmZip = require('adm-zip');
 const { createSequelizeFromEnv, SQL_MIGRATIONS_TABLE } = require('../utils/migrate');
 const { resolveAppDbEnv, hasAppDbConfig } = require('../utils/env');
-const { resolveDbScope, normalizeOwnedTables, isSystemTable, resolveTablePrefix } = require('../utils/dbIdentity');
+const { resolveDbScope, normalizeOwnedTables, isSystemTable, resolveTablePrefix, filterOwnedTables } = require('../utils/dbIdentity');
 const { assertReadOnlyQuerySql } = require('../utils/sqlQueryGuard');
 
 module.exports = fp(async (fastify, options) => {
@@ -83,15 +83,7 @@ module.exports = fp(async (fastify, options) => {
     return { table, columns, primaryKey };
   };
 
-  const getOwnedTables = (app, allTables) => {
-    const scope = resolveDbScope(app.env || {}, app.options || {});
-    const existing = new Set(allTables);
-    if (scope === 'dedicated') {
-      return allTables.filter(t => !isSystemTable(t));
-    }
-    const owned = normalizeOwnedTables(app.options?.ownedTables);
-    return owned.filter(t => existing.has(t));
-  };
+  const getOwnedTables = (app, allTables) => filterOwnedTables({ appEnv: app.env || {}, ownedTables: app.options?.ownedTables, allTables });
 
   const assertTableOwned = (app, allTables, table) => {
     const owned = getOwnedTables(app, allTables);

package/libs/utils/dbIdentity.js

@@ -1,5 +1,5 @@
 const path = require('node:path');
-const { hasAppDbConfig } = require('./env');
+const { isAppDbEnabled } = require('./env');
 
 const SYSTEM_TABLES = new Set(['_fs_sql_migrations']);
 
@@ -69,12 +69,8 @@ const assertDefaultAppDbSeparated = (defaultAppDb, hostSequelize) => {
   }
 };
 
-const resolveDbScope = (appEnv = {}, options = {}) => {
-  if (options.dbScope === 'dedicated' || options.dbScope === 'shared') {
-    return options.dbScope;
-  }
-  return hasAppDbConfig(appEnv) ? 'dedicated' : 'shared';
-};
+// 与 startProcess 注入的连接一致：只看 env（独立库配置 + DB_DEDICATED 开关）。options.dbScope 只是认领表时写入的缓存，env 变化后会过期
+const resolveDbScope = (appEnv = {}) => (isAppDbEnabled(appEnv) ? 'dedicated' : 'shared');
 
 const normalizeOwnedTables = tables => [...new Set((Array.isArray(tables) ? tables : []).map(t => String(t || '').trim()).filter(Boolean))];
 
@@ -104,8 +100,21 @@ const resolveTablePrefix = (appName, appEnv = {}) => {
   return buildTablePrefix(appName);
 };
 
+/**
+ * 共享库：只认登记过的表；独立库：库内业务表全归本应用，但显式配了 DB_TABLE_PREFIX 说明该库与其它系统共用，只认本前缀的表
+ */
+const filterOwnedTables = ({ appEnv = {}, ownedTables, allTables = [] }) => {
+  if (resolveDbScope(appEnv) === 'dedicated') {
+    const prefix = String(appEnv.DB_TABLE_PREFIX || '').trim();
+    return allTables.filter(t => !isSystemTable(t) && (!prefix || String(t).startsWith(prefix)));
+  }
+  const existing = new Set(allTables);
+  return normalizeOwnedTables(ownedTables).filter(t => existing.has(t));
+};
+
 module.exports = {
   SYSTEM_TABLES,
+  filterOwnedTables,
   fingerprintDbConfig,
   fingerprintFromEnv,
   assertDefaultAppDbSeparated,

package/libs/utils/env.js

@@ -23,6 +23,22 @@ const hasAppDbConfig = (appEnv = {}) => {
   return !!appEnv.DB_DATABASE;
 };
 
+const DB_DEDICATED_KEY = 'DB_DEDICATED';
+const DB_CONNECTION_KEYS = ['DB_DIALECT', 'DB_HOST', 'DB_PORT', 'DB_DATABASE', 'DB_USERNAME', 'DB_PASSWORD', 'DB_STORAGE'];
+
+// 配好独立库后默认启用；DB_DEDICATED=false 时保留配置但回落共享库
+const isAppDbEnabled = (appEnv = {}) =>
+  hasAppDbConfig(appEnv) &&
+  String(appEnv[DB_DEDICATED_KEY] ?? '')
+    .trim()
+    .toLowerCase() !== 'false';
+
+const omitDbConnection = (appEnv = {}) => {
+  const next = Object.assign({}, appEnv);
+  DB_CONNECTION_KEYS.forEach(key => delete next[key]);
+  return next;
+};
+
 const buildDefaultAppDbEnv = (defaultAppDb = {}) => {
   const dialect = defaultAppDb.dialect || 'sqlite';
   const env = { DB_DIALECT: dialect };
@@ -59,10 +75,11 @@ const buildDefaultAppDbEnv = (defaultAppDb = {}) => {
  */
 const resolveAppDbEnv = ({ passthroughEnvKeys = [], appEnv = {}, defaultAppDb = null, port = null, includePort = false, appName = null, injectTablePrefix = true } = {}) => {
   const base = Object.assign({}, pickHostEnv(passthroughEnvKeys));
-  if (defaultAppDb && !hasAppDbConfig(appEnv)) {
+  const useAppDb = isAppDbEnabled(appEnv || {});
+  if (defaultAppDb && !useAppDb) {
     Object.assign(base, buildDefaultAppDbEnv(defaultAppDb));
   }
-  Object.assign(base, appEnv || {});
+  Object.assign(base, useAppDb ? appEnv || {} : omitDbConnection(appEnv || {}));
   if (includePort && port != null) {
     base.PORT = String(port);
   }
@@ -105,17 +122,17 @@ const isSecretKey = (key, pattern, secretKeys = []) => {
   return isPatternSecretKey(key, pattern);
 };
 
-// 由系统写入维护：不在接口中返回，也不接受外部新增 / 修改 / 删除
+// 由系统写入维护：不在接口中返回，也不接受外部新增 / 修改 / 删除；宿主可通过 systemEnvKeys 选项追加
 const SYSTEM_ENV_KEYS = ['DB_TABLE_PREFIX'];
 
-const isSystemEnvKey = key => SYSTEM_ENV_KEYS.includes(key);
+const isSystemEnvKey = (key, systemEnvKeys = []) => SYSTEM_ENV_KEYS.includes(key) || (systemEnvKeys || []).includes(key);
 
-const omitSystemEnv = (appEnv = {}) => Object.fromEntries(Object.entries(appEnv || {}).filter(([key]) => !isSystemEnvKey(key)));
+const omitSystemEnv = (appEnv = {}, systemEnvKeys = []) => Object.fromEntries(Object.entries(appEnv || {}).filter(([key]) => !isSystemEnvKey(key, systemEnvKeys)));
 
-const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const masked = {};
   const explicit = normalizeSecretKeys(secretEnvKeys);
-  for (const [key, value] of Object.entries(omitSystemEnv(appEnv))) {
+  for (const [key, value] of Object.entries(omitSystemEnv(appEnv, systemEnvKeys))) {
     if (isSecretKey(key, secretEnvKeyPattern, explicit)) {
       masked[key] = value == null || value === '' ? null : SECRET_MASK;
     } else {
@@ -131,11 +148,11 @@ const maskEnvForResponse = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys =
  * SECRET_MASK => keep existing (when key is secret by pattern or explicit list)
  * other => set
  */
-const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const next = Object.assign({}, current);
   const explicit = normalizeSecretKeys(secretEnvKeys);
   for (const [key, value] of Object.entries(patch || {})) {
-    if (isSystemEnvKey(key)) {
+    if (isSystemEnvKey(key, systemEnvKeys)) {
       continue;
     }
     if (value === null) {
@@ -153,10 +170,10 @@ const applyEnvPatch = (current = {}, patch = {}, { secretEnvKeyPattern, secretEn
 /**
  * 响应中的密钥键列表 = 显式列表 ∪ 当前 env 中匹配 pattern 的键
  */
-const collectSecretKeys = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [] } = {}) => {
+const collectSecretKeys = (appEnv = {}, { secretEnvKeyPattern, secretEnvKeys = [], systemEnvKeys = [] } = {}) => {
   const explicit = normalizeSecretKeys(secretEnvKeys);
   const fromPattern = Object.keys(appEnv || {}).filter(key => isPatternSecretKey(key, secretEnvKeyPattern));
-  return normalizeSecretKeys([...explicit, ...fromPattern]).filter(key => !isSystemEnvKey(key));
+  return normalizeSecretKeys([...explicit, ...fromPattern]).filter(key => !isSystemEnvKey(key, systemEnvKeys));
 };
 
 const PM2_CONFIG_KEYS = ['exec_mode', 'instances', 'autorestart', 'max_memory_restart', 'max_restarts', 'min_uptime', 'kill_timeout', 'merge_logs'];
@@ -176,6 +193,8 @@ module.exports = {
   normalizeSecretKeys,
   pickHostEnv,
   hasAppDbConfig,
+  DB_DEDICATED_KEY,
+  isAppDbEnabled,
   buildDefaultAppDbEnv,
   resolveAppDbEnv,
   mergeEnv,

package/libs/utils/pathRewrite.js

@@ -27,9 +27,11 @@ const rewriteSetCookiePath = (setCookie, mountPrefix) => {
   });
 };
 
-const TEXTUAL_TYPES = /text\/|javascript|json|xml|svg/i;
+const TEXTUAL_TYPES = /text\/|json|xml|svg/i;
+// 前端脚本已按注入的 runtimePublicUrl / runtimeApiUrl 自行拼前缀（如 axios baseURL + '/api/...'），再改写会得到 /app/x/app/x/api
+const SCRIPT_TYPES = /javascript|ecmascript/i;
 
-const shouldRewriteBody = contentType => TEXTUAL_TYPES.test(contentType || '');
+const shouldRewriteBody = contentType => TEXTUAL_TYPES.test(contentType || '') && !SCRIPT_TYPES.test(contentType || '');
 
 const rewriteBody = (body, mountPrefix, prefixes = ['/static', '/api', '/account']) => {
   if (!body || !mountPrefix) {
@@ -47,9 +49,32 @@ const rewriteBody = (body, mountPrefix, prefixes = ['/static', '/api', '/account
   return text;
 };
 
+// 路径模式响应体经网关改写，ETag 带上改写规则版本，与子应用原始文件及旧规则下的缓存区分；改写规则变化时递增
+const ETAG_SUFFIX = '-gw2';
+
+const tagEtag = etag => (typeof etag === 'string' && etag.endsWith('"') ? `${etag.slice(0, -1)}${ETAG_SUFFIX}"` : etag);
+
+// 只有本网关签发的 ETag 才还原后交给子应用协商缓存；其它（旧规则缓存）去掉条件头，强制返回完整内容
+const restoreConditionalHeaders = headers => {
+  const next = { ...headers };
+  const tags = String(next['if-none-match'] || '')
+    .split(',')
+    .map(tag => tag.trim())
+    .filter(Boolean);
+  if (tags.length && tags.every(tag => tag.endsWith(`${ETAG_SUFFIX}"`))) {
+    next['if-none-match'] = tags.map(tag => `${tag.slice(0, -(ETAG_SUFFIX.length + 1))}"`).join(', ');
+  } else {
+    delete next['if-none-match'];
+    delete next['if-modified-since'];
+  }
+  return next;
+};
+
 module.exports = {
   rewriteLocation,
   rewriteSetCookiePath,
   shouldRewriteBody,
-  rewriteBody
+  rewriteBody,
+  tagEtag,
+  restoreConditionalHeaders
 };

package/package.json

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