@cloudbase/manager-node 5.8.7 → 5.8.8

package/types/platform/type.d.ts

@@ -0,0 +1,525 @@
+/**
+ * 平台版套餐相关接口类型定义
+ */
+import { CircleTime, MetricUsage } from '../interfaces/tcb.interface';
+import { HTTPServiceDomain, HTTPServiceDomainParam, HTTPServiceRouteFilter, OwnershipVerificationInfo, VerifyHttpServiceRouteCheckItem } from '../env/type';
+/**
+ * 平台版环境配置（资源状态变更）
+ * 用于云存储（Storage）、FlexDB（文档型数据库）等资源的状态更新
+ */
+export interface PlatformEnvResource {
+    /** 资源状态（为空或不传则不更新）。ENABLE：正常 / DISABLE：彻底禁用 / READONLY：只读 */
+    Status?: 'ENABLE' | 'DISABLE' | 'READONLY';
+}
+/**
+ * ModifyPlatformEnv 请求参数
+ */
+export interface ModifyPlatformEnvParams {
+    /** 环境ID（可选，不传则自动使用当前环境 ID） */
+    EnvId?: string;
+    /** 环境状态。ENABLE：启用环境 / DISABLE：禁用环境 */
+    Status?: 'ENABLE' | 'DISABLE';
+    /** 云存储信息变更（不传或为空则不更新） */
+    Storage?: PlatformEnvResource;
+    /** FlexDB（文档型数据库）状态更新（为空或不传则不更新） */
+    FlexDB?: PlatformEnvResource;
+}
+/**
+ * ModifyPlatformEnv 返回结果
+ */
+export interface ModifyPlatformEnvRes {
+    /** 最终状态，如 manualLimited */
+    Status?: string;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 平台版套餐信息
+ */
+export interface PlatformPackageInfo {
+    /** 套餐id */
+    PackageId?: string;
+    /** 套餐名称 */
+    Name?: string;
+    /** 计费下单参数（JSON 字符串） */
+    BillTags?: string;
+    /** 套餐规格信息（JSON 字符串） */
+    Spec?: string;
+    /** 套餐描述信息 */
+    Description?: string;
+    /** 套餐数字id */
+    Id?: number;
+}
+/**
+ * DescribePlatformPackageList 请求参数
+ */
+export interface DescribePlatformPackageListParams {
+    /** 平台版套餐id */
+    PackageId?: string;
+}
+/**
+ * DescribePlatformPackageList 返回结果
+ */
+export interface DescribePlatformPackageListRes {
+    /** 平台版套餐列表 */
+    PackageList: PlatformPackageInfo[];
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 平台版资源项信息（平台版套餐下的具体资源，如日志、云存储、静态托管）
+ */
+export interface PlatFormResourceInfo {
+    /** 资源类型。log：日志 / storage：云存储 / hosting：静态托管 */
+    ResType?: string;
+    /** 资源唯一标识 */
+    ResName?: string;
+    /** 资源详细信息（JSON 字符串） */
+    Detail?: string;
+    /** 资源状态。0：正常 / 5：初始化中 */
+    Status?: number;
+    /** 资源id */
+    PlatformId?: number;
+    /** 对应平台资源id */
+    Id?: number;
+}
+/**
+ * 平台版资源信息
+ */
+export interface PlatformInfo {
+    /** 平台版套餐id */
+    PlatformId?: string;
+    /** 套餐别名 */
+    Alias?: string;
+    /** 套餐id */
+    PackageId?: string;
+    /** 计费状态。normal：正常 / isolated：已隔离 / destroyed：已销毁 */
+    BillStatus?: string;
+    /** 套餐资源状态。0：可用 / 5：发货中 */
+    Status?: number;
+    /** 资源配置（JSON 字符串） */
+    Spec?: string;
+    /** 购买时间，格式 'YYYY-MM-DD HH:mm:ss' */
+    BillTime?: string;
+    /** 套餐过期时间，格式 'YYYY-MM-DD HH:mm:ss' */
+    ExpireTime?: string;
+    /** 是否自动续费。0：未设置 / 1：自动续费 / 2：设置为到期不续费 */
+    IsAutoRenew?: number;
+    /** 资源信息列表 */
+    Resources?: PlatFormResourceInfo[];
+    /** 所属地域。ap-shanghai：上海 / ap-singapore：新加坡 */
+    Region?: string;
+}
+/**
+ * DescribePlatforms 请求参数
+ */
+export interface DescribePlatformsParams {
+    /** 平台版套餐id列表（不指定则分页返回当前账号下所有平台版资源） */
+    PlatformIds?: string[];
+    /** 分页限制，取值范围 [10, 100]，默认 10 */
+    Limit?: number;
+    /** 分页偏移量，默认 0 */
+    Offset?: number;
+}
+/**
+ * DescribePlatforms 返回结果
+ */
+export interface DescribePlatformsRes {
+    /** 平台版资源列表 */
+    PlatformList: PlatformInfo[];
+    /** 总数 */
+    Total?: number;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * DescribePlatformAccountCircle 请求参数
+ */
+export interface DescribePlatformAccountCircleParams {
+    /** 平台版资源id */
+    PlatformId: string;
+    /** false 仅返回当前套餐周期，true 返回当前周期以及上个、上上个周期 */
+    WithHistoryCircle?: boolean;
+}
+/**
+ * DescribePlatformAccountCircle 返回结果
+ */
+export interface DescribePlatformAccountCircleRes {
+    /** 套餐计费周期开始时间 */
+    StartTime: string;
+    /** 套餐计费周期结束时间 */
+    EndTime: string;
+    /** 依次为当前套餐的上个、上上个历史周期（开始时间不早于下单时间，可能不足两个周期） */
+    HistoryTime?: CircleTime[];
+    /** 套餐当前是否过期 */
+    Expired?: boolean;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 平台版每日资源点消耗数据
+ */
+export interface PlatformCreditsUsageDaily {
+    /** 日期 */
+    Date?: string;
+    /** 资源点套餐内用量 */
+    DeductValue?: number;
+    /** 资源点资源包用量 */
+    PackageDeductValue?: number;
+    /** 资源点按量用量 */
+    ReportValue?: number;
+    /** 资源点原价消耗 */
+    OriginCredits?: number;
+}
+/**
+ * DescribePlatformCreditsUsage 请求参数
+ */
+export interface DescribePlatformCreditsUsageParams {
+    /** 开始日期，格式 'YYYY-MM-DD' */
+    StartDate: string;
+    /** 结束日期，格式 'YYYY-MM-DD' */
+    EndDate: string;
+    /** 平台版资源id */
+    PlatformId: string;
+}
+/**
+ * DescribePlatformCreditsUsage 返回结果
+ */
+export interface DescribePlatformCreditsUsageRes {
+    /** 资源点套餐内抵扣总量 */
+    DeductValueCount?: number;
+    /** 资源点资源包抵扣总量 */
+    PackageDeductValueCount?: number;
+    /** 资源点按量上报总量 */
+    ReportValueCount?: number;
+    /** 资源点原价消耗总量 */
+    OriginCreditsCount?: number;
+    /** 每日资源点用量列表 */
+    DailyList?: PlatformCreditsUsageDaily[];
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 模块内平台版资源点用量及原始用量数据
+ */
+export interface PlatformPkgCreditsUsage {
+    /** 平台版资源id */
+    PlatformId?: string;
+    /** 模块 */
+    Module?: string;
+    /** module 总资源点用量 */
+    CreditsValue?: number;
+    /** 指标用量明细 */
+    MetricUsageDetail?: MetricUsage[];
+    /** 资源点套餐内用量 */
+    DeductValue?: number;
+    /** 资源点资源包用量 */
+    PackageDeductValue?: number;
+    /** 资源点按量用量 */
+    ReportValue?: number;
+    /** 资源点原价消耗 */
+    OriginCredits?: number;
+}
+/**
+ * DescribePlatformCreditsUsageDetail 请求参数
+ */
+export interface DescribePlatformCreditsUsageDetailParams {
+    /** 模块列表。枚举值：
+     * FLEXDB 文档数据库 / TDSQL MYSQL数据库 / SCF 云函数 / AI 大模型 / EKS 云托管 /
+     * COS 云存储 / HOSTING 静态托管 / Auth 用户权限 / APIInvocation API调用 /
+     * HTTPInvocation HTTP调用 / VM 主机 / Workflow 工作流 / Other 其他 /
+     * PostgreSQL PostgreSQL / Token Token */
+    Modules: string[];
+    /** 开始日期，格式 'YYYY-MM-DD' */
+    StartDate: string;
+    /** 结束日期，格式 'YYYY-MM-DD' */
+    EndDate: string;
+    /** 是否需要每日用量明细 */
+    NeedUsageDetails: boolean;
+    /** 平台版资源id */
+    PlatformId: string;
+}
+/**
+ * DescribePlatformCreditsUsageDetail 返回结果
+ */
+export interface DescribePlatformCreditsUsageDetailRes {
+    /** 用量数据 */
+    Usages: PlatformPkgCreditsUsage[];
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 每日用量详情
+ */
+export interface DailyUsageList {
+    /** 资源点用量 */
+    Credits?: number;
+    /** 资源点用量日期，格式 'YYYY-MM-DD' */
+    Date?: string;
+    /** 原始资源用量 */
+    UsageValue?: number;
+}
+/**
+ * 平台版指标用量信息
+ */
+export interface PlatformMetricUsageItem {
+    /** 指标名称 */
+    MetricName?: string;
+    /** 原始资源类型。如 COS：对象存储 */
+    OriginalResourceType?: string;
+    /** 原始指标名 */
+    OriginalMetricName?: string;
+    /** 资源用量 */
+    UsageValue?: number;
+    /** 资源用量单位，如 MB、Count */
+    UsageUnit?: string;
+    /** 资源点 */
+    Credits?: number;
+    /** 用量按日明细列表 */
+    DailyUsageList?: DailyUsageList[];
+}
+/**
+ * 平台版资源用量信息
+ */
+export interface PlatformResUsageItem {
+    /** 资源类型。Storage：云存储 / Function：云函数 / Database：数据库 / HOSTING：静态托管 /
+     * Log：日志 / Gateway：网关 / Cloudrun：云托管 / Token：Token / EO：EdgeOne */
+    ResourceType?: string;
+    /** 该资源类型的资源点总量 */
+    TotalCredits?: number;
+    /** 指标用量信息 */
+    Metrics?: PlatformMetricUsageItem[];
+}
+/**
+ * DescribePlatformEnvUsage 请求参数
+ */
+export interface DescribePlatformEnvUsageParams {
+    /** 环境ID（可选，不传则自动使用当前环境 ID） */
+    EnvId?: string;
+    /** 查询用量起始时间，格式 'YYYY-MM-DD' */
+    StartDate?: string;
+    /** 查询用量结束时间，格式 'YYYY-MM-DD' */
+    EndDate?: string;
+    /** 资源类型。Storage：云存储 / Function：云函数 / Database：数据库 / HOSTING：静态托管 /
+     * Log：日志 / Gateway：网关 / Cloudrun：云托管 / Token：Token / EO：EdgeOne */
+    ResourceTypes?: string[];
+    /** 是否展示用量明细 */
+    NeedUsageDetails?: boolean;
+}
+/**
+ * DescribePlatformEnvUsage 返回结果
+ */
+export interface DescribePlatformEnvUsageRes {
+    /** 资源用量信息 */
+    Resources?: PlatformResUsageItem[];
+    /** 资源点总量 */
+    TotalCredits?: number;
+    /** 资源点取整倍数 */
+    CreditsScale?: number;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * 环境资源点排行项
+ */
+export interface EnvCreditsRank {
+    /** 环境id */
+    EnvId?: string;
+    /** 总资源点用量 */
+    TotalCredits?: number;
+    /** 资源点从上往下排行序号 */
+    Rank?: number;
+}
+/**
+ * DescribePlatformEnvCreditsRanking 请求参数
+ */
+export interface DescribePlatformEnvCreditsRankingParams {
+    /** 平台版资源id */
+    PlatformId?: string;
+    /** 查询时间范围。Today：近1天 / Recent7Days：近7天 / CurrentCycle：当前计费周期 /
+     * PreviousCycle：上一个计费周期 / Previous2Cycle：上两个计费周期。默认 Today */
+    TimeRange?: string;
+    /** 每页条数，默认 50 */
+    PageSize?: number;
+    /** 分页 offset */
+    AfterRank?: number;
+}
+/**
+ * DescribePlatformEnvCreditsRanking 返回结果
+ */
+export interface DescribePlatformEnvCreditsRankingRes {
+    /** 查询时间范围。Recent7Days：近7天 / Recent30Days：近30天 / CurrentCycle：当前计费周期 /
+     * PreviousCycle：上一个计费周期 / Previous2Cycle：上两个计费周期 */
+    TimeRange?: string;
+    /** 起始时间，格式 'YYYY-MM-DD HH:mm:ss' */
+    StartTime?: string;
+    /** 结束时间，格式 'YYYY-MM-DD HH:mm:ss' */
+    EndTime?: string;
+    /** 统计的截止时间，格式 'YYYY-MM-DD HH:mm:ss' */
+    DataAsOfTime?: string;
+    /** 是否还有下一页数据 */
+    HasMore?: boolean;
+    /** 下一条数据的 offset 值 */
+    NextAfterRank?: number;
+    /** 总数量 */
+    TotalCount?: number;
+    /** 资源点精度 */
+    CreditsScale?: number;
+    /** 排行快照版本 */
+    SnapshotId?: string;
+    /** 环境排行列表 */
+    Items?: EnvCreditsRank[];
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * DestroyPlatformEnv 请求参数
+ */
+export interface DestroyPlatformEnvParams {
+    /** 环境id */
+    EnvId: string;
+}
+/**
+ * DestroyPlatformEnv 返回结果
+ */
+export interface DestroyPlatformEnvRes {
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * CreatePlatformEnv 请求参数
+ */
+export interface CreatePlatformEnvParams {
+    /** 环境别名 */
+    Alias: string;
+    /** 套餐池标识 */
+    PlatformId: string;
+    /** 幂等键 */
+    ReqKey: string;
+}
+/**
+ * CreatePlatformEnv 返回结果
+ */
+export interface CreatePlatformEnvRes {
+    /** 环境id */
+    EnvId?: string;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * ModifyPlatformHTTPServiceRoute 请求参数
+ */
+export interface ModifyPlatformHTTPServiceRouteParams {
+    /** 平台id */
+    PlatformId: string;
+    /** 域名路由信息（增量修改，对应字段不传则不修改） */
+    Domain: HTTPServiceDomainParam;
+}
+/**
+ * ModifyPlatformHTTPServiceRoute 返回结果
+ */
+export interface ModifyPlatformHTTPServiceRouteRes {
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * CreatePlatformHTTPServiceRoute 请求参数
+ */
+export interface CreatePlatformHTTPServiceRouteParams {
+    /** 平台id */
+    PlatformId: string;
+    /** 域名路由信息。不传 Domain.Routes 时仅创建域名信息 */
+    Domain: HTTPServiceDomainParam;
+}
+/**
+ * CreatePlatformHTTPServiceRoute 返回结果
+ */
+export interface CreatePlatformHTTPServiceRouteRes {
+    /** 归属权校验不通过时返回的验证指引，按指引配置 DNS 或文件验证后，
+     * 可调用 verifyPlatformHttpServiceRoute 验证归属权是否通过 */
+    OwnershipVerification?: OwnershipVerificationInfo;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * VerifyPlatformHTTPServiceRoute 请求参数
+ */
+export interface VerifyPlatformHTTPServiceRouteParams {
+    /** 平台id */
+    PlatformId: string;
+    /** 域名路由信息 */
+    Domain: HTTPServiceDomainParam;
+}
+/**
+ * VerifyPlatformHTTPServiceRoute 返回结果
+ */
+export interface VerifyPlatformHTTPServiceRouteRes {
+    /** 前置校验总开关。所有启用的检查项均为 PASS 或 SKIPPED 时为 true，
+     * 任一检查项为 FAIL 时为 false */
+    Passed?: boolean;
+    /** 域名归属权校验结果 */
+    Ownership?: VerifyHttpServiceRouteCheckItem;
+    /** 证书校验结果；CertId 为空时 Status=SKIPPED */
+    Cert?: VerifyHttpServiceRouteCheckItem;
+    /** 域名/路径数量配额校验结果 */
+    Quota?: VerifyHttpServiceRouteCheckItem;
+    /** 同域名下路由路径冲突校验结果 */
+    RouteConflict?: VerifyHttpServiceRouteCheckItem;
+    /** 域名被其他环境占用校验结果 */
+    DomainConflict?: VerifyHttpServiceRouteCheckItem;
+    /** 内部域名且非内部账号校验结果 */
+    InternalAccount?: VerifyHttpServiceRouteCheckItem;
+    /** 域名黑名单校验结果 */
+    Blacklist?: VerifyHttpServiceRouteCheckItem;
+    /** AccessType=CDN 时 CDN 资源存在性/状态校验结果（含 ICP 未备案提示） */
+    CDNResource?: VerifyHttpServiceRouteCheckItem;
+    /** AccessType=EO 时的 EdgeOne 预检结果（域名冲突/备案/归属权） */
+    EO?: VerifyHttpServiceRouteCheckItem;
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * DeletePlatformHTTPServiceRoute 请求参数
+ */
+export interface DeletePlatformHTTPServiceRouteParams {
+    /** 平台id */
+    PlatformId: string;
+    /** 域名 */
+    Domain: string;
+    /** 路径列表。为空则表示删除此域名及所有路由；不为空则仅删除对应的 path 路由 */
+    Paths?: string[];
+}
+/**
+ * DeletePlatformHTTPServiceRoute 返回结果
+ */
+export interface DeletePlatformHTTPServiceRouteRes {
+    /** 唯一请求 ID */
+    RequestId: string;
+}
+/**
+ * DescribePlatformHTTPServiceRoute 请求参数
+ */
+export interface DescribePlatformHTTPServiceRouteParams {
+    /** 平台id */
+    PlatformId: string;
+    /** 过滤条件。可过滤: Domain、Path、DomainType、UpstreamResourceType。
+     * 过滤条件数量限制为 10，Values 单条不超过 100 */
+    Filters?: HTTPServiceRouteFilter[];
+    /** 分页偏移量，默认 0 */
+    Offset?: number;
+    /** 分页限制，默认 20，最大值 1000 */
+    Limit?: number;
+}
+/**
+ * DescribePlatformHTTPServiceRoute 返回结果
+ */
+export interface DescribePlatformHTTPServiceRouteRes {
+    /** 域名路由信息列表 */
+    Domains?: HTTPServiceDomain[];
+    /** 自定义接入的源站域名（HTTPService接入层域名） */
+    OriginDomain: string;
+    /** 域名总数，分页查询使用总数判断是否已经拉取到所有数据 */
+    TotalCount: number;
+    /** 唯一请求 ID */
+    RequestId: string;
+}

package/types/storage/index.d.ts

@@ -1,5 +1,6 @@
 import { Environment } from '../environment';
 import { IUploadMetadata, IListFileInfo, IFileInfo, ITempUrlInfo, IResponseInfo } from '../interfaces';
+import { IStorageConfig } from '../utils/storage-config';
 import { IUploadObjectHttpOptions, IUploadObjectHttpResult, IDeleteObjectHttpOptions, IDeleteObjectHttpResult, IDeleteObjectsHttpOptions, IDeletedObjectInfo, ICopyObjectHttpOptions, ICopyObjectHttpResult, IMoveObjectHttpOptions, IMoveObjectHttpResult, IListObjectsHttpOptions, IListObjectsHttpResult, ISignObjectHttpOptions, ISignObjectHttpResult, ISignObjectsHttpOptions, ISignObjectsHttpResult, ISignUploadObjectHttpOptions, ISignUploadObjectHttpResult, IUploadObjectBySignHttpOptions, IUploadObjectBySignHttpResult, IDownloadAuthenticatedObjectHttpOptions, IDownloadObjectHttpOptions, IDownloadPublicObjectHttpOptions, IDownloadObjectBySignHttpOptions, IDownloadObjectHttpResult, IGetObjectInfoAuthenticatedHttpOptions, IGetObjectInfoPublicHttpOptions, IGetObjectInfoHttpResult, IConsistentUploadOptions, IConsistentUploadResult, ILocalManifestItem, IManifestDiffResult, IManifestVerifyResult, IPruneResult, IRemoteManifestItem } from './type';
 export interface IProgressData {
     loaded: number;
@@ -34,12 +35,19 @@ export interface IFilesOptions extends IOptions {
 export interface ICustomOptions {
     bucket: string;
     region: string;
+    /**
+     * 共享桶（ExternalStorage）内的目录前缀。*Custom 方法不会自动读取环境的 BasePath，
+     * 未传时按 COS 原始 Key 处理；传入后入参按逻辑路径处理，返回的 Key 映射回逻辑路径
+     */
+    basePath?: string;
 }
 export interface IWalkCloudDirOptions {
     prefix: string;
     bucket: string;
     region: string;
     marker?: string;
+    /** 同 ICustomOptions.basePath */
+    basePath?: string;
 }
 export interface IGetRemoteManifestOptions extends ICustomOptions {
     /** 云端前缀，无前导斜杠（如 'dist'）；空串表示整桶 */
@@ -104,6 +112,8 @@ export interface IGetBucketOpions {
     prefix?: string;
     marker?: string;
     maxKeys?: number;
+    /** 同 ICustomOptions.basePath：传入后 prefix / marker 按逻辑路径处理，返回的 Contents.Key、NextMarker 映射回逻辑路径 */
+    basePath?: string;
 }
 export type AclType = 'READONLY' | 'PRIVATE' | 'ADMINWRITE' | 'ADMINONLY' | 'CUSTOM';
 export interface IStorageAclRule {
@@ -191,6 +201,22 @@ export interface ISearchResult {
 type OnProgress = (progressData: IProgressData) => void;
 type OnFileFinish = (error: Error, res: any, fileData: any) => void;
 export { md5File } from './helper';
+export interface IBatchDeleteFailure {
+    fileId: string;
+    cloudPath: string | undefined;
+    code: string;
+}
+/**
+ * 整理 storage.batchDeleteFile 的逐文件删除结果，取出失败项并回填对应的 cloudPath
+ *
+ * 该接口逐文件返回 code，未失败的文件已经删除成功。把结果汇总成一条错误消息会丢掉逐项信息，
+ * 调用方无法区分「删掉了哪些」和「哪些本来就不存在」，因此保留结构化失败列表。
+ * 接口未保证 delete_list 与入参同序，这里按 fileID 反查。
+ */
+export declare function collectBatchDeleteFailures(deleteList: {
+    fileID: string;
+    code: string;
+}[], fileIdList: string[], cloudPathList: string[]): IBatchDeleteFailure[];
 export declare class StorageService {
     private environment;
     private tcbService;
@@ -202,6 +228,7 @@ export declare class StorageService {
     getRemoteManifest(prefix: string): Promise<IRemoteManifestItem[]>;
     /**
      * 获取远端 manifest，支持自定义 Bucket 和 Region。prefix 规则同 getRemoteManifest。
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      */
     getRemoteManifestCustom(options: IGetRemoteManifestOptions): Promise<IRemoteManifestItem[]>;
     /**
@@ -291,6 +318,7 @@ export declare class StorageService {
     uploadFiles(options: IFilesOptions): Promise<void>;
     /**
      * 上传文件，支持自定义 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；fileId 始终按逻辑路径 cloudPath 获取
      * @param {string} localPath
      * @param {string} cloudPath
      * @param {string} bucket
@@ -311,6 +339,7 @@ export declare class StorageService {
     uploadDirectory(options: IFileOptions): Promise<void>;
     /**
      * 上传文件夹，支持自定义 Region 和 Bucket
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      * @param {string} localPath
      * @param {string} cloudPath
      * @param {number} parallel
@@ -348,6 +377,7 @@ export declare class StorageService {
     createCloudDirectroy(cloudPath: string): Promise<void>;
     /**
      * 创建一个空的文件夹，支持自定义 Region 和 Bucket
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath
      * @param {string} cloudPath
      * @param {string} bucket
      * @param {string} region
@@ -400,6 +430,7 @@ export declare class StorageService {
     deleteFile(cloudPathList: string[]): Promise<void>;
     /**
      * 删除文件，可以指定 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，cloudPathList 按 COS 原始 Key 处理
      * @param {string[]} cloudPathList
      * @param {string} bucket
      * @param {string} region
@@ -425,6 +456,7 @@ export declare class StorageService {
     }>;
     /**
      * 删除文件，可以指定 bucket 和 region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；返回的 Key 为逻辑路径
      * @param {string} cloudPath
      * @param {string} bucket
      * @param {string} region
@@ -497,6 +529,7 @@ export declare class StorageService {
     walkCloudDir(prefix: string, marker?: string): Promise<IListFileInfo[]>;
     /**
      * 遍历云端文件夹，支持自定义 Bucket 和 Region
+     * 不会自动拼接环境的共享桶 BasePath，需要时显式传入 basePath；传入后返回的 Key 为逻辑路径
      * @param {string} prefix
      * @param {string} [marker]
      * @param {string} bucket
@@ -686,9 +719,10 @@ export declare class StorageService {
      */
     private cloudPathToFileId;
     /**
-     * 获取存储桶配置
+     * 获取存储桶配置，兼容共享桶（ExternalStorage）环境
+     * basePath 为共享桶内的目录前缀，普通环境为空串
      */
-    private getStorageConfig;
+    getStorageConfig(): IStorageConfig;
     /**
      * 带重试功能的上传多文件函数
      * @param uploadFiles sdk上传函数

package/types/storage/type.d.ts

@@ -377,6 +377,8 @@ export interface IConsistentUploadOptions {
      * 未指定时默认识别所有层级下的 index.html。
      */
     entries?: string[];
+    /** 共享桶（ExternalStorage）内的目录前缀，未传时按 COS 原始 Key 处理 */
+    basePath?: string;
 }
 /** 远端多余文件清理结果 */
 export interface IPruneResult {

package/types/utils/storage-config.d.ts

@@ -0,0 +1,41 @@
+import { EnvInfo, ExternalStorage } from '../interfaces';
+export interface IStorageConfig {
+    env: string;
+    region: string;
+    bucket: string;
+    basePath: string;
+}
+/**
+ * 逻辑路径 → COS 物理 Key：共享桶环境拼上 basePath 前缀，basePath 为空时原样返回
+ * cloudPath 为空或为 '/' 时返回 `${basePath}/`，即共享桶内本环境的根目录
+ */
+export declare function toPhysicalKey(basePath: string, cloudPath?: string): string;
+/**
+ * COS 物理 Key → 逻辑路径：去掉 basePath 前缀，basePath 为空或 Key 不在前缀下时原样返回
+ */
+export declare function toLogicalPath(basePath: string, key: string): string;
+/**
+ * 解析环境的有效云存储配置
+ * 共享桶环境（Storages[0].ExternalStorage.Enabled 为 true）下，BasePath 从 ExternalStorage 读取，桶名、地域在顶层为空时回退到 ExternalStorage；
+ * 普通环境保持读取 Storages[0].Bucket / Region，basePath 为空串
+ */
+export declare function resolveStorageConfig(envConfig: EnvInfo): IStorageConfig;
+/**
+ * 按共享桶规则解析有效桶，云存储（Storages）与静态托管（DescribeStaticStore）共用
+ *
+ * 是否共享桶只看 ExternalStorage.Enabled，不看顶层 Bucket 是否为空：
+ * 目前线上共享桶环境的顶层 Bucket 均返回空串，但接口定义并未保证这一点，
+ * 若后端回填桶名而 basePath 仍按「Bucket 为空」判定，文件会静默写到桶根目录，
+ * 造成同一共享桶内跨环境污染。因此 basePath 只由 Enabled + BasePath 决定，
+ * 桶名则优先用顶层 Bucket，为空时回退到 ExternalStorage.BucketName。
+ */
+export declare function resolveBucketConfig(options: {
+    envId: string;
+    bucket: string;
+    region: string;
+    externalStorage?: ExternalStorage;
+}): {
+    bucket: string;
+    region: string;
+    basePath: string;
+};