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

package/types/cloudApp/types.d.ts

@@ -10,19 +10,80 @@
  * 部署类型
  * - static-hosting: 静态托管部署
  * - http-function: HTTP 云函数部署（预留）
+ * - custom: 自定义构建（CloudApp custom：源码 ZIP → 容器内执行 CustomSteps → docker build/push TCR），
+ *   用于 HTTP 函数镜像的云端构建（buildStrategy: cloud）
  */
-export type DeployType = 'static-hosting' | 'http-function';
+export type DeployType = 'static-hosting' | 'http-function' | 'custom';
 /**
  * 构建类型
  * - GIT: 从 Git 仓库构建
  * - ZIP: 从 ZIP 包构建
  * - TEMPLATE: 从模板构建
+ * - zip: custom 构建的源码 ZIP（与 API 文档 BuildType 大小写保持一致）
  */
-export type BuildType = 'GIT' | 'ZIP' | 'TEMPLATE';
+export type BuildType = 'GIT' | 'ZIP' | 'TEMPLATE' | 'zip' | 'git';
+/**
+ * custom 构建源码来源
+ *对应 API 的 Source 字段，zip 模式回填 DescribeCloudAppCosInfo 返回的时间戳
+ */
+export interface ICustomBuildSource {
+    /** 源码类型，当前实现为 zip */
+    type: 'zip' | 'git';
+    /** COS 时间戳，原样使用 DescribeCloudAppCosInfo 返回的 UnixTimestamp */
+    cosTimestamp?: string;
+    /** COS 文件后缀，默认 .zip */
+    cosSuffix?: string;
+}
+/** custom 构建环境变量项（明文，禁止写入敏感值） */
+export interface ICustomBuildEnv {
+    key: string;
+    value: string;
+}
+/**
+ * custom 构建密钥项
+ * CloudApp 在构建容器中按 $SECRET_{NAME} 注入，Value 不应进入日志或普通环境变量。
+ */
+export interface ICustomBuildSecret {
+    name: string;
+    value: string;
+}
+/**
+ * custom 构建自定义步骤
+ * SDK 固定生成模板，用户不可控字段绝不作为任意 shell 片段拼接
+ */
+export interface ICustomBuildStep {
+    name: string;
+    command: string;
+}
+/**
+ * custom 构建单步状态（API 响应，字段大小写与响应一致）
+ * 注意：Duration 为字符串、Status 为小写
+ */
+export interface CloudAppBuildStep {
+    Name: string;
+    Status: string;
+    Duration?: string;
+    /** 失败时的退出码，用于定位 */
+    ExitCode?: number;
+}
+/**
+ * custom 构建产物（API 响应）
+ * 镜像构建成功后Type 通常为 image
+ */
+export interface CloudAppArtifact {
+    Type: string;
+    Name: string;
+    Status?: string;
+    /** 部分场景直接回传完整镜像地址 */
+    ImageUri?: string;
+    /** 部分场景回传 digest */
+    Digest?: string;
+}
 /**
  * 构建状态
+ * custom 构建终态为 SUCCESS / FAILED / CANCELED
  */
-export type BuildStatus = 'BUILDING' | 'SUCCESS' | 'FAILED';
+export type BuildStatus = 'BUILDING' | 'SUCCESS' | 'FAILED' | 'CANCELED';
 /**
  * 构建命令配置（入参）
  */
@@ -149,14 +210,24 @@ export interface CloudAppVersion {
 export interface ICreateCloudAppParams {
     /** 环境 ID（可选，默认从 Environment 获取） */
     envId?: string;
-    /** 部署类型：static-hosting / http-function */
+    /** 部署类型：static-hosting / http-function / custom */
     deployType: DeployType;
     /** 服务名称 */
     serviceName: string;
-    /** 构建类型：GIT / ZIP / TEMPLATE */
+    /** 构建类型：GIT / ZIP / TEMPLATE / zip / git */
     buildType?: BuildType;
     /** 静态托管配置（deployType 为 static-hosting 时使用） */
     staticConfig?: IStaticConfig;
+    /** custom 构建源码来源（deployType 为 custom 时使用） */
+    source?: ICustomBuildSource;
+    /** custom 构建环境变量（deployType 为 custom 时使用，禁止敏感值） */
+    env?: ICustomBuildEnv[];
+    /** custom 构建密钥（deployType 为 custom 时使用） */
+    secrets?: ICustomBuildSecret[];
+    /** custom 构建自定义步骤（deployType 为 custom 时使用，SDK 固定模板） */
+    customSteps?: ICustomBuildStep[];
+    /** 跳过云端构建（纯静态直传场景：产物已直传，仅写部署记录，对应 API SkipBuild） */
+    skipBuild?: boolean;
 }
 export interface ICreateCloudAppResult {
     ServiceName: string;
@@ -232,6 +303,10 @@ export interface IDescribeCloudAppVersionResult {
     Framework?: string;
     StaticConfig?: CloudAppStaticConfig;
     BuildTime?: string;
+    /** custom 构建的分步状态（deployType 为 custom 时返回） */
+    Steps?: CloudAppBuildStep[] | null;
+    /** custom 构建产物（deployType 为 custom 时返回，镜像信息优先从此获取） */
+    Artifacts?: CloudAppArtifact[] | null;
     RequestId: string;
 }
 export interface IDescribeCloudAppVersionListParams {
@@ -324,8 +399,14 @@ export interface IUploadCloudAppCodeParams {
     serviceName: string;
     /** 本地文件夹路径 */
     localPath: string;
-    /** 忽略的文件/目录模式 */
+    /** 忽略的文件/目录模式（追加到内置默认规则之后） */
     ignore?: string[];
+    /**
+     * 是否排除 node_modules：
+     * 默认 true（静态产物 / 版本快照场景，避免误传大目录）；
+     * 云端构建（需云端 install）场景设为 false，允许私有/离线依赖随源码包上传
+     */
+    excludeNodeModules?: boolean;
     /** 进度回调 */
     onProgress?: (progress: IProgressData) => void;
     /** 分步计时回调（各阶段完成时触发，用于 verbose 模式输出耗时） */

package/types/deploy/DatabaseDeployer.d.ts

@@ -0,0 +1,70 @@
+import { Environment } from '../environment';
+import { IPGUserMigrationInput } from '../database/type';
+/** 数据库迁移部署配置（对应 cloudbaserc.json 中的 database 块） */
+export interface IDatabaseDeployConfig {
+    /** 数据库类型（v2.1 schema: 目前仅支持 postgresql） */
+    type: 'postgresql';
+    /** migration SQL 文件目录（相对项目根） */
+    migrations?: string;
+}
+/** Plan 中单条 migration 的状态 */
+export interface IDatabasePlanItem {
+    /** 14位数字时间串 */
+    version: string;
+    /** migration 名称 */
+    name: string;
+    /** pending=待执行；applied=已应用；conflict=冲突 */
+    status: 'pending' | 'applied' | 'conflict';
+    /** 冲突原因（仅 conflict 时有值） */
+    reason?: string;
+}
+/** deploy 返回结果 */
+export interface IDatabaseDeployResult {
+    /** 异步任务 ID（无pending时为空字符串） */
+    taskId: string;
+}
+export declare class DatabaseDeployer {
+    private environment;
+    constructor(environment: Environment);
+    /**
+     * 从本地目录解析 migration 文件列表
+     *
+     * 文件名格式：{14位时间戳}_{小写下划线名称}.sql
+     * 例如：20260526000000_create_users.sql
+     *
+     * 按文件名升序排列（即按版本号从早到晚）
+     */
+    parseMigrationFiles(migrationsDir: string): IPGUserMigrationInput[];
+    /**
+     * 生成部署计划
+     *
+     * 调用 previewPGUserMigrations 获取云端对比结果，
+     * 返回每条migration 的状态（pending / applied / conflict）
+     */
+    plan(config: IDatabaseDeployConfig, cwd: string, envId: string): Promise<IDatabasePlanItem[]>;
+    /**
+     * 执行数据库迁移
+     *
+     * 流程：
+     * 1. 解析本地 migration 文件
+     * 2. 预览确认无冲突（有冲突直接 throw，中断整个部署）
+     * 3. 无 pending 则跳过
+     * 4. 提交 pushPGUserMigrations
+     * 5. 轮询describeTaskResult 等待完成
+     */
+    deploy(config: IDatabaseDeployConfig, cwd: string, envId: string): Promise<IDatabaseDeployResult>;
+    /**
+     * 解析 migrations 目录路径
+     * - 未配置：默认 ./cloudbase/migrations
+     * - 仅允许相对路径（禁止 / 开头）
+     */
+    private resolveMigrationsDir;
+    /**
+     * 校验 database.type（当前仅支持 postgresql）
+     */
+    private assertDatabaseType;
+    /**
+     * 轮询等待异步任务完成
+     */
+    private waitForTask;
+}

package/types/deploy/DeployOrchestrator.d.ts

@@ -0,0 +1,170 @@
+import { Environment } from '../environment';
+/** 可编排的资源类型 */
+export type ResourceType = 'database' | 'functions' | 'app' | 'hosting' | 'gateway';
+/** 声明式部署选项 */
+export interface IDeployOptions {
+    /** 解析后的 cloudbaserc 配置（ConfigParser 输出，含 envOverrides 已应用） */
+    config: Record<string, any>;
+    envId: string;
+    /** 只部署指定类型 */
+    only?: ResourceType[];
+    /** 跳过指定类型 */
+    skip?: ResourceType[];
+    /** dry-run：只输出计划不实际部署 */
+    dryRun?: boolean;
+    /** 项目根目录（默认 process.cwd()） */
+    cwd?: string;
+    /** 已存在资源（函数）的覆盖更新：yes=true 直接放行（AI Agent / CI 场景） */
+    yes?: boolean;
+    /** 已存在资源（函数）的覆盖更新确认回调：返回 true 部署、false 跳过（CLI 注入 autoConfirm） */
+    confirmUpdate?: (item: IDeployPlanItem) => Promise<boolean>;
+    /** 强制云端对比（漂移检测）：忽略本地 state 快照的 skip 判定，强制重新对比/部署 */
+    refresh?: boolean;
+    /** 同类型资源最大并行数，默认 1（串行）。仅作用于同类型连续实例之间，跨类型依赖顺序不变 */
+    concurrency?: number;
+    /** 失败后继续部署其余资源（database 失败仍强制中断） */
+    continueOnError?: boolean;
+    log?: {
+        info?: (msg: string) => void;
+        success?: (msg: string) => void;
+        warn?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}
+/** 部署计划项（资源级） */
+export interface IDeployPlanItem {
+    type: ResourceType;
+    name: string;
+    /** 动作分类：create=新建；update=覆盖更新已有资源；skip=已存在且配置一致；conflict=检测到冲突（需中断）；deploy=直传覆盖（无存在性概念） */
+    status: 'create' | 'update' | 'skip' | 'conflict' | 'deploy';
+    /** 动作说明（用户可读） */
+    action: string;
+    /** 变更字段明细（如 database 迁移聚合、gateway 路由差异等） */
+    changes?: Array<{
+        field: string;
+        from?: string;
+        to?: string;
+    }>;
+    /** hosting 文件级 diff（新增/修改/删除，前 N 条 + 统计） */
+    fileDiff?: {
+        added: string[];
+        modified: string[];
+        deleted: string[];
+        totalChanged: number;
+    };
+    /** 资源级详情子行（dry-run 树状渲染用）：如函数 runtime/构建策略、迁移逐条状态等 */
+    details?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+/** 部署结果 */
+export interface IDeployResult {
+    plan: IDeployPlanItem[];
+    results: Array<{
+        type: ResourceType;
+        name: string;
+        ok: boolean;
+        url?: string;
+        error?: string;
+        /** 原始异常中的请求 ID（若可提取），用于定位平台侧接口报错 */
+        requestId?: string;
+        /** 未执行原因：skip=未变更自动跳过；no-confirm=无确认机制保守跳过；skipped-by-user=用户拒绝覆盖 */
+        reason?: 'skip' | 'no-confirm' | 'skipped-by-user';
+    }>;
+}
+/**
+ * 声明式部署编排器
+ * 顺序：database → functions → app → hosting → gateway
+ * 支持 dry-run / only / skip / 幂等重试（database 失败/冲突会中断后续步骤）
+ */
+export declare class DeployOrchestrator {
+    private environment;
+    private databaseDeployer;
+    private functionDeployer;
+    private staticDeployer;
+    private gatewayDeployer;
+    constructor(environment: Environment);
+    /**
+     * 计算部署计划（dry-run 输出）
+     */
+    deployPlan(options: IDeployOptions): Promise<IDeployPlanItem[]>;
+    /**
+     * 执行部署
+     *
+     * 编排模型：plan 按「连续相同资源类型」切成 segments，segment 之间严格按
+     * DEPLOY_ORDER 串行；segment 内部按 concurrency 并行执行。失败中断策略：
+     * - 默认 fail-fast：任一资源失败即中断后续（return）
+     * - continueOnError：非 database 资源失败仍继续，最后汇总失败数
+     * - database 失败始终强制中断（无论是否 continueOnError）
+     */
+    deploy(options: IDeployOptions): Promise<IDeployResult>;
+    /**
+     * 将扁平 plan 按「连续相同资源类型」切成有序 segments
+     *
+     * segment 之间保留 DEPLOY_ORDER 依赖顺序（严格串行）；segment 内部为同类型
+     * 多实例，可并行执行。例如 [db, fnA, fnB, hostingX, hostingY, gateway]
+     * → [[db], [fnA, fnB], [hostingX, hostingY], [gateway]]
+     */
+    private segmentPlan;
+    /**
+     * 部署成功后写回本地 state 快照
+     *
+     * - hosting：成功部署/未变更（skip）的项重算产物指纹；失败项保留旧快照
+     * - app：成功部署写 buildAppConfig 快照；skip 复用旧快照
+     * - gateway：保留旧快照（本轮不做路由级实时快照）
+     */
+    private persistState;
+    /**
+     * 构建完整部署计划（按依赖顺序 + only/skip 过滤）
+     *
+     * 通过查询云端状态判定每个资源的动作：
+     * - database：先按迁移文件做 preview，再聚合成单条资源级计划项（pending→create，存在 conflict→conflict，全部 applied→不出现在 plan）
+     * - functions：ListFunctions 判断是否已存在 → create / update（不做本地 hash / 字段 diff）
+     * - app：describeAppInfo 判断是否已存在 → create / update；本地 state 配置一致 → skip
+     * - hosting：本地 state 指纹 diff → 一致 skip（不重新上传）/ 有差异 deploy（带文件级明细）
+     * - gateway：planRoutes 对比云端路由 → create / update / skip（含变更字段明细）
+     * 云端查询失败时降级为保守判定（全 create），不影响 dry-run 展示。
+     */
+    private buildPlan;
+    /**
+     * 按资源类型构建计划（拆分自 buildPlan，控制圈复杂度）
+     */
+    private buildPlanForType;
+    /**
+     * database 计划：preview 聚合成单条资源级计划项
+     */
+    private buildDatabasePlan;
+    /**
+     * app 计划：本地 state 配置一致 → skip；否则按云端存在性 → create / update
+     */
+    private buildAppPlan;
+    /**
+     * hosting 计划：本地 state 指纹 diff → 一致 skip / 有差异 deploy（带文件级明细）
+     */
+    private buildHostingPlans;
+    /**
+     * gateway 计划：planRoutes 对比云端路由 → create / update / skip（含变更字段明细）
+     */
+    private buildGatewayPlans;
+    /**
+     * 查询环境中已存在的函数名集合（查询失败返回空集，降级为全新建判定）
+     */
+    private listExistingFunctionNames;
+    /**
+     * 判断云应用是否已存在（查询失败返回 false，降级为新建判定）
+     */
+    private appExists;
+    /**
+     * 执行单个计划步骤
+     */
+    private executeStep;
+    /** 深比较（JSON 快照语义）：仅用于 app 配置快照等简单对象 */
+    private deepEqual;
+    /** app 配置差异明细（from → to） */
+    private appConfigChanges;
+    /**
+     * 轻量 inline 守卫：配置合法 + 目录存在（validateProject 接线点）
+     */
+    private guardConfig;
+}

package/types/deploy/FunctionDeployer.d.ts

@@ -0,0 +1,159 @@
+import { Environment } from '../environment';
+import { ICloudBuildService } from './function/builders/cloud';
+import { IImagePreflightDeps } from './function/image-preflight';
+import { ICheckReport, IFunctionDeployConfig, IFunctionDeployOptions, IFunctionDeployPlan, IFunctionDeployResult, INormalizedDeployConfig } from './types';
+interface ILegacyFunctionDeployResult {
+    name: string;
+    url?: string;
+}
+/**
+ * 函数部署编排器
+ *
+ * 统一编排 Event 与 HTTP 函数的部署流程，对上层屏蔽以下差异：
+ * - Event 与 HTTP 的运行模型
+ * - zip、cloud、local、image 四种构建策略
+ * - 创建、更新与不可原地更新的场景识别
+ *
+ * 已支持代码包、已有镜像、云端构建、本地构建、匿名访问与网关路径收敛；
+ * 函数类型、运行时或协议等创建期字段变化时不会自动删除函数，而是引导用户
+ * 在控制台确认并手工删除后重新部署。local 企业版 TCR 等未实现能力会显式报错。
+ */
+export declare class FunctionDeployer {
+    private readonly environment;
+    private readonly functionService;
+    /** 镜像远端校验依赖，默认真实 docker；测试可注入以避免真实网络/命令 */
+    private readonly imagePreflightDeps?;
+    /**
+     * 云端构建能力工厂，默认基于 CloudAppService 构造真实实现；
+     * 测试可注入以替换打包/网络/tcb API，避免真实 IO
+     */
+    private readonly cloudBuildServiceFactory;
+    constructor(environment: Environment, deps?: {
+        imagePreflightDeps?: IImagePreflightDeps;
+        cloudBuildServiceFactory?: () => ICloudBuildService;
+    });
+    /**
+     * 兼容既有声明式部署入口
+     *
+     * 该方法只负责补齐声明式上下文并委托 deployFunction，避免继续维护第二套
+     * cloud/local/image 分发逻辑。force 在旧入口中表示允许覆盖，计划阶段会自行
+     * 判断 create/update；不可原地更新的变更始终要求用户在控制台手工删除函数。
+     */
+    deploy(options: {
+        func: IFunctionDeployConfig;
+        functionRootPath?: string;
+        /** 直接指定函数代码目录（优先于 functionRootPath/name 拼接），对齐 CLI resolveFunctionPath 的 dir 语义 */
+        functionPath?: string;
+        force?: boolean;
+    }): Promise<ILegacyFunctionDeployResult>;
+    /** 解析最终部署策略：显式 buildStrategy 优先，未配置默认 zip */
+    resolveStrategy(config: IFunctionDeployConfig): IFunctionDeployPlan['buildStrategy'];
+    /**
+     * 配置 HTTP 函数匿名访问（public=true）
+     * 通过 OPA Rego 策略追加匿名放通规则，不覆盖用户已有策略
+     */
+    ensurePublicAccess(functionName: string): Promise<void>;
+    /**
+     * 收敛 HTTP 函数网关路由（gatewayPath 配置）
+     *
+     * 幂等：云端不存在该 path → 创建；已存在且一致 → 跳过；不一致 → 更新。
+     * 复用 GatewayDeployer 的幂等收敛与默认域名解析逻辑，与 gateway.routes 声明式部署行为一致。
+     * 返回该函数网关访问 URL（与 resolveUrl 解析结果一致），无 envId 时返回 undefined。
+     */
+    ensureGatewayRoute(config: INormalizedDeployConfig): Promise<string | undefined>;
+    /** 生成匿名访问 OPA Rego 规则 */
+    buildPublicAccessRego(functionName: string): string;
+    /** 生成 HTTP 函数可访问 URL */
+    resolveUrl(config: IFunctionDeployConfig): Promise<string | undefined>;
+    /**
+     * 校验部署配置
+     *
+     * 只做纯函数、无 IO 的配置契约校验，一次返回全部问题
+     */
+    checkConfig(config: IFunctionDeployConfig): ICheckReport;
+    /**
+     * 生成部署计划
+     *
+     * 会查询线上函数状态，用于判断创建、更新或识别不可原地更新的变更
+     */
+    plan(config: IFunctionDeployConfig): Promise<IFunctionDeployPlan>;
+    /**
+     * 部署前本地环境检查（有 IO）
+     *
+     * 与 checkConfig 不同，本方法会读取文件系统，覆盖 HTTP 代码包和 cloud 镜像构建
+     * 所需的本地文件条件。先做配置契约校验，再执行本地检查。
+     */
+    preflight(config: IFunctionDeployConfig): ICheckReport;
+    /**
+     * 部署函数
+     * @param config 部署配置
+     * @param options 部署选项，dryRun 时只生成计划不做任何变更
+     */
+    deployFunction(config: IFunctionDeployConfig, options?: IFunctionDeployOptions): Promise<IFunctionDeployResult>;
+    /**
+     * 将既有声明式调用补齐为完整部署配置
+     */
+    private withLegacyDeployContext;
+    /**
+     * 解析函数部署地域，供镜像远端地域校验使用
+     *
+     * 地域来源于 environment 的鉴权配置；未显式配置时返回 undefined，
+     * 由image-preflight 自动跳过地域校验，不误报。
+     */
+    private resolveDeployRegion;
+    /**
+     * 构造镜像拉取授权 Preflight 所需的 CAM 适配器
+     *
+     * 用 CommonService 走 CAM 通道：ListAttachedRolePolicies 读已绑策略、
+     * AttachRolePolicies 按策略名绑定。任何权限/网络错误都原样抛出，
+     * 交由 cam-preflight 判定并降级，本层不吞异常。
+     */
+    private createCamPreflightAdapter;
+    /** 查询线上函数详情，不存在时返回 null */
+    private getCurrentFunction;
+    /** 判断是否为函数不存在错误，其他错误必须继续抛出 */
+    private isFunctionNotFoundError;
+    /**
+     * 校验 Preflight 报告，存在 fail 项时聚合抛错
+     */
+    private assertPreflightReady;
+    /**
+     * 判断计划是否可以在当前实现范围内执行
+     *
+     * 未实现的能力必须显式报错，避免用户误认为访问规则或镜像构建已经生效
+     */
+    private assertPlanExecutable;
+    /**
+     * 准备部署物
+     *
+     * cloud 策略在云端构建容器内build+push，产出镜像部署物（不依赖本地 Docker）；
+     * local 策略需要先做 Docker 本地能力检查，再本地构建并推送镜像，产出镜像部署物；
+     * 其余策略走同步的 pack。
+     */
+    private prepareArtifact;
+    /** 生成部署物 */
+    private createArtifact;
+    /** 执行部署计划 */
+    private applyPlan;
+    /** 收敛 HTTP 函数访问配置（匿名访问 + 网关路由） */
+    private applyAccessPlan;
+    /** 执行单个步骤并记录耗时与进度 */
+    private runStep;
+    /** 上报进度，回调异常不影响部署流程 */
+    private emitProgress;
+    /** 汇总部署结果 */
+    private buildResult;
+    private emitProgressDone;
+}
+export * from './types';
+export { assertDeployConfig, checkDeployConfig, isCustomImageRuntime, normalizeDeployConfig, normalizeGatewayPath, parseImageReference } from './function/config-guard';
+export { createDeployPlan, toCurrentState } from './function/planner';
+export { createCodeArtifact, createImageArtifactFromConfig, toCloudFunction } from './function/artifact';
+export { buildImageOnCloud } from './function/builders/cloud';
+export type { ICloudBuildService, ICloudBuildResult, ICloudCosInfo, ICloudCreateBuildInput, ICloudCreateBuildResult, ICloudVersionStatus } from './function/builders/cloud';
+export { createCloudBuildService } from './function/cloud-build-service';
+export { runLocalPreflight } from './function/preflight';
+export { runImageRemotePreflight } from './function/image-preflight';
+export type { IImagePreflightDeps } from './function/image-preflight';
+export { runImagePullAuthPreflight, isCamPermissionError, SCF_PULL_IMAGE_ROLE, REQUIRED_IMAGE_PULL_POLICY, IMAGE_PULL_GRANT_URL } from './function/cam-preflight';
+export type { ICamPreflightService } from './function/cam-preflight';