@cloudbase/manager-node 5.8.7 → 5.8.8

package/lib/utils/storage-config.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPhysicalKey = toPhysicalKey;
+exports.toLogicalPath = toLogicalPath;
+exports.resolveStorageConfig = resolveStorageConfig;
+exports.resolveBucketConfig = resolveBucketConfig;
+const error_1 = require("../error");
+function trimSlashes(p) {
+    return p.replace(/^\/+|\/+$/g, '');
+}
+/**
+ * 逻辑路径 → COS 物理 Key：共享桶环境拼上 basePath 前缀，basePath 为空时原样返回
+ * cloudPath 为空或为 '/' 时返回 `${basePath}/`，即共享桶内本环境的根目录
+ */
+function toPhysicalKey(basePath, cloudPath = '') {
+    const base = trimSlashes(basePath || '');
+    if (!base) {
+        return cloudPath;
+    }
+    return `${base}/${cloudPath.replace(/^\/+/, '')}`;
+}
+/**
+ * COS 物理 Key → 逻辑路径：去掉 basePath 前缀，basePath 为空或 Key 不在前缀下时原样返回
+ */
+function toLogicalPath(basePath, key) {
+    const base = trimSlashes(basePath || '');
+    const prefix = `${base}/`;
+    if (!base || !key || !key.startsWith(prefix)) {
+        return key;
+    }
+    return key.slice(prefix.length);
+}
+/**
+ * 解析环境的有效云存储配置
+ * 共享桶环境（Storages[0].ExternalStorage.Enabled 为 true）下，BasePath 从 ExternalStorage 读取，桶名、地域在顶层为空时回退到 ExternalStorage；
+ * 普通环境保持读取 Storages[0].Bucket / Region，basePath 为空串
+ */
+function resolveStorageConfig(envConfig) {
+    var _a;
+    // 环境信息由带 @preLazy 的方法首次调用时加载，直接调用 getStorageConfig 可能早于加载
+    if (!envConfig) {
+        throw new error_1.CloudBaseError('环境信息尚未加载，无法获取存储配置，请先调用任一存储方法（如 listDirectoryFiles）或 environment.lazyInit() 完成初始化');
+    }
+    const storage = (_a = envConfig.Storages) === null || _a === void 0 ? void 0 : _a[0];
+    if (!storage) {
+        throw new error_1.CloudBaseError(`环境 ${envConfig === null || envConfig === void 0 ? void 0 : envConfig.EnvId} 未查询到云存储资源（Storages 为空），请确认环境 ID 正确且环境已开通云存储`);
+    }
+    return Object.assign({ env: envConfig.EnvId }, resolveBucketConfig({
+        envId: envConfig.EnvId,
+        bucket: storage.Bucket,
+        region: storage.Region,
+        externalStorage: storage.ExternalStorage
+    }));
+}
+/**
+ * 按共享桶规则解析有效桶，云存储（Storages）与静态托管（DescribeStaticStore）共用
+ *
+ * 是否共享桶只看 ExternalStorage.Enabled，不看顶层 Bucket 是否为空：
+ * 目前线上共享桶环境的顶层 Bucket 均返回空串，但接口定义并未保证这一点，
+ * 若后端回填桶名而 basePath 仍按「Bucket 为空」判定，文件会静默写到桶根目录，
+ * 造成同一共享桶内跨环境污染。因此 basePath 只由 Enabled + BasePath 决定，
+ * 桶名则优先用顶层 Bucket，为空时回退到 ExternalStorage.BucketName。
+ */
+function resolveBucketConfig(options) {
+    const { envId, bucket, region, externalStorage } = options;
+    if ((externalStorage === null || externalStorage === void 0 ? void 0 : externalStorage.Enabled) === true) {
+        const effectiveBucket = bucket || externalStorage.BucketName;
+        // 线上存在已启用外部存储但未返回桶名的环境，继续执行会在 COS 调用时报 missing param Bucket
+        if (!effectiveBucket) {
+            throw new error_1.CloudBaseError(`环境 ${envId} 已启用外部存储（ExternalStorage），但未返回存储桶名称（BucketName），无法访问存储桶，请联系平台检查该环境的共享桶配置`);
+        }
+        return {
+            bucket: effectiveBucket,
+            region: region || externalStorage.Region,
+            basePath: externalStorage.BasePath || ''
+        };
+    }
+    return { bucket, region, basePath: '' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cloudbase/manager-node",
-    "version": "5.8.7",
+    "version": "5.8.8",
     "description": "The node manage service api for cloudbase.",
     "main": "lib/index.js",
     "scripts": {

package/types/env/index.d.ts

@@ -864,8 +864,14 @@ export declare class EnvService {
      */
     describeBillingInfo(params: {
         EnvId?: string;
+        /** 分页条数 */
+        Limit?: number;
+        /** 分页偏移 */
+        Offset?: number;
     }): Promise<{
         EnvBillingInfoList: EnvBillingInfoItem[];
+        /** 环境总数（实测与实际可翻页的条数不一致，不宜直接作为总数展示） */
+        Total?: number;
         RequestId: string;
     }>;
     /**

package/types/env/type.d.ts

@@ -215,11 +215,62 @@ export interface HTTPServiceHeadersHandler {
     ResponseHeadersToAdd?: HTTPServiceHeaderToAdd[];
     ResponseHeadersToRemove?: string[];
 }
+/**
+ * HTTPService 缓存配置（域名维度）
+ */
+export interface HTTPServiceCacheSet {
+    Rules?: HTTPServiceCacheRule[];
+}
+/**
+ * HTTPService 缓存规则条目
+ */
+export interface HTTPServiceCacheRule {
+    Description?: string;
+    Enable?: boolean;
+    Condition: HTTPServiceRuleCondition;
+    Actions: HTTPServiceCacheAction[];
+}
+/**
+ * HTTPService 缓存规则匹配条件
+ */
+export interface HTTPServiceRuleCondition {
+    Target?: 'url_path' | 'file_extension' | 'full_uri';
+    MatchType?: 'prefix' | 'suffix' | 'contains' | 'exact';
+    Values?: string[];
+}
+/**
+ * HTTPService 缓存动作（Type 与被设置的子字段必须一一对应）
+ */
+export interface HTTPServiceCacheAction {
+    Type?: 'Cache' | 'CacheKey';
+    Cache?: HTTPServiceCacheParams;
+    CacheKey?: HTTPServiceCacheKeyParams;
+}
+/**
+ * HTTPService 缓存参数（节点缓存 + 浏览器缓存）
+ * FollowOrigin / NoCache / (CacheTime||MaxAgeTime) 三者互斥，必须开启其一
+ */
+export interface HTTPServiceCacheParams {
+    FollowOrigin?: boolean;
+    NoCache?: boolean;
+    CacheTime?: number;
+    MaxAgeTime?: number;
+}
+/**
+ * 自定义缓存键参数。约束：FullURLCache=on 与 QueryStringSwitch=on 互斥
+ */
+export interface HTTPServiceCacheKeyParams {
+    FullURLCache?: 'on' | 'off';
+    QueryStringSwitch?: 'on' | 'off';
+    QueryStringAction?: 'includeCustom' | 'excludeCustom';
+    QueryStringValues?: string[];
+}
 /**
  * HTTP访问服务路由扩展字段
  */
 export interface HTTPServiceExtension {
     HeadersHandler?: HTTPServiceHeadersHandler;
+    Cache?: HTTPServiceCacheSet;
     [key: string]: unknown;
 }
 /**
@@ -245,14 +296,15 @@ export interface HTTPServiceRoute {
 export interface HTTPServiceDomain {
     Domain: string;
     DomainType: 'HTTPSERVICE' | 'CBR' | 'ANYSERVICE' | 'AI_AGENT' | 'VM' | 'INTEGRATION_CALLBACK';
-    AccessType: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO';
+    AccessType: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO' | 'NONE';
     CertId: string;
     Protocol: 'HTTP_AND_HTTPS' | 'HTTP_TO_HTTPS' | 'HTTPS_TO_HTTP';
     Cname: string;
     IsDefault: boolean;
     Enable: boolean;
-    Status: 'PROCESSING' | 'FAIL' | 'SUCCESS';
-    DNSStatus: 'OK' | 'INVALID';
+    Status: 'PROCESSING' | 'FAIL' | 'EO_PENDING_VERIFICATION' | 'SUCCESS';
+    DNSStatus: 'OK' | 'EMPTY' | 'INVALID';
+    PlatformCnameDNSStatus?: 'OK' | 'EMPTY' | 'INVALID';
     Routes?: HTTPServiceRoute[];
     Extension?: HTTPServiceExtension;
     CreateTime: string;
@@ -303,7 +355,7 @@ export interface HTTPServiceRouteParam {
  */
 export interface HTTPServiceDomainParam {
     Domain: string;
-    AccessType?: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO';
+    AccessType?: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO' | 'NONE';
     CertId?: string;
     Protocol?: 'HTTP' | 'HTTPS' | 'HTTP_AND_HTTPS' | 'HTTP_TO_HTTPS' | 'HTTPS_TO_HTTP';
     CustomCname?: string;

package/types/environment.d.ts

@@ -21,6 +21,7 @@ import { SandboxService } from './sandbox';
 import { AiModelService } from './aiModel';
 import { MonitorService } from './monitor';
 import { IntegrationService } from './integration';
+import { PlatformService } from './platform';
 export declare class Environment {
     inited: boolean;
     cloudBaseContext: CloudBaseContext;
@@ -47,6 +48,7 @@ export declare class Environment {
     private aiModelService;
     private monitorService;
     private integrationService;
+    private platformService;
     constructor(context: CloudBaseContext, envId: string);
     lazyInit(): Promise<any>;
     getEnvId(): string;
@@ -75,6 +77,10 @@ export declare class Environment {
     getAiModelService(): AiModelService;
     getMonitorService(): MonitorService;
     getIntegrationService(): IntegrationService;
+    /**
+     * 获取平台版套餐服务
+     */
+    getPlatformService(): PlatformService;
     getCommonService(serviceType: string, serviceVersion: any): CommonService;
     getServicesEnvInfo(): Promise<any>;
     getAuthConfig(): {

package/types/error.d.ts

@@ -4,6 +4,7 @@ interface Options {
     code?: string | number;
     requestId?: string;
     action?: string;
+    meta?: Record<string, any>;
 }
 export declare class CloudBaseError extends Error {
     readonly exit: number;
@@ -13,6 +14,7 @@ export declare class CloudBaseError extends Error {
     readonly code: string | number;
     readonly requestId: string;
     readonly action: string;
+    readonly meta: Record<string, any> | undefined;
     constructor(message: string, options?: Options);
 }
 export {};

package/types/hosting/index.d.ts

@@ -1,5 +1,5 @@
 import { Environment } from '../environment';
-import { IListFileInfo } from '../interfaces';
+import { ExternalStorage, IListFileInfo } from '../interfaces';
 export interface IProgressData {
     loaded: number;
     total: number;
@@ -116,10 +116,12 @@ export interface IHostingInfo {
     CdnDomain: string;
     Bucket: string;
     Regoin: string;
+    Region?: string;
     Status: string;
     MaxDomain: number;
     Id: number;
     PolicyId: number;
+    ExternalStorage?: ExternalStorage;
 }
 export interface IRoutingRules {
     keyPrefixEquals?: string;
@@ -261,6 +263,11 @@ export declare class HostingService {
      * 检查 hosting 服务状态
      */
     private checkStatus;
+    /**
+     * 检查 hosting 服务状态并解析有效桶，兼容共享桶（ExternalStorage）环境
+     * 静态托管的共享桶与 BasePath 独立于云存储，不能复用 StorageService.getStorageConfig
+     */
+    private getHostingBucket;
     /**
      * 获取配置
      */

package/types/index.d.ts

@@ -23,6 +23,7 @@ import { CloudAppService } from './cloudApp';
 import { AiModelService } from './aiModel';
 import { IntegrationService } from './integration';
 import { MonitorService } from './monitor';
+import { PlatformService } from './platform';
 import { ProjectValidator } from './projectValidator';
 import { DeployOrchestrator } from './deploy/DeployOrchestrator';
 import { resolveBuildCommand as frameworkResolveBuildCommand, resolveHostingOutputDir as frameworkResolveHostingOutputDir, buildHostingItem as frameworkBuildHostingItem } from './deploy/framework';
@@ -113,6 +114,11 @@ declare class CloudBase {
      * 提供指标查询能力
      */
     get monitor(): MonitorService;
+    /**
+     * 平台版套餐服务
+     * 提供平台版套餐查询、环境管理、资源用量及 HTTP 访问服务路由等能力
+     */
+    get platform(): PlatformService;
     get docs(): DocsService;
     get projectValidator(): ProjectValidator;
     getProjectValidator(): ProjectValidator;

package/types/interfaces/tcb.interface.d.ts

@@ -450,6 +450,7 @@ export interface CreateEnvParams {
     Alias: string;
     PackageId: string;
     Resources: string[];
+    ExternalStorage?: ExternalStorage;
     Period?: number;
     AutoVoucher?: boolean;
     Tags?: Tag[];

package/types/platform/index.d.ts

@@ -0,0 +1,133 @@
+import { Environment } from '../environment';
+import { CreatePlatformEnvParams, CreatePlatformEnvRes, CreatePlatformHTTPServiceRouteParams, CreatePlatformHTTPServiceRouteRes, DescribePlatformAccountCircleParams, DescribePlatformAccountCircleRes, DescribePlatformCreditsUsageDetailParams, DescribePlatformCreditsUsageDetailRes, DescribePlatformCreditsUsageParams, DescribePlatformCreditsUsageRes, DescribePlatformEnvCreditsRankingParams, DescribePlatformEnvCreditsRankingRes, DescribePlatformEnvUsageParams, DescribePlatformEnvUsageRes, DescribePlatformHTTPServiceRouteParams, DescribePlatformHTTPServiceRouteRes, DescribePlatformPackageListParams, DescribePlatformPackageListRes, DescribePlatformsParams, DescribePlatformsRes, DeletePlatformHTTPServiceRouteParams, DeletePlatformHTTPServiceRouteRes, DestroyPlatformEnvParams, DestroyPlatformEnvRes, ModifyPlatformEnvParams, ModifyPlatformEnvRes, ModifyPlatformHTTPServiceRouteParams, ModifyPlatformHTTPServiceRouteRes, VerifyPlatformHTTPServiceRouteParams, VerifyPlatformHTTPServiceRouteRes } from './type';
+/**
+ * 平台版服务
+ * 提供平台版套餐查询、资源用量统计、环境生命周期管理及 HTTP 访问服务路由管理能力
+ */
+export declare class PlatformService {
+    private environment;
+    private envId;
+    private cloudService;
+    constructor(environment: Environment);
+    /**
+     * 查询在售的平台版套餐列表
+     * 返回当前可购买的平台版套餐，包括计费下单配置（BillTags）、套餐规格（Spec）等商品信息，
+     * 用于购买前的套餐查询，不涉及用户已购资源。
+     * @param {DescribePlatformPackageListParams} params 查询参数，可通过 PackageId 查询指定套餐
+     * @returns {Promise<DescribePlatformPackageListRes>} 在售套餐列表
+     */
+    describePlatformPackageList(params?: DescribePlatformPackageListParams): Promise<DescribePlatformPackageListRes>;
+    /**
+     * 查询当前账号下的平台版资源实例列表
+     * 返回已购平台版资源的计费信息（购买与过期时间、计费状态、自动续费），
+     * 以及存储、日志、静态托管等底层资源明细。
+     * @param {DescribePlatformsParams} params 查询参数，PlatformIds 指定实例（缺省分页返回全部），Limit 取值 [10, 100]
+     * @returns {Promise<DescribePlatformsRes>} 平台版资源列表及总数
+     * @throws {CloudBaseError} Limit 非法时抛出，须为 10 至 100 的整数
+     */
+    describePlatforms(params?: DescribePlatformsParams): Promise<DescribePlatformsRes>;
+    /**
+     * 查询平台版资源当前所处的计费周期
+     * 平台版资源点按月结算，计费周期自购买日起算，每个周期各享有一笔抵扣额度。
+     * 例如 2026-01-05 购买 3 个月（2026-04-05 到期），则三个周期分别为
+     * 01-05 ~ 02-05、02-06 ~ 03-05、03-06 ~ 04-05。
+     * @param {DescribePlatformAccountCircleParams} params 查询参数，WithHistoryCircle 为 true 时附带返回最近两个历史周期
+     * @returns {Promise<DescribePlatformAccountCircleRes>} 当前周期起止时间及是否过期
+     */
+    describePlatformAccountCircle(params: DescribePlatformAccountCircleParams): Promise<DescribePlatformAccountCircleRes>;
+    /**
+     * 查询平台版资源的资源点用量汇总
+     * 返回指定时间范围内的资源点用量统计，包括套餐内抵扣、资源包抵扣、
+     * 按量上报、原价消耗四类总量的每日明细。
+     * @param {DescribePlatformCreditsUsageParams} params 查询参数，StartDate/EndDate 格式为 'YYYY-MM-DD'
+     * @returns {Promise<DescribePlatformCreditsUsageRes>} 四类用量总量及每日明细
+     */
+    describePlatformCreditsUsage(params: DescribePlatformCreditsUsageParams): Promise<DescribePlatformCreditsUsageRes>;
+    /**
+     * 查询平台版资源的资源点用量明细
+     * 按模块（Usages）→ 指标（MetricUsageDetail）→ 每日明细（ValueDetailList）三个层级，
+     * 返回各模块的资源点用量及原始用量明细。
+     * @param {DescribePlatformCreditsUsageDetailParams} params 查询参数，Modules 指定查询的模块（如 FLEXDB、SCF、AI、COS 等）
+     * @returns {Promise<DescribePlatformCreditsUsageDetailRes>} 各模块的用量明细数据
+     */
+    describePlatformCreditsUsageDetail(params: DescribePlatformCreditsUsageDetailParams): Promise<DescribePlatformCreditsUsageDetailRes>;
+    /**
+     * 查询平台版下各环境的资源点用量排行
+     * 按 TimeRange 指定的时间范围返回各环境的资源点用量排序，
+     * 排行数据由后台定时计算，可能存在小时级延迟。
+     * @param {DescribePlatformEnvCreditsRankingParams} params 查询参数，TimeRange 缺省为 Today（近 1 天）
+     * @returns {Promise<DescribePlatformEnvCreditsRankingRes>} 环境用量排行列表及分页信息
+     */
+    describePlatformEnvCreditsRanking(params?: DescribePlatformEnvCreditsRankingParams): Promise<DescribePlatformEnvCreditsRankingRes>;
+    /**
+     * 查询平台版环境内各资源类型的用量
+     * 按资源类型（存储、函数、数据库等）返回各指标的用量及按日明细，
+     * 包括资源点用量与原始用量值及对应单位。
+     * @param {DescribePlatformEnvUsageParams} params 查询参数，EnvId 缺省时使用当前环境，ResourceTypes 指定资源类型
+     * @returns {Promise<DescribePlatformEnvUsageRes>} 资源用量明细及资源点总量
+     */
+    describePlatformEnvUsage(params: DescribePlatformEnvUsageParams): Promise<DescribePlatformEnvUsageRes>;
+    /**
+     * 创建平台版环境
+     * 在已购平台版资源下开通新环境。
+     * @param {CreatePlatformEnvParams} params 创建参数，ReqKey 为幂等键，可用于防止重复创建
+     * @returns {Promise<CreatePlatformEnvRes>} 新创建环境的 EnvId
+     */
+    createPlatformEnv(params: CreatePlatformEnvParams): Promise<CreatePlatformEnvRes>;
+    /**
+     * 修改平台版环境状态
+     * 支持启用/禁用环境，以及云存储（Storage）、FlexDB 资源的状态变更，未传入的资源不做更新。
+     * @param {ModifyPlatformEnvParams} params 修改参数，EnvId 缺省时使用当前环境
+     * @returns {Promise<ModifyPlatformEnvRes>} 环境的最终状态
+     * @throws {CloudBaseError} Status 非法时抛出，仅支持 ENABLE / DISABLE
+     */
+    modifyPlatformEnv(params: ModifyPlatformEnvParams): Promise<ModifyPlatformEnvRes>;
+    /**
+     * 删除平台版环境
+     * 删除操作不可逆，须显式指定目标环境 ID。
+     * @param {DestroyPlatformEnvParams} params 删除参数，EnvId 为必填
+     * @returns {Promise<DestroyPlatformEnvRes>} 请求执行结果
+     */
+    destroyPlatformEnv(params: DestroyPlatformEnvParams): Promise<DestroyPlatformEnvRes>;
+    /**
+     * 校验 HTTP 访问服务路由配置（预检）
+     * 创建路由前的只读预检，覆盖域名归属权、证书、配额、路由冲突、域名占用等检查项，
+     * 不创建任何资源。Passed 为 true 时可调用 createPlatformHttpServiceRoute 正式创建；
+     * 为 false 时根据各检查项的 Code 定位并修正问题。
+     * 预检通过不代表创建必然成功，但预检不通过则创建必然失败。
+     * @param {VerifyPlatformHTTPServiceRouteParams} params 校验参数，包含待校验的域名路由信息
+     * @returns {Promise<VerifyPlatformHTTPServiceRouteRes>} 整体校验结果及各检查项明细
+     */
+    verifyPlatformHttpServiceRoute(params: VerifyPlatformHTTPServiceRouteParams): Promise<VerifyPlatformHTTPServiceRouteRes>;
+    /**
+     * 创建 HTTP 访问服务路由
+     * 不传 Domain.Routes 时仅创建域名信息。域名与路由均为异步下发，创建后需调用
+     * describePlatformHttpServiceRoute 轮询域名状态，直到 SUCCESS 或 FAIL（FAIL 可删除后重新创建）；
+     * 下发完成前访问域名可能返回 404 或 HTTPS 握手失败。
+     * @param {CreatePlatformHTTPServiceRouteParams} params 创建参数
+     * @returns {Promise<CreatePlatformHTTPServiceRouteRes>} 域名归属权验证指引（归属校验未通过时返回）
+     */
+    createPlatformHttpServiceRoute(params: CreatePlatformHTTPServiceRouteParams): Promise<CreatePlatformHTTPServiceRouteRes>;
+    /**
+     * 修改 HTTP 访问服务路由
+     * 增量更新，对应字段未传入则不修改。
+     * @param {ModifyPlatformHTTPServiceRouteParams} params 修改参数，包含目标域名及待更新的路由信息
+     * @returns {Promise<ModifyPlatformHTTPServiceRouteRes>} 请求执行结果
+     */
+    modifyPlatformHttpServiceRoute(params: ModifyPlatformHTTPServiceRouteParams): Promise<ModifyPlatformHTTPServiceRouteRes>;
+    /**
+     * 删除 HTTP 访问服务路由
+     * Paths 为空时删除域名及其下全部路由，非空时仅删除指定路径的路由。
+     * @param {DeletePlatformHTTPServiceRouteParams} params 删除参数，Paths 缺省时删除整个域名
+     * @returns {Promise<DeletePlatformHTTPServiceRouteRes>} 请求执行结果
+     */
+    deletePlatformHttpServiceRoute(params: DeletePlatformHTTPServiceRouteParams): Promise<DeletePlatformHTTPServiceRouteRes>;
+    /**
+     * 查询 HTTP 访问服务路由
+     * 返回各域名及其路由信息列表、自定义接入的源站域名及域名总数，
+     * 支持按 Domain、Path、DomainType、UpstreamResourceType 过滤及分页。
+     * @param {DescribePlatformHTTPServiceRouteParams} params 查询参数，Limit 默认 20、最大 1000
+     * @returns {Promise<DescribePlatformHTTPServiceRouteRes>} 域名路由列表及域名总数
+     */
+    describePlatformHttpServiceRoute(params: DescribePlatformHTTPServiceRouteParams): Promise<DescribePlatformHTTPServiceRouteRes>;
+}