@cloudbase/manager-node 5.9.3 → 5.10.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [5.9.4] 2026-10-28
+
+- [Fixed] storage: uploadObject 默认 Cache-Control 为 max-age=3600
+## [5.9.3] 2026-10-27
+
+- [Added] env: 增加 HTTP 服务路由 UpstreamResourceVersion 字段
 ## [5.9.2] 2026-10-21
 
 - [Fixed] function: COS 上传超时改为连续无进度判定，避免大包被总耗时误杀

package/changelog_content_en.md

@@ -1,4 +1,3 @@
-## [5.9.2] 2026-10-21
+## [5.9.4] 2026-10-28
 
-- [Fixed] [TODO: translate] function: COS 上传超时改为连续无进度判定，避免大包被总耗时误杀
-- [Fixed] [TODO: translate] utils: 解压远程 zip 增加路径穿越防护并支持失败即中止
+- [Fixed] [TODO: translate] storage: uploadObject 默认 Cache-Control 为 max-age=3600

package/lib/database/index.js

@@ -325,6 +325,73 @@ class DatabaseService {
         }
         return this.dbOpService.request('ExecutePGSql', params);
     }
+    /**
+     * 开通 PG 数据库 Realtime 能力
+     * 用于服务首次开通；已开通时重复调用仍返回 Enabled: true（幂等）
+     *
+     * @param options 开通参数
+     * @param options.EnvId 环境 ID（可选，不传则自动使用当前环境 ID）
+     * @returns 开通状态
+     *
+     * @example
+     * // 使用当前环境 ID 开通
+     * const res = await database.enablePGRealtime()
+     * console.log(res.Enabled) // true
+     *
+     * @example
+     * // 指定环境 ID 开通
+     * const res = await database.enablePGRealtime({ EnvId: 'pg-shared-d4gq5c0ne1a30f155' })
+     */
+    async enablePGRealtime(options = {}) {
+        return this.dbOpService.request('EnablePGRealtime', {
+            EnvId: options.EnvId || this.envId
+        });
+    }
+    /**
+     * 查询 PG Realtime 设置
+     * 返回当前挂起状态、频道策略、限流阈值、连接池大小及创建/更新时间
+     *
+     * @param options 查询参数
+     * @param options.EnvId 环境 ID（可选，不传则自动使用当前环境 ID）
+     * @returns Realtime 当前配置
+     *
+     * @example
+     * const settings = await database.describePGRealtimeSettings()
+     * console.log(settings.Suspend, settings.MaxConcurrentUsers)
+     */
+    async describePGRealtimeSettings(options = {}) {
+        return this.dbOpService.request('DescribePGRealtimeSettings', {
+            EnvId: options.EnvId || this.envId
+        });
+    }
+    /**
+     * 修改 PG Realtime 设置
+     *
+     * 增量修改：只需传要变更的字段，未传字段保持服务端当前值；
+     * 建议先用 describePGRealtimeSettings 获取当前配置再按需调整。
+     * 关闭/挂起 Realtime 会断开所有已有连接，客户端需重连。
+     *
+     * @param options 需要变更的设置项
+     * @param options.EnvId 环境 ID（可选，不传则自动使用当前环境 ID）
+     * @returns RequestId
+     *
+     * @example
+     * // 启用 Realtime（取消挂起）
+     * await database.modifyPGRealtimeSettings({ Suspend: false })
+     *
+     * @example
+     * // 更新最大并发用户数与限流阈值
+     * await database.modifyPGRealtimeSettings({
+     *     MaxConcurrentUsers: 50002,
+     *     MaxEventsPerSecond: 200
+     * })
+     */
+    async modifyPGRealtimeSettings(options = {}) {
+        const { EnvId, Suspend, PrivateOnly, PresenceEnabled, MaxConcurrentUsers, MaxEventsPerSecond, MaxJoinsPerSecond, MaxBytesPerSecond, MaxChannelsPerClient, MaxPresenceEventsPerSecond, MaxPayloadSizeInKB, ConnectionPool, PostgresChangesPool } = options;
+        return this.dbOpService.request('ModifyPGRealtimeSettings', Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ EnvId: EnvId || this.envId }, (Suspend !== undefined ? { Suspend } : {})), (PrivateOnly !== undefined ? { PrivateOnly } : {})), (PresenceEnabled !== undefined ? { PresenceEnabled } : {})), (MaxConcurrentUsers !== undefined ? { MaxConcurrentUsers } : {})), (MaxEventsPerSecond !== undefined ? { MaxEventsPerSecond } : {})), (MaxJoinsPerSecond !== undefined ? { MaxJoinsPerSecond } : {})), (MaxBytesPerSecond !== undefined ? { MaxBytesPerSecond } : {})), (MaxChannelsPerClient !== undefined ? { MaxChannelsPerClient } : {})), (MaxPresenceEventsPerSecond !== undefined
+            ? { MaxPresenceEventsPerSecond }
+            : {})), (MaxPayloadSizeInKB !== undefined ? { MaxPayloadSizeInKB } : {})), (ConnectionPool !== undefined ? { ConnectionPool } : {})), (PostgresChangesPool !== undefined ? { PostgresChangesPool } : {})));
+    }
     /**
      * 预览 PG 用户 migrations 的远端执行计划（不实际执行 SQL）
      * @param options 预览参数
@@ -548,6 +615,15 @@ __decorate([
 __decorate([
     preLazy()
 ], DatabaseService.prototype, "executePGSql", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "enablePGRealtime", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "describePGRealtimeSettings", null);
+__decorate([
+    preLazy()
+], DatabaseService.prototype, "modifyPGRealtimeSettings", null);
 __decorate([
     preLazy()
 ], DatabaseService.prototype, "previewPGUserMigrations", null);

package/lib/deploy/DeployOrchestrator.js

@@ -10,6 +10,7 @@ const DatabaseDeployer_1 = require("./DatabaseDeployer");
 const FunctionDeployer_1 = require("./FunctionDeployer");
 const StaticDeployer_1 = require("./StaticDeployer");
 const GatewayDeployer_1 = require("./GatewayDeployer");
+const framework_1 = require("./framework");
 const config_guard_1 = require("./function/config-guard");
 const parallel_1 = require("../utils/parallel");
 /** 部署顺序（按依赖：database 最先，函数依赖新 Schema；gateway 最后，依赖函数/hosting） */
@@ -31,7 +32,7 @@ class DeployOrchestrator {
      * 计算部署计划（dry-run 输出）
      */
     async deployPlan(options) {
-        const config = this.normalizeFunctionConfigs(options.config, options.envId, options.cwd);
+        const config = this.normalizeConfigInput(options.config, options.envId, options.cwd);
         return this.buildPlan(config, options);
     }
     /**
@@ -46,7 +47,7 @@ class DeployOrchestrator {
     async deploy(options) {
         var _a, _b, _c, _d, _e, _f, _g, _h;
         const { config: inputConfig, envId, dryRun, cwd = process.cwd(), log, concurrency = 5, continueOnError = false } = options;
-        const config = this.normalizeFunctionConfigs(inputConfig, envId, cwd);
+        const config = this.normalizeConfigInput(inputConfig, envId, cwd);
         // 1. 轻量 inline 守卫（validateProject 未接入时的兜底）
         this.guardConfig(config);
         const plan = await this.buildPlan(config, options);
@@ -173,6 +174,31 @@ class DeployOrchestrator {
         }
         return { plan, results };
     }
+    /**
+     * 部署入口归一化：cloudbaserc 原文 → 编排器内部契约（唯一的输入形状收口处）
+     *
+     * cloudbaserc 是用户手改的 JSON，schema 只在 `tcb validate` / MCP 注入侧生效
+     * （见 `StaticDeployer.resolveInsideBase` 注释里 `"root": 123` 的例子），因此
+     * `"functions": ""` / `0` / `false` / `{}`、`"hosting": 123`、`"gateway": []`
+     * 都是真实可达输入。
+     *
+     * 为什么必须收口在**入口**而不是各消费点自己防：
+     * `(config.hosting || []).map(...)` 对 `''` 恰好安全，对 `{}` / `123` 会抛
+     * `x.map is not a function` —— 不含字段名，用户无从定位。这类守卫此前分散在
+     * `buildHostingPlans` / `executeStep` / 网关归一化三处，每新增一个消费点就漏一处。
+     * 归一化后，消费点可以假设「顶层资源声明一定是对象数组」。
+     *
+     * 降级口径与历史 `config.hosting || []` 一致 —— **非数组一律降级为空数组且不报错**，
+     * 存量把手写错的配置仍能跑通其余资源的部署；数组元素非对象则没有静默降级的合理语义
+     * （会漏部署一个站点/一条路由），显式报 `INVALID_PARAM` 并带字段名与下标。
+     */
+    normalizeConfigInput(config, envId, cwd = process.cwd()) {
+        this.guardConfigShape(config);
+        // 先收口形状，再跑函数归一化：`normalizeFunctionConfigs` 会直接 `.map` functions，
+        // 元素非对象时同样会抛不含字段名的原生错误
+        const shaped = Object.assign(Object.assign({}, config), { functions: normalizeResourceList(config.functions, 'functions'), hosting: normalizeResourceList(config.hosting, 'hosting'), gateway: normalizeGatewayConfig(config.gateway) });
+        return this.normalizeFunctionConfigs(shaped, envId, cwd);
+    }
     /**
      * 归一化声明式函数配置：直接消费 cloudbaserc 的嵌套形状（imageConfig.build），
      * 不做字段平铺映射；非 HTTP 函数原样返回。
@@ -312,10 +338,10 @@ class DeployOrchestrator {
             });
         }
         if (type === 'app') {
-            return this.buildAppPlan({ config, envId });
+            return this.buildAppPlan({ config, envId, cwd });
         }
         if (type === 'hosting') {
-            return this.buildHostingPlans(config);
+            return this.buildHostingPlans(config, cwd);
         }
         return this.buildGatewayPlans(config, envId);
     }
@@ -373,53 +399,190 @@ class DeployOrchestrator {
     }
     /**
      * app 计划：按云端存在性 → create / update
+     *
+     * 附带 buildHint：声明式部署不构建，调用方需要据此自行构建（见 IBuildHint）。
      */
     async buildAppPlan(options) {
-        const { config, envId } = options;
+        const { config, envId, cwd } = options;
         if (!config.app)
             return [];
         const name = config.app.serviceName || 'app';
         const appExists = await this.appExists(name);
+        const buildHint = this.resolveBuildHint(config.app, cwd, 'app');
+        // 与 buildHostingPlans 对称：框架 / 构建 / 部署路径三行必须都给，否则 `--only app`
+        // 的预演比 `--only hosting` 少一段，用户读不到「产物按什么推断、会挂到哪个路径」。
+        // ⚠️ 部署路径必须与 apply 同口径（StaticDeployer.deployApp 的默认 `/${serviceName}`
+        // 与 `normalizeDeployPath` 校验），写错了会让预演与真实发布路径对不上：
+        // 不仅默认值要一致，用户显式配的非法值（相对路径 / 带空格 / 含 shell 元字符 / 含 `..`）
+        // 也必须在预演里点出来 —— apply 会对同一个值抛 INVALID_PARAM，把必然失败的配置
+        // 渲染成正常计划，比「少渲染一行」更误导。
+        const resolvedDeployPath = (0, StaticDeployer_1.tryNormalizeDeployPath)(config.app.deployPath || `/${name}`, 'app.deployPath', true);
+        const details = [
+            // 这里的框架是**配置项**，只用于推断产物目录；写进版本记录的固定是 `static`
+            // （skipBuild 的唯一认可值），两者不是同一个概念，不要合并
+            { label: '框架', value: config.app.framework || 'static' },
+            {
+                label: '构建',
+                value: !buildHint
+                    ? '不构建；产物目录无法按部署口径解析（配置可能非法），apply 时会报错'
+                    : buildHint.buildCommand
+                        ? '不构建，上传已有产物（产物目录按框架/构建配置推断）'
+                        : '不构建，直接上传'
+            },
+            {
+                label: '部署路径',
+                value: resolvedDeployPath !== null && resolvedDeployPath !== void 0 ? resolvedDeployPath : 
+                // 非法值不回显原值：原值可能含 shell 元字符，回显到计划里等于把
+                // 用户可能误粘贴的命令片段再渲染一遍；点明「apply 会报错」即可。
+                // 注意这里不再提「必须以 / 开头」：缺 `/` 会被 normalizeDeployPath 补全，
+                // 真正会让 apply 失败的是这些字符本身
+                '部署路径非法（含空格 / shell 特殊字符 / ../，或以 - 开头），apply 时会报错'
+            }
+        ];
+        // 产物未就绪 / 产物目录解析不出来时，在计划里点明 apply 必定失败。
+        // 只靠 buildHint 字段表达的话，读纯文本计划的人看不到任何异常 ——
+        // 计划项会渲染成与正常部署别无二致的一条。
+        if (!buildHint) {
+            // buildHint 缺省 = 未能按 apply 的口径解析出产物目录（outputDir 类型非法 /
+            // 路径越界 / 软链逃逸），apply 会抛 INVALID_PARAM。
+            details.push({
+                label: '产物',
+                value: '产物目录无法按部署口径解析（app.outputDir 类型非法或路径越界），apply 时会报错'
+            });
+        }
+        else if (!buildHint.artifactReady) {
+            details.push({
+                label: '产物',
+                value: `缺失或为空：${buildHint.outputDir}（需先完成构建）`
+            });
+        }
         return [
             {
                 type: 'app',
                 name,
                 status: appExists ? 'update' : 'create',
                 action: appExists
-                    ? `覆盖更新云应用 ${name}`
-                    : `新建云应用 ${name}`
+                    ? `覆盖更新静态托管应用 ${name}`
+                    : `新建静态托管应用 ${name}`,
+                // 框架 / 构建 / 部署路径恒有三行，无需再判空
+                details,
+                buildHint
             }
         ];
     }
+    /**
+     * 解析 app / hosting 的构建上下文（见 IBuildHint）
+     *
+     * ⚠️ root / outputDir 必须复用 `StaticDeployer` 导出的 `resolveDeployRoot` /
+     * `resolveArtifactDir`，**不能自己再写一份解析**：
+     * 1. plan 与 apply 口径一旦分叉，`artifactReady` 的契约就会反转 —— 例如 apply 拒绝的配置
+     *    plan 报「可以 apply」，或 apply 能部署的配置 plan 报「配置非法」
+     * 2. 不做越界校验时 `hasFilesInDir` 会**同步递归遍历项目外的目录树**；
+     *    `outputDir: '/'` 或用户主目录会让 plan 直接卡死
+     *
+     * 非法值（非字符串 / 含 NUL / 越界 / 软链逃逸）一律返回 `undefined` 而不抛错：
+     * plan 是只读预演，报错留给 apply 的参数校验，让 plan 始终能完整渲染。
+     * `null` / `''` 与「未配置」同义，走推断，不属非法值。
+     */
+    resolveBuildHint(resourceConfig, cwd, kind) {
+        // 校验函数在非法输入上抛 CloudBaseError（apply 的行为），plan 只需降级为「无上下文」
+        try {
+            const root = (0, StaticDeployer_1.resolveDeployRoot)(cwd, resourceConfig.root, `${kind}.root`);
+            const outputDir = (0, StaticDeployer_1.resolveArtifactDir)({ config: resourceConfig, root, kind });
+            return {
+                buildCommand: (0, framework_1.resolveBuildCommand)(resourceConfig, root),
+                outputDir,
+                artifactReady: (0, StaticDeployer_1.hasFilesInDir)(outputDir)
+            };
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
     /**
      * hosting 计划：每次直传覆盖（无本地指纹 skip）
+     *
+     * 声明式部署只部署不构建，因此 `buildCommand` / `framework` 在计划里只用来说明
+     * **产物目录是怎么推断出来的**，不代表会执行构建（历史文案「本地构建后直传」已废除）。
+     * 机器可读的构建上下文见每项的 `buildHint`。
      */
-    buildHostingPlans(config) {
+    buildHostingPlans(config, cwd) {
         const plans = [];
-        for (const h of config.hosting || []) {
+        // 形状由 normalizeConfigInput 保证（一定是对象数组），这里不再需要 `|| []` 守卫
+        for (const h of config.hosting) {
             const name = h.name || 'default';
-            const hasBuild = !!h.buildCommand ||
-                (!!h.framework && h.framework !== 'static' && h.framework !== 'custom');
+            const buildHint = this.resolveBuildHint(h, cwd, 'hosting');
+            // 三分支而非 `!!buildHint?.buildCommand` 二分：buildHint 缺省意味着「产物目录
+            // 没能按 apply 的口径解析出来」（配置类型非法 / 路径越界），此时若落到
+            // 「不构建，直接上传」会把一个 apply 必然报错的配置渲染成最正常的那条文案。
             const details = [
                 { label: '框架', value: h.framework || 'static' },
                 {
                     label: '构建',
-                    value: hasBuild ? '本地构建后上传' : '无构建，直接上传'
+                    value: !buildHint
+                        ? '不构建；产物目录无法按部署口径解析（配置可能非法），apply 时会报错'
+                        : buildHint.buildCommand
+                            ? '不构建，上传已有产物（产物目录按框架/构建配置推断）'
+                            : '不构建，直接上传'
                 },
-                { label: '部署路径', value: h.deployPath || '/' }
+                {
+                    label: '部署路径',
+                    // 与 apply 同口径（`deployHosting` 的 normalizeDeployPath）：预演里显示的
+                    // 必须是**实际生效**的路径，`"deployPath": "web"` 会补全成 `/web`
+                    value: (0, StaticDeployer_1.tryNormalizeDeployPath)(h.deployPath || '/', 'hosting.deployPath', true) || '部署路径非法（apply 时会报错）'
+                }
             ];
+            // 产物未就绪时在计划里直接点明：apply 必定失败，让用户在预演阶段就看到
+            if (buildHint && !buildHint.artifactReady) {
+                details.push({
+                    label: '产物',
+                    value: `缺失或为空：${buildHint.outputDir}（需先完成构建）`
+                });
+            }
             plans.push({
                 type: 'hosting',
                 name,
                 status: 'deploy',
-                action: hasBuild
-                    ? `本地构建后直传静态托管 ${name}`
-                    : `直传覆盖静态托管 ${name}`,
-                details
+                action: `直传覆盖静态托管 ${name}`,
+                details,
+                buildHint
             });
         }
         return plans;
     }
+    /**
+     * 传给网关的 hosting 配置：deployPath 必须是**归一化后**的值
+     *
+     * 同一个字段被两处消费，必须同源：GatewayDeployer 用它生成 `PathRewrite.Prefix`
+     * （parseRouteWithType），StaticDeployer 用它算上传的 `cloudPath`
+     * （`deployHosting` 里的 normalizeDeployPath）。只归一化预演显示的那一份时，
+     * `"deployPath": "web"` 会让产物传到 `/web`、网关前缀却写成 `web`，请求重写后
+     * 落到存储根路径 → 线上 404，而 plan 显示 `/web`、apply 也不报错。
+     *
+     * 判据是「归一化是否成功」，不是「原始值是否为真」—— 下游 `if (hosting.deployPath)`
+     * 只判真值，`123` 与 `'   '` 都算真值，原样下发会得到 `Prefix: 123` / `Prefix: '   '`。
+     *
+     * 三类输入分别处理：
+     * 1. 未配置（null/undefined/''/0/false）：保持原样，与 `deployHosting` 的
+     *    `deployPath || '/'` 同口径，网关侧 falsy → 不生成 PathRewrite（不能补成
+     *    `Prefix: '/'`，否则给存量配置制造出路由 diff）
+     * 2. 非字符串（手改 JSON 的 `"deployPath": 123`）：先 `String()` 收口再归一化，
+     *    与 `deployHosting` 内部 `String(value)` 同源，两侧都得到 `/123`
+     * 3. 纯空白 / 归一化失败（`'   '`、`'../web'`）：**不回落原值**，置为 undefined
+     *    让网关不生成 Prefix，失败出口收敛到 apply 的 INVALID_PARAM，避免「部署成功
+     *    但前缀与真实上传路径不一致」的静默 404
+     *
+     * 入参形状由 `normalizeConfigInput` 保证（一定是对象数组），因此这里不再需要
+     * `Array.isArray` / `|| []` 守卫 —— 守卫分散在各消费点正是「修一处漏一处」的来源。
+     */
+    normalizeHostingsForGateway(hostings) {
+        return hostings.map(h => {
+            if (!h || !h.deployPath)
+                return h;
+            const normalized = (0, StaticDeployer_1.tryNormalizeDeployPath)(String(h.deployPath), 'hosting.deployPath', true);
+            return normalized ? Object.assign(Object.assign({}, h), { deployPath: normalized }) : Object.assign(Object.assign({}, h), { deployPath: undefined });
+        });
+    }
     /**
      * gateway 计划：planRoutes 对比云端路由 → create / update / skip（含变更字段明细）
      */
@@ -431,7 +594,7 @@ class DeployOrchestrator {
         const routePlans = await this.gatewayDeployer.planRoutes({
             routes,
             envId,
-            hostings: config.hosting || []
+            hostings: this.normalizeHostingsForGateway(config.hosting)
         });
         const routeConfigMap = new Map(routes.map(r => [r.path, r]));
         return routePlans.map(rp => {
@@ -464,7 +627,7 @@ class DeployOrchestrator {
         }
     }
     /**
-     * 判断云应用是否已存在（查询失败返回 false，降级为新建判定）
+     * 判断静态托管应用是否已存在（查询失败返回 false，降级为新建判定）
      */
     async appExists(name) {
         try {
@@ -511,7 +674,7 @@ class DeployOrchestrator {
                 return result.url;
             }
             case 'hosting': {
-                const h = (config.hosting || []).find((x) => (x.name || 'default') === item.name);
+                const h = config.hosting.find((x) => (x.name || 'default') === item.name);
                 const result = await this.staticDeployer.deployHosting({ config: h, cwd });
                 return result.url;
             }
@@ -519,8 +682,9 @@ class DeployOrchestrator {
                 const result = await this.gatewayDeployer.deploy({
                     routes: config.gateway.routes,
                     envId,
-                    // 传入 hosting 配置：hosting 路由自动生成 PathRewrite.Prefix = deployPath
-                    hostings: config.hosting || []
+                    // 传入 hosting 配置：hosting 路由自动生成 PathRewrite.Prefix = deployPath。
+                    // 与 plan / StaticDeployer 同口径先归一化，避免前缀与真实上传路径不一致而 404
+                    hostings: this.normalizeHostingsForGateway(config.hosting)
                 });
                 return result.domain;
             }
@@ -530,12 +694,48 @@ class DeployOrchestrator {
      * 轻量 inline 守卫：配置合法 + 目录存在（validateProject 接线点）
      */
     guardConfig(config) {
-        if (!config || typeof config !== 'object') {
-            (0, error_1.throwInvalidParam)('无效的配置：config 必须为对象');
-        }
+        this.guardConfigShape(config);
         if (!config.envId) {
             (0, error_1.throwInvalidParam)('无效的配置：缺少 envId');
         }
     }
+    /**
+     * config 必须是普通对象（不含数组）。
+     *
+     * 拆出来给 plan / apply 共用：此前只有 `deploy` 走 `guardConfig`，`deployPlan`
+     * 完全没校验，`deployPlan({ config: null })` 会在 `buildPlanForType` 里抛原生
+     * TypeError。`envId` 的校验仍留在 `guardConfig` —— plan 侧的 envId 真相源是
+     * `options.envId`（`config.envId` 允许缺省）。
+     */
+    guardConfigShape(config) {
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            (0, error_1.throwInvalidParam)('无效的配置：config 必须为对象');
+        }
+    }
 }
 exports.DeployOrchestrator = DeployOrchestrator;
+/**
+ * 顶层资源声明（`functions` / `hosting` / `gateway.routes`）的入口归一化。
+ *
+ * 非数组一律降级为空数组：与历史 `config.hosting || []` 同口径，存量把手写错的
+ * 配置（`"hosting": ""`）仍能跑通其余资源；数组元素非对象则显式报错 —— 静默丢弃
+ * 会少部署一个站点/一条路由，比报错更难排查。
+ */
+function normalizeResourceList(value, field) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item, index) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            const actualType = item === null ? 'null' : Array.isArray(item) ? 'array' : typeof item;
+            (0, error_1.throwInvalidParam)(`${field}[${index}] 必须是对象，当前类型：${actualType}`);
+        }
+        return item;
+    });
+}
+/** `gateway` 声明归一化：非对象视为「未配置网关」，`routes` 缺省/非数组降级为空数组 */
+function normalizeGatewayConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const gateway = value;
+    return Object.assign(Object.assign({}, gateway), { routes: normalizeResourceList(gateway.routes, 'gateway.routes') });
+}

package/lib/deploy/FunctionDeployer.js

@@ -160,8 +160,11 @@ class FunctionDeployer {
             return undefined;
         }
         const pathValue = config.path || config.gatewayPath;
-        // 推荐方式：通过 API 网关调用云函数（无需配置访问服务）
-        const recommendedUrl = `${(0, domain_1.getGatewayBaseUrl)(this.environment, envId)}/v1/functions/${config.name}`;
+        // 推荐方式：通过 API 网关调用云函数（无需配置访问服务）。
+        // `webfn=true` 必填：网关据此区分「HTTP 云函数」与普通（事件）云函数，
+        // 缺了它请求会被当成事件函数处理、进不到 HTTP 路由。见官方文档「HTTP API 调用格式」：
+        // https://docs.cloudbase.net/cloud-function/function-calls/#api-调用格式
+        const recommendedUrl = `${(0, domain_1.getGatewayBaseUrl)(this.environment, envId)}/v1/functions/${config.name}?webfn=true`;
         if (!pathValue) {
             return recommendedUrl;
         }