@kne/fastify-app-manager 0.1.11 → 0.1.13

package/README.md

@@ -64,6 +64,8 @@ deploy(versionId)
        ↓
  目录缺失则按 fileId 解压 + npm install → 数据库 SQL 覆盖写回
        ↓
+ 按 env.schema.json 校验环境变量（不通过即 400，不切版本、不启动）
+       ↓
  status=deploying → 可选 SQL 迁移 → inject entryHtml → pm2.start → 清理其它版本目录
        ↓（立即返回）
  后台 healthCheck → running / error
@@ -111,6 +113,7 @@ deploy(versionId)
 | 应用自有库 | 应用 `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` 扫描；运维仅限归属表 |
+| 变量声明 | 子应用在 `server/env.schema.json` 声明所需变量（标准 JSON Schema，必填放顶层 `required`，敏感值 `writeOnly`）；上传缺失即拒绝，启动前（deploy / start / restart / 恢复）按它校验最终变量；`GET .../app/env/schema` 列出需要用户填写的变量，隐藏 `PORT`、托管库 `DB_*`、系统变量等应用中心注入的键 |
 
 ##### SQL 迁移
 
@@ -122,7 +125,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 推送（含下载 / 解压 / 安装依赖等子阶段） |
+| 部署进度 | `deploy` 按「准备部署包 → 校验环境变量 → SQL 迁移 → 启动进程 → 等待就绪」上报阶段，经 `GET .../app/deploy/stream` SSE 推送（含下载 / 解压 / 安装依赖等子阶段） |
 | 生命周期 | `start` / `stop` / `restart` / `remove`；父应用重启后异步 `syncAllStatuses` 对齐 PM2 |
 | 双通道访问 | 自定义域名透明反代 + `/app/{name}` 剥前缀反代 |
 | 日志 | PM2 落盘 + 历史分页（`beforeLine` 上滚、每页最多 100 行）+ SSE（含回放行与心跳） |
@@ -171,6 +174,7 @@ await fastify.listen({ port: 3000 });
 | `package.json` | 根包描述 |
 | `server/package.json` | 服务端依赖 |
 | `server/index.js` | PM2 入口 |
+| `server/env.schema.json` | 环境变量声明（必需）；规范见 API 文档「环境变量 schema」 |
 | `build/` | 已构建前端；含 `index.html` / `entry.html` / `entry-prod.html` 之一 |
 | `server/sql/*.sql` | 可选；存在则 `hasMigration=true` |
 
@@ -286,11 +290,52 @@ await fastify.listen({ port: 3000 });
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
 | name | string | 是 | 应用 slug |
-| env | object | 是 | patch：`null` 删键；secret 键值为 `********` 时保持原值 |
+| env | object | 是 | patch：`null` 删键；secret 键值为 `********` 时保持原值；`PORT` 与 `systemEnvKeys` 中的键忽略 |
 | secretEnvKeys | array | 否 | 新增的显式密钥键名，与原列表合并写入 `options.secretEnvKeys`（仅保留仍存在于 env 的键）。密钥类型不可撤销，只有删除该变量才会移出列表 |
 
 > **关键设计**：密钥判定 = 键名匹配 `secretEnvKeyPattern` **或** 出现在 `options.secretEnvKeys`。响应顶层 `secretEnvKeys` 为二者并集，便于管理端把普通变量标成密钥而不改键名。
 
+##### GET `{prefix}/app/env/schema`
+
+按版本的 `server/env.schema.json` 列出需要用户填写的环境变量，供环境变量管理页针对性补充。
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| name | string | 是 | 应用 slug |
+| versionId | string | 否 | 默认取当前版本，没有则取最新上传的版本 |
+
+返回：
+
+```json
+{
+  "name": "demo",
+  "versionId": "354173577374729216",
+  "version": "1.0.0",
+  "hasSchema": true,
+  "valid": false,
+  "declared": [
+    {
+      "key": "API_TOKEN",
+      "type": "string",
+      "required": true,
+      "default": null,
+      "description": "接口令牌",
+      "enum": null,
+      "secret": true,
+      "configured": false,
+      "value": null,
+      "error": "必填，未配置"
+    }
+  ],
+  "others": [{ "key": "EXTRA", "secret": false, "value": "x" }]
+}
+```
+
+- `declared`：schema `properties` 中的变量；`secret` 来自 `writeOnly: true` 或密钥判定；`value` 为当前值（密钥掩码）；`error` 为按当前配置校验的结果。
+- `others`：已配置但 schema 未声明的变量。
+- 两者都**不含应用中心注入的变量**（见 `services.app.listInjectedEnvKeys`）：`PORT`、`DB_TABLE_PREFIX`、`systemEnvKeys`、`passthroughEnvKeys`、托管库连接 `DB_DIALECT` / `DB_HOST` / `DB_PORT` / `DB_DATABASE` / `DB_USERNAME` / `DB_PASSWORD` / `DB_STORAGE` 与 `DB_DEDICATED`（自有库在数据页签配置），以及最近一次启动时 `resolveSystemEnv` 返回的键（记录在 `options.injectedEnvKeys`）。注入的变量照常参与启动前校验。
+- 版本没有 schema 时 `hasSchema=false`、`declared=[]`，该版本无法部署。
+
 ##### 数据运维与表生命周期
 
 解析后的应用库：应用 `env` 的 `DB_*` 优先，否则注入 `defaultAppDb`。共享库（未自配 `DB_*`）仅能操作 `options.ownedTables`。
@@ -337,7 +382,7 @@ await fastify.listen({ port: 3000 });
 | version | string | 是 | 版本号；同应用内唯一 |
 | label | string | 否 | 版本说明 |
 
-成功返回 `appVersion` 记录（含 `artifactPath`、`hasMigration`、`fileId`、`sqlFiles` 等）。包中 `server/{sqlPath}/*.sql` 的内容写入版本记录（数据库）。传 `fileId` 时只解压校验、不装依赖，也不保留版本目录（部署时再从宿主文件解压）；multipart 上传无处重建，解压并 `npm install` 后保留目录。包在临时目录处理完才写入版本表，上传中或失败的包不会出现在版本列表；包非法或 npm 失败时清理临时目录并返回 400。版本号已存在返回 409；同版本号仅残留软删除记录时会先彻底清除再写入。
+成功返回 `appVersion` 记录（含 `artifactPath`、`hasMigration`、`hasEnvSchema`、`fileId`、`sqlFiles` 等）。包中 `server/{sqlPath}/*.sql` 的内容与 `server/env.schema.json` 写入版本记录（数据库）；缺少 `server/env.schema.json` 或其不符合规范的包直接拒绝（400）。传 `fileId` 时只解压校验、不装依赖，也不保留版本目录（部署时再从宿主文件解压）；multipart 上传无处重建，解压并 `npm install` 后保留目录。包在临时目录处理完才写入版本表，上传中或失败的包不会出现在版本列表；包非法或 npm 失败时清理临时目录并返回 400。版本号已存在返回 409；同版本号仅残留软删除记录时会先彻底清除再写入。
 
 ##### GET `{prefix}/app/version/list`
 
@@ -379,7 +424,7 @@ await fastify.listen({ port: 3000 });
 
 ##### POST `{prefix}/app/deploy`
 
-选择版本部署。版本目录不在磁盘时先经 `resolveVersionFile` 取回 zip 解压并 `npm install`（耗时，取不回返回 400 且不改应用状态），再以数据库中的 SQL 覆盖目录内 `.sql`；随后立即返回 `deploying`，后台做健康检查。进程启动后删除该应用其它有 `fileId` 的版本目录（只保留当前版本）。
+选择版本部署。版本目录不在磁盘时先经 `resolveVersionFile` 取回 zip 解压并 `npm install`（耗时，取不回返回 400 且不改应用状态），再以数据库中的 SQL 覆盖目录内 `.sql`；接着按版本的 `env.schema.json` 校验最终环境变量（含注入的变量），版本没有 schema 或变量不合规时返回 400，且不切换版本、不执行迁移、不启动进程；随后立即返回 `deploying`，后台做健康检查。进程启动后删除该应用其它有 `fileId` 的版本目录（只保留当前版本）。
 
 | 参数名 | 类型 | 必填 | 默认值 | 说明 |
 |--------|------|------|--------|------|
@@ -426,6 +471,7 @@ SSE 部署进度。连接时先推送 `snapshot`（该应用最近一次部署
 | step | 说明 | `detail`（`status=running` 时） |
 |------|------|------|
 | `package` | 准备版本目录 | `reuse` 目录已在磁盘 / `download` 取回 zip / `extract` 解压 / `install` 安装依赖 |
+| `env` | 按 `env.schema.json` 校验环境变量；失败时 `message` 列出每个不合规的键与原因 | - |
 | `migrate` | 预跑 SQL 迁移；未开启 `runMigration`、`migrateBeforeStart` 或版本无脚本时为 `skipped` | - |
 | `start` | PM2 拉起进程 | - |
 | `ready` | 健康检查；通过为 `done`，否则 `error`（`message` 为原因，如 `health check timeout`） | - |
@@ -434,7 +480,7 @@ SSE 部署进度。连接时先推送 `snapshot`（该应用最近一次部署
 
 ```text
 event: snapshot
-data: {"steps":["package","migrate","start","ready"],"events":[]}
+data: {"steps":["package","env","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"}
@@ -509,9 +555,9 @@ data: {"progressId":"p-1","step":"ready","status":"done","detail":null,"message"
 
 | 动作 | 行为摘要 |
 |------|----------|
-| start | 需已有 `currentVersionId`；拉起进程并后台健康检查 |
+| start | 需已有 `currentVersionId`；先按 `env.schema.json` 校验环境变量，不通过返回 400 且不改状态；拉起进程并后台健康检查 |
 | stop | PM2 stop，状态 `stopped` |
-| restart | 优先 PM2 restart，失败则重新 startProcess |
+| restart | 先校验环境变量（不通过返回 400，正在运行的进程不受影响），再停止并重新 startProcess |
 | remove | 删 PM2 进程、版本记录、落盘目录与 App 行 |
 
 ##### GET `{prefix}/app/logs`
@@ -686,6 +732,9 @@ data: {"name":"demo","ts":1791456608533,...}
 | `listVersions({ name, perPage, currentPage })` | 版本列表 |
 | `deploy({ name, versionId, version, runMigration, migrations?, progressId? })` | 部署；版本目录缺失时先从宿主文件重建，启动后清理其它版本目录；立即 `deploying`，后台 `syncRealStatus`；各阶段进度写入 `getDeployProgress()` |
 | `getDeployProgress()` | 部署进度中心：`emitter`（事件名 `deploy:{name}`）、`snapshot(name)` 返回最近一次部署 `{ progressId, events }` |
+| `waitDeployProgress({ name, progressId, timeoutMs? })` | 等到该次部署出错或 `ready` 结束（默认超时 120000ms），返回 `{ progressId, ok, timedOut, events }`；供 MCP 等同步调用方使用 |
+| `getEnvDeclaration({ name, versionId? })` | 同 `GET .../app/env/schema` |
+| `listInjectedEnvKeys(app)` | 应用中心注入（或在其它页签维护）的变量名 `Set`，环境变量声明中不展示 |
 | `start` / `stop` / `restart` | 生命周期；`start`/`restart` 立即 `deploying`，后台按 PM2+health 写回真实状态 |
 | `syncStatus({ name, recoverIfMissing? })` | 同步单个应用真实状态并返回公开对象 |
 | `syncAllStatuses({ recoverIfMissing?, excludeIds? })` | 批量同步（父应用启动 reconcile 使用）；`excludeIds` 中的应用跳过 |
@@ -777,6 +826,7 @@ data: {"name":"demo","ts":1791456608533,...}
 | migrationPath | string | 相对 server 的 sql 目录，默认 `sql` |
 | fileId | string / null | 宿主文件 id（经 `fileId` 上传时写入）；版本目录据此按需重建，非当前版本不常驻磁盘 |
 | migrationFiles | json / null | SQL 迁移脚本 `[{ name, content, updatedAt }]`，接口不返回（列表只给 `sqlFiles` 文件名） |
+| envSchema | json / null | `server/env.schema.json` 内容，接口不返回（列表只给 `hasEnvSchema`）；老版本为空时从版本目录回填 |
 
 唯一约束：`(app_name, version)`。
 
@@ -840,9 +890,31 @@ rename 为 {stream}-{起始时间}.log ──→ pm2 reloadLogs ──→ gzip
 | 非 Buffer / 超 `maxZipSize` / 超 `maxZipEntries` | 抛错 |
 | 条目含 `..` 或逃出目标目录 | Zip Slip，抛错 |
 | 缺根/server package、server/index、build 入口 html | `invalid package` |
+| 缺 `server/env.schema.json`、JSON 非法或不符合规范 | `invalid package`（从宿主文件还原老版本目录时不检查，由启动前校验提示） |
 
 部署时会将根 `build/` 复制到 `server/build/`，再对 `server/build` 做 entryHtml 注入。
 
+##### 环境变量 schema（server/env.schema.json）
+
+标准 JSON Schema，子应用 `@fastify/env` 直接 `require` 使用；为兼容 ajv 严格模式只用标准关键字：
+
+- 顶层 `"type": "object"`，必填项写进顶层 `required`（其中的键必须在 `properties` 中声明）。
+- `properties.<KEY>` 内用 `type` / `default` / `enum` / `pattern` / `description` / `title`；敏感值标 `"writeOnly": true`（环境变量管理按密钥处理）。不使用 `x-` 等自定义关键字。
+- 校验规则与 `@fastify/env` 一致（`coerceTypes`、`useDefaults`）；空字符串视为未配置。
+
+启动前（deploy 的 `env` 阶段、start、restart、宿主重启后的恢复）都会校验，不通过时不启动进程。
+
+```json
+{
+  "type": "object",
+  "required": ["API_TOKEN"],
+  "properties": {
+    "API_TOKEN": { "type": "string", "writeOnly": true, "description": "接口令牌" },
+    "PORT": { "type": "number", "default": 8040, "description": "服务端口（应用中心注入）" }
+  }
+}
+```
+
 ##### 环境合并顺序
 
 ```

package/libs/controllers/app.js

@@ -114,6 +114,25 @@ module.exports = fp(async (fastify, options) => {
     async request => services.app.saveEnv(request.body)
   );
 
+  fastify.get(
+    `${options.prefix}/app/env/schema`,
+    {
+      onRequest: auth(),
+      schema: {
+        summary: '环境变量声明：按版本 env.schema.json 列出需要填写的变量（不含应用中心注入的变量）',
+        query: {
+          type: 'object',
+          required: ['name'],
+          properties: {
+            name: { type: 'string' },
+            versionId: { type: 'string', description: '默认取当前版本，没有则取最新上传的版本' }
+          }
+        }
+      }
+    },
+    async request => services.app.getEnvDeclaration(request.query)
+  );
+
   fastify.post(
     `${options.prefix}/app/version/upload`,
     {

package/libs/controllers/gateway.js

@@ -1,5 +1,7 @@
 const fp = require('fastify-plugin');
+const http = require('node:http');
 const { Readable } = require('node:stream');
+const httpProxy = require('http-proxy');
 const { rewriteLocation, rewriteSetCookiePath, shouldRewriteBody, rewriteBody, tagEtag, restoreConditionalHeaders } = require('../utils/pathRewrite');
 const { wantsHtml, renderUnavailablePage, getStatusText } = require('../utils/unavailablePage');
 
@@ -7,17 +9,20 @@ module.exports = fp(async (fastify, options) => {
   const ns = options.name;
   const pathPrefix = options.pathPrefix.replace(/\/$/, '') || '/app';
 
-  const proxyToApp = async (request, reply, app, { stripPrefix } = {}) => {
-    let targetPath = request.raw.url || '/';
-    if (stripPrefix) {
-      const mount = `${pathPrefix}/${app.name}`;
-      if (targetPath === mount || targetPath.startsWith(mount + '/') || targetPath.startsWith(mount + '?')) {
-        targetPath = targetPath.slice(mount.length) || '/';
-        if (!targetPath.startsWith('/')) {
-          targetPath = `/${targetPath}`;
-        }
-      }
+  const pathMatcher = new RegExp(`^${pathPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/?#]+)`);
+
+  const stripMountPrefix = (url, appName) => {
+    const mount = `${pathPrefix}/${appName}`;
+    if (url === mount || url.startsWith(mount + '/') || url.startsWith(mount + '?')) {
+      const rest = url.slice(mount.length) || '/';
+      return rest.startsWith('/') ? rest : `/${rest}`;
     }
+    return url;
+  };
+
+  const proxyToApp = async (request, reply, app, { stripPrefix } = {}) => {
+    const rawUrl = request.raw.url || '/';
+    const targetPath = stripPrefix ? stripMountPrefix(rawUrl, app.name) : rawUrl;
 
     const dest = `http://127.0.0.1:${app.port}${targetPath}`;
     const mountPrefix = `${pathPrefix}/${app.name}`;
@@ -128,7 +133,7 @@ module.exports = fp(async (fastify, options) => {
       return byHost.status === 'running' ? proxyToApp(request, reply, byHost, { stripPrefix: false }) : replyUnavailable(request, reply, byHost);
     }
 
-    const match = url.match(new RegExp(`^${pathPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/([^/?#]+)`));
+    const match = url.match(pathMatcher);
     if (match) {
       const appName = decodeName(match[1]);
       const app = await services.app.findByPathName(appName, { running: false });
@@ -138,4 +143,68 @@ module.exports = fp(async (fastify, options) => {
       return replyUnavailable(request, reply, { name: appName, status: 'missing' });
     }
   });
+
+  const wsProxy = httpProxy.createProxyServer({ changeOrigin: true });
+
+  const rejectUpgrade = (socket, statusCode) => {
+    if (!socket.writable) {
+      return socket.destroy();
+    }
+    socket.end(`HTTP/1.1 ${statusCode} ${http.STATUS_CODES[statusCode]}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  };
+
+  const resolveUpgradeTarget = async req => {
+    const url = req.url || '/';
+    if (url.startsWith(options.prefix)) {
+      return null;
+    }
+    const services = fastify[ns]?.services;
+    if (!services?.app) {
+      return null;
+    }
+    const byHost = await services.app.findByHost(req.headers.host, { running: false });
+    if (byHost) {
+      return { app: byHost, targetPath: url };
+    }
+    const match = url.match(pathMatcher);
+    if (!match) {
+      return null;
+    }
+    const appName = decodeName(match[1]);
+    const app = await services.app.findByPathName(appName, { running: false });
+    return { app: app || { name: appName, status: 'missing' }, targetPath: stripMountPrefix(url, appName) };
+  };
+
+  // reply-from only speaks plain HTTP, so WebSocket handshakes under an app go through http-proxy instead.
+  const onUpgrade = async (req, socket, head) => {
+    socket.on('error', () => socket.destroy());
+    let target;
+    try {
+      target = await resolveUpgradeTarget(req);
+    } catch (error) {
+      fastify.log.error(error);
+      return rejectUpgrade(socket, 502);
+    }
+    if (!target) {
+      return;
+    }
+    // Node servers allow half-open sockets; once our side has finished writing (tunnel ended or upgrade declined) drop the connection.
+    socket.once('finish', () => socket.destroy());
+    const { app, targetPath } = target;
+    if (app.status !== 'running') {
+      return rejectUpgrade(socket, app.status === 'missing' ? 404 : 503);
+    }
+
+    req.url = targetPath;
+    wsProxy.ws(req, socket, head, { target: `http://127.0.0.1:${app.port}` }, error => {
+      fastify.log.warn({ err: error, app: app.name }, 'websocket upgrade proxy failed');
+      rejectUpgrade(socket, 502);
+    });
+  };
+
+  fastify.server.on('upgrade', onUpgrade);
+  fastify.addHook('onClose', async () => {
+    fastify.server.removeListener('upgrade', onUpgrade);
+    wsProxy.close();
+  });
 });

package/libs/models/appVersion.js

@@ -43,6 +43,11 @@ module.exports = ({ DataTypes }) => {
         type: DataTypes.JSON,
         allowNull: true,
         comment: 'SQL 迁移文件 [{ name, content, updatedAt }]；版本目录可随时删除，部署时写回磁盘'
+      },
+      envSchema: {
+        type: DataTypes.JSON,
+        allowNull: true,
+        comment: 'server/env.schema.json 内容；启动前按它校验环境变量'
       }
     },
     options: {

package/libs/services/app.js

@@ -3,7 +3,22 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const fs = require('fs-extra');
 const portPool = require('../utils/portPool');
-const { mergeEnv, maskEnvForResponse, applyEnvPatch, mergePm2Config, normalizeSecretKeys, collectSecretKeys, isSystemEnvKey, omitSystemEnv } = require('../utils/env');
+const {
+  mergeEnv,
+  maskEnvForResponse,
+  applyEnvPatch,
+  mergePm2Config,
+  normalizeSecretKeys,
+  collectSecretKeys,
+  isSystemEnvKey,
+  isSecretKey,
+  omitSystemEnv,
+  SECRET_MASK,
+  SYSTEM_ENV_KEYS,
+  DB_CONNECTION_KEYS,
+  DB_DEDICATED_KEY
+} = require('../utils/env');
+const { readEnvSchema, validateEnv, ENV_SCHEMA_FILE } = require('../utils/envSchema');
 const { prepareVersionArtifact } = require('../utils/version');
 const { injectEntryHtml } = require('../utils/entryInject');
 const { ensureLogFiles, readLogTail, readLastLines, appendLog, countLines } = require('../utils/logFiles');
@@ -198,7 +213,9 @@ module.exports = fp(async (fastify, options) => {
     const app = await getByName(name);
     // 密钥类型不可撤销，只随变量删除而移除
     const secretEnvKeys = normalizeSecretKeys([...resolveSecretEnvKeys(app), ...(nextSecretKeys || [])]);
-    const nextEnv = applyEnvPatch(app.env || {}, env || {}, Object.assign({}, options, { secretEnvKeys }));
+    // PORT 由端口池分配，启动时总会覆盖，不接受外部写入
+    const { PORT, ...envPatch } = env || {};
+    const nextEnv = applyEnvPatch(app.env || {}, envPatch, Object.assign({}, options, { secretEnvKeys }));
     const cleanedSecrets = secretEnvKeys.filter(key => !isSystemEnvKey(key, options.systemEnvKeys) && Object.prototype.hasOwnProperty.call(nextEnv, key));
     await app.update({
       env: nextEnv,
@@ -279,13 +296,31 @@ module.exports = fp(async (fastify, options) => {
   };
 
   const toPublicVersion = (row, files = row.migrationFiles) => {
-    const { migrationFiles, ...json } = row.toJSON();
+    const { migrationFiles, envSchema, ...json } = row.toJSON();
     if (Array.isArray(files) && files.length) {
       json.sqlFiles = files.map(item => item.name);
     }
+    json.hasEnvSchema = !!envSchema;
     return json;
   };
 
+  /** schema 以数据库为准；旧版本行（envSchema 为空）且版本目录在磁盘时从目录回填 */
+  const getVersionEnvSchema = async ver => {
+    if (ver.envSchema) {
+      return ver.envSchema;
+    }
+    if (!(await hasArtifact(ver))) {
+      return null;
+    }
+    try {
+      const schema = await readEnvSchema(path.join(ver.artifactPath, 'server'));
+      await ver.update({ envSchema: schema });
+      return schema;
+    } catch (e) {
+      return null;
+    }
+  };
+
   const uploadVersion = async ({ name, version, label, zipBuffer, fileId }) => {
     if (!version) {
       httpError(400, 'version is required');
@@ -338,7 +373,8 @@ module.exports = fp(async (fastify, options) => {
             hasMigration: migrationFiles.length > 0,
             migrationPath: prepared.migrationPath,
             fileId: fileId ? String(fileId) : null,
-            migrationFiles
+            migrationFiles,
+            envSchema: prepared.envSchema
           },
           { transaction }
         );
@@ -579,13 +615,9 @@ module.exports = fp(async (fastify, options) => {
     return results.filter(Boolean);
   };
 
-  const startProcess = async app => {
-    const version = await models.appVersion.findByPk(app.currentVersionId);
-    if (!version) {
-      throw new Error('current version missing');
-    }
+  /** 子进程最终环境变量：宿主透传 → 托管库 → 应用变量 → PORT → resolveSystemEnv；顺带持久化表前缀与系统变量 */
+  const buildProcessEnv = async (app, version) => {
     const serverDir = path.join(version.artifactPath, 'server');
-    const { outFile, errFile } = await ensureLogFiles(app.rootPath);
     const env = mergeEnv({
       passthroughEnvKeys: options.passthroughEnvKeys,
       appEnv: app.env,
@@ -604,6 +636,7 @@ module.exports = fp(async (fastify, options) => {
 
     if (typeof options.resolveSystemEnv === 'function') {
       const systemEnv = await options.resolveSystemEnv({ app, version, serverDir });
+      const injectedKeys = [];
       if (systemEnv && typeof systemEnv === 'object') {
         const persisted = {};
         for (const [key, value] of Object.entries(systemEnv)) {
@@ -611,6 +644,7 @@ module.exports = fp(async (fastify, options) => {
             continue;
           }
           env[key] = String(value);
+          injectedKeys.push(key);
           if ((options.systemEnvKeys || []).includes(key) && app.env?.[key] !== env[key]) {
             persisted[key] = env[key];
           }
@@ -620,7 +654,143 @@ module.exports = fp(async (fastify, options) => {
           await app.reload();
         }
       }
+      // 记下本次由系统注入的键，供环境变量声明接口隐藏（如未配置 ORIGIN 时由宿主补上的值）
+      const recorded = app.options?.injectedEnvKeys || [];
+      if (recorded.length !== injectedKeys.length || recorded.some(key => !injectedKeys.includes(key))) {
+        await app.update({ options: Object.assign({}, app.options || {}, { injectedEnvKeys: injectedKeys }) });
+        await app.reload();
+      }
     }
+    return env;
+  };
+
+  const envSchemaMissingError = () => {
+    const err = new Error(`该版本缺少 server/${ENV_SCHEMA_FILE}，请补充后重新上传`);
+    err.envErrors = [];
+    return err;
+  };
+
+  /** 按版本的 env.schema.json 校验最终环境变量，不通过时抛错（err.envErrors 为 [{ key, message }]） */
+  const assertEnvValid = async (app, version, env) => {
+    const schema = await getVersionEnvSchema(version);
+    if (!schema) {
+      throw envSchemaMissingError();
+    }
+    const errors = validateEnv(schema, env);
+    if (errors.length) {
+      const injected = listInjectedEnvKeys(app);
+      const detail = errors.map(({ key, message }) => `${key}${injected.has(key) ? '（应用中心注入）' : ''} ${message}`).join('；');
+      const err = new Error(`环境变量不符合 ${ENV_SCHEMA_FILE}：${detail}`);
+      err.envErrors = errors;
+      throw err;
+    }
+  };
+
+  /** 应用中心自动注入或在其它页签维护的变量名：环境变量管理中不展示 */
+  const listInjectedEnvKeys = app =>
+    new Set([
+      'PORT',
+      ...SYSTEM_ENV_KEYS,
+      ...(options.systemEnvKeys || []),
+      ...(options.passthroughEnvKeys || []),
+      // 托管库连接由宿主注入，自有库在数据页签配置
+      ...DB_CONNECTION_KEYS,
+      DB_DEDICATED_KEY,
+      ...(app.options?.injectedEnvKeys || [])
+    ]);
+
+  const resolveDeclarationVersion = async (app, versionId) => {
+    if (versionId) {
+      const ver = await models.appVersion.findByPk(versionId);
+      if (!ver || ver.appName !== app.name) {
+        httpError(404, 'version not found');
+      }
+      return ver;
+    }
+    if (app.currentVersionId) {
+      const ver = await models.appVersion.findByPk(app.currentVersionId);
+      if (ver) {
+        return ver;
+      }
+    }
+    return models.appVersion.findOne({ where: { appName: app.name }, order: [['createdAt', 'DESC']] });
+  };
+
+  /**
+   * 环境变量声明：declared 为 schema 中需要用户填写的变量，others 为已配置但未声明的变量；
+   * 两者都不含应用中心注入的变量，密钥值掩码
+   */
+  const getEnvDeclaration = async ({ name, versionId } = {}) => {
+    const app = await getByName(name);
+    const ver = await resolveDeclarationVersion(app, versionId);
+    const schema = ver ? await getVersionEnvSchema(ver) : null;
+    const injected = listInjectedEnvKeys(app);
+    const appEnv = omitSystemEnv(app.env || {}, options.systemEnvKeys);
+    const secretOpts = Object.assign({}, options, { secretEnvKeys: resolveSecretEnvKeys(app) });
+    const isSecret = (key, prop) => !!prop?.writeOnly || isSecretKey(key, options.secretEnvKeyPattern, secretOpts.secretEnvKeys);
+    const maskValue = (key, prop) => {
+      const value = appEnv[key];
+      if (value == null || value === '') {
+        return null;
+      }
+      return isSecret(key, prop) ? SECRET_MASK : value;
+    };
+
+    const properties = schema?.properties || {};
+    const required = new Set(schema?.required || []);
+    const errorMap = new Map();
+    if (schema) {
+      const previewEnv = mergeEnv({
+        passthroughEnvKeys: options.passthroughEnvKeys,
+        appEnv: app.env,
+        port: app.port,
+        defaultAppDb: options.defaultAppDb,
+        appName: app.name
+      });
+      validateEnv(schema, previewEnv)
+        .filter(item => !injected.has(item.key))
+        .forEach(item => errorMap.set(item.key, item.message));
+    }
+
+    const declared = Object.entries(properties)
+      .filter(([key]) => !injected.has(key))
+      .map(([key, prop]) => ({
+        key,
+        type: prop?.type || null,
+        required: required.has(key),
+        default: prop?.default === undefined ? null : prop.default,
+        description: prop?.description || prop?.title || null,
+        enum: Array.isArray(prop?.enum) ? prop.enum : null,
+        secret: isSecret(key, prop),
+        configured: appEnv[key] != null && appEnv[key] !== '',
+        value: maskValue(key, prop),
+        error: errorMap.get(key) || null
+      }));
+
+    const others = Object.keys(appEnv)
+      .filter(key => !injected.has(key) && !Object.prototype.hasOwnProperty.call(properties, key))
+      .map(key => ({ key, secret: isSecret(key), value: maskValue(key) }));
+
+    return {
+      name: app.name,
+      versionId: ver ? String(ver.id) : null,
+      version: ver ? ver.version : null,
+      hasSchema: !!schema,
+      valid: !!schema && errorMap.size === 0,
+      declared,
+      others
+    };
+  };
+
+  const startProcess = async (app, { env: preparedEnv } = {}) => {
+    const version = await models.appVersion.findByPk(app.currentVersionId);
+    if (!version) {
+      throw new Error('current version missing');
+    }
+    const serverDir = path.join(version.artifactPath, 'server');
+    const env = preparedEnv || (await buildProcessEnv(app, version));
+    await assertEnvValid(app, version, env);
+    const { outFile, errFile } = await ensureLogFiles(app.rootPath);
 
     const pathBase = mountPrefix(app.name);
     // Domain-first: inject `/` so custom Host SPA works; path mode then relies on gateway rewrite fallback.
@@ -688,6 +858,8 @@ module.exports = fp(async (fastify, options) => {
           maxZipEntries: options.maxZipEntries,
           npmInstallTimeoutMs: options.npmInstallTimeoutMs,
           sqlPath: options.sqlPath,
+          // 老版本可能没有 env.schema.json：照常还原目录，由启动前的环境变量校验给出提示
+          requireEnvSchema: false,
           onProgress
         });
         await fs.move(stagingPath, ver.artifactPath, { overwrite: true });
@@ -777,6 +949,19 @@ module.exports = fp(async (fastify, options) => {
     }
     progress.report(step, 'done');
 
+    // 变量不合规时不切换版本、不执行迁移、不启动进程
+    step = 'env';
+    progress.report(step, 'running');
+    let processEnv;
+    try {
+      processEnv = await buildProcessEnv(app, ver);
+      await assertEnvValid(app, ver, processEnv);
+    } catch (e) {
+      progress.report(step, 'error', { message: e.message });
+      httpError(400, e.message);
+    }
+    progress.report(step, 'done');
+
     await app.update({
       status: 'deploying',
       currentVersionId: String(ver.id),
@@ -830,13 +1015,13 @@ module.exports = fp(async (fastify, options) => {
 
       if (runMigration === false) {
         // child may honor RUN_SQL_ON_SYNC
-        app.env = Object.assign({}, app.env, { RUN_SQL_ON_SYNC: 'false' });
+        processEnv.RUN_SQL_ON_SYNC = 'false';
       }
 
       step = 'start';
       progress.report(step, 'running');
       const beforeForReady = await snapshotTablesSafe(app);
-      await startProcess(app);
+      await startProcess(app, { env: processEnv });
       progress.report(step, 'done');
       step = 'ready';
       progress.report(step, 'running');
@@ -872,15 +1057,28 @@ module.exports = fp(async (fastify, options) => {
     return toPublicApp(app);
   };
 
-  const start = async ({ name }) => {
-    const app = await getByName(name);
-    if (!app.currentVersionId) {
+  /** 启动 / 重启前先按 schema 校验，不通过直接报错，不改动正在运行的进程与状态 */
+  const prepareStartEnv = async app => {
+    const version = app.currentVersionId ? await models.appVersion.findByPk(app.currentVersionId) : null;
+    if (!version) {
       httpError(400, 'no version deployed');
     }
+    const env = await buildProcessEnv(app, version);
+    try {
+      await assertEnvValid(app, version, env);
+    } catch (e) {
+      httpError(400, e.message);
+    }
+    return env;
+  };
+
+  const start = async ({ name }) => {
+    const app = await getByName(name);
+    const env = await prepareStartEnv(app);
     await app.update({ status: 'deploying', message: null });
     try {
       const beforeTables = await snapshotTablesSafe(app);
-      await startProcess(app);
+      await startProcess(app, { env });
       scheduleStatusSync(app.id, { beforeTables });
       return toPublicApp(await getByName(name));
     } catch (e) {
@@ -891,6 +1089,7 @@ module.exports = fp(async (fastify, options) => {
 
   const restart = async ({ name }) => {
     const app = await getByName(name);
+    const env = await prepareStartEnv(app);
     await app.update({ status: 'deploying', message: null });
     try {
       const beforeTables = await snapshotTablesSafe(app);
@@ -900,7 +1099,7 @@ module.exports = fp(async (fastify, options) => {
       } catch (e) {
         // ignore if not running
       }
-      await startProcess(app);
+      await startProcess(app, { env });
       scheduleStatusSync(app.id, { beforeTables });
       return toPublicApp(await getByName(name));
     } catch (e) {
@@ -1100,6 +1299,9 @@ module.exports = fp(async (fastify, options) => {
       load,
       getLoadStore,
       getDeployProgress: () => deployProgress,
+      waitDeployProgress: ({ name, progressId, timeoutMs }) => deployProgress.wait(name, progressId, { timeoutMs }),
+      getEnvDeclaration,
+      listInjectedEnvKeys,
       toPublicApp,
       mountPrefix,
       findByHost,

package/libs/services/bootstrap.js

@@ -42,7 +42,7 @@ module.exports = fp(async (fastify, options) => {
     const queryInterface = model.sequelize.getQueryInterface();
     const table = model.getTableName();
     const columns = await queryInterface.describeTable(table);
-    for (const name of ['fileId', 'migrationFiles']) {
+    for (const name of ['fileId', 'migrationFiles', 'envSchema']) {
       const attr = model.rawAttributes[name];
       if (!columns[attr.field]) {
         await queryInterface.addColumn(table, attr.field, { type: attr.type, allowNull: true, comment: attr.comment });

package/libs/utils/deployProgress.js

@@ -1,7 +1,7 @@
 const { EventEmitter } = require('node:events');
 
-/** 部署阶段，按顺序推进：准备部署包 → SQL 迁移 → 启动进程 → 等待就绪 */
-const DEPLOY_STEPS = ['package', 'migrate', 'start', 'ready'];
+/** 部署阶段，按顺序推进：准备部署包 → 校验环境变量 → SQL 迁移 → 启动进程 → 等待就绪 */
+const DEPLOY_STEPS = ['package', 'env', 'migrate', 'start', 'ready'];
 
 /**
  * 每个应用只保留最近一次部署的进度事件，供 SSE 订阅与断线重连回放。
@@ -28,7 +28,36 @@ const createDeployProgress = () => {
 
   const clear = name => latest.delete(name);
 
-  return { emitter, begin, snapshot, clear };
+  const isFinished = event => event.status === 'error' || (event.step === 'ready' && event.status !== 'running');
+
+  /** 等到该次部署出错或就绪阶段结束（或超时）；返回 { progressId, ok, timedOut, events } */
+  const wait = (name, progressId, { timeoutMs = 120000 } = {}) =>
+    new Promise(resolve => {
+      const collect = () => {
+        const state = latest.get(name);
+        return state && state.progressId === progressId ? state.events.slice() : [];
+      };
+      let timer = null;
+      const listener = event => {
+        if (event.progressId === progressId && isFinished(event)) {
+          finish(false);
+        }
+      };
+      const finish = timedOut => {
+        clearTimeout(timer);
+        emitter.off(`deploy:${name}`, listener);
+        const events = collect();
+        resolve({ progressId, ok: !timedOut && !events.some(event => event.status === 'error'), timedOut, events });
+      };
+      if (collect().some(isFinished)) {
+        finish(false);
+        return;
+      }
+      emitter.on(`deploy:${name}`, listener);
+      timer = setTimeout(() => finish(true), timeoutMs);
+    });
+
+  return { emitter, begin, snapshot, clear, wait };
 };
 
 module.exports = {

package/libs/utils/env.js

@@ -194,6 +194,7 @@ module.exports = {
   pickHostEnv,
   hasAppDbConfig,
   DB_DEDICATED_KEY,
+  DB_CONNECTION_KEYS,
   isAppDbEnabled,
   buildDefaultAppDbEnv,
   resolveAppDbEnv,

package/libs/utils/envSchema.js

@@ -0,0 +1,105 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const Ajv = require('ajv');
+
+const ENV_SCHEMA_FILE = 'env.schema.json';
+
+// 与 @fastify/env（env-schema）一致：类型转换、填充默认值，separator 为其内置关键字
+const createAjv = () => {
+  const ajv = new Ajv({ allErrors: true, coerceTypes: true, useDefaults: true, allowUnionTypes: true });
+  ajv.addKeyword('separator');
+  return ajv;
+};
+
+/** 检查 schema 是否符合规范：顶层 object、有 properties、required 中的键都已声明、能被 ajv 编译 */
+const checkEnvSchema = schema => {
+  const errors = [];
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+    return ['env.schema.json must be a JSON object'];
+  }
+  if (schema.type !== 'object') {
+    errors.push('env.schema.json: "type" must be "object"');
+  }
+  if (!schema.properties || typeof schema.properties !== 'object' || Array.isArray(schema.properties)) {
+    errors.push('env.schema.json: "properties" must be an object');
+  }
+  if (schema.required !== undefined) {
+    if (!Array.isArray(schema.required) || schema.required.some(key => typeof key !== 'string')) {
+      errors.push('env.schema.json: "required" must be an array of strings');
+    } else if (schema.properties && typeof schema.properties === 'object') {
+      const undeclared = schema.required.filter(key => !Object.prototype.hasOwnProperty.call(schema.properties, key));
+      if (undeclared.length) {
+        errors.push(`env.schema.json: required keys not declared in properties: ${undeclared.join(', ')}`);
+      }
+    }
+  }
+  if (!errors.length) {
+    try {
+      createAjv().compile(schema);
+    } catch (e) {
+      errors.push(`env.schema.json: ${e.message}`);
+    }
+  }
+  return errors;
+};
+
+/** 读取 server/env.schema.json；文件缺失、JSON 非法或不符合规范时抛错 */
+const readEnvSchema = async serverDir => {
+  const file = path.join(serverDir, ENV_SCHEMA_FILE);
+  if (!(await fs.pathExists(file))) {
+    throw new Error(`missing server/${ENV_SCHEMA_FILE}`);
+  }
+  let schema;
+  try {
+    schema = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (e) {
+    throw new Error(`server/${ENV_SCHEMA_FILE} is not valid JSON: ${e.message}`);
+  }
+  const errors = checkEnvSchema(schema);
+  if (errors.length) {
+    throw new Error(errors.join('; '));
+  }
+  return schema;
+};
+
+const formatError = error => {
+  const { keyword, params = {} } = error;
+  if (keyword === 'required') {
+    return { key: params.missingProperty, message: '必填，未配置' };
+  }
+  const key = String(error.instancePath || '')
+    .replace(/^\//, '')
+    .split('/')[0];
+  if (keyword === 'type') {
+    return { key, message: `类型应为 ${params.type}` };
+  }
+  if (keyword === 'enum') {
+    return { key, message: `取值应为 ${(params.allowedValues || []).join(' / ')}` };
+  }
+  if (keyword === 'pattern') {
+    return { key, message: `格式应匹配 ${params.pattern}` };
+  }
+  return { key, message: error.message };
+};
+
+/** 按 schema 校验环境变量；空字符串视为未配置。返回 [{ key, message }]，空数组表示通过 */
+const validateEnv = (schema, env = {}) => {
+  const data = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (value != null && value !== '') {
+      data[key] = value;
+    }
+  }
+  const validate = createAjv().compile(schema);
+  if (validate(data)) {
+    return [];
+  }
+  return (validate.errors || []).map(formatError);
+};
+
+module.exports = {
+  ENV_SCHEMA_FILE,
+  checkEnvSchema,
+  readEnvSchema,
+  validateEnv
+};

package/libs/utils/validatePackage.js

@@ -1,9 +1,11 @@
 const path = require('node:path');
 const fs = require('fs-extra');
+const { readEnvSchema } = require('./envSchema');
 
 const ENTRY_CANDIDATES = ['index.html', 'entry.html', 'entry-prod.html'];
 
-const validatePackageRoot = async rootDir => {
+/** requireEnvSchema=false 时缺少 / 非法的 env.schema.json 不算错误，envSchema 返回 null（用于从宿主文件还原老版本） */
+const validatePackageRoot = async (rootDir, { requireEnvSchema = true } = {}) => {
   const errors = [];
   const rootPkg = path.join(rootDir, 'package.json');
   const serverPkg = path.join(rootDir, 'server', 'package.json');
@@ -28,9 +30,19 @@ const validatePackageRoot = async rootDir => {
     }
   }
 
+  let envSchema = null;
+  try {
+    envSchema = await readEnvSchema(path.join(rootDir, 'server'));
+  } catch (e) {
+    if (requireEnvSchema) {
+      errors.push(e.message);
+    }
+  }
+
   return {
     ok: errors.length === 0,
     errors,
+    envSchema,
     hasMigration: await hasSqlMigrations(path.join(rootDir, 'server', 'sql'))
   };
 };

package/libs/utils/version.js

@@ -34,14 +34,14 @@ const runNpmInstall = (cwd, timeoutMs) =>
   });
 
 /** install=false 时只解压校验，不装依赖（用于不常驻磁盘的版本上传） */
-const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath, install = true, onProgress }) => {
+const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, maxZipEntries, npmInstallTimeoutMs, sqlPath, install = true, requireEnvSchema = 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);
 
-  const validation = await validatePackageRoot(packageRoot);
+  const validation = await validatePackageRoot(packageRoot, { requireEnvSchema });
   if (!validation.ok) {
     await fs.remove(artifactPath);
     throw new Error(`invalid package: ${validation.errors.join('; ')}`);
@@ -72,7 +72,8 @@ const prepareVersionArtifact = async ({ zipBuffer, artifactPath, maxZipSize, max
   return {
     hasMigration: sqlFiles.length > 0,
     migrationPath: sqlPath || 'sql',
-    sqlFiles
+    sqlFiles,
+    envSchema: validation.envSchema
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-app-manager",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Fastify 单机应用市场插件：版本上传、PM2 托管、路径/域名反代与日志 SSE",
   "main": "index.js",
   "scripts": {
@@ -69,7 +69,9 @@
     "@fastify/reply-from": "^12.6.5",
     "@kne/ensure-slash": "^0.1.0",
     "adm-zip": "^0.6.0",
+    "ajv": "^8.17.1",
     "fs-extra": "^11.4.0",
+    "http-proxy": "^1.18.1",
     "jsdom": "^29.1.1",
     "lodash": "^4.18.1",
     "pm2": "^7.0.4",