@cloudbase/manager-node 5.7.1-beta.1 → 5.8.0-beta.1

package/lib/deploy/function/docker-preflight.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDockerPreflight = runDockerPreflight;
+const child_process_1 = require("child_process");
+const types_1 = require("../types");
+/**
+ * Docker 本地能力 Preflight（local 策略，scope: local）
+ *
+ * 在本地构建镜像前，检测 docker CLI、daemon 与 buildx 是否可用。
+ * 全部为只读命令，不产生任何副作用，不涉及网络与凭证。
+ *
+ * 安全：所有命令用 execFile + 参数数组执行，shell 关闭，命令与参数均为
+ * 固定常量、无外部输入拼接，杜绝命令注入（对应 security_rules 的 RCE 防护）。
+ * 本地能力缺失统一标注 canFallbackToCloud，供上层决定是否回退云端构建。
+ *
+ * 命令执行器以参数注入，默认使用真实 execFile，便于在测试中替换（不依赖 jest.mock）。
+ */
+/** 单条命令执行超时（毫秒），避免 daemon 卡死拖垮检查 */
+const COMMAND_TIMEOUT = 15000;
+/** 默认执行器：安全执行只读命令（固定参数数组、无 shell、带超时） */
+function defaultRunner(command, args) {
+    return new Promise(resolve => {
+        (0, child_process_1.execFile)(command, args, { timeout: COMMAND_TIMEOUT, shell: false, windowsHide: true }, (error, stdout, stderr) => {
+            resolve({
+                ok: !error,
+                stdout: (stdout || '').toString().trim(),
+                stderr: (stderr || '').toString().trim()
+            });
+        });
+    });
+}
+function fail(id, summary, remediation) {
+    return { id, status: 'fail', summary, remediation, canFallbackToCloud: true };
+}
+function pass(id, summary) {
+    return { id, status: 'pass', summary };
+}
+function buildReport(checks) {
+    const ready = !checks.some(item => item.status === 'fail');
+    const report = {
+        scope: 'local',
+        strategy: 'local',
+        ready,
+        checks
+    };
+    // 存在可回退云端的失败项时，建议改用 cloud 策略
+    if (!ready && checks.some(item => item.status === 'fail' && item.canFallbackToCloud)) {
+        report.recommendedStrategy = 'cloud';
+    }
+    return report;
+}
+/**
+ * 执行 Docker 本地能力检查
+ *
+ * 检测顺序：CLI 存在性 → daemon 可用性 → buildx 可用性。
+ * CLI 缺失时短路（daemon/buildx 无从谈起），其余项独立收集后聚合返回。
+ *
+ * @param runner 命令执行器，默认真实 execFile；测试可注入 mock
+ */
+async function runDockerPreflight(runner = defaultRunner) {
+    const checks = [];
+    // 1. Docker CLI 是否存在（不需要 daemon）
+    const cli = await runner('docker', ['--version']);
+    if (!cli.ok) {
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_CLI_MISSING, '未检测到 docker 命令', '请安装 Docker 并确保 docker 在 PATH 中，或改用 cloud 策略在云端构建镜像'));
+        // CLI 不存在，后续检查无意义，直接返回
+        return buildReport(checks);
+    }
+    checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_CLI_MISSING, `Docker CLI 可用：${cli.stdout}`));
+    // 2. Docker daemon 是否可用
+    const daemon = await runner('docker', ['info', '--format', '{{.ServerVersion}}']);
+    if (!daemon.ok || !daemon.stdout) {
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_DAEMON_UNAVAILABLE, 'Docker daemon 不可用或未运行', '请启动 Docker daemon（如 Docker Desktop）后重试，或改用 cloud 策略'));
+    }
+    else {
+        checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_DAEMON_UNAVAILABLE, `Docker daemon 可用：${daemon.stdout}`));
+    }
+    // 3. buildx 是否可用（跨平台构建 amd64 依赖它）
+    const buildx = await runner('docker', ['buildx', 'version']);
+    if (!buildx.ok) {
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_BUILDX_MISSING, '未检测到 docker buildx', '请安装/启用 docker buildx 插件以构建 linux/amd64 镜像，或改用 cloud 策略'));
+    }
+    else {
+        checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_DOCKER_BUILDX_MISSING, `docker buildx 可用：${buildx.stdout.split('\n')[0]}`));
+    }
+    return buildReport(checks);
+}

package/lib/deploy/function/image-preflight.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runImageRemotePreflight = runImageRemotePreflight;
+const child_process_1 = require("child_process");
+const config_guard_1 = require("./config-guard");
+const types_1 = require("../types");
+/**
+ * 镜像远端校验 Preflight（有 IO，scope: cloud）
+ *
+ * 仅用于 image 策略（已有镜像）。config-guard 已做过纯字符串层面的校验
+ * （URI 格式、缺 tag/digest、禁 latest、imageType/registryId）；本模块进一步
+ * 校验镜像在远端仓库的“真实状态”：
+ *   1. 远端 manifest 是否存在（镜像确实已推送），并解析出不可变 digest；
+ *   2. 企业版 TCR：镜像 registry 域名地域与函数部署地域是否一致（跨地域拉取失败/慢）。
+ *
+ * 设计边界（与 cam-preflight 同构）：
+ * - 命令一律 execFile + 参数数组 + shell 关闭，imageUri 作为独立参数传入，杜绝命令注入；
+ * - 本模块不接触任何凭证，假设调用方已 docker login 目标私有仓库；
+ * - 远端查不到镜像属于真实前置缺失 → fail 阻断；
+ * - inspect 因命令缺失/网络波动等无法执行时不硬失败 → 降级 warn，避免误伤；
+ * - 个人版 CCR 无地域概念，无法从域名解析地域或部署地域未知时跳过地域校验，不误报。
+ */
+/** imagetools inspect 超时（毫秒）：仅查manifest，较快 */
+const INSPECT_TIMEOUT = 60 * 1000;
+/** 默认命令执行器：固定参数数组、无 shell、带超时 */
+function defaultRunCommand(command, args) {
+    return new Promise(resolve => {
+        (0, child_process_1.execFile)(command, args, { timeout: INSPECT_TIMEOUT, shell: false, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+            // ENOENT 表示命令不存在（docker 未安装），需与“执行了但失败”区分
+            const spawnFailed = !!error && (error.code === 'ENOENT' || error.errno === 'ENOENT');
+            resolve({
+                ok: !error,
+                stdout: (stdout || '').toString(),
+                stderr: (stderr || '').toString(),
+                spawnFailed
+            });
+        });
+    });
+}
+const defaultDeps = {
+    runCommand: defaultRunCommand
+};
+function pass(id, summary) {
+    return { id, status: 'pass', summary };
+}
+function warn(id, summary, remediation) {
+    return { id, status: 'warn', summary, remediation };
+}
+function fail(id, summary, options = {}) {
+    return { id, status: 'fail', summary, remediation: options.remediation, detail: options.detail };
+}
+function buildReport(checks) {
+    return {
+        scope: 'cloud',
+        strategy: 'image',
+        ready: !checks.some(item => item.status === 'fail'),
+        checks
+    };
+}
+/** 从 imagetools inspect 输出解析远端 digest */
+function parseRemoteDigest(output) {
+    const match = output.match(/Digest:\s*(sha256:[0-9a-f]{64})/i);
+    return match ? match[1] : undefined;
+}
+/**
+ * 从企业版 TCR registry 域名解析地域
+ *
+ * 企业版 TCR 域名形如 `<instance>.tencentcloudcr.com`，地域信息不在域名中，
+ * 需由 registryId/其它渠道确定，本阶段无法仅凭域名解析 → 返回 undefined 跳过。
+ * 个人版 CCR `ccr.ccs.tencentyun.com` 为全局服务，无地域概念 → 同样返回 undefined。
+ *
+ * 仅当 registry 域名中显式内嵌可识别地域（如包含 ap-guangzhou 等地域片段）时才解析出，
+ * 用于对“显式跨地域”这一确定性错误给出拦截，其余情况一律跳过、不误报。
+ */
+function resolveRegistryRegion(registry) {
+    if (!registry) {
+        return undefined;
+    }
+    const lower = registry.toLowerCase();
+    // 个人版 CCR 与企业版通用域名无地域信息，跳过
+    if (lower.includes('ccr.ccs.tencentyun.com') || /^[^.]+\.tencentcloudcr\.com$/.test(lower)) {
+        return undefined;
+    }
+    // 匹配域名中显式内嵌的腾讯云地域片段（ap-/eu-/na-/sa- 前缀）
+    const match = lower.match(/\b((?:ap|eu|na|sa)-[a-z]+(?:-[a-z]+)?)\b/);
+    return match ? match[1] : undefined;
+}
+/** 是否需要执行远端校验：仅 HTTP image 策略 */
+function needsRemoteCheck(config) {
+    return config.type === 'HTTP' && config.buildStrategy === 'image';
+}
+/** 校验 registry 地域与函数部署地域一致性 */
+function checkRegion(registry, deployRegion, checks) {
+    const imageRegion = resolveRegistryRegion(registry);
+    // 任一地域无法确定则跳过，避免对个人版/无地域信息的场景误报
+    if (!imageRegion || !deployRegion) {
+        return;
+    }
+    const target = deployRegion.toLowerCase();
+    if (imageRegion !== target) {
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_REGION_MISMATCH, `镜像仓库地域(${imageRegion})与函数部署地域(${target})不一致`, {
+            remediation: '跨地域拉取镜像会失败或明显变慢，请使用与函数同地域的镜像仓库',
+            detail: `registry：${registry}`
+        }));
+    }
+}
+/**
+ * 执行镜像远端校验 Preflight
+ *
+ * @param config 规范化部署配置
+ * @param deployRegion 函数部署地域（可选，来源于 environment；未知时跳过地域校验）
+ * @param deps 可注入依赖，默认真实命令；测试可传 mock
+ * @returns scope 为 cloud 的检查报告
+ */
+async function runImageRemotePreflight(config, deployRegion, deps = defaultDeps) {
+    var _a;
+    if (!needsRemoteCheck(config)) {
+        return buildReport([]);
+    }
+    // needsRemoteCheck 为类型守卫，early-return 后 config 已收窄为 INormalizedHttpImageConfig
+    const imageUri = (_a = config.imageConfig) === null || _a === void 0 ? void 0 : _a.imageUri;
+    if (typeof imageUri !== 'string' || !imageUri.trim()) {
+        // 缺 URI 属于配置契约问题，已由 config-guard 覆盖，此处不重复
+        return buildReport([]);
+    }
+    const parsed = (0, config_guard_1.parseImageReference)(imageUri);
+    const checks = [];
+    // 地域校验（不依赖远端查询，先做）
+    checkRegion(parsed === null || parsed === void 0 ? void 0 : parsed.registry, deployRegion, checks);
+    // 远端 manifest 查询
+    const inspect = await deps.runCommand('docker', ['buildx', 'imagetools', 'inspect', imageUri]);
+    if (inspect.spawnFailed) {
+        // docker 不可用，无法远端自查→ 降级提示，不阻断（zip/已存在镜像等场景可能无docker）
+        checks.push(warn(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_REMOTE_UNVERIFIABLE, '本地无可用的 docker，无法校验镜像远端是否存在', '若镜像确实已推送到目标仓库可忽略；否则请确认镜像已 push 且账号有拉取权限'));
+        return buildReport(checks);
+    }
+    if (!inspect.ok) {
+        const combined = `${inspect.stderr} ${inspect.stdout}`.toLowerCase();
+        // 明确的“不存在”类错误 → fail 阻断
+        const notFound = combined.includes('not found') ||
+            combined.includes('manifest unknown') ||
+            combined.includes('no such') ||
+            combined.includes('does not exist');
+        if (notFound) {
+            checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_REMOTE_NOT_FOUND, '目标镜像在远端仓库不存在', {
+                remediation: '请确认 imageConfig.imageUri 正确、镜像已 push 到该仓库，且当前账号已 docker login 具备拉取权限',
+                detail: `imageUri：${imageUri}`
+            }));
+            return buildReport(checks);
+        }
+        // 其它错误（如未登录私有仓库、网络波动）无法断定不存在 → 降级 warn，不误伤
+        checks.push(warn(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_REMOTE_UNVERIFIABLE, '无法确认镜像远端状态（可能未登录私有仓库或网络异常）', `请确认已 docker login 目标仓库后重试；错误：${(inspect.stderr || inspect.stdout || '').trim().slice(0, 200)}`));
+        return buildReport(checks);
+    }
+    // 远端存在，解析 digest
+    const digest = parseRemoteDigest(inspect.stdout);
+    if (digest) {
+        checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_REMOTE_NOT_FOUND, `镜像远端存在，digest 为 ${digest}`));
+    }
+    else {
+        checks.push(warn(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_DIGEST_UNRESOLVED, '镜像远端存在，但未能解析出 digest', '部署可继续，但无法记录不可变 digest 用于回溯'));
+    }
+    return buildReport(checks);
+}

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

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAndPushImage = buildAndPushImage;
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const error_1 = require("../../error");
+const types_1 = require("../types");
+/**
+ * 本地镜像构建与推送（local 策略，个人版先行版）
+ *
+ * 流程：解析构建上下文与目标镜像 → buildx 构建 amd64 并推送 → 查询远端 digest。
+ *
+ * 安全（对应 security_rules 的 RCE 防护）：
+ * - 所有 docker 命令用 execFile + 参数数组执行，shell 关闭；tag、路径、buildArgs
+ *   都作为独立参数传入，绝不拼接进 shell 字符串，杜绝命令注入。
+ * - 不处理登录：假设调用方已 docker login 目标仓库；本模块不接触任何凭证/密码。
+ *
+ * 命令与文件系统操作以依赖注入方式提供，默认使用真实实现，便于测试替换（不依赖 jest.mock）。
+ */
+/** 构建/推送命令超时（毫秒），镜像构建较慢，给足时间 */
+const BUILD_TIMEOUT = 10 * 60 * 1000;
+/** 默认命令执行器：固定参数数组、无 shell、带超时与最大缓冲 */
+function defaultRunCommand(command, args) {
+    return new Promise(resolve => {
+        (0, child_process_1.execFile)(command, args, { timeout: BUILD_TIMEOUT, shell: false, windowsHide: true, maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+            resolve({
+                ok: !error,
+                stdout: (stdout || '').toString(),
+                stderr: (stderr || '').toString()
+            });
+        });
+    });
+}
+/** 默认依赖：真实命令执行与 fs 检查 */
+const defaultDeps = {
+    runCommand: defaultRunCommand,
+    existsSync: target => fs_1.default.existsSync(target),
+    isDirectory: target => fs_1.default.statSync(target).isDirectory(),
+    isFile: target => fs_1.default.statSync(target).isFile()
+};
+/** 解析构建上下文目录（绝对路径） */
+function resolveContext(config) {
+    const cwd = config.build.cwd || config.functionPath || process.cwd();
+    return path_1.default.resolve(cwd);
+}
+/** 解析目标镜像完整引用 imageUri（repository 需为含域名与命名空间的完整仓库地址，个人版/企业版通用） */
+function resolveImageUri(config) {
+    const repository = config.build.repository;
+    if (typeof repository !== 'string' || !repository.trim()) {
+        throw new error_1.CloudBaseError('local 策略缺少目标镜像仓库地址 build.repository', {
+            code: types_1.FUNCTION_DEPLOY_ERROR.LOCAL_BUILD_REPOSITORY_MISSING
+        });
+    }
+    // tag 缺省用时间戳，避免 latest；不可变 tag 便于回溯
+    const tag = config.build.tag || `v${Date.now()}`;
+    return `${repository.trim()}:${tag}`;
+}
+/** 从 buildx imagetools inspect 输出解析 digest */
+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(' ')}`;
+}
+/**
+ * 本地构建镜像并推送到目标仓库
+ *
+ * @param config 规范化的 local 部署配置
+ * @param onLog 可选日志回调，用于透出构建输出（不含凭证）
+ * @param deps 可注入依赖，默认真实命令与 fs；测试可传 mock
+ * @returns 最终镜像引用与 digest
+ */
+async function buildAndPushImage(config, onLog, deps = defaultDeps) {
+    const context = resolveContext(config);
+    if (!deps.existsSync(context) || !deps.isDirectory(context)) {
+        throw new error_1.CloudBaseError(`构建上下文目录不存在：${context}`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.LOCAL_BUILD_CONTEXT_MISSING
+        });
+    }
+    const dockerfile = config.build.dockerfile || types_1.DEFAULT_DOCKERFILE;
+    const dockerfilePath = path_1.default.resolve(context, dockerfile);
+    if (!deps.existsSync(dockerfilePath) || !deps.isFile(dockerfilePath)) {
+        throw new error_1.CloudBaseError(`Dockerfile 不存在：${dockerfilePath}`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.LOCAL_BUILD_DOCKERFILE_MISSING
+        });
+    }
+    const imageUri = resolveImageUri(config);
+    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(`执行 ${formatBuildCommandForLog(args)}`);
+    const build = await deps.runCommand('docker', args);
+    if (!build.ok) {
+        throw new error_1.CloudBaseError('镜像构建或推送失败，请查看 Docker 构建输出定位具体原因', {
+            code: types_1.FUNCTION_DEPLOY_ERROR.LOCAL_PUSH_FAILED
+        });
+    }
+    // 查询远端 digest，产出不可变引用
+    const inspect = await deps.runCommand('docker', ['buildx', 'imagetools', 'inspect', imageUri]);
+    const imageDigest = inspect.ok ? parseDigest(inspect.stdout) : undefined;
+    return { imageUri, imageDigest };
+}

package/lib/deploy/function/planner.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCurrentState = toCurrentState;
+exports.createDeployPlan = createDeployPlan;
+const constant_1 = require("../../constant");
+const config_guard_1 = require("./config-guard");
+/**
+ * 部署计划生成
+ *
+ * 纯函数实现，线上函数状态由调用方查询后传入，便于单独测试
+ */
+/** 将 SCF 返回的函数详情收敛为计划所需的状态摘要 */
+function toCurrentState(info) {
+    var _a;
+    const rawType = typeof (info === null || info === void 0 ? void 0 : info.Type) === 'string' ? info.Type : '';
+    const type = rawType.toLowerCase() === 'http' ? 'HTTP' : 'Event';
+    const imageUri = typeof ((_a = info === null || info === void 0 ? void 0 : info.ImageConfig) === null || _a === void 0 ? void 0 : _a.ImageUri) === 'string'
+        ? info.ImageConfig.ImageUri
+        : undefined;
+    return {
+        functionName: info === null || info === void 0 ? void 0 : info.FunctionName,
+        type,
+        runtime: info === null || info === void 0 ? void 0 : info.Runtime,
+        status: info === null || info === void 0 ? void 0 : info.Status,
+        protocolType: info === null || info === void 0 ? void 0 : info.ProtocolType,
+        triggerNames: Array.isArray(info === null || info === void 0 ? void 0 : info.Triggers)
+            ? info.Triggers.map(item => (item === null || item === void 0 ? void 0 : item.TriggerName) || (item === null || item === void 0 ? void 0 : item.Name)).filter(Boolean)
+            : [],
+        isCustomImage: (0, config_guard_1.isCustomImageRuntime)(info === null || info === void 0 ? void 0 : info.Runtime),
+        imageUri,
+        timeout: typeof (info === null || info === void 0 ? void 0 : info.Timeout) === 'number' ? info.Timeout : undefined,
+        memorySize: typeof (info === null || info === void 0 ? void 0 : info.MemorySize) === 'number' ? info.MemorySize : undefined,
+        description: typeof (info === null || info === void 0 ? void 0 : info.Description) === 'string' ? info.Description : undefined,
+        envVariables: extractEnvVariables(info)
+    };
+}
+/** 从线上函数详情提取环境变量为键值对 */
+function extractEnvVariables(info) {
+    var _a;
+    const list = (_a = info === null || info === void 0 ? void 0 : info.Environment) === null || _a === void 0 ? void 0 : _a.Variables;
+    if (!Array.isArray(list)) {
+        return undefined;
+    }
+    const result = {};
+    for (const item of list) {
+        const key = item === null || item === void 0 ? void 0 : item.Key;
+        if (typeof key === 'string') {
+            result[key] = typeof (item === null || item === void 0 ? void 0 : item.Value) === 'string' ? item.Value : '';
+        }
+    }
+    return result;
+}
+/** 归一化运行时字符串，便于大小写不敏感比较 */
+function normalizeRuntime(runtime) {
+    return typeof runtime === 'string' ? runtime.trim().toLowerCase() : '';
+}
+/** 归一化协议类型：SCF 缺省/空值与显式 HTTP 都表示普通 HTTP */
+function normalizeProtocolType(protocolType) {
+    const normalized = typeof protocolType === 'string' ? protocolType.trim().toUpperCase() : '';
+    return normalized || 'HTTP';
+}
+/**
+ * 计算运行时变化导致的重建原因
+ *
+ * 需要区分三类不可原地修改的变化：
+ * - 托管运行时与自定义镜像互切
+ * - 两个不同托管运行时之间互切（SCF Runtime 是创建期字段）
+ * 两侧都是自定义镜像时，runtime 统一为 CustomImage，镜像内容变化走更新而非重建
+ */
+function collectRuntimeReplaceReasons(config, current) {
+    const reasons = [];
+    const targetIsCustomImage = (0, config_guard_1.isCustomImageRuntime)(config.runtime);
+    if (current.isCustomImage !== targetIsCustomImage) {
+        reasons.push(targetIsCustomImage
+            ? `运行时需要从 ${current.runtime || '托管运行时'} 变更为自定义镜像`
+            : '运行时需要从自定义镜像变更为托管运行时');
+        return reasons;
+    }
+    // 两侧都是镜像时，runtime 恒为 CustomImage，不因镜像地址差异触发重建
+    if (targetIsCustomImage) {
+        return reasons;
+    }
+    const targetRuntime = config.runtime;
+    // 目标未显式指定 runtime 时不推断变化，交由更新流程按现状处理
+    if (targetRuntime === undefined) {
+        return reasons;
+    }
+    if (normalizeRuntime(targetRuntime) !== normalizeRuntime(current.runtime)) {
+        reasons.push(`运行时需要从 ${current.runtime || '未知'} 变更为 ${targetRuntime}`);
+    }
+    return reasons;
+}
+/**
+ * 计算协议类型变化导致的重建原因
+ *
+ * ProtocolType 是创建期字段，新增、移除或切换都无法通过更新接口生效。
+ * 仅 HTTP 函数存在协议类型，Event 函数不参与判断。
+ */
+function collectProtocolReplaceReasons(config, current) {
+    if (config.type !== 'HTTP' || current.type !== 'HTTP') {
+        return [];
+    }
+    const target = normalizeProtocolType(config.protocolType);
+    const online = normalizeProtocolType(current.protocolType);
+    if (target === online) {
+        return [];
+    }
+    const describe = (value) => (value === '' ? '普通 HTTP' : value);
+    return [`协议类型需要从 ${describe(online)} 变更为 ${describe(target)}`];
+}
+/**
+ * 计算必须删除重建的原因
+ *
+ * SCF 的 Type、Runtime、ProtocolType 只能在创建时指定，
+ * 这些字段发生变化时无法通过更新接口生效
+ */
+function collectReplaceReasons(config, current) {
+    const reasons = [];
+    if (current.type !== config.type) {
+        reasons.push(`函数类型需要从 ${current.type} 变更为 ${config.type}`);
+    }
+    reasons.push(...collectRuntimeReplaceReasons(config, current));
+    reasons.push(...collectProtocolReplaceReasons(config, current));
+    return reasons;
+}
+/** 计算部署后需要收敛的访问相关操作 */
+function collectAccessOperations(config) {
+    const operations = [];
+    if (config.type !== 'HTTP') {
+        return operations;
+    }
+    if (config.public !== undefined) {
+        operations.push('configure-access');
+    }
+    if (config.gatewayPath !== undefined) {
+        operations.push('configure-gateway');
+    }
+    return operations;
+}
+/** 归一化环境变量为可比较的稳定字符串（键排序后 JSON） */
+function serializeEnv(env) {
+    if (!env || typeof env !== 'object') {
+        return '';
+    }
+    const keys = Object.keys(env).sort();
+    return keys.map(key => `${key}=${String(env[key])}`).join('\n');
+}
+/**
+ * 计算相对线上状态的变更原因
+ *
+ * 返回空数组表示所有可比字段一致，可判定为 noop。
+ * 保守原则：任何无法可靠比较的维度都视为“有变更”，宁可多更新也不漏更新。
+ * - code 类（zip/cos）无法从线上取回源码比较，始终视为有变更；
+ * - 仅比较配置方显式提供的字段，未提供的字段不参与（避免默认值误判）。
+ */
+function collectChangeReasons(config, current) {
+    var _a;
+    const reasons = [];
+    // code 类部署无法可靠比较本地代码与线上代码，始终按更新处理
+    if (config.buildStrategy !== 'image') {
+        reasons.push('代码包部署无法比对本地与线上代码内容，按更新处理');
+        return reasons;
+    }
+    // image 策略：比较镜像地址
+    const targetImageUri = (_a = config.imageConfig) === null || _a === void 0 ? void 0 : _a.imageUri;
+    if (typeof targetImageUri === 'string' && targetImageUri.trim()) {
+        // 线上ImageUri 可能带 @sha256 digest 后缀，用前缀匹配容忍 digest 附加
+        const online = current.imageUri || '';
+        const matched = online === targetImageUri || online.startsWith(`${targetImageUri}@`);
+        if (!matched) {
+            reasons.push(`镜像地址需要从 ${online || '未知'} 变更为 ${targetImageUri}`);
+        }
+    }
+    else {
+        // 期望镜像地址缺失，无法比较，保守更新
+        reasons.push('无法确定目标镜像地址，按更新处理');
+    }
+    reasons.push(...collectConfigChangeReasons(config, current));
+    return reasons;
+}
+/** 比较可原地更新的配置字段（仅比较配置方显式提供的） */
+function collectConfigChangeReasons(config, current) {
+    var _a, _b;
+    const reasons = [];
+    const cfg = config;
+    if (typeof cfg.timeout === 'number' && cfg.timeout !== current.timeout) {
+        reasons.push(`超时时间需要从 ${(_a = current.timeout) !== null && _a !== void 0 ? _a : '未知'} 变更为 ${cfg.timeout}`);
+    }
+    if (typeof cfg.memorySize === 'number' && cfg.memorySize !== current.memorySize) {
+        reasons.push(`内存规格需要从 ${(_b = current.memorySize) !== null && _b !== void 0 ? _b : '未知'} 变更为 ${cfg.memorySize}`);
+    }
+    if (typeof cfg.description === 'string' && cfg.description !== (current.description || '')) {
+        reasons.push('函数描述发生变更');
+    }
+    if (cfg.envVariables !== undefined) {
+        const target = serializeEnv(cfg.envVariables);
+        const online = serializeEnv(current.envVariables);
+        if (target !== online) {
+            reasons.push('环境变量发生变更');
+        }
+    }
+    return reasons;
+}
+/**
+ * 生成部署计划
+ * @param config 已规范化的部署配置
+ * @param current 线上函数详情，不存在时传 null
+ */
+function createDeployPlan(config, current) {
+    const currentState = current ? toCurrentState(current) : undefined;
+    const accessOperations = collectAccessOperations(config);
+    const reasons = [];
+    // 函数不存在，或存在但处于 CREATE_FAILED 状态（上次部署失败残留，视为需重新创建）。
+    // 走 create 通道后，FunctionService.createFunction 内部会检测到同名残留并自动删除重建，
+    // 对齐 tcb fn deploy 的 CREATE_FAILED 清理行为。
+    if (!currentState || currentState.status === constant_1.SCF_STATUS.CREATE_FAILED) {
+        const operations = ['create-function', ...accessOperations];
+        reasons.push((currentState === null || currentState === void 0 ? void 0 : currentState.status) === constant_1.SCF_STATUS.CREATE_FAILED
+            ? `检测到同名函数处于 CreateFailed 状态（上次部署失败残留），将清理后重新创建 ${config.type} 函数`
+            : `线上不存在同名函数，将创建 ${config.type} 函数`);
+        return {
+            functionName: config.name,
+            functionType: config.type,
+            buildStrategy: config.buildStrategy,
+            exists: false,
+            action: 'create',
+            operations,
+            reasons,
+            replaceReasons: []
+        };
+    }
+    const replaceReasons = collectReplaceReasons(config, currentState);
+    if (replaceReasons.length > 0) {
+        return {
+            functionName: config.name,
+            functionType: config.type,
+            buildStrategy: config.buildStrategy,
+            exists: true,
+            action: 'replace',
+            operations: ['replace-function', ...accessOperations],
+            reasons: [
+                '存在无法通过更新接口生效的变更，需要删除后重新创建函数',
+                ...replaceReasons
+            ],
+            replaceReasons,
+            current: currentState
+        };
+    }
+    const changeReasons = collectChangeReasons(config, currentState);
+    // 无任何可检出的变更时判定为 noop，跳过代码与配置更新
+    // 但访问收敛（public/gatewayPath）若配置方显式要求，仍需保留为待执行操作
+    if (changeReasons.length === 0) {
+        return {
+            functionName: config.name,
+            functionType: config.type,
+            buildStrategy: config.buildStrategy,
+            exists: true,
+            action: 'noop',
+            operations: [...accessOperations],
+            reasons: ['线上函数与目标配置一致，无需更新代码或配置'],
+            replaceReasons: [],
+            current: currentState
+        };
+    }
+    reasons.push('线上已存在同名函数，将更新代码与配置');
+    reasons.push(...changeReasons);
+    return {
+        functionName: config.name,
+        functionType: config.type,
+        buildStrategy: config.buildStrategy,
+        exists: true,
+        action: 'update',
+        operations: ['update-code', 'update-config', ...accessOperations],
+        reasons,
+        replaceReasons: [],
+        current: currentState
+    };
+}