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

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

@@ -0,0 +1,654 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TCR_LOGIN_PUSH_SCRIPT = exports.TCR_PUSH_SCRIPT_ZIP_PATH = void 0;
+exports.buildImageOnCloud = buildImageOnCloud;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+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 TCR_REGISTRY_AUTH_EXIT_CODE = 42;
+const TCR_REGISTRY_INVALID_EXIT_CODE = 43;
+/** 个人版 TCR 自动创建目标仓库时，仓库数量已达到地域配额 */
+const TCR_PERSONAL_REPOSITORY_QUOTA_EXIT_CODE = 44;
+/** 仓库地址/命名空间/服务名等安全字符白名单：域名、路径、字母数字与常见分隔符 */
+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)) {
+        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
+        });
+    }
+}
+/** 校验 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命令一致） */
+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}"
+IS_PERSONAL_REGISTRY=0
+
+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}")
+
+  ERROR_CODE=$(printf '%s' "\${RESP}" | jq -r '.Response.Error.Code // empty')
+  if [ -n "\${ERROR_CODE}" ]; then
+    case "\${ERROR_CODE}" in
+      AuthFailure*|UnauthorizedOperation*|FailedOperation.NoPermission*)
+        echo "企业版 TCR 鉴权失败，请确认当前身份有权访问该实例并调用 CreateInstanceToken" >&2
+        exit ${TCR_REGISTRY_AUTH_EXIT_CODE}
+        ;;
+      ResourceNotFound*|InvalidParameterValue.RegistryId*)
+        echo "企业版 TCR 实例不存在或实例 ID 无效" >&2
+        exit ${TCR_REGISTRY_INVALID_EXIT_CODE}
+        ;;
+      *)
+        echo "企业版 TCR 获取登录凭证失败：\${ERROR_CODE}" >&2
+        exit 1
+        ;;
+    esac
+  fi
+
+  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 注入） ----
+  IS_PERSONAL_REGISTRY=1
+  : "\${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
+
+PUSH_LOG=$(mktemp)
+trap 'rm -f "\${PUSH_LOG}"' EXIT
+set +e
+docker push "\${IMAGE}" 2>&1 | tee "\${PUSH_LOG}"
+PUSH_STATUS=\${PIPESTATUS[0]}
+set -e
+
+if [ "\${PUSH_STATUS}" -ne 0 ]; then
+  if [ "\${IS_PERSONAL_REGISTRY}" -eq 1 ] && {
+    grep -Fq 'LimitExceeded.ErrRepoMaxLimit' "\${PUSH_LOG}" ||
+    grep -Fq '用户仓库已经达到最大配额' "\${PUSH_LOG}"
+  }; then
+    echo "个人版 TCR 镜像仓库数量已达到当前地域配额，无法自动创建目标仓库" >&2
+    exit ${TCR_PERSONAL_REPOSITORY_QUOTA_EXIT_CODE}
+  fi
+  exit 1
+fi
+
+echo "::output::tag=\${CLOUDBASE_VERSION_NAME}"
+`;
+function resolveTarget(config) {
+    const build = config.build;
+    const repository = (build.repository || config.name).trim();
+    const rawRegistryId = build.registryId;
+    const registryId = typeof rawRegistryId === 'string' ? rawRegistryId.trim() : rawRegistryId;
+    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') {
+        if (rawRegistryId === undefined || rawRegistryId === null) {
+            throw new error_1.CloudBaseError('cloud 策略的企业版 TCR 未配置 build.registryId；如果当前没有企业版实例，请改用 imageType=personal', { code: types_1.FUNCTION_DEPLOY_ERROR.IMAGE_REGISTRY_ID_MISSING });
+        }
+        if (typeof registryId !== 'string' || !registryId) {
+            throw new error_1.CloudBaseError('cloud 策略的企业版 TCR build.registryId 已声明但解析结果为空；若使用 {{env.*}}，请确认环境变量已赋值，当前没有企业版实例时请改用 imageType=personal', { code: types_1.FUNCTION_DEPLOY_ERROR.IMAGE_REGISTRY_ID_INVALID });
+        }
+    }
+    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
+    };
+}
+/**
+ * 解析并校验 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）。
+ *
+ * Dockerfile、platform 和 build arg value 通过 CloudApp Env 注入；只有通过严格
+ * ENV key 校验的 build arg key 会进入固定 command。forceBuild 显式映射为 --no-cache。
+ */
+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' +
+                ' --platform "$CLOUDBASE_BUILD_PLATFORM"' +
+                ' -f "$CLOUDBASE_DOCKERFILE"' +
+                noCache +
+                extraArgs +
+                ' -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, buildOptions, region) {
+    const env = [
+        { key: 'TCR_REGISTRY', value: target.registry },
+        { 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 });
+    }
+    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 resolveCloudBuildContext(config, dockerfile) {
+    const cwd = path_1.default.resolve(config.build.cwd || config.functionPath || process.cwd());
+    const dockerfilePath = path_1.default.resolve(cwd, dockerfile);
+    let stat = null;
+    try {
+        stat = fs_1.default.statSync(dockerfilePath);
+    }
+    catch (error) {
+        if (!error || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    if ((stat === null || stat === void 0 ? void 0 : stat.isFile()) !== true) {
+        throw new error_1.CloudBaseError(`Dockerfile 不存在或不是普通文件：${dockerfilePath}`, {
+            code: types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_DOCKERFILE_MISSING
+        });
+    }
+    return cwd;
+}
+/** 从构建产物或拼接规则得到最终不可变镜像地址 */
+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 };
+}
+/** 判断企业版 TCR 推送步骤是否因实例鉴权失败 */
+function isRegistryAuthFailure(steps) {
+    return (steps || []).some(step => {
+        var _a;
+        return (step === null || step === void 0 ? void 0 : step.Name) === 'push-image' &&
+            ((_a = step === null || step === void 0 ? void 0 : step.Status) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === 'failed' &&
+            step.ExitCode === TCR_REGISTRY_AUTH_EXIT_CODE;
+    });
+}
+/** 判断企业版 TCR 推送步骤是否因实例 ID 无效失败 */
+function isRegistryIdFailure(steps) {
+    return (steps || []).some(step => {
+        var _a;
+        return (step === null || step === void 0 ? void 0 : step.Name) === 'push-image' &&
+            ((_a = step === null || step === void 0 ? void 0 : step.Status) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === 'failed' &&
+            step.ExitCode === TCR_REGISTRY_INVALID_EXIT_CODE;
+    });
+}
+/** 判断个人版 TCR 是否因自动创建目标仓库时达到仓库数量配额而失败 */
+function isPersonalRepositoryQuotaFailure(target, steps) {
+    if (target.registryId) {
+        return false;
+    }
+    return (steps || []).some(step => {
+        var _a;
+        return (step === null || step === void 0 ? void 0 : step.Name) === 'push-image' &&
+            ((_a = step === null || step === void 0 ? void 0 : step.Status) === null || _a === void 0 ? void 0 : _a.toLowerCase()) === 'failed' &&
+            step.ExitCode === TCR_PERSONAL_REPOSITORY_QUOTA_EXIT_CODE;
+    });
+}
+/** 汇总失败 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 buildOptions = resolveCloudBuildOptions(config);
+    // 在打包和上传前完成真实消费字段校验，避免无效配置触发远端资源操作。
+    const registryCredentials = buildRegistryCredentials(config, target);
+    const serviceName = target.serviceName;
+    const cwd = resolveCloudBuildContext(config, buildOptions.dockerfile);
+    // 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, buildOptions, region),
+                ...registryCredentials.env
+            ],
+            secrets: registryCredentials.secrets,
+            customSteps: buildCustomSteps(buildOptions)
+        });
+        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 registryAuthFailure = isRegistryAuthFailure(finalStatus.steps);
+            const registryIdFailure = isRegistryIdFailure(finalStatus.steps);
+            const personalRepositoryQuotaFailure = isPersonalRepositoryQuotaFailure(target, finalStatus.steps);
+            const code = finalStatus.status === 'CANCELED'
+                ? types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_CANCELED
+                : registryAuthFailure
+                    ? types_1.FUNCTION_DEPLOY_ERROR.CLOUD_REGISTRY_AUTH_FAILED
+                    : registryIdFailure
+                        ? types_1.FUNCTION_DEPLOY_ERROR.IMAGE_REGISTRY_ID_INVALID
+                        : personalRepositoryQuotaFailure
+                            ? types_1.FUNCTION_DEPLOY_ERROR.CLOUD_PERSONAL_REGISTRY_REPOSITORY_QUOTA_EXCEEDED
+                            : types_1.FUNCTION_DEPLOY_ERROR.CLOUD_BUILD_FAILED;
+            const guidance = finalStatus.status === 'CANCELED'
+                ? ''
+                : registryAuthFailure
+                    ? '；企业版 TCR 鉴权失败，请确认实例属于当前账号/地域，且当前身份拥有 CreateInstanceToken 和仓库推送权限'
+                    : registryIdFailure
+                        ? '；企业版 TCR 实例不存在或实例 ID 无效，请检查 build.registryId 对应的环境变量和实例状态'
+                        : personalRepositoryQuotaFailure
+                            ? '；个人版 TCR 当前地域的镜像仓库数量已达到配额，目标仓库无法自动创建。请在容器镜像服务个人版中删除不再使用的仓库（删除前请备份其中镜像），或将 build.repository 改为已有仓库；如需更多仓库，请切换企业版 TCR。实际配额请以控制台为准'
+                            : '';
+            throw new error_1.CloudBaseError(`云端构建未成功（${finalStatus.status}）${detail}${reqId}${guidance}`, { 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 });
+}