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

package/lib/projectValidator/index.js

@@ -0,0 +1,375 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectValidator = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const toolbox_1 = require("@cloudbase/toolbox");
+class ProjectValidator {
+    async validate(options = {}) {
+        var _a;
+        const cwd = path_1.default.resolve(options.cwd || process.cwd());
+        const errors = [];
+        const warnings = [];
+        const loaded = await this.loadProjectConfig(cwd, {
+            configPath: options.configPath,
+            mode: options.mode,
+            errors,
+        });
+        const version = String(((_a = loaded.rawConfig) === null || _a === void 0 ? void 0 : _a.version) || '2.1');
+        if (loaded.rawConfig) {
+            this.validateSchema(loaded.rawConfig, errors);
+        }
+        if (loaded.config) {
+            this.validateEnvId(cwd, { raw: loaded.rawConfig || {}, resolved: loaded.config }, errors);
+            this.validatePersonalRegistryConfig(loaded.config, errors);
+            const resourceIssues = this.validateResources(cwd, loaded.config);
+            errors.push(...resourceIssues.errors);
+            warnings.push(...resourceIssues.warnings);
+            this.validateConsistency(loaded.config, errors);
+        }
+        const summary = this.getSummary(loaded.config);
+        return {
+            valid: errors.length === 0,
+            version,
+            errors,
+            warnings,
+            summary,
+        };
+    }
+    async loadProjectConfig(cwd, options) {
+        const { configPath, mode, errors } = options;
+        let filepath = configPath ? path_1.default.resolve(cwd, configPath) : undefined;
+        try {
+            if (!filepath) {
+                const result = await (0, toolbox_1.searchConfig)(cwd);
+                filepath = result === null || result === void 0 ? void 0 : result.filepath;
+            }
+            if (!filepath) {
+                errors.push({
+                    level: 'error',
+                    field: 'cloudbaserc',
+                    message: '未找到 cloudbaserc 配置文件',
+                    fix: '在项目根目录新增 cloudbaserc.json / cloudbaserc.js / cloudbaserc.yaml / cloudbaserc.yml',
+                });
+                return {};
+            }
+            const rawConfig = (await (0, toolbox_1.loadConfig)({ configPath: filepath }));
+            const config = (await toolbox_1.ConfigParser.parseRawConfig(rawConfig || {}, cwd, {
+                mode,
+            }));
+            return {
+                filepath,
+                rawConfig,
+                config,
+            };
+        }
+        catch (e) {
+            errors.push({
+                level: 'error',
+                field: 'cloudbaserc',
+                message: `配置文件解析失败：${this.getErrorMessage(e)}`,
+                fix: '检查 cloudbaserc 配置文件语法是否正确',
+            });
+            return { filepath };
+        }
+    }
+    validateSchema(config, errors) {
+        const result = (0, toolbox_1.validateCloudBaseConfigBySchema)(config, { version: '2.1' });
+        result.errors.forEach((error) => {
+            errors.push({
+                level: 'error',
+                field: this.normalizeSchemaPath(error.dataPath),
+                message: `配置不符合 v2.1 Schema：${error.message}`,
+                fix: `请检查 ${this.normalizeSchemaPath(error.dataPath) || 'cloudbaserc'} 字段`,
+            });
+        });
+    }
+    validateEnvId(cwd, config, errors) {
+        if (this.hasPersonalCloudFunction(config.resolved)) {
+            if (typeof config.raw.envId !== 'string' || !config.raw.envId.trim()) {
+                errors.push({
+                    level: 'error',
+                    field: 'envId',
+                    message: '个人版 TCR 云端构建必须在 cloudbaserc 中显式声明 envId',
+                    fix: '声明 envId: "{{env.ENV_ID}}"，并在 .env* 中设置 ENV_ID',
+                });
+                return;
+            }
+            if (typeof config.resolved.envId !== 'string' || !config.resolved.envId.trim()) {
+                errors.push({
+                    level: 'error',
+                    field: 'envId',
+                    message: '个人版 TCR 云端构建的 envId 未赋值',
+                    fix: '在 .env* 中设置 cloudbaserc 通过 {{env.ENV_ID}} 引用的 ENV_ID',
+                });
+            }
+            return;
+        }
+        if (config.resolved.envId || this.getLinkedEnvId(cwd)) {
+            return;
+        }
+        errors.push({
+            level: 'error',
+            field: 'envId',
+            message: '缺少 envId，且未检测到 .tcb/project.json 关联环境',
+            fix: '在 cloudbaserc 中配置 envId，或先执行环境关联流程',
+        });
+    }
+    /**
+     * 个人版 TCR 的 username/password/namespace 必须在 cloudbaserc 中显式声明。
+     * ConfigParser 已先解析 {{env.*}}，因此这里同时承担缺失 env 值的前置校验。
+     */
+    validatePersonalRegistryConfig(config, errors) {
+        ;
+        (config.functions || []).forEach((func, index) => {
+            var _a;
+            if (!this.isPersonalCloudFunction(func)) {
+                return;
+            }
+            const build = (_a = func.imageConfig) === null || _a === void 0 ? void 0 : _a.build;
+            const namespace = build === null || build === void 0 ? void 0 : build.namespace;
+            if (typeof namespace !== 'string' || !namespace.trim()) {
+                errors.push({
+                    level: 'error',
+                    resource: `functions[${index}]`,
+                    field: 'imageConfig.build.namespace',
+                    message: '个人版 TCR 缺少 namespace，或对应环境变量未赋值',
+                    fix: '声明 namespace: "{{env.TCB_TCR_NAMESPACE}}"，并在 .env* 中设置该变量',
+                });
+            }
+            const credential = build === null || build === void 0 ? void 0 : build.registryCredential;
+            if (!credential || typeof credential !== 'object') {
+                errors.push({
+                    level: 'error',
+                    resource: `functions[${index}]`,
+                    field: 'imageConfig.build.registryCredential',
+                    message: '个人版 TCR 缺少 username/password 凭证声明',
+                    fix: '在 registryCredential 中使用 {{env.TCB_TCR_USERNAME}} 与 {{env.TCB_TCR_PASSWORD}}',
+                });
+                return;
+            }
+            const { username, password } = credential;
+            if (typeof username !== 'string' || !/^\d{5,20}$/.test(username.trim())) {
+                errors.push({
+                    level: 'error',
+                    resource: `functions[${index}]`,
+                    field: 'imageConfig.build.registryCredential.username',
+                    message: '个人版 TCR username 未赋值或不是有效腾讯云账号 ID',
+                    fix: '声明 username: "{{env.TCB_TCR_USERNAME}}"，并在 .env* 中设置该变量',
+                });
+            }
+            if (typeof password !== 'string' || !password || password.length > 16 * 1024) {
+                errors.push({
+                    level: 'error',
+                    resource: `functions[${index}]`,
+                    field: 'imageConfig.build.registryCredential.password',
+                    message: '个人版 TCR password 未赋值或长度不合法',
+                    fix: '声明 password: "{{env.TCB_TCR_PASSWORD}}"，并在 .env* 中设置该变量',
+                });
+            }
+        });
+    }
+    hasPersonalCloudFunction(config) {
+        return (config.functions || []).some((func) => this.isPersonalCloudFunction(func));
+    }
+    isPersonalCloudFunction(func) {
+        var _a;
+        return (func.type === 'HTTP' &&
+            func.buildStrategy === 'cloud' &&
+            ((_a = func.imageConfig) === null || _a === void 0 ? void 0 : _a.imageType) === 'personal');
+    }
+    validateResources(cwd, config) {
+        const errors = [];
+        const warnings = [];
+        const functionRoot = config.functionRoot || './functions';
+        (config.functions || []).forEach((func, index) => {
+            const resource = `functions[${index}]`;
+            const functionDir = path_1.default.resolve(cwd, func.dir || path_1.default.join(functionRoot, func.name));
+            if (!fs_1.default.existsSync(functionDir)) {
+                errors.push({
+                    level: 'error',
+                    resource,
+                    field: 'dir',
+                    message: `函数目录不存在：${path_1.default.relative(cwd, functionDir)}`,
+                    fix: '创建函数目录，或修正 functions[].dir / functionRoot 配置',
+                });
+                return;
+            }
+            const functionType = func.type || 'Event';
+            const buildStrategy = func.buildStrategy || 'zip';
+            if (functionType === 'HTTP' && buildStrategy === 'zip') {
+                const bootstrapPath = path_1.default.join(functionDir, 'scf_bootstrap');
+                if (!fs_1.default.existsSync(bootstrapPath)) {
+                    errors.push({
+                        level: 'error',
+                        resource,
+                        field: 'scf_bootstrap',
+                        message: '缺少 scf_bootstrap 文件（HTTP 函数 zip 部署必须）',
+                        fix: '在函数目录中新增 scf_bootstrap，并确保其具备执行权限',
+                    });
+                }
+            }
+            if (functionType === 'Event') {
+                const handlerFile = `${(func.handler || 'index.main').split('.')[0]}.js`;
+                if (!fs_1.default.existsSync(path_1.default.join(functionDir, handlerFile))) {
+                    warnings.push({
+                        level: 'warning',
+                        resource,
+                        field: 'handler',
+                        message: `未找到入口文件 ${handlerFile}`,
+                        fix: '确认 handler 配置与函数入口文件一致',
+                    });
+                }
+            }
+        });
+        (config.hosting || []).forEach((hosting, index) => {
+            const root = path_1.default.resolve(cwd, hosting.root || '.');
+            if (!fs_1.default.existsSync(root)) {
+                errors.push({
+                    level: 'error',
+                    resource: `hosting[${index}]`,
+                    field: 'root',
+                    message: `静态托管根目录不存在：${path_1.default.relative(cwd, root)}`,
+                    fix: '创建目录，或修正 hosting[].root 配置',
+                });
+            }
+        });
+        if (config.database) {
+            const migrations = config.database.migrations || './cloudbase/migrations';
+            if (path_1.default.isAbsolute(migrations) || migrations.startsWith('/')) {
+                errors.push({
+                    level: 'error',
+                    resource: 'database',
+                    field: 'migrations',
+                    message: 'database.migrations 仅支持相对路径',
+                    fix: '请使用相对路径，例如 ./cloudbase/migrations',
+                });
+            }
+            else {
+                const migrationsDir = path_1.default.resolve(cwd, migrations);
+                if (!fs_1.default.existsSync(migrationsDir)) {
+                    errors.push({
+                        level: 'error',
+                        resource: 'database',
+                        field: 'migrations',
+                        message: `数据库迁移目录不存在：${path_1.default.relative(cwd, migrationsDir)}`,
+                        fix: '创建迁移目录，或修正 database.migrations 配置',
+                    });
+                }
+            }
+        }
+        return { errors, warnings };
+    }
+    validateConsistency(config, errors) {
+        this.validateUniqueNames('functions', config.functions || [], errors);
+        this.validateUniqueNames('hosting', config.hosting || [], errors);
+        this.validateUniqueField('hosting', config.hosting || [], { field: 'deployPath', errors });
+        this.validateGatewayTargets(config, errors);
+    }
+    validateUniqueNames(resource, items, errors) {
+        const names = new Map();
+        items.forEach((item, index) => {
+            if (!item.name)
+                return;
+            const prev = names.get(item.name);
+            if (typeof prev === 'number') {
+                errors.push({
+                    level: 'error',
+                    resource: `${resource}[${index}]`,
+                    field: 'name',
+                    message: `${resource} 名称重复：${item.name}`,
+                    fix: `修改 ${resource}[${index}].name，避免与 ${resource}[${prev}].name 重复`,
+                });
+            }
+            else {
+                names.set(item.name, index);
+            }
+        });
+    }
+    validateUniqueField(resource, items, options) {
+        const { field, errors } = options;
+        const values = new Map();
+        items.forEach((item, index) => {
+            const value = item[field];
+            if (!value)
+                return;
+            const prev = values.get(value);
+            if (typeof prev === 'number') {
+                errors.push({
+                    level: 'error',
+                    resource: `${resource}[${index}]`,
+                    field,
+                    message: `${resource}.${field} 配置重复：${value}`,
+                    fix: `修改 ${resource}[${index}].${field}，避免与 ${resource}[${prev}].${field} 重复`,
+                });
+            }
+            else {
+                values.set(value, index);
+            }
+        });
+    }
+    validateGatewayTargets(config, errors) {
+        var _a;
+        const functionNames = new Set((config.functions || []).map((item) => item.name));
+        const hostingNames = new Set((config.hosting || []).map((item) => item.name));
+        (((_a = config.gateway) === null || _a === void 0 ? void 0 : _a.routes) || []).forEach((route, index) => {
+            const [type, name] = route.target.split(':');
+            if ((type === 'function' && !functionNames.has(name)) || (type === 'hosting' && !hostingNames.has(name))) {
+                errors.push({
+                    level: 'error',
+                    resource: `gateway.routes[${index}]`,
+                    field: 'target',
+                    message: `网关目标不存在：${route.target}`,
+                    fix: '确认 gateway.routes[].target 引用了已声明的 function 或 hosting 资源',
+                });
+            }
+        });
+    }
+    getSummary(config) {
+        var _a, _b, _c, _d;
+        return {
+            functions: ((_a = config === null || config === void 0 ? void 0 : config.functions) === null || _a === void 0 ? void 0 : _a.length) || 0,
+            hosting: ((_b = config === null || config === void 0 ? void 0 : config.hosting) === null || _b === void 0 ? void 0 : _b.length) || 0,
+            databases: (config === null || config === void 0 ? void 0 : config.database) ? 1 : 0,
+            gateways: ((_d = (_c = config === null || config === void 0 ? void 0 : config.gateway) === null || _c === void 0 ? void 0 : _c.routes) === null || _d === void 0 ? void 0 : _d.length) || 0,
+        };
+    }
+    getLinkedEnvId(cwd) {
+        const projectPath = path_1.default.join(cwd, '.tcb', 'project.json');
+        if (!fs_1.default.existsSync(projectPath)) {
+            return '';
+        }
+        try {
+            const project = JSON.parse(fs_1.default.readFileSync(projectPath, 'utf8'));
+            return project.envId || project.EnvId || '';
+        }
+        catch (e) {
+            return '';
+        }
+    }
+    normalizeSchemaPath(dataPath) {
+        return dataPath.replace(/^\//, '').replace(/\//g, '.');
+    }
+    getErrorMessage(error) {
+        return (error === null || error === void 0 ? void 0 : error.message) || String(error);
+    }
+}
+exports.ProjectValidator = ProjectValidator;
+__exportStar(require("./types"), exports);

package/lib/projectValidator/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/storage/index.js

@@ -1046,20 +1046,19 @@ class StorageService {
      * 配置文档
      */
     async putBucketWebsite(options) {
-        const { indexDocument, errorDocument, bucket, region, routingRules } = options;
+        const { indexDocument, errorDocument, originalHttpStatus, charity404, autoAddressing, bucket, region, routingRules } = options;
         const cos = this.getCos();
         const putBucketWebsite = util_1.default.promisify(cos.putBucketWebsite).bind(cos);
         let params = {
             Bucket: bucket,
             Region: region,
-            WebsiteConfiguration: {
-                IndexDocument: {
+            WebsiteConfiguration: Object.assign(Object.assign(Object.assign({}, (autoAddressing ? { AutoAddressing: { Status: autoAddressing } } : {})), { IndexDocument: {
                     Suffix: indexDocument
-                },
-                ErrorDocument: {
-                    Key: errorDocument
+                } }), (errorDocument !== undefined
+                ? {
+                    ErrorDocument: Object.assign(Object.assign({ Key: errorDocument }, (originalHttpStatus ? { OriginalHttpStatus: originalHttpStatus } : {})), (charity404 ? { Charity404: charity404 } : {}))
                 }
-            }
+                : {}))
         };
         if (routingRules) {
             params.WebsiteConfiguration.RoutingRules = [];

package/lib/utils/index.js

@@ -34,6 +34,7 @@ const archiver_1 = __importDefault(require("archiver"));
 const crypto_1 = __importDefault(require("crypto"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const lodash_1 = __importDefault(require("lodash"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const unzipper_1 = __importDefault(require("unzipper"));
 const constant_1 = require("../constant");
@@ -47,17 +48,37 @@ __exportStar(require("./http-request"), exports);
 var uuid_1 = require("./uuid");
 Object.defineProperty(exports, "guid6", { enumerable: true, get: function () { return uuid_1.guid6; } });
 async function compressToZip(option) {
-    const { dirPath, outputPath, ignore, pattern = '**/*' } = option;
+    const { dirPath, outputPath, ignore, pattern = '**/*', extraEntries } = option;
+    // 额外注入的文件先落地到临时目录，用 archive.file() 追加，
+    // 使 archiver 正确计算 CRC/size（archiver 3.x 的 append(buffer/string)
+    // 会写出 CRC=0 的流式条目，被严格解压器判为 bad CRC）。
+    let extraTmpDir;
+    if (extraEntries && extraEntries.length > 0) {
+        extraTmpDir = path_1.default.join(os_1.default.tmpdir(), `zip-extra-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        fs_extra_1.default.mkdirpSync(extraTmpDir);
+    }
     return new Promise((resolve, reject) => {
+        const cleanupExtra = () => {
+            if (extraTmpDir) {
+                try {
+                    fs_extra_1.default.removeSync(extraTmpDir);
+                }
+                catch (_a) {
+                    // 清理临时目录失败不影响主流程
+                }
+            }
+        };
         const output = fs_extra_1.default.createWriteStream(outputPath);
         const archive = (0, archiver_1.default)('zip');
         output.on('close', function () {
+            cleanupExtra();
             resolve({
                 zipPath: outputPath,
                 size: Math.ceil(archive.pointer() / 1024)
             });
         });
         archive.on('error', function (err) {
+            cleanupExtra();
             reject(err);
         });
         archive.pipe(output);
@@ -68,6 +89,25 @@ async function compressToZip(option) {
             ignore: ignore,
             dot: true
         });
+        // 追加 SDK 注入的额外文件（如构建推送脚本），不污染用户源码目录
+        if (extraEntries && extraEntries.length > 0 && extraTmpDir) {
+            try {
+                extraEntries.forEach((entry, index) => {
+                    const tmpFile = path_1.default.join(extraTmpDir, `entry-${index}`);
+                    const buf = Buffer.isBuffer(entry.content)
+                        ? entry.content
+                        : Buffer.from(entry.content, 'utf8');
+                    fs_extra_1.default.writeFileSync(tmpFile, buf, { mode: entry.mode });
+                    archive.file(tmpFile, { name: entry.zipPath, mode: entry.mode });
+                });
+            }
+            catch (error) {
+                cleanupExtra();
+                archive.abort();
+                reject(error);
+                return;
+            }
+        }
         archive.finalize();
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/manager-node",
-    "version": "5.6.7",
+    "version": "5.7.0-beta.0",
     "description": "The node manage service api for cloudbase.",
     "main": "lib/index.js",
     "scripts": {
@@ -42,6 +42,7 @@
     },
     "dependencies": {
         "@cloudbase/signature-nodejs": "^1.0.0",
+        "@cloudbase/toolbox": "^0.8.3-beta.0",
         "@cloudbase/database": "^0.6.2",
         "archiver": "^3.1.1",
         "cos-nodejs-sdk-v5": "^2.14.0",

package/types/cloudApp/index.d.ts

@@ -57,6 +57,10 @@ export declare class CloudAppService {
      * 注意：此方法不依赖应用是否已创建，可在创建应用前调用
      * 返回的 cosTimestamp 用于 createApp 时传入 staticConfig.cosTimestamp
      *
+     * 内置默认忽略：.git 目录、.DS_Store（含任意层级）；node_modules 仅在
+     * excludeNodeModules 为 true（默认）时排除——云端构建（需云端 install）场景应传
+     * excludeNodeModules: false 允许私有/离线依赖随源码包上传。
+     *
      * @param params 上传参数
      */
     uploadCode(params: IUploadCloudAppCodeParams): Promise<IUploadCloudAppCodeResult>;

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 模式输出耗时） */