@cloudbase/manager-node 5.7.0-beta.1 → 5.7.0-beta.3

package/lib/deploy/DeployOrchestrator.js

@@ -12,6 +12,7 @@ const StaticDeployer_1 = require("./StaticDeployer");
 const GatewayDeployer_1 = require("./GatewayDeployer");
 const StateStore_1 = require("./StateStore");
 const framework_1 = require("./framework");
+const parallel_1 = require("../utils/parallel");
 /** 部署顺序（按依赖：database 最先，函数依赖新 Schema；gateway 最后，依赖函数/hosting） */
 const DEPLOY_ORDER = ['database', 'functions', 'app', 'hosting', 'gateway'];
 /**
@@ -35,10 +36,16 @@ class DeployOrchestrator {
     }
     /**
      * 执行部署
+     *
+     * 编排模型：plan 按「连续相同资源类型」切成 segments，segment 之间严格按
+     * DEPLOY_ORDER 串行；segment 内部按 concurrency 并行执行。失败中断策略：
+     * - 默认 fail-fast：任一资源失败即中断后续（return）
+     * - continueOnError：非 database 资源失败仍继续，最后汇总失败数
+     * - database 失败始终强制中断（无论是否 continueOnError）
      */
     async deploy(options) {
         var _a, _b, _c, _d, _e, _f, _g;
-        const { config, envId, dryRun, cwd = process.cwd(), log } = options;
+        const { config, envId, dryRun, cwd = process.cwd(), log, concurrency = 1, continueOnError = false } = options;
         // 1. 轻量 inline 守卫（validateProject 未接入时的兜底）
         this.guardConfig(config);
         const plan = await this.buildPlan(config, options);
@@ -47,55 +54,89 @@ class DeployOrchestrator {
             return { plan, results: [] };
         }
         const results = [];
-        for (const item of plan) {
-            // skip：产物/配置未变更，静默跳过（不执行、不询问）
-            if (item.status === 'skip') {
-                (_b = log === null || log === void 0 ? void 0 : log.info) === null || _b === void 0 ? void 0 : _b.call(log, `[${item.type}] ${item.name}: ${item.action}`);
-                // reason: 'skip' 标记，供展示层区分「成功」与「跳过」
-                results.push({ type: item.type, name: item.name, ok: true, reason: 'skip' });
-                continue;
+        // 按连续相同 type 切段：段间串行（依赖顺序），段内并行
+        const segments = this.segmentPlan(plan);
+        const limit = Math.max(1, Math.min(Number(concurrency) || 1, 20));
+        for (const segment of segments) {
+            // 段内预判定（顺序执行，保留交互/冲突中断语义）
+            const toExecute = [];
+            let segmentFailed = false;
+            let segmentDbFailed = false;
+            for (const item of segment) {
+                // skip：产物/配置未变更，静默跳过（不执行、不询问）
+                if (item.status === 'skip') {
+                    (_b = log === null || log === void 0 ? void 0 : log.info) === null || _b === void 0 ? void 0 : _b.call(log, `[${item.type}] ${item.name}: ${item.action}`);
+                    results.push({ type: item.type, name: item.name, ok: true, reason: 'skip' });
+                    continue;
+                }
+                (_c = log === null || log === void 0 ? void 0 : log.info) === null || _c === void 0 ? void 0 : _c.call(log, `[${item.type}] ${item.name}: ${item.action}`);
+                // conflict：数据库迁移冲突 → 中断整个部署（后续资源可能依赖新 Schema）
+                if (item.status === 'conflict') {
+                    const message = '检测到冲突，已中断部署';
+                    (_d = log === null || log === void 0 ? void 0 : log.error) === null || _d === void 0 ? void 0 : _d.call(log, `[${item.type}] ${item.name} ${message}`);
+                    results.push({ type: item.type, name: item.name, ok: false, error: message });
+                    if (item.type === 'database') {
+                        return { plan, results };
+                    }
+                    segmentFailed = true;
+                    continue;
+                }
+                // 覆盖确认：仅函数已存在（update）时触发，对齐 tcb fn deploy 的 FunctionConflictChecker 语义
+                // yes=true 直接放行；注入 confirmUpdate 按回调决定；两者都无 → 保守跳过（no-confirm）
+                if (item.type === 'functions' && item.status === 'update') {
+                    let confirmed = false;
+                    if (options.yes) {
+                        confirmed = true;
+                    }
+                    else if (options.confirmUpdate) {
+                        confirmed = await options.confirmUpdate(item);
+                    }
+                    if (!confirmed) {
+                        const reason = options.confirmUpdate
+                            ? 'skipped-by-user'
+                            : 'no-confirm';
+                        (_e = log === null || log === void 0 ? void 0 : log.warn) === null || _e === void 0 ? void 0 : _e.call(log, `[${item.type}] ${item.name} 跳过覆盖更新（${reason}）`);
+                        results.push({ type: item.type, name: item.name, ok: false, reason });
+                        continue;
+                    }
+                }
+                toExecute.push(item);
             }
-            (_c = log === null || log === void 0 ? void 0 : log.info) === null || _c === void 0 ? void 0 : _c.call(log, `[${item.type}] ${item.name}: ${item.action}`);
-            // conflict：数据库迁移冲突 → 中断整个部署（后续资源可能依赖新 Schema）
-            if (item.status === 'conflict') {
-                const message = '检测到冲突，已中断部署';
-                (_d = log === null || log === void 0 ? void 0 : log.error) === null || _d === void 0 ? void 0 : _d.call(log, `[${item.type}] ${item.name} ${message}`);
-                results.push({ type: item.type, name: item.name, ok: false, error: message });
-                if (item.type === 'database') {
+            if (toExecute.length === 0) {
+                // 段内无实际执行项：若本段已因 conflict 标记失败且 fail-fast，则中断
+                if (segmentFailed && !continueOnError) {
                     return { plan, results };
                 }
                 continue;
             }
-            // 覆盖确认：仅函数已存在（update）时触发，对齐 tcb fn deploy 的 FunctionConflictChecker 语义
-            // yes=true 直接放行；注入 confirmUpdate 按回调决定；两者都无 → 保守跳过（no-confirm）
-            if (item.type === 'functions' && item.status === 'update') {
-                let confirmed = false;
-                if (options.yes) {
-                    confirmed = true;
+            // 段内并行执行
+            const controller = new parallel_1.AsyncTaskParallelController(limit);
+            const tasks = toExecute.map((item) => async () => {
+                var _a;
+                try {
+                    const stepResult = await this.executeStep({ item, config, envId, cwd });
+                    results.push({ type: item.type, name: item.name, ok: true, url: stepResult });
                 }
-                else if (options.confirmUpdate) {
-                    confirmed = await options.confirmUpdate(item);
+                catch (e) {
+                    const message = (e === null || e === void 0 ? void 0 : e.message) || String(e);
+                    (_a = log === null || log === void 0 ? void 0 : log.error) === null || _a === void 0 ? void 0 : _a.call(log, `[${item.type}] ${item.name} 部署失败: ${message}`);
+                    results.push({ type: item.type, name: item.name, ok: false, error: message });
+                    segmentFailed = true;
+                    if (item.type === 'database') {
+                        segmentDbFailed = true;
+                    }
                 }
-                if (!confirmed) {
-                    const reason = options.confirmUpdate
-                        ? 'skipped-by-user'
-                        : 'no-confirm';
-                    (_e = log === null || log === void 0 ? void 0 : log.warn) === null || _e === void 0 ? void 0 : _e.call(log, `[${item.type}] ${item.name} 跳过覆盖更新（${reason}）`);
-                    results.push({ type: item.type, name: item.name, ok: false, reason });
-                    continue;
+            });
+            controller.loadTasks(tasks);
+            await controller.run();
+            // 段内失败中断决策
+            if (segmentFailed) {
+                if (segmentDbFailed) {
+                    (_f = log === null || log === void 0 ? void 0 : log.error) === null || _f === void 0 ? void 0 : _f.call(log, '数据库迁移失败，中断部署');
+                    return { plan, results };
                 }
-            }
-            try {
-                const stepResult = await this.executeStep({ item, config, envId, cwd });
-                results.push({ type: item.type, name: item.name, ok: true, url: stepResult });
-            }
-            catch (e) {
-                const message = (e === null || e === void 0 ? void 0 : e.message) || String(e);
-                (_f = log === null || log === void 0 ? void 0 : log.error) === null || _f === void 0 ? void 0 : _f.call(log, `[${item.type}] ${item.name} 部署失败: ${message}`);
-                results.push({ type: item.type, name: item.name, ok: false, error: message });
-                // database 失败中断整个部署：后续资源可能依赖新 Schema
-                if (item.type === 'database') {
-                    (_g = log === null || log === void 0 ? void 0 : log.error) === null || _g === void 0 ? void 0 : _g.call(log, '数据库迁移失败，中断部署');
+                if (!continueOnError) {
+                    (_g = log === null || log === void 0 ? void 0 : log.error) === null || _g === void 0 ? void 0 : _g.call(log, '存在资源部署失败，中断部署');
                     return { plan, results };
                 }
             }
@@ -106,6 +147,33 @@ class DeployOrchestrator {
         }
         return { plan, results };
     }
+    /**
+     * 将扁平 plan 按「连续相同资源类型」切成有序 segments
+     *
+     * segment 之间保留 DEPLOY_ORDER 依赖顺序（严格串行）；segment 内部为同类型
+     * 多实例，可并行执行。例如 [db, fnA, fnB, hostingX, hostingY, gateway]
+     * → [[db], [fnA, fnB], [hostingX, hostingY], [gateway]]
+     */
+    segmentPlan(plan) {
+        const segments = [];
+        let current = [];
+        let currentType;
+        for (const item of plan) {
+            if (currentType === undefined || item.type === currentType) {
+                current.push(item);
+                currentType = item.type;
+            }
+            else {
+                segments.push(current);
+                current = [item];
+                currentType = item.type;
+            }
+        }
+        if (current.length > 0) {
+            segments.push(current);
+        }
+        return segments;
+    }
     /**
      * 部署成功后写回本地 state 快照
      *

package/lib/deploy/GatewayDeployer.js

@@ -72,13 +72,39 @@ class GatewayDeployer {
                 });
             }
             if (toCreate.length > 0) {
-                await envService.createHttpServiceRoute({
-                    EnvId: envId,
-                    Domain: {
-                        Domain: domain,
-                        Routes: toCreate
+                try {
+                    await envService.createHttpServiceRoute({
+                        EnvId: envId,
+                        Domain: {
+                            Domain: domain,
+                            Routes: toCreate
+                        }
+                    });
+                }
+                catch (e) {
+                    // 路由已存在（getExistingRoutes 因域名格式差异漏查，导致误判 create）：
+                    // 幂等降级为「逐个创建，已存在的跳过」，避免整批失败
+                    if (!this.isAlreadyExistsError(e)) {
+                        throw e;
                     }
-                });
+                    for (const route of toCreate) {
+                        try {
+                            await envService.createHttpServiceRoute({
+                                EnvId: envId,
+                                Domain: {
+                                    Domain: domain,
+                                    Routes: [route]
+                                }
+                            });
+                        }
+                        catch (e2) {
+                            // 该条已存在 → 跳过（已收敛）；否则（环境/资源不存在等真实失败）必须抛出，避免静默吞掉
+                            if (!this.isAlreadyExistsError(e2)) {
+                                throw e2;
+                            }
+                        }
+                    }
+                }
             }
             deployedDomains.push(domain);
             for (let i = 0; i < parsedRoutes.length; i++) {
@@ -197,24 +223,80 @@ class GatewayDeployer {
     }
     /**
      * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     *
+     * 匹配策略（优先级从高到低）：
+     * 1. 用 Filters 精确查询目标域名：DescribeHTTPServiceRoute 不带 Filters 时返回的 Domains
+     *    列表可能不完整（如 lowcode 环境 TotalCount=67 但 Domains 只返回部分，HTTPSERVICE 的
+     *    .app.tcloudbase.com 域名缺失），导致云端已有路由查不到被误判为 create
+     * 2. 降级：不带 Filters 全量查询，按域名归一化匹配（去协议/尾斜杠/转小写）
+     *    若目标域名找不到则返回空（保留 domain 维度，避免把其他域名同 path 误判为已存在）
      */
     async getExistingRoutes(envId, domain) {
+        var _a;
+        const normalizedTarget = this.normalizeDomain(domain);
+        // 1. Filters 精确查询目标域名（deleteCustomDomain 同款用法）
         try {
             const res = await this.environment.getEnvService().describeHttpServiceRoute({
-                EnvId: envId
+                EnvId: envId,
+                Filters: [{ Name: 'Domain', Values: [domain] }]
             });
-            const targetDomain = (res.Domains || []).find(d => d.Domain === domain);
+            const targetDomain = (res.Domains || []).find((d) => this.normalizeDomain(d.Domain) === normalizedTarget);
             const map = new Map();
             for (const route of (targetDomain === null || targetDomain === void 0 ? void 0 : targetDomain.Routes) || []) {
                 map.set(route.Path, route);
             }
+            if (map.size > 0) {
+                return map;
+            }
+        }
+        catch (_b) {
+            // Filters 查询失败（环境不支持）→ 走降级
+        }
+        // 2. 降级：全量查询 + 归一化匹配（严格保留域名维度）
+        try {
+            const res = await this.environment.getEnvService().describeHttpServiceRoute({
+                EnvId: envId
+            });
+            const targetDomain = (res.Domains || []).find((d) => this.normalizeDomain(d.Domain) === normalizedTarget);
+            const map = new Map();
+            if ((_a = targetDomain === null || targetDomain === void 0 ? void 0 : targetDomain.Routes) === null || _a === void 0 ? void 0 : _a.length) {
+                for (const route of targetDomain.Routes) {
+                    map.set(route.Path, route);
+                }
+            }
+            // 不再按 path 跨域兜底归并：
+            // 路由唯一键是 (domain, path)，不同域名同 path 合法；
+            // 若目标域名缺失，返回空并交由 create + AlreadyExists 幂等降级收敛，避免误判 skip/update。
             return map;
         }
-        catch (_a) {
+        catch (_c) {
             // 查询失败（首次部署/环境未初始化）视为无已存在路由
             return new Map();
         }
     }
+    /**
+     * 域名归一化：去协议、去尾斜杠、转小写（用于幂等收敛的域名匹配）
+     */
+    normalizeDomain(domain) {
+        if (!domain)
+            return '';
+        return domain.replace(/^https?:\/\//, '').replace(/\/+$/, '').toLowerCase();
+    }
+    /**
+     * 判断错误是否属于「路由已存在/已占用」类（幂等降级专用）
+     *
+     * 只匹配明确的重复/占用语义（code 含 AlreadyExists/Duplicate/ResourceInUse/Conflict，
+     * 或 message 含 already exists），并显式排除否定语义（not exists/not found 等），
+     * 避免把「环境/资源不存在」等真实失败误判为「已存在」而被静默跳过
+     */
+    isAlreadyExistsError(e) {
+        const msg = String((e === null || e === void 0 ? void 0 : e.message) || '') + String((e === null || e === void 0 ? void 0 : e.code) || '');
+        // 否定语义优先：资源/环境不存在 → 不是「已存在」，必须抛出让调用方感知真实失败
+        if (/not\s*exists?|doesn't?\s*exist|does\s+not\s+exist|not\s*found/i.test(msg)) {
+            return false;
+        }
+        return /already\s*exists?|already[_\s-]*exists|AlreadyExists|ALREADY_EXISTS|RESOURCE_ALREADY_EXISTS|Duplicate|ResourceInUse|ResourceOccupied|Conflict|已存在/i.test(msg);
+    }
     /**
      * 判断期望路由与云端已存在路由是否一致
      *
@@ -395,8 +477,16 @@ class GatewayDeployer {
                     `或为该路由显式配置 pathRewrite.prefix/staticStorePrefix 以引用已部署的托管实例`);
             }
             // 未显式配置时自动生成 Prefix = hosting 部署路径
+            // 透传会覆盖路径重写：用户显式开启 enablePathTransmission=true 时与自动重写冲突，
+            // 不再静默强制关闭（避免反向改写云端用户显式配置），明确报错让用户二选一
             if (hosting.deployPath) {
-                return Object.assign(Object.assign({}, parsed), { PathRewrite: { Prefix: hosting.deployPath } });
+                if (route.enablePathTransmission === true) {
+                    throw new error_1.CloudBaseError(`网关路由 ${route.path} 目标为 hosting:${hostingName} 且未显式配置 pathRewrite：` +
+                        `部署将自动生成 PathRewrite.Prefix=${hosting.deployPath}，` +
+                        `但 enablePathTransmission=true 会覆盖路径重写导致请求打不到托管部署路径。` +
+                        `请删除 enablePathTransmission，或显式配置 pathRewrite.prefix`);
+                }
+                return Object.assign(Object.assign({}, parsed), { EnablePathTransmission: false, PathRewrite: { Prefix: hosting.deployPath } });
             }
             return parsed;
         }

package/lib/deploy/StaticDeployer.js

@@ -79,28 +79,6 @@ class StaticDeployer {
             ignore: config.ignore || ['.DS_Store']
         };
         await this.environment.getHostingService().uploadFiles(hostingOptions);
-        // SPA 回退：
-        // - true：404 时返回 index.html（OriginalHttpStatus=Disabled 保留 200，Charity404=Disabled 防公益页面覆盖）
-        // - false：显式取消，重置 ErrorDocument 为空（静态托管首页 IndexDocument 保留）
-        // - undefined：不关心，保持云端现状
-        // 注意：putBucketWebsite 是整体覆盖，设置前先读取现有配置并保留 RoutingRules + AutoAddressing，
-        // 否则会清空用户之前在控制台配置的路由规则（如路径前缀重写/错误码重定向）和忽略 .html 扩展名能力
-        if (config.spaFallback === true) {
-            try {
-                await this.environment.getHostingService().setWebsiteDocument(Object.assign({ indexDocument: 'index.html', errorDocument: 'index.html', originalHttpStatus: 'Disabled', charity404: 'Disabled' }, (await this.preserveWebsiteConfig())));
-            }
-            catch (e) {
-                throw new error_1.CloudBaseError(`[${name}] 设置 SPA 回退失败（spaFallback: true）：${(e === null || e === void 0 ? void 0 : e.message) || String(e)}`);
-            }
-        }
-        else if (config.spaFallback === false) {
-            try {
-                await this.environment.getHostingService().setWebsiteDocument(Object.assign({ indexDocument: 'index.html', errorDocument: '' }, (await this.preserveWebsiteConfig())));
-            }
-            catch (e) {
-                throw new error_1.CloudBaseError(`[${name}] 取消 SPA 回退失败（spaFallback: false）：${(e === null || e === void 0 ? void 0 : e.message) || String(e)}`);
-            }
-        }
         const url = await this.resolveHostingUrl(cloudPath);
         return { name, url, wroteRecord: false };
     }
@@ -188,34 +166,6 @@ class StaticDeployer {
         const url = await this.resolveAppUrl(serviceName, config.deployPath || `/${serviceName}`);
         return { name: serviceName, url, wroteRecord: true };
     }
-    /**
-     * 读取现有静态网站配置并保留 RoutingRules + AutoAddressing
-     * （putBucketWebsite 为整体覆盖，设置 SPA 回退前必须带回已有配置，否则会被清空）
-     */
-    async preserveWebsiteConfig() {
-        var _a;
-        try {
-            const res = await this.environment.getHostingService().getWebsiteConfig();
-            const website = (res === null || res === void 0 ? void 0 : res.WebsiteConfiguration) || {};
-            const rules = website.RoutingRules || [];
-            return {
-                routingRules: rules.map((r) => {
-                    var _a, _b, _c, _d;
-                    return ({
-                        keyPrefixEquals: (_a = r.Condition) === null || _a === void 0 ? void 0 : _a.KeyPrefixEquals,
-                        httpErrorCodeReturnedEquals: (_b = r.Condition) === null || _b === void 0 ? void 0 : _b.HttpErrorCodeReturnedEquals,
-                        replaceKeyWith: (_c = r.Redirect) === null || _c === void 0 ? void 0 : _c.ReplaceKeyWith,
-                        replaceKeyPrefixWith: (_d = r.Redirect) === null || _d === void 0 ? void 0 : _d.ReplaceKeyPrefixWith
-                    });
-                }),
-                autoAddressing: (_a = website.AutoAddressing) === null || _a === void 0 ? void 0 : _a.Status
-            };
-        }
-        catch (_b) {
-            // 查询失败（未开启静态网站/首次部署）视为无已有配置
-            return { routingRules: [], autoAddressing: undefined };
-        }
-    }
     /**
      * 解析 hosting 访问地址：https://{CdnDomain}{deployPath}
      */

package/lib/deploy/domain.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveAccessServiceDomain = resolveAccessServiceDomain;
 exports.getGatewayBaseUrl = getGatewayBaseUrl;
+/** 环境 HTTP 访问服务默认域名后缀（如 `xxx-1326375956.ap-shanghai.${ACCESS_DOMAIN_SUFFIX}`） */
+const ACCESS_DOMAIN_SUFFIX = 'app.tcloudbase.com';
 /**
- * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
  *
  * 关键：用 `UserInfo.AppId`（腾讯云 appid）而非 `UserInfo.Uin`（账号 uin）。
- * 控制台默认域名格式是 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ * 控制台默认域名格式是 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
  * （如 `xxx-1326375956.ap-shanghai.app.tcloudbase.com`），与 cookie 中的 `appid` 字段对应。
  * AppId/Region 缺失或查询失败时返回 undefined
  */
@@ -17,7 +19,7 @@ async function resolveAccessServiceDomain(environment, envId) {
         const appId = (_a = EnvInfo === null || EnvInfo === void 0 ? void 0 : EnvInfo.UserInfo) === null || _a === void 0 ? void 0 : _a.AppId;
         const region = EnvInfo === null || EnvInfo === void 0 ? void 0 : EnvInfo.Region;
         if (appId && region) {
-            return `${envId}-${appId}.${region}.app.tcloudbase.com`;
+            return `${envId}-${appId}.${region}.${ACCESS_DOMAIN_SUFFIX}`;
         }
     }
     catch (_b) {

package/lib/deploy/function/builders/cloud.js

@@ -41,6 +41,12 @@ const POLL_MAX_TRANSIENT_ERRORS = 5;
 const SAFE_REGISTRY_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._\-/]*$/;
 /** tag 白名单：字母数字、下划线、点、中划线 */
 const SAFE_TAG_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+/** Dockerfile 路径：只能是构建上下文内的安全相对路径 */
+const SAFE_DOCKERFILE_PATTERN = /^[a-zA-Z0-9._\-/]+$/;
+/** Docker build arg key 与环境变量同规则 */
+const SAFE_BUILD_ARG_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 疑似敏感构建参数名；cloud 构建会把参数写入命令/构建记录，因此直接拒绝 */
+const SENSITIVE_BUILD_ARG_KEY_PATTERN = /(secret|token|password|passwd|credential|private[_-]?key|access[_-]?key)/i;
 /** 校验仓库/命名空间等镜像地址片段，拒绝命令注入风险字符 */
 function assertSafeRegistryToken(value, field) {
     if (!SAFE_REGISTRY_PATTERN.test(value)) {
@@ -62,6 +68,40 @@ function assertSafeTag(tag) {
         });
     }
 }
+/** 校验 Dockerfile 路径，避免通过 shell command 逃逸构建上下文 */
+function assertSafeDockerfile(dockerfile) {
+    const value = dockerfile.trim();
+    const segments = value.split('/');
+    if (!value ||
+        value.length > 512 ||
+        value.startsWith('/') ||
+        value.startsWith('\\') ||
+        /^[A-Za-z]:[\\/]/.test(value) ||
+        !SAFE_DOCKERFILE_PATTERN.test(value) ||
+        segments.some(segment => segment === '..')) {
+        throw new error_1.CloudBaseError('Dockerfile 路径不合法，需为构建上下文内的安全相对路径', {
+            code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_DOCKERFILE_INVALID
+        });
+    }
+}
+/** 校验 cloud 构建参数；值进入 CloudApp Env，command 中只引用固定变量名 */
+function assertSafeBuildArgs(buildArgs) {
+    for (const [key, value] of Object.entries(buildArgs)) {
+        if (!SAFE_BUILD_ARG_KEY_PATTERN.test(key)) {
+            throw new error_1.CloudBaseError(`构建参数名不合法：${key}`, {
+                code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID
+            });
+        }
+        if (SENSITIVE_BUILD_ARG_KEY_PATTERN.test(key)) {
+            throw new error_1.CloudBaseError(`构建参数 ${key} 可能包含敏感信息；cloud 构建禁止通过 buildArgs 传递密钥`, { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID });
+        }
+        if (typeof value !== 'string' || /[\u0000]/.test(value)) {
+            throw new error_1.CloudBaseError(`构建参数 ${key} 的值必须是无 NUL 字符的字符串`, {
+                code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID
+            });
+        }
+    }
+}
 /** 个人版 CCR 默认域名 */
 const DEFAULT_PERSONAL_REGISTRY = 'ccr.ccs.tencentyun.com';
 /** 注入到构建上下文 zip 中的推送脚本相对路径（与 CustomSteps 的 push命令一致） */
@@ -222,18 +262,50 @@ function resolveTarget(config) {
     };
 }
 /**
- * 生成固定的 CustomSteps 模板（build + push）
+ * 解析并校验 cloud 构建执行参数。
+ * 用户值不直接拼入 shell：Dockerfile/platform/buildArgs value 均通过 CloudApp Env 注入，
+ * CustomSteps 只包含 SDK 固定命令和经过白名单校验的 build arg key。
+ */
+function resolveCloudBuildOptions(config) {
+    const dockerfile = config.build.dockerfile || types_1.DEFAULT_DOCKERFILE;
+    const platform = config.build.platform || types_1.DEFAULT_IMAGE_PLATFORM;
+    const buildArgs = config.build.buildArgs || {};
+    assertSafeDockerfile(dockerfile);
+    if (platform !== types_1.DEFAULT_IMAGE_PLATFORM) {
+        throw new error_1.CloudBaseError(`当前仅支持构建 ${types_1.DEFAULT_IMAGE_PLATFORM} 镜像`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_PLATFORM_INVALID
+        });
+    }
+    assertSafeBuildArgs(buildArgs);
+    return {
+        dockerfile,
+        platform,
+        buildArgs,
+        forceBuild: config.build.forceBuild === true
+    };
+}
+/**
+ * 生成固定的 CustomSteps 模板（build + push）。
  *
- * 关键安全点：command 完全由 SDK 生成，用户输入只以构建环境变量方式注入
- * （$TCR_REGISTRY / $TCR_NAMESPACE / $CLOUDBASE_SERVICE_NAME / $CLOUDBASE_VERSION_NAME），
- * 这些变量的值已在 resolveTarget 中做白名单校验，故命令本身无注入面。
+ * Dockerfile、platform 和 build arg value 通过 CloudApp Env 注入；只有通过严格
+ * ENV key 校验的 build arg key 会进入固定 command。forceBuild 显式映射为 --no-cache。
  */
-function buildCustomSteps() {
+function buildCustomSteps(options) {
+    const buildArgs = Object.keys(options.buildArgs)
+        .sort()
+        .map(key => `--build-arg ${key}="$BUILD_ARG_${key}"`)
+        .join(' ');
+    const noCache = options.forceBuild ? ' --no-cache' : '';
+    const extraArgs = buildArgs ? ` ${buildArgs}` : '';
     return [
         {
             name: 'build-image',
-            command: 'docker build -t ' +
-                '$TCR_REGISTRY/$TCR_NAMESPACE/$CLOUDBASE_SERVICE_NAME:$CLOUDBASE_VERSION_NAME .'
+            command: 'docker build' +
+                ' --platform "$CLOUDBASE_BUILD_PLATFORM"' +
+                ' -f "$CLOUDBASE_DOCKERFILE"' +
+                noCache +
+                extraArgs +
+                ' -t $TCR_REGISTRY/$TCR_NAMESPACE/$CLOUDBASE_SERVICE_NAME:$CLOUDBASE_VERSION_NAME .'
         },
         {
             name: 'push-image',
@@ -249,10 +321,16 @@ function buildCustomSteps() {
  * - TCR_INSTANCE_ID：仅企业版 TCR 注入，脚本据此走 CreateInstanceToken 分支；
  *   个人版 CCR 不注入，脚本走 STS 直接 docker login 分支。
  */
-function buildEnv(target, region) {
+function buildEnv(target, buildOptions, region) {
     const env = [
         { key: 'TCR_REGISTRY', value: target.registry },
-        { key: 'TCR_NAMESPACE', value: target.namespace }
+        { key: 'TCR_NAMESPACE', value: target.namespace },
+        { key: 'CLOUDBASE_DOCKERFILE', value: buildOptions.dockerfile },
+        { key: 'CLOUDBASE_BUILD_PLATFORM', value: buildOptions.platform },
+        ...Object.entries(buildOptions.buildArgs).map(([key, value]) => ({
+            key: `BUILD_ARG_${key}`,
+            value
+        }))
     ];
     if (region) {
         env.push({ key: 'TCR_REGION', value: region });
@@ -331,7 +409,8 @@ function summarizeFailedSteps(steps) {
 async function buildImageOnCloud(config, service, options = {}) {
     const { onLog, region } = options;
     const target = resolveTarget(config);
-    // 在打包和上传前完成真实消费字段校验，避免额外维护环境变量名清单。
+    const buildOptions = resolveCloudBuildOptions(config);
+    // 在打包和上传前完成真实消费字段校验，避免无效配置触发远端资源操作。
     const registryCredentials = buildRegistryCredentials(config, target);
     const serviceName = target.serviceName;
     const cwd = config.build.cwd || config.functionPath || process.cwd();
@@ -361,9 +440,12 @@ async function buildImageOnCloud(config, service, options = {}) {
         const created = await service.createBuild({
             serviceName,
             cosTimestamp: cosInfo.unixTimestamp,
-            env: [...buildEnv(target, region), ...registryCredentials.env],
+            env: [
+                ...buildEnv(target, buildOptions, region),
+                ...registryCredentials.env
+            ],
             secrets: registryCredentials.secrets,
-            customSteps: buildCustomSteps()
+            customSteps: buildCustomSteps(buildOptions)
         });
         if (!(created === null || created === void 0 ? void 0 : created.versionName)) {
             throw new error_1.CloudBaseError('触发云端构建失败：返回缺少 VersionName', {

package/lib/deploy/function/config-guard.js

@@ -449,7 +449,11 @@ function checkBuildTarget(raw, checks) {
                     checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID, `构建参数 ${key} 的值必须是字符串`));
                 }
                 if (SENSITIVE_KEY_PATTERN.test(key)) {
-                    checks.push(warn(types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID, `构建参数 ${key} 可能包含敏感信息`, '构建参数会写入镜像构建记录，请改用运行时环境变量或密钥管理'));
+                    const message = `构建参数 ${key} 可能包含敏感信息`;
+                    const remediation = '构建参数会写入镜像构建记录，请改用运行时环境变量或密钥管理';
+                    checks.push(raw.buildStrategy === 'cloud'
+                        ? fail(types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID, message, remediation)
+                        : warn(types_1.FUNCTION_DEPLOY_ERROR.BUILD_ARG_INVALID, message, remediation));
                 }
             });
         }

package/lib/deploy/function/local-builder.js

@@ -64,6 +64,22 @@ function parseDigest(output) {
     const match = output.match(/Digest:\s*(sha256:[0-9a-f]{64})/i);
     return match ? match[1] : undefined;
 }
+/** 生成脱敏后的命令摘要，避免 buildArgs 值进入部署日志 */
+function formatBuildCommandForLog(args) {
+    const displayArgs = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        displayArgs.push(arg);
+        if (arg === '--build-arg' && index + 1 < args.length) {
+            const buildArg = args[index + 1];
+            const separatorIndex = buildArg.indexOf('=');
+            const key = separatorIndex >= 0 ? buildArg.slice(0, separatorIndex) : buildArg;
+            displayArgs.push(`${key}=<redacted>`);
+            index += 1;
+        }
+    }
+    return `docker ${displayArgs.join(' ')}`;
+}
 /**
  * 本地构建镜像并推送到目标仓库
  *
@@ -90,16 +106,19 @@ async function buildAndPushImage(config, onLog, deps = defaultDeps) {
     const platform = config.build.platform || types_1.DEFAULT_IMAGE_PLATFORM;
     // 组装 buildx 参数：构建目标平台镜像并直接推送
     const args = ['buildx', 'build', '--platform', platform, '-f', dockerfilePath, '-t', imageUri];
+    if (config.build.forceBuild) {
+        args.push('--no-cache');
+    }
     // 追加构建参数（键值均作为独立参数，无 shell 拼接）
     const buildArgs = config.build.buildArgs || {};
     for (const key of Object.keys(buildArgs)) {
         args.push('--build-arg', `${key}=${buildArgs[key]}`);
     }
     args.push('--push', context);
-    onLog === null || onLog === void 0 ? void 0 : onLog(`执行 docker ${args.join(' ')}`);
+    onLog === null || onLog === void 0 ? void 0 : onLog(`执行 ${formatBuildCommandForLog(args)}`);
     const build = await deps.runCommand('docker', args);
     if (!build.ok) {
-        throw new error_1.CloudBaseError(`镜像构建或推送失败：${build.stderr || build.stdout}`, {
+        throw new error_1.CloudBaseError('镜像构建或推送失败，请查看 Docker 构建输出定位具体原因', {
             code: types_1.FUNCTION_DEPLOY_ERROR.LOCAL_PUSH_FAILED
         });
     }

package/lib/projectValidator/index.js

@@ -42,7 +42,7 @@ class ProjectValidator {
             const resourceIssues = this.validateResources(cwd, loaded.config);
             errors.push(...resourceIssues.errors);
             warnings.push(...resourceIssues.warnings);
-            this.validateConsistency(loaded.config, errors);
+            this.validateConsistency(loaded.config, errors, warnings);
         }
         const summary = this.getSummary(loaded.config);
         return {
@@ -277,11 +277,76 @@ class ProjectValidator {
         }
         return { errors, warnings };
     }
-    validateConsistency(config, errors) {
+    validateConsistency(config, errors, warnings = []) {
         this.validateUniqueNames('functions', config.functions || [], errors);
         this.validateUniqueNames('hosting', config.hosting || [], errors);
         this.validateUniqueField('hosting', config.hosting || [], { field: 'deployPath', errors });
         this.validateGatewayTargets(config, errors);
+        this.validateGatewayPathRewriteConflicts(config, warnings);
+        this.validateHostingSubPathBaseRisks(config, warnings);
+    }
+    /**
+     * 检测 hosting 路由中 enablePathTransmission=true 与自动生成 pathRewrite 的冲突
+     *
+     * hosting 目标未显式配置 pathRewrite 时，部署会自动生成 PathRewrite.Prefix = hosting.deployPath。
+     * 若同时显式开启 enablePathTransmission=true，路径透传会覆盖路径重写，导致请求打到错误的托管路径（404）。
+     */
+    validateGatewayPathRewriteConflicts(config, warnings) {
+        var _a;
+        const hostingMap = new Map((config.hosting || []).map((h) => [h.name, h]));
+        (((_a = config.gateway) === null || _a === void 0 ? void 0 : _a.routes) || []).forEach((route, index) => {
+            var _a, _b, _c;
+            if (!((_a = route.target) === null || _a === void 0 ? void 0 : _a.startsWith('hosting:')))
+                return;
+            // 用户显式配置了 pathRewrite → 无自动重写，无冲突
+            if (((_b = route.pathRewrite) === null || _b === void 0 ? void 0 : _b.prefix) || ((_c = route.pathRewrite) === null || _c === void 0 ? void 0 : _c.staticStorePrefix))
+                return;
+            // 未显式开启透传 → 无冲突
+            if (route.enablePathTransmission !== true)
+                return;
+            const hostingName = route.target.slice('hosting:'.length);
+            const hosting = hostingMap.get(hostingName);
+            // hosting 无 deployPath → 不会自动生成 PathRewrite，不冲突
+            if (!(hosting === null || hosting === void 0 ? void 0 : hosting.deployPath))
+                return;
+            warnings.push({
+                level: 'warning',
+                resource: `gateway.routes[${index}]`,
+                field: 'enablePathTransmission',
+                message: `hosting 路由 ${route.target} 未显式配置 pathRewrite，部署将自动生成 ` +
+                    `PathRewrite.Prefix=${hosting.deployPath}，但 enablePathTransmission=true 会覆盖路径重写，` +
+                    `导致请求打不到托管实际部署路径`,
+                fix: '删除 enablePathTransmission，让自动生成的 pathRewrite 生效；' +
+                    '或显式配置 pathRewrite.prefix 指向托管部署路径',
+            });
+        });
+    }
+    /**
+     * 子路径部署（deployPath !== '/'）下，前端构建产物若仍使用根路径 base（如 Vite 默认 '/'），
+     * 会导致资源请求落到 /assets/* 而非 /{deployPath}/assets/*，出现 404/白屏。
+     *
+     * 这里在“可能存在构建步骤”的 hosting 配置上给出防坑告警。
+     */
+    validateHostingSubPathBaseRisks(config, warnings) {
+        ;
+        (config.hosting || []).forEach((hosting, index) => {
+            const deployPath = typeof hosting.deployPath === 'string' ? hosting.deployPath.trim() : '';
+            if (!deployPath || deployPath === '/')
+                return;
+            const framework = typeof hosting.framework === 'string' ? hosting.framework.trim().toLowerCase() : '';
+            const hasBuildStep = (typeof hosting.buildCommand === 'string' && hosting.buildCommand.trim().length > 0) ||
+                (!!framework && framework !== 'static' && framework !== 'custom');
+            if (!hasBuildStep)
+                return;
+            warnings.push({
+                level: 'warning',
+                resource: `hosting[${index}]`,
+                field: 'deployPath',
+                message: `静态托管部署在子路径 ${deployPath}，请确认前端构建 base 与子路径匹配，` +
+                    `否则资源可能请求到根路径（如 /assets/*）导致 404/白屏`,
+                fix: "建议将前端 base 配置为 './' 或与 deployPath 对齐（例如 '/serviceName/'）",
+            });
+        });
     }
     validateUniqueNames(resource, items, errors) {
         const names = new Map();

package/lib/utils/index.js

@@ -58,6 +58,17 @@ async function compressToZip(option) {
         fs_extra_1.default.mkdirpSync(extraTmpDir);
     }
     return new Promise((resolve, reject) => {
+        // 幂等清理：archiver 的 error 事件与 output.close 事件在不同代码路径上，
+        // 但 extraEntries 写入异常分支调用 archive.abort() 后的异步收尾流程
+        // 仍可能间接触发 archive.error，导致 cleanupExtra 被多次调用。
+        // 用 done 标志保证清理和 resolve/reject 仅生效一次。
+        let done = false;
+        const settle = (fn) => {
+            if (done)
+                return;
+            done = true;
+            fn();
+        };
         const cleanupExtra = () => {
             if (extraTmpDir) {
                 try {
@@ -71,15 +82,19 @@ async function compressToZip(option) {
         const output = fs_extra_1.default.createWriteStream(outputPath);
         const archive = (0, archiver_1.default)('zip');
         output.on('close', function () {
-            cleanupExtra();
-            resolve({
-                zipPath: outputPath,
-                size: Math.ceil(archive.pointer() / 1024)
+            settle(() => {
+                cleanupExtra();
+                resolve({
+                    zipPath: outputPath,
+                    size: Math.ceil(archive.pointer() / 1024)
+                });
             });
         });
         archive.on('error', function (err) {
-            cleanupExtra();
-            reject(err);
+            settle(() => {
+                cleanupExtra();
+                reject(err);
+            });
         });
         archive.pipe(output);
         // append files from a glob pattern
@@ -102,9 +117,11 @@ async function compressToZip(option) {
                 });
             }
             catch (error) {
-                cleanupExtra();
-                archive.abort();
-                reject(error);
+                settle(() => {
+                    cleanupExtra();
+                    archive.abort();
+                    reject(error);
+                });
                 return;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/manager-node",
-    "version": "5.7.0-beta.1",
+    "version": "5.7.0-beta.3",
     "description": "The node manage service api for cloudbase.",
     "main": "lib/index.js",
     "scripts": {

package/types/deploy/DeployOrchestrator.d.ts

@@ -20,6 +20,10 @@ export interface IDeployOptions {
     confirmUpdate?: (item: IDeployPlanItem) => Promise<boolean>;
     /** 强制云端对比（漂移检测）：忽略本地 state 快照的 skip 判定，强制重新对比/部署 */
     refresh?: boolean;
+    /** 同类型资源最大并行数，默认 1（串行）。仅作用于同类型连续实例之间，跨类型依赖顺序不变 */
+    concurrency?: number;
+    /** 失败后继续部署其余资源（database 失败仍强制中断） */
+    continueOnError?: boolean;
     log?: {
         info?: (msg: string) => void;
         success?: (msg: string) => void;
@@ -85,8 +89,22 @@ export declare class DeployOrchestrator {
     deployPlan(options: IDeployOptions): Promise<IDeployPlanItem[]>;
     /**
      * 执行部署
+     *
+     * 编排模型：plan 按「连续相同资源类型」切成 segments，segment 之间严格按
+     * DEPLOY_ORDER 串行；segment 内部按 concurrency 并行执行。失败中断策略：
+     * - 默认 fail-fast：任一资源失败即中断后续（return）
+     * - continueOnError：非 database 资源失败仍继续，最后汇总失败数
+     * - database 失败始终强制中断（无论是否 continueOnError）
      */
     deploy(options: IDeployOptions): Promise<IDeployResult>;
+    /**
+     * 将扁平 plan 按「连续相同资源类型」切成有序 segments
+     *
+     * segment 之间保留 DEPLOY_ORDER 依赖顺序（严格串行）；segment 内部为同类型
+     * 多实例，可并行执行。例如 [db, fnA, fnB, hostingX, hostingY, gateway]
+     * → [[db], [fnA, fnB], [hostingX, hostingY], [gateway]]
+     */
+    private segmentPlan;
     /**
      * 部署成功后写回本地 state 快照
      *

package/types/deploy/GatewayDeployer.d.ts

@@ -104,8 +104,27 @@ export declare class GatewayDeployer {
     }>>;
     /**
      * 查询指定域名下已存在的路由（幂等收敛用），返回 Map<path, 云端路由详情>
+     *
+     * 匹配策略（优先级从高到低）：
+     * 1. 用 Filters 精确查询目标域名：DescribeHTTPServiceRoute 不带 Filters 时返回的 Domains
+     *    列表可能不完整（如 lowcode 环境 TotalCount=67 但 Domains 只返回部分，HTTPSERVICE 的
+     *    .app.tcloudbase.com 域名缺失），导致云端已有路由查不到被误判为 create
+     * 2. 降级：不带 Filters 全量查询，按域名归一化匹配（去协议/尾斜杠/转小写）
+     *    若目标域名找不到则返回空（保留 domain 维度，避免把其他域名同 path 误判为已存在）
      */
     private getExistingRoutes;
+    /**
+     * 域名归一化：去协议、去尾斜杠、转小写（用于幂等收敛的域名匹配）
+     */
+    private normalizeDomain;
+    /**
+     * 判断错误是否属于「路由已存在/已占用」类（幂等降级专用）
+     *
+     * 只匹配明确的重复/占用语义（code 含 AlreadyExists/Duplicate/ResourceInUse/Conflict，
+     * 或 message 含 already exists），并显式排除否定语义（not exists/not found 等），
+     * 避免把「环境/资源不存在」等真实失败误判为「已存在」而被静默跳过
+     */
+    private isAlreadyExistsError;
     /**
      * 判断期望路由与云端已存在路由是否一致
      *

package/types/deploy/StaticDeployer.d.ts

@@ -28,8 +28,6 @@ export interface IHostingDeployConfig {
     ignore?: string[];
     /** 构建时环境变量（注入本地构建进程，非敏感） */
     envVariables?: Record<string, string | number | boolean>;
-    /** SPA 回退：true 时 404 返回 index.html */
-    spaFallback?: boolean;
 }
 export interface IStaticDeployResult {
     name: string;
@@ -80,11 +78,6 @@ export declare class StaticDeployer {
      * app 云端构建：上传源码 ZIP → createApp 云端构建 → 写版本记录
      */
     private deployAppCloud;
-    /**
-     * 读取现有静态网站配置并保留 RoutingRules + AutoAddressing
-     * （putBucketWebsite 为整体覆盖，设置 SPA 回退前必须带回已有配置，否则会被清空）
-     */
-    private preserveWebsiteConfig;
     /**
      * 解析 hosting 访问地址：https://{CdnDomain}{deployPath}
      */

package/types/deploy/domain.d.ts

@@ -1,9 +1,9 @@
 import { Environment } from '../environment';
 /**
- * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
  *
  * 关键：用 `UserInfo.AppId`（腾讯云 appid）而非 `UserInfo.Uin`（账号 uin）。
- * 控制台默认域名格式是 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ * 控制台默认域名格式是 `${envId}-${AppId}.${region}.${ACCESS_DOMAIN_SUFFIX}`
  * （如 `xxx-1326375956.ap-shanghai.app.tcloudbase.com`），与 cookie 中的 `appid` 字段对应。
  * AppId/Region 缺失或查询失败时返回 undefined
  */

package/types/projectValidator/index.d.ts

@@ -13,6 +13,20 @@ export declare class ProjectValidator {
     private isPersonalCloudFunction;
     private validateResources;
     private validateConsistency;
+    /**
+     * 检测 hosting 路由中 enablePathTransmission=true 与自动生成 pathRewrite 的冲突
+     *
+     * hosting 目标未显式配置 pathRewrite 时，部署会自动生成 PathRewrite.Prefix = hosting.deployPath。
+     * 若同时显式开启 enablePathTransmission=true，路径透传会覆盖路径重写，导致请求打到错误的托管路径（404）。
+     */
+    private validateGatewayPathRewriteConflicts;
+    /**
+     * 子路径部署（deployPath !== '/'）下，前端构建产物若仍使用根路径 base（如 Vite 默认 '/'），
+     * 会导致资源请求落到 /assets/* 而非 /{deployPath}/assets/*，出现 404/白屏。
+     *
+     * 这里在“可能存在构建步骤”的 hosting 配置上给出防坑告警。
+     */
+    private validateHostingSubPathBaseRisks;
     private validateUniqueNames;
     private validateUniqueField;
     private validateGatewayTargets;