@cloudbase/manager-node 5.6.7 → 5.7.0-beta.0

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

@@ -0,0 +1,454 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TCR_LOGIN_PUSH_SCRIPT = exports.TCR_PUSH_SCRIPT_ZIP_PATH = void 0;
+exports.buildImageOnCloud = buildImageOnCloud;
+const error_1 = require("../../../error");
+const types_1 = require("../../types");
+/**
+ * 云端镜像构建（cloud 策略）
+ *
+ * 对应构建方案（https://iwiki.woa.com/p/4020519533）的「阶段 A：构建镜像（CloudApp custom）」：
+ *   源码打包 ZIP → DescribeCloudAppCosInfo拿上传凭证 → PUT 上传 COS
+ *   → CreateCloudApp(DeployType:custom) 触发容器内 docker build + push TCR
+ *   → 退避轮询 DescribeCloudAppVersion 到终态 → 从 Artifacts 或拼接得到 imageUri/digest。
+ *
+ * 产物只返回镜像引用（imageUri/digest/buildId/logsUrl），由编排器交回统一
+ * SCF 部署链，本模块不创建/更新任何函数（对应实施规划：builder 只获得 image artifact）。
+ *
+ * 安全（对应 security_rules）：
+ * - CustomSteps 由 SDK 固定模板生成；用户可控值（如 tag、registry、namespace）先经
+ *   白名单校验，绝不作为任意 shell 片段拼接进 command。
+ * - 企业版 TCR 在构建容器内使用 STS 临时凭证换取登录 token；个人版固定密码先做
+ *   Base64 封装，再通过 CloudApp Secrets 注入为 $SECRET_TCR_PASSWORD_B64，构建容器内
+ *   解码后直接送入 docker login stdin，不进入普通 Env、命令行参数或日志。
+ * - COS 上传必须携带服务端返回的全部 UploadHeaders。
+ * - tag 使用 $CLOUDBASE_VERSION_NAME 或内容摘要，绝不使用 latest。
+ *
+ * 所有外部依赖（打包、tcb API、COS 上传）以接口注入，默认由编排器提供真实实现，
+ * 便于测试替换（不依赖 jest.mock）。
+ */
+/** custom 构建的固定 DeployType */
+const CUSTOM_DEPLOY_TYPE = 'custom';
+/** custom 构建的源码类型 */
+const CUSTOM_BUILD_TYPE = 'zip';
+/** 轮询默认参数：初始 5s、退避到 30s、总超时 15 分钟 */
+const POLL_INITIAL_INTERVAL = 5000;
+const POLL_MAX_INTERVAL = 30000;
+const POLL_TOTAL_TIMEOUT = 15 * 60 * 1000;
+/** 轮询临时错误最大连续重试次数，超过则判失败 */
+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}$/;
+/** 校验仓库/命名空间等镜像地址片段，拒绝命令注入风险字符 */
+function assertSafeRegistryToken(value, field) {
+    if (!SAFE_REGISTRY_PATTERN.test(value)) {
+        throw new error_1.CloudBaseError(`${field} 含非法字符，可能导致命令注入：${value}`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_REPOSITORY_INVALID
+        });
+    }
+}
+/** 校验 tag，拒绝 latest 与非法字符 */
+function assertSafeTag(tag) {
+    if (!SAFE_TAG_PATTERN.test(tag)) {
+        throw new error_1.CloudBaseError(`镜像 tag 含非法字符：${tag}`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_TAG_INVALID
+        });
+    }
+    if (tag.toLowerCase() === 'latest') {
+        throw new error_1.CloudBaseError('镜像 tag 禁止使用 latest，请使用不可变 tag', {
+            code: types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TAG_LATEST_FORBIDDEN
+        });
+    }
+}
+/** 个人版 CCR 默认域名 */
+const DEFAULT_PERSONAL_REGISTRY = 'ccr.ccs.tencentyun.com';
+/** 注入到构建上下文 zip 中的推送脚本相对路径（与 CustomSteps 的 push命令一致） */
+exports.TCR_PUSH_SCRIPT_ZIP_PATH = 'scripts/tcr-login-and-push.sh';
+/**
+ * 注入到构建 zip 的 TCR/CCR 登录推送脚本（完整可运行）
+ *
+ * 对应构建方案（https://iwiki.woa.com/p/4020519533）「阶段 A」的 push 步骤：
+ * push-image 步骤执行 `bash./scripts/tcr-login-and-push.sh`，该脚本必须随源码
+ * 一同打进zip 根目录，否则云端会 `No such file or directory` 秒挂。
+ *
+ * 关键设计：
+ * - 地域参数化：REGION 读环境变量 $TCR_REGION（由 buildEnv 按部署地域注入），
+ *   避免硬编码 ap-shanghai跨地域时 AuthFailure.SignatureFailure。
+ * - 双仓库兼容：设置了 $TCR_INSTANCE_ID 走企业版 TCR CreateInstanceToken；
+ *   否则走个人版 CCR，用户名来自普通 Env，固定密码来自 CloudApp Secrets。
+ * - 安全红线：凭证一律经 --password-stdin 传入，绝不出现在 ps/日志；
+ *   不打印任何 $API_SECRET_* / token / $SECRET_TCR_PASSWORD_B64 或解码后的密码。
+ *
+ * 脚本内容为SDK 固定模板，不拼接任何用户输入（镜像地址等均由已校验的
+ * 环境变量在容器内组装），无命令注入面。
+ */
+exports.TCR_LOGIN_PUSH_SCRIPT = `#!/usr/bin/env bash
+# scripts/tcr-login-and-push.sh
+# 由 CloudBase SDK 自动注入：企业版使用 STS 换取临时 token，个人版使用 CloudApp Secret
+set -euo pipefail
+
+: "\${TCR_REGISTRY:?TCR_REGISTRY 未设置}"
+: "\${TCR_NAMESPACE:?TCR_NAMESPACE 未设置}"
+: "\${CLOUDBASE_SERVICE_NAME:?平台变量缺失}"
+: "\${CLOUDBASE_VERSION_NAME:?平台变量缺失}"
+
+REGION="\${TCR_REGION:-ap-shanghai}"
+IMAGE="\${TCR_REGISTRY}/\${TCR_NAMESPACE}/\${CLOUDBASE_SERVICE_NAME}:\${CLOUDBASE_VERSION_NAME}"
+
+if [ -n "\${TCR_INSTANCE_ID:-}" ]; then
+  : "\${API_SECRET_ID:?STS 凭证缺失}"
+  : "\${API_SECRET_KEY:?STS 凭证缺失}"
+  : "\${API_TOKEN:?STS 凭证缺失}"
+
+  # ---- 企业版 TCR：CreateInstanceToken 换登录态 ----
+  HOST="tcr.tencentcloudapi.com"
+  SERVICE="tcr"
+  VERSION="2019-09-24"
+  ACTION="CreateInstanceToken"
+  ALGORITHM="TC3-HMAC-SHA256"
+  TIMESTAMP=$(date +%s)
+  DATE=$(date -u -d "@\${TIMESTAMP}" +"%Y-%m-%d" 2>/dev/null || date -u -r "\${TIMESTAMP}" +"%Y-%m-%d")
+
+  PAYLOAD=$(printf '{"RegistryId":"%s","TokenType":"LongTermToken"}' "\${TCR_INSTANCE_ID}")
+  HASHED_PAYLOAD=$(printf '%s' "\${PAYLOAD}" | openssl dgst -sha256 -hex | awk '{print $NF}')
+  CANONICAL_HEADERS="content-type:application/json; charset=utf-8\\nhost:\${HOST}\\nx-tc-action:$(echo "\${ACTION}" | tr '[:upper:]' '[:lower:]')\\n"
+  SIGNED_HEADERS="content-type;host;x-tc-action"
+  CANONICAL_REQUEST="POST\\n/\\n\\n\${CANONICAL_HEADERS}\\n\${SIGNED_HEADERS}\\n\${HASHED_PAYLOAD}"
+
+  CREDENTIAL_SCOPE="\${DATE}/\${SERVICE}/tc3_request"
+  HASHED_CR=$(printf "\${CANONICAL_REQUEST}" | openssl dgst -sha256 -hex | awk '{print $NF}')
+  STRING_TO_SIGN="\${ALGORITHM}\\n\${TIMESTAMP}\\n\${CREDENTIAL_SCOPE}\\n\${HASHED_CR}"
+
+  secret_date=$(printf '%s' "\${DATE}" | openssl dgst -sha256 -hmac "TC3\${API_SECRET_KEY}" -hex | awk '{print $NF}')
+  secret_svc=$(printf '%s' "\${SERVICE}" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"\${secret_date}" -hex | awk '{print $NF}')
+  secret_sign=$(printf '%s' "tc3_request" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"\${secret_svc}" -hex | awk '{print $NF}')
+  SIGNATURE=$(printf "\${STRING_TO_SIGN}" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"\${secret_sign}" -hex | awk '{print $NF}')
+
+  AUTHZ="\${ALGORITHM} Credential=\${API_SECRET_ID}/\${CREDENTIAL_SCOPE}, SignedHeaders=\${SIGNED_HEADERS}, Signature=\${SIGNATURE}"
+
+  RESP=$(curl -sS -X POST "https://\${HOST}" \\
+    -H "Authorization: \${AUTHZ}" \\
+    -H "Content-Type: application/json; charset=utf-8" \\
+    -H "Host: \${HOST}" \\
+    -H "X-TC-Action: \${ACTION}" \\
+    -H "X-TC-Timestamp: \${TIMESTAMP}" \\
+    -H "X-TC-Version: \${VERSION}" \\
+    -H "X-TC-Region: \${REGION}" \\
+    -H "X-TC-Token: \${API_TOKEN}" \\
+    --data "\${PAYLOAD}")
+
+  TOKEN_USER=$(printf '%s' "\${RESP}" | jq -er '.Response.Username')
+  TOKEN_PASS=$(printf '%s' "\${RESP}" | jq -er '.Response.Token')
+
+  printf '%s' "\${TOKEN_PASS}" | docker login -u "\${TOKEN_USER}" --password-stdin "\${TCR_REGISTRY}"
+else
+  # ---- 个人版 CCR：账号 ID + 固定密码（Base64 封装后由 CloudApp Secrets 注入） ----
+  : "\${TCR_USERNAME:?TCR_USERNAME 未设置}"
+  : "\${SECRET_TCR_PASSWORD_B64:?TCR_PASSWORD 未设置}"
+  printf '%s' "\${SECRET_TCR_PASSWORD_B64}" | base64 --decode | docker login -u "\${TCR_USERNAME}" --password-stdin "\${TCR_REGISTRY}"
+fi
+
+docker push "\${IMAGE}"
+
+echo "::output::tag=\${CLOUDBASE_VERSION_NAME}"
+`;
+function resolveTarget(config) {
+    const build = config.build;
+    const repository = (build.repository || config.name).trim();
+    const registryId = build.registryId;
+    const isEnterprise = config.imageType === 'enterprise' || Boolean(registryId);
+    // CloudApp custom 构建与推送必须使用同一个平台版本 tag。
+    // 若允许自定义 tag，build-image 会构建自定义 tag，而固定推送脚本会推
+    // $CLOUDBASE_VERSION_NAME，最终必然找不到本地镜像。
+    if (build.tag) {
+        assertSafeTag(build.tag);
+        throw new error_1.CloudBaseError('cloud 策略不支持自定义 build.tag，请移除该字段并使用平台生成的 CLOUDBASE_VERSION_NAME', { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_TAG_INVALID });
+    }
+    // repository 允许两种形态：
+    // 1) namespace/image 或完整 registry/namespace/image：直接拆分
+    // 2) 仅镜像名：使用 cloudbaserc 中显式声明并经 {{env.*}} 解析后的 build.namespace
+    let registry = DEFAULT_PERSONAL_REGISTRY;
+    let hasExplicitRegistry = false;
+    let namespace = (build.namespace || '').trim();
+    let imageName = repository;
+    if (!isEnterprise && !namespace) {
+        throw new error_1.CloudBaseError('个人版 TCR 云端构建缺少 build.namespace；请在 cloudbaserc 中显式声明，' +
+            '推荐使用 "{{env.TCB_TCR_NAMESPACE}}"', { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_REPOSITORY_INVALID });
+    }
+    if (repository.includes('/')) {
+        assertSafeRegistryToken(repository, 'build.repository');
+        const parts = repository.split('/').filter(Boolean);
+        // 形如 domain/ns/name或 ns/name
+        let repositoryNamespace;
+        if (parts.length >= 3 && parts[0].includes('.')) {
+            registry = parts[0];
+            hasExplicitRegistry = true;
+            repositoryNamespace = parts.slice(1, -1).join('/');
+        }
+        else {
+            repositoryNamespace = parts.slice(0, -1).join('/');
+        }
+        if (namespace && namespace !== repositoryNamespace) {
+            throw new error_1.CloudBaseError('build.namespace 与 build.repository 中的命名空间不一致', { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_REPOSITORY_INVALID });
+        }
+        namespace = namespace || repositoryNamespace;
+        imageName = parts[parts.length - 1];
+    }
+    else {
+        assertSafeRegistryToken(repository, 'build.repository');
+    }
+    assertSafeRegistryToken(registry, 'TCR registry');
+    if (!namespace) {
+        throw new error_1.CloudBaseError('cloud 策略缺少 TCR 命名空间，请配置 build.namespace 或在完整 repository 中声明', { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_REPOSITORY_INVALID });
+    }
+    assertSafeRegistryToken(namespace, 'TCR namespace');
+    if (config.imageType === 'personal' && registryId) {
+        throw new error_1.CloudBaseError('cloud 策略的 personal 镜像不能配置 build.registryId；请移除该字段或改用 enterprise', { code: types_1.FUNCTION_DEPLOY_ERROR.IMAGE_TYPE_INVALID });
+    }
+    if (config.imageType === 'enterprise' && !registryId) {
+        throw new error_1.CloudBaseError('cloud 策略的企业版 TCR 缺少 registryId，请配置 build.registryId', { code: types_1.FUNCTION_DEPLOY_ERROR.IMAGE_REGISTRY_ID_MISSING });
+    }
+    if (isEnterprise && !hasExplicitRegistry) {
+        throw new error_1.CloudBaseError('cloud 策略的企业版 TCR 需要明确仓库域名：请将 build.repository 配置为 ' +
+            'registry/namespace/repository；registryId 无法用于推导仓库域名', { code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_REPOSITORY_INVALID });
+    }
+    return {
+        registry,
+        namespace,
+        registryId,
+        serviceName: imageName
+    };
+}
+/**
+ * 生成固定的 CustomSteps 模板（build + push）
+ *
+ * 关键安全点：command 完全由 SDK 生成，用户输入只以构建环境变量方式注入
+ * （$TCR_REGISTRY / $TCR_NAMESPACE / $CLOUDBASE_SERVICE_NAME / $CLOUDBASE_VERSION_NAME），
+ * 这些变量的值已在 resolveTarget 中做白名单校验，故命令本身无注入面。
+ */
+function buildCustomSteps() {
+    return [
+        {
+            name: 'build-image',
+            command: 'docker build -t ' +
+                '$TCR_REGISTRY/$TCR_NAMESPACE/$CLOUDBASE_SERVICE_NAME:$CLOUDBASE_VERSION_NAME .'
+        },
+        {
+            name: 'push-image',
+            command: 'bash ./scripts/tcr-login-and-push.sh'
+        }
+    ];
+}
+/**
+ * 组装 custom 构建的环境变量（用户可控值已校验，此处只做键值透传）
+ *
+ * - TCR_REGION：部署地域，供推送脚本换取镜像仓库登录态时签名/请求用，
+ *   缺省交由脚本回退默认地域；参数化后跨地域不会 SignatureFailure。
+ * - TCR_INSTANCE_ID：仅企业版 TCR 注入，脚本据此走 CreateInstanceToken 分支；
+ *   个人版 CCR 不注入，脚本走 STS 直接 docker login 分支。
+ */
+function buildEnv(target, region) {
+    const env = [
+        { key: 'TCR_REGISTRY', value: target.registry },
+        { key: 'TCR_NAMESPACE', value: target.namespace }
+    ];
+    if (region) {
+        env.push({ key: 'TCR_REGION', value: region });
+    }
+    if (target.registryId) {
+        assertSafeRegistryToken(target.registryId, 'registryId');
+        env.push({ key: 'TCR_INSTANCE_ID', value: target.registryId });
+    }
+    return env;
+}
+/**
+ * 组装个人版 TCR 凭证。
+ * username 可作为普通构建变量；password 必须进入 CloudApp Secrets。
+ */
+function buildRegistryCredentials(config, target) {
+    var _a;
+    if (target.registryId) {
+        return { env: [] };
+    }
+    const credential = config.build.registryCredential;
+    if (!credential) {
+        throw new error_1.CloudBaseError('个人版 TCR 云端构建缺少 build.registryCredential；请在 cloudbaserc 中显式声明 ' +
+            'username/password，推荐分别使用 "{{env.TCB_TCR_USERNAME}}" 和 ' +
+            '"{{env.TCB_TCR_PASSWORD}}"', { code: types_1.FUNCTION_DEPLOY_ERROR.CLOUD_REGISTRY_CREDENTIAL_MISSING });
+    }
+    const username = (_a = credential.username) === null || _a === void 0 ? void 0 : _a.trim();
+    const password = credential.password;
+    if (typeof username !== 'string' ||
+        !/^\d{5,20}$/.test(username) ||
+        typeof password !== 'string' ||
+        !password ||
+        password.length > 16 * 1024) {
+        throw new error_1.CloudBaseError('个人版 TCR 凭证不合法：TCB_TCR_USERNAME 需为腾讯云账号 ID，' +
+            'TCB_TCR_PASSWORD 不能为空且长度不能超过 16KB', { code: types_1.FUNCTION_DEPLOY_ERROR.CLOUD_REGISTRY_CREDENTIAL_INVALID });
+    }
+    // CloudApp Secret 对原始特殊字符的处理需要与本地 dotenv 解耦验证，因此这里先做
+    // Base64 封装；构建容器内仅在管道中解码并直接送入 docker login stdin。
+    // Base64 不是加密，安全边界仍由 CloudApp Secrets 提供，编码值不得进入普通 Env 或日志。
+    const passwordBase64 = Buffer.from(password, 'utf8').toString('base64');
+    return {
+        env: [{ key: 'TCR_USERNAME', value: username }],
+        secrets: [{ name: 'TCR_PASSWORD_B64', value: passwordBase64 }]
+    };
+}
+/** 从构建产物或拼接规则得到最终不可变镜像地址 */
+function resolveImageUri(target, versionName, artifacts) {
+    // 优先从 Artifacts 取平台回传的镜像信息
+    const imageArtifact = (artifacts || []).find(item => (item === null || item === void 0 ? void 0 : item.Type) === 'image');
+    if (imageArtifact === null || imageArtifact === void 0 ? void 0 : imageArtifact.ImageUri) {
+        return { imageUri: imageArtifact.ImageUri, imageDigest: imageArtifact.Digest };
+    }
+    // 无Artifacts 时按约定拼接：{registry}/{namespace}/{name}:{tag}
+    const imageUri = `${target.registry}/${target.namespace}/${target.serviceName}:${versionName}`;
+    return { imageUri, imageDigest: imageArtifact === null || imageArtifact === void 0 ? void 0 : imageArtifact.Digest };
+}
+/** 汇总失败 Step 的定位信息（脱敏：只取步骤名/状态/退出码，不含日志明文） */
+function summarizeFailedSteps(steps) {
+    const failed = (steps || []).filter(step => typeof (step === null || step === void 0 ? void 0 : step.Status) === 'string' && step.Status.toLowerCase() === 'failed');
+    if (failed.length === 0) {
+        return '';
+    }
+    return failed
+        .map(step => {
+        const code = step.ExitCode !== undefined ? ` (exit ${step.ExitCode})` : '';
+        return `${step.Name}${code}`;
+    })
+        .join(', ');
+}
+/**
+ * 执行云端构建并推送镜像
+ *
+ * @param config 规范化的 cloud 部署配置
+ * @param service 注入的外部能力（打包/tcb API/COS 上传）
+ * @param options 可选项：日志回调 onLog、部署地域 region
+ */
+async function buildImageOnCloud(config, service, options = {}) {
+    const { onLog, region } = options;
+    const target = resolveTarget(config);
+    // 在打包和上传前完成真实消费字段校验，避免额外维护环境变量名清单。
+    const registryCredentials = buildRegistryCredentials(config, target);
+    const serviceName = target.serviceName;
+    const cwd = config.build.cwd || config.functionPath || process.cwd();
+    // 1. 打包构建上下文（注入 push 脚本，不污染用户源码目录）
+    onLog === null || onLog === void 0 ? void 0 : onLog('打包构建上下文');
+    const zipPath = await service.packContext(cwd, [
+        {
+            zipPath: exports.TCR_PUSH_SCRIPT_ZIP_PATH,
+            content: exports.TCR_LOGIN_PUSH_SCRIPT,
+            mode: 0o755
+        }
+    ]);
+    try {
+        // 2. 获取 COS 上传凭证
+        onLog === null || onLog === void 0 ? void 0 : onLog('获取 COS 上传凭证');
+        const cosInfo = await service.getCosInfo(serviceName);
+        if (!(cosInfo === null || cosInfo === void 0 ? void 0 : cosInfo.uploadUrl) || !(cosInfo === null || cosInfo === void 0 ? void 0 : cosInfo.unixTimestamp)) {
+            throw new error_1.CloudBaseError('获取 COS 上传凭证失败：返回缺少 UploadUrl 或 UnixTimestamp', {
+                code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_CONTEXT_INVALID
+            });
+        }
+        // 3. 上传源码 ZIP（携带全部 UploadHeaders）
+        onLog === null || onLog === void 0 ? void 0 : onLog('上传源码到 COS');
+        await service.uploadZip(cosInfo, zipPath);
+        // 4. 触发 custom 构建
+        onLog === null || onLog === void 0 ? void 0 : onLog('触发云端构建');
+        const created = await service.createBuild({
+            serviceName,
+            cosTimestamp: cosInfo.unixTimestamp,
+            env: [...buildEnv(target, region), ...registryCredentials.env],
+            secrets: registryCredentials.secrets,
+            customSteps: buildCustomSteps()
+        });
+        if (!(created === null || created === void 0 ? void 0 : created.versionName)) {
+            throw new error_1.CloudBaseError('触发云端构建失败：返回缺少 VersionName', {
+                code: types_1.FUNCTION_DEPLOY_ERROR.BUILD_CONTEXT_INVALID
+            });
+        }
+        // 打出触发构建的 RequestId 与版本号，便于把构建问题反馈给平台后端定位
+        onLog === null || onLog === void 0 ? void 0 : onLog(`已触发云端构建 versionName=${created.versionName}` +
+            (created.requestId ? ` requestId=${created.requestId}` : ''));
+        // 5. 退避轮询到终态
+        const finalStatus = await pollUntilTerminal({
+            service,
+            serviceName,
+            versionName: created.versionName,
+            onLog
+        });
+        if (finalStatus.status === 'FAILED' || finalStatus.status === 'CANCELED') {
+            const failedInfo = summarizeFailedSteps(finalStatus.steps);
+            const detail = failedInfo ? `，失败步骤：${failedInfo}` : '';
+            const reqId = finalStatus.requestId
+                ? `，requestId=${finalStatus.requestId}`
+                : '';
+            const code = finalStatus.status === 'CANCELED'
+                ? types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_CANCELED
+                : types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_FAILED;
+            throw new error_1.CloudBaseError(`云端构建未成功（${finalStatus.status}）${detail}${reqId}`, { code });
+        }
+        // 6. 得到不可变镜像地址与digest
+        const { imageUri, imageDigest } = resolveImageUri(target, created.versionName, finalStatus.artifacts);
+        return {
+            imageUri,
+            imageDigest,
+            buildId: created.buildId,
+            versionName: created.versionName
+        };
+    }
+    finally {
+        // 清理临时 zip，失败不影响主流程
+        try {
+            await service.cleanup(zipPath);
+        }
+        catch (_a) {
+            // 忽略清理异常
+        }
+    }
+}
+/**
+ * 退避轮询构建版本状态直到终态
+ *
+ * - 间隔从 5s 退避到 30s，总超时 15 分钟。
+ * - 临时网络错误连续重试，超过阈值才判失败，避免抖动误杀长构建。
+ */
+async function pollUntilTerminal(params) {
+    const { service, serviceName, versionName, onLog } = params;
+    const start = Date.now();
+    let interval = POLL_INITIAL_INTERVAL;
+    let transientErrors = 0;
+    // 先等一个间隔再查，构建刚触发通常还没状态
+    while (Date.now() - start < POLL_TOTAL_TIMEOUT) {
+        await service.delay(interval);
+        let status;
+        try {
+            status = await service.getVersionStatus(serviceName, versionName);
+            transientErrors = 0;
+        }
+        catch (error) {
+            transientErrors += 1;
+            if (transientErrors > POLL_MAX_TRANSIENT_ERRORS) {
+                throw new error_1.CloudBaseError(`查询构建状态连续失败 ${transientErrors} 次：${(error === null || error === void 0 ? void 0 : error.message) || error}`, { code: types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_FAILED });
+            }
+            // 临时错误，继续退避重试
+            interval = Math.min(interval * 2, POLL_MAX_INTERVAL);
+            continue;
+        }
+        const normalized = (status.status || '').toUpperCase();
+        onLog === null || onLog === void 0 ? void 0 : onLog(`构建状态：${normalized}`);
+        if (normalized === 'SUCCESS' || normalized === 'FAILED' || normalized === 'CANCELED') {
+            // 终态时打出查询接口 RequestId，便于把该次构建版本反馈给平台后端定位
+            if (status.requestId) {
+                onLog === null || onLog === void 0 ? void 0 : onLog(`构建版本查询 requestId=${status.requestId}`);
+            }
+            return Object.assign(Object.assign({}, status), { status: normalized });
+        }
+        // 仍在构建，退避
+        interval = Math.min(interval * 2, POLL_MAX_INTERVAL);
+    }
+    throw new error_1.CloudBaseError(`云端构建超时（超过 ${Math.round(POLL_TOTAL_TIMEOUT / 60000)} 分钟仍未完成）`, { code: types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_TIMEOUT });
+}

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

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMAGE_PULL_GRANT_URL = exports.REQUIRED_IMAGE_PULL_POLICY = exports.SCF_PULL_IMAGE_ROLE = void 0;
+exports.isCamPermissionError = isCamPermissionError;
+exports.runImagePullAuthPreflight = runImagePullAuthPreflight;
+const types_1 = require("../types");
+/**
+ * 镜像拉取授权 Preflight（涉及 CAM，scope: cloud）
+ *
+ * SCF 拉取镜像由服务角色 SCF_QcsRole 代理，个人版镜像要求该角色绑定
+ * QcloudAccessForSCFRoleInPullImage 策略。本模块在 image 策略部署前：
+ *   1. 探测该角色与策略是否就绪；
+ *   2. 缺失且允许时，自动绑定「唯一白名单策略」补齐（绝不放大到其它策略）；
+ *   3. 当前身份无 CAM 权限时不硬失败，降级为结构化指引 + 一键授权链接兜底。
+ *
+ * 安全边界（对应 security_rules 的 AuthZ / 最小权限）：
+ * - 自动授权只允许绑定 REQUIRED_IMAGE_PULL_POLICY 这一条部署必需的预置策略；
+ * - 不代用户创建角色、不绑定任何白名单外策略；
+ * - 探测/授权失败一律走降级，不阻断到无法给出可操作指引。
+ */
+/** SCF 拉取镜像使用的服务角色 */
+exports.SCF_PULL_IMAGE_ROLE = 'SCF_QcsRole';
+/** 拉取个人版镜像所需的唯一预置策略（自动授权白名单，仅此一条） */
+exports.REQUIRED_IMAGE_PULL_POLICY = 'QcloudAccessForSCFRoleInPullImage';
+/** 官方一键授权链接，作为无 CAM 权限时的兜底指引 */
+exports.IMAGE_PULL_GRANT_URL = 'https://console.cloud.tencent.com/cam/role/grant' +
+    `?roleName=${exports.SCF_PULL_IMAGE_ROLE}&policyName=${exports.REQUIRED_IMAGE_PULL_POLICY}` +
+    '&principal=eyJzZXJ2aWNlIjoic2NmLnFjbG91ZC5jb20ifQ%3D%3D';
+/** 判断错误是否为 CAM 权限不足 */
+function isCamPermissionError(error) {
+    const code = typeof (error === null || error === void 0 ? void 0 : error.code) === 'string' ? error.code : '';
+    const message = typeof (error === null || error === void 0 ? void 0 : error.message) === 'string' ? error.message : '';
+    const haystack = `${code} ${message}`.toLowerCase();
+    return (haystack.includes('unauthorizedoperation') ||
+        haystack.includes('no permission') ||
+        haystack.includes('not authorized') ||
+        haystack.includes('cam_unauthorized'));
+}
+/** 判断错误是否为角色不存在 */
+function isRoleNotFoundError(error) {
+    const code = typeof (error === null || error === void 0 ? void 0 : error.code) === 'string' ? error.code : '';
+    const message = typeof (error === null || error === void 0 ? void 0 : error.message) === 'string' ? error.message : '';
+    const haystack = `${code} ${message}`.toLowerCase();
+    return haystack.includes('notfound') || haystack.includes('not exist') || haystack.includes('rolenotexist');
+}
+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
+    };
+}
+/** 是否需要执行镜像拉取授权检查 */
+function needsImagePullAuth(config) {
+    var _a;
+    if (config.type !== 'HTTP') {
+        return false;
+    }
+    // image：已有个人版镜像；local：本地构建推送的也是个人版镜像，SCF 拉取同样需要该授权
+    if (config.buildStrategy === 'image') {
+        // 联合类型已按 buildStrategy 收窄为 INormalizedHttpImageConfig，可直接访问顶层与 imageConfig 字段
+        const imageType = ((_a = config.imageConfig) === null || _a === void 0 ? void 0 : _a.imageType) || config.imageType;
+        return imageType === 'personal';
+    }
+    if (config.buildStrategy === 'local' || config.buildStrategy === 'cloud') {
+        // local/cloud 个人版先行：构建推送的默认是个人版镜像，SCF 拉取同样需要该授权；
+        // 未显式指定 imageType 时视为 personal；企业版另行处理
+        const imageType = config.imageType;
+        return imageType === undefined || imageType === 'personal';
+    }
+    return false;
+}
+/** 无 CAM 读权限时的降级检查项：无法自查，转手动指引 */
+function unverifiableCheck() {
+    return warn(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_AUTH_UNVERIFIABLE, `当前身份无 CAM 权限，无法自动校验或补齐 ${exports.SCF_PULL_IMAGE_ROLE} 的拉镜像授权`, `若个人版镜像拉取失败，请用具备 CAM 权限的账号访问一键授权链接完成授权：${exports.IMAGE_PULL_GRANT_URL}`);
+}
+/**
+ * 执行镜像拉取授权 Preflight
+ *
+ * @param service CAM 能力适配（无则视为无法校验，直接降级为提示）
+ * @param config 规范化部署配置
+ * @param autoGrant 是否允许自动补齐授权（默认 true）
+ * @returns scope 为 cloud 的检查报告，聚合全部结论
+ */
+async function runImagePullAuthPreflight(service, config, autoGrant = true) {
+    if (!needsImagePullAuth(config)) {
+        return buildReport([]);
+    }
+    // 无 CAM 适配能力：不阻断，仅提示手动授权入口
+    if (!service) {
+        return buildReport([unverifiableCheck()]);
+    }
+    const checks = [];
+    let roleDetail;
+    try {
+        roleDetail = await service.getRoleWithPolicies(exports.SCF_PULL_IMAGE_ROLE);
+    }
+    catch (error) {
+        if (isCamPermissionError(error)) {
+            // 无 CAM 读权限，无法自查，降级为提示（warn，不阻断部署尝试）
+            return buildReport([unverifiableCheck()]);
+        }
+        if (isRoleNotFoundError(error)) {
+            // 角色不存在属于真实前置缺失，不自动创建角色，给出可操作指引
+            checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_ROLE_MISSING, `缺少服务角色 ${exports.SCF_PULL_IMAGE_ROLE}`, {
+                remediation: `请访问一键授权链接创建角色并授予拉镜像策略：${exports.IMAGE_PULL_GRANT_URL}`
+            }));
+            return buildReport(checks);
+        }
+        // 其它未知错误同样降级为提示，避免因 CAM 波动阻断部署
+        return buildReport([unverifiableCheck()]);
+    }
+    const attached = roleDetail.attachedPolicyNames || [];
+    if (attached.includes(exports.REQUIRED_IMAGE_PULL_POLICY)) {
+        checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_POLICY_MISSING, `${exports.SCF_PULL_IMAGE_ROLE} 已具备拉镜像策略 ${exports.REQUIRED_IMAGE_PULL_POLICY}`));
+        return buildReport(checks);
+    }
+    // 未绑定拉镜像策略
+    if (!autoGrant) {
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_POLICY_MISSING, `${exports.SCF_PULL_IMAGE_ROLE} 缺少拉镜像策略 ${exports.REQUIRED_IMAGE_PULL_POLICY}`, {
+            remediation: `已关闭自动授权（autoGrant=false）。请访问一键授权链接手动授予：${exports.IMAGE_PULL_GRANT_URL}`
+        }));
+        return buildReport(checks);
+    }
+    // 自动授权：只绑定唯一白名单策略
+    try {
+        await service.attachPolicyByName(exports.SCF_PULL_IMAGE_ROLE, exports.REQUIRED_IMAGE_PULL_POLICY);
+        checks.push(pass(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_AUTH_GRANTED, `已自动为 ${exports.SCF_PULL_IMAGE_ROLE} 绑定拉镜像策略 ${exports.REQUIRED_IMAGE_PULL_POLICY}`));
+        return buildReport(checks);
+    }
+    catch (error) {
+        if (isCamPermissionError(error)) {
+            // 无 CAM 写权限：不硬失败，降级为可操作指引 + 兜底链接
+            checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_CAM_PERMISSION_DENIED, `当前身份无 CAM 授权权限，无法自动为 ${exports.SCF_PULL_IMAGE_ROLE} 补齐拉镜像策略`, {
+                remediation: `请用具备 CAM 权限的账号（如主账号）访问一键授权链接完成授权：${exports.IMAGE_PULL_GRANT_URL}`,
+                detail: error === null || error === void 0 ? void 0 : error.message
+            }));
+            return buildReport(checks);
+        }
+        // 其它授权错误同样给出结构化失败与指引
+        checks.push(fail(types_1.FUNCTION_DEPLOY_ERROR.PREFLIGHT_IMAGE_PULL_POLICY_MISSING, `自动绑定拉镜像策略 ${exports.REQUIRED_IMAGE_PULL_POLICY} 失败`, {
+            remediation: `请访问一键授权链接手动授予：${exports.IMAGE_PULL_GRANT_URL}`,
+            detail: error === null || error === void 0 ? void 0 : error.message
+        }));
+        return buildReport(checks);
+    }
+}