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

package/types/deploy/StateStore.d.ts

@@ -0,0 +1,170 @@
+/** hosting 文件指纹（hash + size；size 用于懒加载 diff 预判，避免为未变文件重复读内容） */
+export interface IHostingFileFingerprint {
+    hash: string;
+    size: number;
+}
+/** 快照中指纹值：兼容旧格式（纯 string = 仅 hash，size 未知） */
+export type HostingFileValue = string | IHostingFileFingerprint;
+/** hosting 状态快照条目（产物指纹，不存文件内容） */
+export interface IHostingStateEntry {
+    name: string;
+    deployPath?: string;
+    /** 相对路径 → 文件指纹（兼容旧格式：纯字符串 = 仅 hash，size 未知） */
+    files: Record<string, HostingFileValue>;
+}
+/** hosting 文件级 diff 结果（懒加载：size 预判 + 按需 hash） */
+export interface IHostingFileDiff {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    totalChanged: number;
+    /** 本地与快照完全一致（可跳过部署） */
+    unchanged: boolean;
+    /** true = 文件数超过指纹上限，diff 被放弃，需降级为全量部署 */
+    overLimit?: boolean;
+}
+/** hosting 指纹扫描选项 */
+export interface IHostingScanOptions {
+    /** 指纹文件数上限：超过则抛 HostingFilesOverLimitError（默认 50000；0 = 不限） */
+    maxFiles?: number;
+    /** hash 截断长度（hex 位数，默认 16；64 = 完整 sha256） */
+    hashLength?: number;
+}
+/** diffHostingFiles 选项（继承扫描选项，追加忽略规则） */
+export interface IHostingDiffOptions extends IHostingScanOptions {
+    /** 自定义忽略规则（追加到默认 node_modules / .DS_Store 之后） */
+    ignore?: string[];
+}
+/** hosting 指纹文件数超过上限时抛出（触发降级为全量部署） */
+export declare class HostingFilesOverLimitError extends Error {
+    fileCount: number;
+    limit: number;
+    constructor(fileCount: number, limit: number);
+}
+/** 默认指纹文件数上限（防快照膨胀与 I/O 失控） */
+export declare const DEFAULT_MAX_HOSTING_FILES = 50000;
+/** 默认 hash 截断长度（16 位 hex = 64bit，碰撞概率可忽略；快照体积减半） */
+export declare const DEFAULT_HASH_LENGTH = 16;
+/** app 状态快照条目（仅 diff 相关字段，不写 envVariables 等敏感信息） */
+export interface IAppStateEntry {
+    serviceName?: string;
+    installCommand?: string;
+    buildCommand?: string;
+    outputDir?: string;
+    deployPath?: string;
+}
+/** 部署状态快照（.cloudbase/state.json） */
+export interface IDeployState {
+    version: number;
+    updatedAt: string;
+    gitCommit?: string;
+    resources: {
+        hosting?: IHostingStateEntry[];
+        gateway?: unknown;
+        app?: IAppStateEntry;
+    };
+}
+interface IStateStoreOptions {
+    /** 项目根目录（默认 process.cwd()） */
+    cwd?: string;
+    /** 环境名（--env production 等）：按环境分文件 state.{env}.json */
+    env?: string;
+    /** 自定义 state 路径（优先于 cwd+env 推导） */
+    stateFile?: string;
+}
+/**
+ * 部署状态快照（StateStore）
+ *
+ * 职责：读写 `.cloudbase/state.json`（默认），为 dry-run 的 hosting/app diff 提供本地基准，
+ * 避免每次 diff 都拉取云端。
+ *
+ * 指纹算法：hosting = 产物目录逐文件内容 sha256（相对路径为 key）。
+ * 只存 hash 不存内容，体积 = O(文件数)；app 快照不写入 envVariables（敏感过滤）。
+ */
+export declare class StateStore {
+    private cwd;
+    private env?;
+    private stateFile?;
+    constructor(options?: IStateStoreOptions);
+    /**
+     * 计算 state 文件路径：
+     * - 自定义 stateFile 优先
+     * - 否则 {cwd}/.cloudbase/state.json（无 env）或 state.{env}.json（多环境隔离）
+     */
+    getFilePath(): string;
+    /**
+     * 读取状态快照；文件不存在或 JSON 损坏返回 null（缺失降级，由调用方走云端兜底）
+     */
+    read(): IDeployState | null;
+    /**
+     * 写入状态快照（自动补 version/updatedAt/gitCommit，自动创建 .cloudbase 目录）
+     */
+    write(state: {
+        resources: IDeployState['resources'];
+        gitCommit?: string;
+    }): void;
+    /**
+     * 计算产物目录逐文件 sha256 指纹（仅 hash，兼容旧调用）
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param ignore 自定义忽略规则（追加到默认 node_modules / .DS_Store 之后）
+     * @param options 扫描选项（maxFiles / hashLength）
+     * @returns 相对路径（/ 分隔）→ 文件内容 sha256（默认截断 16 位）
+     */
+    computeHostingFiles(projectPath: string, ignore?: string[], options?: IHostingScanOptions): Promise<Record<string, string>>;
+    /**
+     * 计算产物目录逐文件指纹（hash + size）
+     *
+     * - 强制忽略 node_modules / .DS_Store（与传入 ignore 合并，不可关闭）
+     * - hash 默认截断为 16 位 hex（hashLength 可调，64 = 完整 sha256）
+     * - 文件数超过 maxFiles 抛 HostingFilesOverLimitError（防快照膨胀与 I/O 失控）
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param ignore 自定义忽略规则
+     * @param options 扫描选项（maxFiles / hashLength）
+     * @returns 相对路径（/ 分隔）→ { hash, size }
+     */
+    computeHostingFingerprints(projectPath: string, ignore?: string[], options?: IHostingScanOptions): Promise<Record<string, IHostingFileFingerprint>>;
+    /**
+     * 计算产物目录与快照的变更集（懒加载）
+     *
+     * 优化：先 stat 拿 size，size 与快照不同的文件直接判定变更（不读文件内容），
+     * 只有 size 相同（或旧快照 size 未知）的文件才读内容 hash 对比，
+     * 避免为未变文件做无谓的 I/O 与 hash。
+     * 文件数超过 maxFiles 时放弃 diff，返回 overLimit=true（调用方应降级为全量部署）。
+     *
+     * @param projectPath 产物目录（hosting 的 outputDir / root）
+     * @param previous 上次快照指纹（undefined = 首次部署，全部视为新增）
+     * @param options 选项（ignore / maxFiles / hashLength）
+     */
+    diffHostingFiles(projectPath: string, previous: Record<string, HostingFileValue> | undefined, options?: IHostingDiffOptions): Promise<IHostingFileDiff>;
+    /**
+     * 提取 app 配置快照（仅 diff 白名单字段）
+     * envVariables / ignore 等非 diff 字段与敏感信息不进入快照
+     */
+    buildAppConfig(config: {
+        serviceName?: string;
+        installCommand?: string;
+        buildCommand?: string;
+        outputDir?: string;
+        deployPath?: string;
+        [key: string]: unknown;
+    }): IAppStateEntry | undefined;
+    private hashFile;
+    /** 合并默认忽略规则（node_modules / .DS_Store 不可被调用方关闭） */
+    private mergeIgnore;
+    /** 归一化快照指纹值：旧格式（纯 string = 仅 hash，size 未知用 -1 表示） */
+    private normalizeFileValue;
+    /**
+     * 是否命中忽略规则：
+     * - 目录模式（结尾 /）：匹配该目录及其下所有
+     * - glob（含 **）：转换为正则匹配相对路径
+     * - 其余：精确/前缀匹配
+     */
+    private isIgnored;
+    private matchPattern;
+    private escapeRegExp;
+    /** 解析当前 git commit（非 git 仓库或失败返回 undefined，不阻断） */
+    private resolveGitCommit;
+}
+export {};

package/types/deploy/StaticDeployer.d.ts

@@ -0,0 +1,104 @@
+import { Environment } from '../environment';
+/** app 声明式配置（cloudbaserc.json app 对象） */
+export interface IAppDeployConfig {
+    serviceName?: string;
+    root?: string;
+    framework?: string;
+    installCommand?: string;
+    buildCommand?: string;
+    outputDir?: string;
+    deployPath?: string;
+    ignore?: string[];
+    envVariables?: Record<string, string | number | boolean>;
+}
+/** hosting 声明式配置（cloudbaserc.json hosting[]） */
+export interface IHostingDeployConfig {
+    name?: string;
+    root?: string;
+    /** 框架类型：显式指定或未配置时读 root/package.json 自动检测；static/custom 表示纯静态（不构建） */
+    framework?: string;
+    /** 安装命令，默认 npm install；空字符串跳过安装 */
+    installCommand?: string;
+    /** 构建命令：非空则本地构建后上传；空字符串/未配置且无法检测 → 纯静态直接上传 outputDir */
+    buildCommand?: string;
+    /** 构建产物目录：有构建时默认 dist，纯静态时默认 root */
+    outputDir?: string;
+    /** 云端部署路径（决定访问 URL 与网关 PathRewrite.Prefix） */
+    deployPath?: string;
+    ignore?: string[];
+    /** 构建时环境变量（注入本地构建进程，非敏感） */
+    envVariables?: Record<string, string | number | boolean>;
+    /** SPA 回退：true 时 404 返回 index.html */
+    spaFallback?: boolean;
+}
+export interface IStaticDeployResult {
+    name: string;
+    url?: string;
+    /** 是否写入了版本记录（app 写、hosting 不写） */
+    wroteRecord: boolean;
+}
+/**
+ * app/hosting 声明式部署器
+ *
+ * app：framework=static → 直传产物 + SkipBuild 写记录（对齐 tcb app deploy 纯静态分支）；
+ *      其余 framework → 云端构建（上传源码 → 云端构建 → 写版本记录），与现有 tcb app deploy 一致
+ * hosting：固定静态流程（buildCommand 非空则本地构建后直传），不写版本记录（现有 tcb hosting deploy 行为）
+ */
+export declare class StaticDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * app 部署（与现有 tcb app deploy 一致）
+     *
+     * framework=static：直传产物（hosting uploadFiles）+ createApp(SkipBuild) 后台写部署记录，跳过云端构建。
+     * 其余 framework：上传源码 ZIP → createApp 云端构建 → 写版本记录。
+     */
+    deployApp(options: {
+        config: IAppDeployConfig;
+        cwd?: string;
+    }): Promise<IStaticDeployResult>;
+    /**
+     * hosting 部署（固定静态流程，不写版本记录）
+     *
+     * 支持本地构建（对齐 Netlify）：buildCommand 非空时自动执行 install + build 后上传产物；
+     * 纯静态（buildCommand 空/未配置且无法检测框架）时直接上传 outputDir（默认 root，保持现状）。
+     * 访问地址 = https://{CdnDomain}{deployPath}（与 tcb hosting deploy 一致）
+     */
+    deployHosting(options: {
+        config: IHostingDeployConfig;
+        cwd?: string;
+    }): Promise<IStaticDeployResult>;
+    /**
+     * app 纯静态直传（对齐 tcb app deploy 的 deployStaticApp 分支）
+     *
+     * 1. hosting uploadFiles 直传产物（文件级上传，立即可访问，无需打 ZIP）
+     * 2. 后台异步 createApp(SkipBuild) 写部署记录（失败不影响文件访问）
+     * 3. 跳过云端构建轮询，返回访问地址
+     */
+    private deployAppStatic;
+    /**
+     * app 云端构建：上传源码 ZIP → createApp 云端构建 → 写版本记录
+     */
+    private deployAppCloud;
+    /**
+     * 读取现有静态网站配置并保留 RoutingRules + AutoAddressing
+     * （putBucketWebsite 为整体覆盖，设置 SPA 回退前必须带回已有配置，否则会被清空）
+     */
+    private preserveWebsiteConfig;
+    /**
+     * 解析 hosting 访问地址：https://{CdnDomain}{deployPath}
+     */
+    private resolveHostingUrl;
+    /**
+     * 本地构建（install + build）
+     *
+     * - installCommand：默认 npm install，显式空字符串跳过安装
+     * - buildCommand：由调用方保证非空（hosting 经 resolveBuildCommand 判定；app local 由 if 判定）
+     * - envVariables：注入构建进程环境变量（值统一转字符串）
+     */
+    private runLocalBuild;
+    /**
+     * 解析 app 访问地址（describeAppInfo.Domain + appPath）
+     */
+    private resolveAppUrl;
+}

package/types/deploy/domain.d.ts

@@ -0,0 +1,17 @@
+import { Environment } from '../environment';
+/**
+ * 构造环境 HTTP 访问服务默认域名 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ *
+ * 关键：用 `UserInfo.AppId`（腾讯云 appid）而非 `UserInfo.Uin`（账号 uin）。
+ * 控制台默认域名格式是 `${envId}-${AppId}.${region}.app.tcloudbase.com`
+ * （如 `xxx-1326375956.ap-shanghai.app.tcloudbase.com`），与 cookie 中的 `appid` 字段对应。
+ * AppId/Region 缺失或查询失败时返回 undefined
+ */
+export declare function resolveAccessServiceDomain(environment: Environment, envId: string): Promise<string | undefined>;
+/**
+ * 构造网关基础地址 `https://{envId}.api.tcloudbasegateway.com`
+ *
+ * 对齐 CLI 的 `EDomain.Gateway`：`isInternalEndpoint` 决定是否国际站域名
+ * （`api.intl.tcloudbasegateway.com`）。
+ */
+export declare function getGatewayBaseUrl(environment: Environment, envId: string): string;

package/types/deploy/framework.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 框架 → 默认构建命令映射（hosting 本地构建 / app 云端构建复用）
+ */
+export declare const FRAMEWORK_BUILD_COMMANDS: Record<string, string>;
+export interface IFrameworkConfig {
+    framework?: string;
+    buildCommand?: string;
+}
+/** 读取 package.json 的函数签名（测试可注入 mock，Node 20+ 下 fs 属性为只读 getter 不便 spy） */
+export type ReadPkgFile = (filePath: string, encoding: 'utf8') => string;
+/**
+ * 探测项目根目录下的框架类型（读 package.json 依赖）
+ * 读取失败或无匹配返回 null（按纯静态处理）
+ */
+export declare function detectFramework(root: string, readPkgFile?: ReadPkgFile): string | null;
+/**
+ * 解析构建命令，优先级：
+ * 1. 显式配置 buildCommand（含空字符串，'' = 不构建）
+ * 2. 显式配置 framework → 映射推导（static/custom → null 不构建）
+ * 3. 未配置 framework → 读 package.json 自动探测框架并推导
+ * 均无法确定 → null（纯静态直接上传）
+ */
+export declare function resolveBuildCommand(config: IFrameworkConfig, root: string, readPkgFile?: ReadPkgFile): string | null;

package/types/deploy/function/artifact.d.ts

@@ -0,0 +1,40 @@
+import { ICloudFunction } from '../../interfaces';
+import { ICodeArtifact, IFunctionArtifact, IImageArtifact, INormalizedDeployConfig, INormalizedHttpCloudConfig, INormalizedHttpImageConfig, INormalizedHttpLocalConfig } from '../types';
+/**
+ * 部署物构造与 SCF 参数映射
+ *
+ * 四种构建策略最终都产出统一的部署物，之后走同一条 SCF 创建或更新流程
+ */
+/** 由本地代码来源构造代码类部署物 */
+export declare function createCodeArtifact(config: INormalizedDeployConfig): ICodeArtifact;
+/** 由已有镜像配置构造镜像类部署物 */
+export declare function createImageArtifactFromConfig(config: INormalizedHttpImageConfig): IImageArtifact;
+/**
+ * 由本地构建结果构造镜像类部署物
+ *
+ * local 策略（个人版先行）产出：镜像已由 local-builder 构建并推送，
+ * 此处仅承载最终 imageUri/digest 与容器启动配置，之后复用镜像部署链。
+ */
+export declare function createImageArtifactFromBuild(config: INormalizedHttpLocalConfig, build: {
+    imageUri: string;
+    imageDigest?: string;
+}): IImageArtifact;
+/**
+ * 由云端构建结果构造镜像类部署物
+ *
+ * cloud 策略（CloudApp custom）产出：镜像已在构建容器内 docker build + push到 TCR，
+ * 此处仅承载最终 imageUri/digest 与构建元信息（buildId/logsUrl），之后复用镜像部署链。
+ * effectiveStrategy 标记为 cloud，便于结果层如实回传实际生效的策略。
+ */
+export declare function createImageArtifactFromCloudBuild(config: INormalizedHttpCloudConfig, build: {
+    imageUri: string;
+    imageDigest?: string;
+    buildId?: string;
+    logsUrl?: string;
+}): IImageArtifact;
+/**
+ * 将部署配置与部署物映射为 FunctionService 所需的云函数配置
+ *
+ * 只映射与 SCF 相关的字段，public、gatewayPath 等访问配置由后处理阶段负责
+ */
+export declare function toCloudFunction(config: INormalizedDeployConfig, artifact: IFunctionArtifact): ICloudFunction;

package/types/deploy/function/builders/cloud.d.ts

@@ -0,0 +1,110 @@
+import { ICustomBuildEnv, ICustomBuildSecret, ICustomBuildStep, CloudAppArtifact, CloudAppBuildStep } from '../../../cloudApp/types';
+import { INormalizedHttpCloudConfig } from '../../types';
+export interface ICloudBuildResult {
+    imageUri: string;
+    imageDigest?: string;
+    buildId?: string;
+    versionName?: string;
+    logsUrl?: string;
+}
+/** COS 上传信息（对应 DescribeCloudAppCosInfo 响应的必要字段） */
+export interface ICloudCosInfo {
+    uploadUrl: string;
+    uploadHeaders: Array<{
+        key: string;
+        value: string;
+    }>;
+    unixTimestamp: string;
+}
+/** 创建 custom 构建入参（不含 envId/deployType/buildType，由 service 补齐固定值） */
+export interface ICloudCreateBuildInput {
+    serviceName: string;
+    cosTimestamp: string;
+    env: ICustomBuildEnv[];
+    secrets?: ICustomBuildSecret[];
+    customSteps: ICustomBuildStep[];
+}
+/** 创建 custom 构建结果 */
+export interface ICloudCreateBuildResult {
+    buildId?: string;
+    versionName: string;
+    /** CreateCloudApp 接口返回的 RequestId，便于把构建问题反馈给平台后端定位 */
+    requestId?: string;
+}
+/** 构建版本状态（对应 DescribeCloudAppVersion 响应必要字段） */
+export interface ICloudVersionStatus {
+    status: string;
+    steps?: CloudAppBuildStep[] | null;
+    artifacts?: CloudAppArtifact[] | null;
+    /** DescribeCloudAppVersion 接口返回的 RequestId，便于把构建问题反馈给平台后端定位 */
+    requestId?: string;
+}
+/** 需要额外注入到构建 zip 的文件条目（zip 内路径 + 内容 + 可选 unix 权限位） */
+export interface ICloudBuildExtraEntry {
+    /** zip 包内的相对路径，如 scripts/tcr-login-and-push.sh */
+    zipPath: string;
+    /** 文件文本内容 */
+    content: string;
+    /** unix 权限位（八进制），如 0o755；脚本需可执行 */
+    mode?: number;
+}
+/**
+ * 云端构建所需的外部能力，由编排器注入
+ *每个方法对应构建方案（https://iwiki.woa.com/p/4020519533）的一个 API/IO 步骤
+ */
+export interface ICloudBuildService {
+    /**
+     * 打包构建上下文为 ZIP，返回本地临时 zip 路径
+     * @param cwd 构建上下文目录
+     * @param extraEntries 额外注入zip 的文件（如 push 脚本），不写入用户源码目录
+     */
+    packContext: (cwd: string, extraEntries?: ICloudBuildExtraEntry[]) => Promise<string>;
+    /** 获取 COS 上传凭证（DescribeCloudAppCosInfo，DeployType:custom） */
+    getCosInfo: (serviceName: string) => Promise<ICloudCosInfo>;
+    /** PUT 上传 zip 到 COS，必须携带全部 uploadHeaders */
+    uploadZip: (cosInfo: ICloudCosInfo, zipPath: string) => Promise<void>;
+    /** 触发 custom 构建（CreateCloudApp，DeployType:custom） */
+    createBuild: (input: ICloudCreateBuildInput) => Promise<ICloudCreateBuildResult>;
+    /** 查询构建版本状态（DescribeCloudAppVersion） */
+    getVersionStatus: (serviceName: string, versionName: string) => Promise<ICloudVersionStatus>;
+    /** 清理本地临时 zip；失败不应影响主流程 */
+    cleanup: (zipPath: string) => Promise<void>;
+    /** 延时（便于测试注入立即返回） */
+    delay: (ms: number) => Promise<void>;
+}
+/** 注入到构建上下文 zip 中的推送脚本相对路径（与 CustomSteps 的 push命令一致） */
+export declare const 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 固定模板，不拼接任何用户输入（镜像地址等均由已校验的
+ * 环境变量在容器内组装），无命令注入面。
+ */
+export declare const TCR_LOGIN_PUSH_SCRIPT = "#!/usr/bin/env bash\n# scripts/tcr-login-and-push.sh\n# \u7531 CloudBase SDK \u81EA\u52A8\u6CE8\u5165\uFF1A\u4F01\u4E1A\u7248\u4F7F\u7528 STS \u6362\u53D6\u4E34\u65F6 token\uFF0C\u4E2A\u4EBA\u7248\u4F7F\u7528 CloudApp Secret\nset -euo pipefail\n\n: \"${TCR_REGISTRY:?TCR_REGISTRY \u672A\u8BBE\u7F6E}\"\n: \"${TCR_NAMESPACE:?TCR_NAMESPACE \u672A\u8BBE\u7F6E}\"\n: \"${CLOUDBASE_SERVICE_NAME:?\u5E73\u53F0\u53D8\u91CF\u7F3A\u5931}\"\n: \"${CLOUDBASE_VERSION_NAME:?\u5E73\u53F0\u53D8\u91CF\u7F3A\u5931}\"\n\nREGION=\"${TCR_REGION:-ap-shanghai}\"\nIMAGE=\"${TCR_REGISTRY}/${TCR_NAMESPACE}/${CLOUDBASE_SERVICE_NAME}:${CLOUDBASE_VERSION_NAME}\"\n\nif [ -n \"${TCR_INSTANCE_ID:-}\" ]; then\n  : \"${API_SECRET_ID:?STS \u51ED\u8BC1\u7F3A\u5931}\"\n  : \"${API_SECRET_KEY:?STS \u51ED\u8BC1\u7F3A\u5931}\"\n  : \"${API_TOKEN:?STS \u51ED\u8BC1\u7F3A\u5931}\"\n\n  # ---- \u4F01\u4E1A\u7248 TCR\uFF1ACreateInstanceToken \u6362\u767B\u5F55\u6001 ----\n  HOST=\"tcr.tencentcloudapi.com\"\n  SERVICE=\"tcr\"\n  VERSION=\"2019-09-24\"\n  ACTION=\"CreateInstanceToken\"\n  ALGORITHM=\"TC3-HMAC-SHA256\"\n  TIMESTAMP=$(date +%s)\n  DATE=$(date -u -d \"@${TIMESTAMP}\" +\"%Y-%m-%d\" 2>/dev/null || date -u -r \"${TIMESTAMP}\" +\"%Y-%m-%d\")\n\n  PAYLOAD=$(printf '{\"RegistryId\":\"%s\",\"TokenType\":\"LongTermToken\"}' \"${TCR_INSTANCE_ID}\")\n  HASHED_PAYLOAD=$(printf '%s' \"${PAYLOAD}\" | openssl dgst -sha256 -hex | awk '{print $NF}')\n  CANONICAL_HEADERS=\"content-type:application/json; charset=utf-8\\nhost:${HOST}\\nx-tc-action:$(echo \"${ACTION}\" | tr '[:upper:]' '[:lower:]')\\n\"\n  SIGNED_HEADERS=\"content-type;host;x-tc-action\"\n  CANONICAL_REQUEST=\"POST\\n/\\n\\n${CANONICAL_HEADERS}\\n${SIGNED_HEADERS}\\n${HASHED_PAYLOAD}\"\n\n  CREDENTIAL_SCOPE=\"${DATE}/${SERVICE}/tc3_request\"\n  HASHED_CR=$(printf \"${CANONICAL_REQUEST}\" | openssl dgst -sha256 -hex | awk '{print $NF}')\n  STRING_TO_SIGN=\"${ALGORITHM}\\n${TIMESTAMP}\\n${CREDENTIAL_SCOPE}\\n${HASHED_CR}\"\n\n  secret_date=$(printf '%s' \"${DATE}\" | openssl dgst -sha256 -hmac \"TC3${API_SECRET_KEY}\" -hex | awk '{print $NF}')\n  secret_svc=$(printf '%s' \"${SERVICE}\" | openssl dgst -sha256 -mac HMAC -macopt hexkey:\"${secret_date}\" -hex | awk '{print $NF}')\n  secret_sign=$(printf '%s' \"tc3_request\" | openssl dgst -sha256 -mac HMAC -macopt hexkey:\"${secret_svc}\" -hex | awk '{print $NF}')\n  SIGNATURE=$(printf \"${STRING_TO_SIGN}\" | openssl dgst -sha256 -mac HMAC -macopt hexkey:\"${secret_sign}\" -hex | awk '{print $NF}')\n\n  AUTHZ=\"${ALGORITHM} Credential=${API_SECRET_ID}/${CREDENTIAL_SCOPE}, SignedHeaders=${SIGNED_HEADERS}, Signature=${SIGNATURE}\"\n\n  RESP=$(curl -sS -X POST \"https://${HOST}\" \\\n    -H \"Authorization: ${AUTHZ}\" \\\n    -H \"Content-Type: application/json; charset=utf-8\" \\\n    -H \"Host: ${HOST}\" \\\n    -H \"X-TC-Action: ${ACTION}\" \\\n    -H \"X-TC-Timestamp: ${TIMESTAMP}\" \\\n    -H \"X-TC-Version: ${VERSION}\" \\\n    -H \"X-TC-Region: ${REGION}\" \\\n    -H \"X-TC-Token: ${API_TOKEN}\" \\\n    --data \"${PAYLOAD}\")\n\n  TOKEN_USER=$(printf '%s' \"${RESP}\" | jq -er '.Response.Username')\n  TOKEN_PASS=$(printf '%s' \"${RESP}\" | jq -er '.Response.Token')\n\n  printf '%s' \"${TOKEN_PASS}\" | docker login -u \"${TOKEN_USER}\" --password-stdin \"${TCR_REGISTRY}\"\nelse\n  # ---- \u4E2A\u4EBA\u7248 CCR\uFF1A\u8D26\u53F7 ID + \u56FA\u5B9A\u5BC6\u7801\uFF08Base64 \u5C01\u88C5\u540E\u7531 CloudApp Secrets \u6CE8\u5165\uFF09 ----\n  : \"${TCR_USERNAME:?TCR_USERNAME \u672A\u8BBE\u7F6E}\"\n  : \"${SECRET_TCR_PASSWORD_B64:?TCR_PASSWORD \u672A\u8BBE\u7F6E}\"\n  printf '%s' \"${SECRET_TCR_PASSWORD_B64}\" | base64 --decode | docker login -u \"${TCR_USERNAME}\" --password-stdin \"${TCR_REGISTRY}\"\nfi\n\ndocker push \"${IMAGE}\"\n\necho \"::output::tag=${CLOUDBASE_VERSION_NAME}\"\n";
+/** buildImageOnCloud 可选项 */
+export interface IBuildImageOnCloudOptions {
+    /** 日志回调，用于透出构建进度（不含凭证） */
+    onLog?: (line: string) => void;
+    /** 部署地域，注入构建环境供推送脚本换取仓库登录态（跨地域必需） */
+    region?: string;
+}
+/**
+ * 执行云端构建并推送镜像
+ *
+ * @param config 规范化的 cloud 部署配置
+ * @param service 注入的外部能力（打包/tcb API/COS 上传）
+ * @param options 可选项：日志回调 onLog、部署地域 region
+ */
+export declare function buildImageOnCloud(config: INormalizedHttpCloudConfig, service: ICloudBuildService, options?: IBuildImageOnCloudOptions): Promise<ICloudBuildResult>;

package/types/deploy/function/cam-preflight.d.ts

@@ -0,0 +1,51 @@
+import { ICheckReport, INormalizedDeployConfig } from '../types';
+/**
+ * 镜像拉取授权 Preflight（涉及 CAM，scope: cloud）
+ *
+ * SCF 拉取镜像由服务角色 SCF_QcsRole 代理，个人版镜像要求该角色绑定
+ * QcloudAccessForSCFRoleInPullImage 策略。本模块在 image 策略部署前：
+ *   1. 探测该角色与策略是否就绪；
+ *   2. 缺失且允许时，自动绑定「唯一白名单策略」补齐（绝不放大到其它策略）；
+ *   3. 当前身份无 CAM 权限时不硬失败，降级为结构化指引 + 一键授权链接兜底。
+ *
+ * 安全边界（对应 security_rules 的 AuthZ / 最小权限）：
+ * - 自动授权只允许绑定 REQUIRED_IMAGE_PULL_POLICY 这一条部署必需的预置策略；
+ * - 不代用户创建角色、不绑定任何白名单外策略；
+ * - 探测/授权失败一律走降级，不阻断到无法给出可操作指引。
+ */
+/** SCF 拉取镜像使用的服务角色 */
+export declare const SCF_PULL_IMAGE_ROLE = "SCF_QcsRole";
+/** 拉取个人版镜像所需的唯一预置策略（自动授权白名单，仅此一条） */
+export declare const REQUIRED_IMAGE_PULL_POLICY = "QcloudAccessForSCFRoleInPullImage";
+/** 官方一键授权链接，作为无 CAM 权限时的兜底指引 */
+export declare const IMAGE_PULL_GRANT_URL: string;
+/** 角色详情，仅取判断所需字段 */
+interface IRoleDetail {
+    RoleName?: string;
+    /** 已绑定的策略名集合，具体来源由适配层填充 */
+    attachedPolicyNames?: string[];
+}
+/**
+ * CAM 能力的最小依赖接口
+ *
+ * 只声明本模块需要的方法，便于解耦具体实现与单元测试。
+ * 适配层负责把 CamService 的返回适配为 attachedPolicyNames。
+ */
+export interface ICamPreflightService {
+    /** 获取角色详情及其已绑定策略名；角色不存在应抛出可识别错误 */
+    getRoleWithPolicies: (roleName: string) => Promise<IRoleDetail>;
+    /** 为角色绑定指定预置策略（按策略名） */
+    attachPolicyByName: (roleName: string, policyName: string) => Promise<void>;
+}
+/** 判断错误是否为 CAM 权限不足 */
+export declare function isCamPermissionError(error: any): boolean;
+/**
+ * 执行镜像拉取授权 Preflight
+ *
+ * @param service CAM 能力适配（无则视为无法校验，直接降级为提示）
+ * @param config 规范化部署配置
+ * @param autoGrant 是否允许自动补齐授权（默认 true）
+ * @returns scope 为 cloud 的检查报告，聚合全部结论
+ */
+export declare function runImagePullAuthPreflight(service: ICamPreflightService | null, config: INormalizedDeployConfig, autoGrant?: boolean): Promise<ICheckReport>;
+export {};

package/types/deploy/function/cloud-build-service.d.ts

@@ -0,0 +1,10 @@
+import { CloudAppService } from '../../cloudApp';
+import { ICloudBuildService } from './builders/cloud';
+export interface ICreateCloudBuildServiceOptions {
+    /** 追加的打包忽略项 */
+    ignore?: string[];
+}
+/**
+ * 由CloudAppService 构造 ICloudBuildService实现
+ */
+export declare function createCloudBuildService(cloudApp: CloudAppService, options?: ICreateCloudBuildServiceOptions): ICloudBuildService;

package/types/deploy/function/config-guard.d.ts

@@ -0,0 +1,41 @@
+import { ICheckReport, IFunctionDeployConfig, INormalizedDeployConfig } from '../types';
+export interface IParsedImageReference {
+    registry?: string;
+    repository: string;
+    tag?: string;
+    digest?: string;
+}
+/**
+ * 解析 OCI 镜像引用
+ *
+ * 支持 [registry[:port]/]repository[:tag][@digest]
+ * 无法仅通过是否包含冒号判断 tag，因为 registry 可能带端口
+ * @returns 解析结果，非法时返回 null
+ */
+export declare function parseImageReference(reference: string): IParsedImageReference | null;
+/**
+ * 规范化网关路径
+ *
+ * 合并连续斜杠并去除尾部斜杠，根路径保持为 /
+ * @returns 规范化结果，非法时返回 null
+ */
+export declare function normalizeGatewayPath(input: string): string | null;
+/** 判断是否为自定义镜像运行时 */
+export declare function isCustomImageRuntime(runtime?: string): boolean;
+/**
+ * 规范化部署配置
+ *
+ * 仅填充默认值与收窄类型，不做合法性判断，保证在非法输入下也能安全返回，
+ * 以便 checkDeployConfig 汇总全部问题
+ */
+export declare function normalizeDeployConfig(config: IFunctionDeployConfig): INormalizedDeployConfig;
+/**
+ * 校验部署配置
+ * @returns 检查报告，包含全部问题而非仅第一个
+ */
+export declare function checkDeployConfig(config: IFunctionDeployConfig): ICheckReport;
+/**
+ * 校验并规范化部署配置
+ * @throws CloudBaseError 存在任一 fail 项时抛出，错误信息包含全部失败原因
+ */
+export declare function assertDeployConfig(config: IFunctionDeployConfig): INormalizedDeployConfig;

package/types/deploy/function/docker-preflight.d.ts

@@ -0,0 +1,17 @@
+import { ICheckReport } from '../types';
+export interface IExecResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+/** 只读命令执行器签名 */
+export type ReadonlyRunner = (command: string, args: string[]) => Promise<IExecResult>;
+/**
+ * 执行 Docker 本地能力检查
+ *
+ * 检测顺序：CLI 存在性 → daemon 可用性 → buildx 可用性。
+ * CLI 缺失时短路（daemon/buildx 无从谈起），其余项独立收集后聚合返回。
+ *
+ * @param runner 命令执行器，默认真实 execFile；测试可注入 mock
+ */
+export declare function runDockerPreflight(runner?: ReadonlyRunner): Promise<ICheckReport>;

package/types/deploy/function/image-preflight.d.ts

@@ -0,0 +1,21 @@
+import { ICheckReport, INormalizedDeployConfig } from '../types';
+export interface IExecResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    /** 命令本身无法启动（如 docker 未安装）时为 true，与“命令执行了但返回非零”区分 */
+    spawnFailed?: boolean;
+}
+/** 可注入依赖：远端 manifest 查询命令 */
+export interface IImagePreflightDeps {
+    runCommand: (command: string, args: string[]) => Promise<IExecResult>;
+}
+/**
+ * 执行镜像远端校验 Preflight
+ *
+ * @param config 规范化部署配置
+ * @param deployRegion 函数部署地域（可选，来源于 environment；未知时跳过地域校验）
+ * @param deps 可注入依赖，默认真实命令；测试可传 mock
+ * @returns scope 为 cloud 的检查报告
+ */
+export declare function runImageRemotePreflight(config: INormalizedDeployConfig, deployRegion?: string, deps?: IImagePreflightDeps): Promise<ICheckReport>;

package/types/deploy/function/local-builder.d.ts

@@ -0,0 +1,26 @@
+import { INormalizedHttpLocalConfig } from '../types';
+export interface ILocalBuildResult {
+    imageUri: string;
+    imageDigest?: string;
+}
+export interface IExecResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}
+/** 可注入依赖：命令执行与文件系统检查 */
+export interface ILocalBuilderDeps {
+    runCommand: (command: string, args: string[]) => Promise<IExecResult>;
+    existsSync: (target: string) => boolean;
+    isDirectory: (target: string) => boolean;
+    isFile: (target: string) => boolean;
+}
+/**
+ * 本地构建镜像并推送到目标仓库
+ *
+ * @param config 规范化的 local 部署配置
+ * @param onLog 可选日志回调，用于透出构建输出（不含凭证）
+ * @param deps 可注入依赖，默认真实命令与 fs；测试可传 mock
+ * @returns 最终镜像引用与 digest
+ */
+export declare function buildAndPushImage(config: INormalizedHttpLocalConfig, onLog?: (line: string) => void, deps?: ILocalBuilderDeps): Promise<ILocalBuildResult>;

package/types/deploy/function/planner.d.ts

@@ -0,0 +1,15 @@
+import { IFunctionInfo } from '../../function/types';
+import { IFunctionCurrentState, IFunctionDeployPlan, INormalizedDeployConfig } from '../types';
+/**
+ * 部署计划生成
+ *
+ * 纯函数实现，线上函数状态由调用方查询后传入，便于单独测试
+ */
+/** 将 SCF 返回的函数详情收敛为计划所需的状态摘要 */
+export declare function toCurrentState(info: IFunctionInfo): IFunctionCurrentState;
+/**
+ * 生成部署计划
+ * @param config 已规范化的部署配置
+ * @param current 线上函数详情，不存在时传 null
+ */
+export declare function createDeployPlan(config: INormalizedDeployConfig, current?: IFunctionInfo | null): IFunctionDeployPlan;