@cloudbase/manager-node 5.8.0-beta.2 → 5.8.1

package/types/env/type.d.ts

@@ -14,6 +14,169 @@ export interface CalculatePackageModifyPriceParams {
     envId: string;
     currency?: 'CNY' | 'USD';
 }
+/** 获取 SSL 证书列表请求参数。 */
+export interface DescribeCertificatesParams {
+    /** 分页偏移量，从 0 开始。 */
+    Offset?: number;
+    /** 每页数量，范围为 1 至 1000。 */
+    Limit?: number;
+    /** 模糊匹配证书 ID、备注名称或证书域名。 */
+    SearchKey?: string;
+    /** 证书类型：CA 为客户端证书，SVR 为服务器证书。 */
+    CertificateType?: 'CA' | 'SVR';
+    /** 项目 ID。 */
+    ProjectId?: number;
+    /** 按证书到期时间排序。 */
+    ExpirationSort?: 'ASC' | 'DESC';
+    /** 证书状态筛选。 */
+    CertificateStatus?: number[];
+    /** 是否仅返回可部署证书：1 是，0 否。 */
+    Deployable?: 0 | 1;
+    /** 是否仅返回上传托管证书：1 是，0 否。 */
+    Upload?: 0 | 1;
+    /** 是否仅返回可续期证书：1 是，0 否。 */
+    Renew?: 0 | 1;
+    /** 来源筛选。 */
+    FilterSource?: 'upload' | 'buy';
+    /** 是否仅返回国密证书：1 是，0 否。 */
+    IsSM?: 0 | 1;
+    /** 是否仅返回即将过期证书：1 是，0 否。 */
+    FilterExpiring?: 0 | 1;
+    /** 是否仅返回可托管证书：1 是，0 否。 */
+    Hostable?: 0 | 1;
+    /** 标签筛选条件。 */
+    Tags?: Array<{
+        TagKey: string;
+        TagValue?: string;
+    }>;
+    /** 是否仅返回等待签发证书：1 是，0 否。 */
+    IsPendingIssue?: 0 | 1;
+    /** 指定证书 ID 列表。 */
+    CertIds?: string[];
+    /** 订阅服务 ID。 */
+    ServiceId?: string;
+}
+/** Certificates.CertificateExtra：证书扩展信息。 */
+export interface CertificateExtra {
+    DomainNumber: string;
+    OriginCertificateId: string | null;
+    ReplacedBy: string | null;
+    ReplacedFor: string | null;
+    RenewOrder: string | null;
+    SMCert: number;
+    CompanyType: number;
+    ServiceRenewCertificateId: string;
+    ServiceOriginCertificateId: string;
+}
+/** Certificates.ProjectInfo：项目信息。 */
+export interface ProjectInfo {
+    ProjectName: string;
+    ProjectCreatorUin: number;
+    ProjectCreateTime: string;
+    ProjectResume: string;
+    OwnerUin: number;
+    ProjectId: string;
+}
+/** Certificates.PreAuditInfo：证书预审核信息。 */
+export interface PreAuditInfo {
+    TotalPeriod: number;
+    NowPeriod: number;
+    ManagerId: string;
+}
+/** Certificates.HostingConfig：托管配置。 */
+export interface HostingConfig {
+    ReplaceTime?: number;
+    MessageTypes?: number[];
+    ReplaceStartTime?: string;
+    ReplaceEndTime?: string;
+}
+/** Certificates.SupportDownloadType：支持下载的服务器格式。 */
+export interface SupportDownloadType {
+    NGINX: boolean;
+    APACHE: boolean;
+    TOMCAT: boolean;
+    IIS: boolean;
+    JKS: boolean;
+    OTHER: boolean;
+    ROOT: boolean;
+}
+/** Certificates.Tags：标签信息。 */
+export interface CertificateTag {
+    TagKey: string;
+    TagValue: string;
+}
+/** SSL 证书列表项，对应 DescribeCertificates 响应中的 Certificates 元素。 */
+export interface Certificates {
+    OwnerUin: string;
+    ProjectId: string;
+    From: string;
+    PackageType: string;
+    CertificateType: 'CA' | 'SVR';
+    ProductZhName: string;
+    Domain: string;
+    Alias: string;
+    Status: number;
+    CertificateExtra: CertificateExtra;
+    VulnerabilityStatus: 'INACTIVE' | 'ACTIVE';
+    StatusMsg: string;
+    VerifyType: 'DNS_AUTO' | 'DNS' | 'FILE' | 'DNS_PROXY' | 'FILE_PROXY';
+    CertBeginTime: string;
+    CertEndTime: string;
+    ValidityPeriod: string;
+    InsertTime: string;
+    CertificateId: string;
+    SubjectAltName: string[];
+    PackageTypeName: string;
+    StatusName: string;
+    IsVip: boolean;
+    IsDv: boolean;
+    IsWildcard: boolean;
+    IsVulnerability: boolean;
+    RenewAble: boolean;
+    ProjectInfo: ProjectInfo;
+    BoundResource: string[];
+    Deployable: boolean;
+    Tags: CertificateTag[];
+    IsIgnore: boolean;
+    IsSM: boolean;
+    EncryptAlgorithm: string;
+    CAEncryptAlgorithms: string[];
+    CAEndTimes: string[];
+    CACommonNames: string[];
+    PreAuditInfo: PreAuditInfo;
+    AutoRenewFlag: number;
+    HostingStatus: number;
+    HostingCompleteTime: string;
+    HostingRenewCertId: string;
+    HasRenewOrder: string;
+    ReplaceOriCertIsDelete: boolean;
+    IsExpiring: boolean;
+    DVAuthDeadline: string;
+    ValidationPassedTime: string;
+    CertSANs: string[];
+    AwaitingValidationMsg: string;
+    AllowDownload: boolean;
+    IsDNSPODResolve: boolean;
+    IsPackage: boolean;
+    KeyPasswordCustomFlag: boolean;
+    SupportDownloadType: SupportDownloadType;
+    CertRevokedTime: string;
+    HostingResourceTypes: string[];
+    HostingConfig: HostingConfig | null;
+    IsHostingUploadRenewCert: boolean;
+    ServiceId: string;
+    ServiceStatus: 'initing' | 'running' | 'expired' | 'refunded' | 'nearExpire';
+    CertServiceBeginTime: string;
+    CertServiceEndTime: string;
+    CertServiceShareEnabled: boolean;
+    CertServiceValidCertificateCount: number;
+}
+/** 获取 SSL 证书列表响应。 */
+export interface DescribeCertificatesRes {
+    TotalCount: number;
+    Certificates: Certificates[];
+    RequestId: string;
+}
 /**
  * 客户端限频配置
  */
@@ -35,18 +198,43 @@ export interface HTTPServicePathRewrite {
     StaticStorePrefix?: string;
     Prefix?: string;
 }
+/**
+ * HTTP 访问服务路由添加 header 配置
+ */
+export interface HTTPServiceHeaderToAdd {
+    Key?: string;
+    Value?: string;
+    Action?: 'APPEND_IF_EXISTS_OR_ADD' | 'ADD_IF_ABSENT' | 'OVERWRITE_IF_EXISTS_OR_ADD' | 'OVERWRITE_IF_EXISTS';
+}
+/**
+ * HTTP 访问服务路由 headers 处理配置
+ */
+export interface HTTPServiceHeadersHandler {
+    RequestHeadersToAdd?: HTTPServiceHeaderToAdd[];
+    RequestHeadersToRemove?: string[];
+    ResponseHeadersToAdd?: HTTPServiceHeaderToAdd[];
+    ResponseHeadersToRemove?: string[];
+}
+/**
+ * HTTP访问服务路由扩展字段
+ */
+export interface HTTPServiceExtension {
+    HeadersHandler?: HTTPServiceHeadersHandler;
+    [key: string]: unknown;
+}
 /**
  * HTTP访问服务路由信息
  */
 export interface HTTPServiceRoute {
     Path: string;
     PathRewrite?: HTTPServicePathRewrite;
-    UpstreamResourceType: 'SCF' | 'CBR' | 'STATIC_STORE' | 'WEB_SCF' | 'LH';
+    UpstreamResourceType: 'SCF' | 'CBR' | 'STATIC_STORE' | 'WEB_SCF' | 'LH' | 'STORAGE';
     UpstreamResourceName: string;
     EnableSafeDomain: boolean;
     EnableAuth: boolean;
     EnablePathTransmission: boolean;
     QPSPolicy?: HTTPServiceRouteQPSPolicy;
+    Extension?: HTTPServiceExtension;
     Enable: boolean;
     CreateTime: string;
     UpdateTime: string;
@@ -57,7 +245,7 @@ export interface HTTPServiceRoute {
 export interface HTTPServiceDomain {
     Domain: string;
     DomainType: 'HTTPSERVICE' | 'CBR' | 'ANYSERVICE' | 'AI_AGENT' | 'VM' | 'INTEGRATION_CALLBACK';
-    AccessType: 'DIRECT' | 'CDN' | 'CUSTOM';
+    AccessType: 'DIRECT' | 'CDN' | 'CUSTOM' | 'EO';
     CertId: string;
     Protocol: 'HTTP_AND_HTTPS' | 'HTTP_TO_HTTPS' | 'HTTPS_TO_HTTP';
     Cname: string;
@@ -66,6 +254,7 @@ export interface HTTPServiceDomain {
     Status: 'PROCESSING' | 'FAIL' | 'SUCCESS';
     DNSStatus: 'OK' | 'INVALID';
     Routes?: HTTPServiceRoute[];
+    Extension?: HTTPServiceExtension;
     CreateTime: string;
     UpdateTime: string;
 }
@@ -99,13 +288,14 @@ export interface DescribeHttpServiceRouteRes {
  */
 export interface HTTPServiceRouteParam {
     Path: string;
-    UpstreamResourceType?: 'SCF' | 'CBR' | 'STATIC_STORE' | 'WEB_SCF' | 'LH';
+    UpstreamResourceType?: 'SCF' | 'CBR' | 'STATIC_STORE' | 'WEB_SCF' | 'LH' | 'STORAGE';
     UpstreamResourceName?: string;
     PathRewrite?: HTTPServicePathRewrite;
     EnableSafeDomain?: boolean;
     EnableAuth?: boolean;
     EnablePathTransmission?: boolean;
     QPSPolicy?: HTTPServiceRouteQPSPolicy;
+    Extension?: HTTPServiceExtension;
     Enable?: boolean;
 }
 /**
@@ -119,6 +309,70 @@ export interface HTTPServiceDomainParam {
     CustomCname?: string;
     Enable?: boolean;
     Routes?: HTTPServiceRouteParam[];
+    Extension?: HTTPServiceExtension;
+}
+/**
+ * 前置校验检查状态
+ */
+export type VerifyHttpServiceRouteCheckStatus = 'PASS' | 'SKIPPED' | 'FAIL';
+/**
+ * 前置校验失败原因
+ */
+export type VerifyHttpServiceRouteCheckCode = 'INTERNAL_CHECK_ERROR' | 'OWNERSHIP_DNS_LOOKUP_FAILED' | 'OWNERSHIP_VERIFY_FAILED' | 'CERT_VERIFY_FAILED' | 'QUOTA_EXCEEDED' | 'ROUTE_CONFLICT' | 'DOMAIN_IN_USE' | 'NON_INTERNAL_ACCOUNT' | 'DOMAIN_IN_BLACKLIST' | 'CDN_RESOURCE_PROCESSING' | 'CDN_RESOURCE_OFFLINE' | 'EO_OWNERSHIP_VERIFY_FAILED' | 'EO_DOMAIN_NOT_ICP' | 'EO_DOMAIN_IN_USE';
+/**
+ * 域名归属权 DNS 验证指引
+ */
+export interface OwnershipVerificationDnsInfo {
+    Subdomain?: string;
+    RecordType?: string;
+    RecordValue?: string;
+}
+/**
+ * 域名归属权文件验证指引
+ */
+export interface OwnershipVerificationFileInfo {
+    Path?: string;
+    Content?: string;
+}
+/**
+ * 域名归属权验证指引
+ */
+export interface OwnershipVerificationInfo {
+    Domain?: string;
+    DnsVerification?: OwnershipVerificationDnsInfo[];
+    FileVerification?: OwnershipVerificationFileInfo[];
+}
+/**
+ * VerifyHTTPServiceRoute 单项前置校验结果
+ */
+export interface VerifyHttpServiceRouteCheckItem {
+    Status: VerifyHttpServiceRouteCheckStatus;
+    Code?: VerifyHttpServiceRouteCheckCode;
+    Message?: string;
+    OwnershipVerification?: OwnershipVerificationInfo;
+}
+/**
+ * VerifyHTTPServiceRoute 请求参数
+ */
+export interface VerifyHttpServiceRouteParams {
+    EnvId: string;
+    Domain: HTTPServiceDomainParam;
+}
+/**
+ * VerifyHTTPServiceRoute 返回结果
+ */
+export interface VerifyHttpServiceRouteRes {
+    Passed: boolean;
+    Ownership: VerifyHttpServiceRouteCheckItem;
+    Cert: VerifyHttpServiceRouteCheckItem;
+    Quota: VerifyHttpServiceRouteCheckItem;
+    RouteConflict: VerifyHttpServiceRouteCheckItem;
+    DomainConflict: VerifyHttpServiceRouteCheckItem;
+    InternalAccount: VerifyHttpServiceRouteCheckItem;
+    Blacklist: VerifyHttpServiceRouteCheckItem;
+    CDNResource: VerifyHttpServiceRouteCheckItem;
+    EO: VerifyHttpServiceRouteCheckItem;
+    RequestId: string;
 }
 /**
  * CreateHTTPServiceRoute 请求参数

package/types/function/index.d.ts

@@ -317,46 +317,46 @@ export declare class FunctionService {
         codeSecret: any;
     }): Promise<IFunctionInfo[]>;
     /**
- * 获取函数日志
- * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
- * @param {{
- *         name: string
- *         offset: number
- *         limit: number
- *         order: string
- *         orderBy: string
- *         startTime: string
- *         endTime: string
- *         requestId: string
- *     }} options
- * @returns {Promise<IFunctionLogRes>}
- */
+     * 获取函数日志
+     * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
+     * @param {{
+     *         name: string
+     *         offset: number
+     *         limit: number
+     *         order: string
+     *         orderBy: string
+     *         startTime: string
+     *         endTime: string
+     *         requestId: string
+     *     }} options
+     * @returns {Promise<IFunctionLogRes>}
+     */
     getFunctionLogs(_options: IFunctionLogOptions): Promise<IFunctionLogRes>;
     /**
-    * 获取函数日志 ID 列表
-    * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
-    * @param {{
-    *         name: string
-    *         offset: number
-    *         limit: number
-    *         startTime: string
-    *         endTime: string
-    *         requestId: string
-    *         qualifier: string
-    *     }} options
-    * @returns {Promise<IFunctionLogResV2>}
-    */
+     * 获取函数日志 ID 列表
+     * @deprecated 底层 GetFunctionLogs 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
+     * @param {{
+     *         name: string
+     *         offset: number
+     *         limit: number
+     *         startTime: string
+     *         endTime: string
+     *         requestId: string
+     *         qualifier: string
+     *     }} options
+     * @returns {Promise<IFunctionLogResV2>}
+     */
     getFunctionLogsV2(_options: IFunctionLogOptionsV2): Promise<IFunctionLogResV2>;
     /**
- * 根据函数日志 ID 查询日志详情
- * @deprecated 底层 GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
- * @param {{
-    *         startTime: string
-    *         endTime: string
-    *         logRequestId: string
-    *     }} options
-    * @returns {Promise<IFunctionLogDetailRes>}
-    */
+     * 根据函数日志 ID 查询日志详情
+     * @deprecated 底层 GetFunctionLogDetail 接口已下线，请使用 env.getLogService().searchClsLog() 查询云函数日志
+     * @param {{
+     *         startTime: string
+     *         endTime: string
+     *         logRequestId: string
+     *     }} options
+     * @returns {Promise<IFunctionLogDetailRes>}
+     */
     getFunctionLogDetail(_options: IFunctionLogDetailOptions): Promise<IFunctionLogDetailRes>;
     /**
      * 获取函数的完整调用日志

package/types/hosting/index.d.ts

@@ -11,6 +11,7 @@ export type OnFileFinish = (error: Error, res: any, fileData: any) => void;
 export interface IHostingFileOptions {
     localPath: string;
     cloudPath?: string;
+    entryFiles?: string[];
     parallel?: number;
     files?: {
         localPath: string;
@@ -21,10 +22,14 @@ export interface IHostingFileOptions {
     ignore?: string | string[];
     retryCount?: number;
     retryInterval?: number;
+    verify?: boolean;
+    safe?: boolean;
+    prune?: boolean;
 }
 export interface IHostingFilesOptions {
     localPath?: string;
     cloudPath?: string;
+    entryFiles?: string[];
     parallel?: number;
     files: {
         localPath: string;
@@ -35,6 +40,9 @@ export interface IHostingFilesOptions {
     ignore?: string | string[];
     retryCount?: number;
     retryInterval?: number;
+    verify?: boolean;
+    safe?: boolean;
+    prune?: boolean;
 }
 export type IHostingOptions = IHostingFileOptions | IHostingFilesOptions;
 export interface IHostingCloudOptions {

package/types/storage/helper.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 流式计算文件 MD5（32 位小写十六进制），不将整个文件读入内存
+ */
+export declare function md5File(filePath: string): Promise<string>;
+/**
+ * 将目录上传文件拆分为资源组和入口组，确保入口文件最后上传
+ */
+export declare function splitEntryUploadFiles(files: Array<{
+    localPath: string;
+    cloudPath: string;
+}>, entryFiles?: string[]): {
+    resourceFiles: Array<{
+        localPath: string;
+        cloudPath: string;
+    }>;
+    entryUploadFiles: Array<{
+        localPath: string;
+        cloudPath: string;
+    }>;
+};

package/types/storage/index.d.ts

@@ -1,6 +1,6 @@
 import { Environment } from '../environment';
 import { IUploadMetadata, IListFileInfo, IFileInfo, ITempUrlInfo, IResponseInfo } from '../interfaces';
-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 } from './type';
+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;
     total: number;
@@ -17,6 +17,7 @@ export interface IOptions {
 export interface IFileOptions extends IOptions {
     localPath: string;
     cloudPath?: string;
+    entryFiles?: string[];
     parallel?: number;
     retryCount?: number;
     retryInterval?: number;
@@ -40,6 +41,44 @@ export interface IWalkCloudDirOptions {
     region: string;
     marker?: string;
 }
+export interface IGetRemoteManifestOptions extends ICustomOptions {
+    /** 云端前缀，无前导斜杠（如 'dist'）；空串表示整桶 */
+    prefix: string;
+    /** 列举起始 Marker；默认 '/' 会排除 . 开头的 Key，列举备份目录时需传 '' */
+    marker?: string;
+}
+/** 一致性发布：远端备份选项 */
+export interface IBackupRemoteOptions extends IGetRemoteManifestOptions {
+    /** 备份目标前缀，须以 .cloudbase-backup/ 开头，如 .cloudbase-backup/1724073600000/ */
+    backupPrefix: string;
+    /** 复制并发数，默认 20 */
+    parallel?: number;
+}
+/** 一致性发布：从备份恢复选项 */
+export interface IRestoreFromBackupOptions extends ICustomOptions {
+    /** 备份前缀，与 backupRemote 所传一致 */
+    backupPrefix: string;
+    /** 待恢复的覆盖文件 Key（相对桶根），来自 diffManifest().overwritten */
+    overwrittenKeys: string[];
+    /** 待删除的新增文件 Key（相对桶根），来自 diffManifest().added */
+    addedKeys: string[];
+    /** 恢复复制并发数，默认 20 */
+    parallel?: number;
+}
+/** 一致性发布：清理备份选项 */
+export interface ICleanupBackupOptions extends ICustomOptions {
+    /** 需要清理的备份前缀，与 backupRemote 所传一致 */
+    backupPrefix: string;
+}
+/** 一致性发布：远端冗余文件清理选项 */
+export interface IPruneRemoteOptions extends ICustomOptions {
+    /** 限定清理范围的前缀，无前导斜杠；空串表示根目录 */
+    prefix: string;
+    /** 待删除 Key（相对桶根），来自 diffManifest().removed；越界与备份 Key 会被自动过滤 */
+    removedKeys: string[];
+    /** 删除并发数，默认 20 */
+    parallel?: number;
+}
 export interface IRoutingRules {
     keyPrefixEquals?: string;
     httpErrorCodeReturnedEquals?: string;
@@ -151,10 +190,92 @@ export interface ISearchResult {
 }
 type OnProgress = (progressData: IProgressData) => void;
 type OnFileFinish = (error: Error, res: any, fileData: any) => void;
+export { md5File } from './helper';
 export declare class StorageService {
     private environment;
     private tcbService;
     constructor(environment: Environment);
+    /**
+     * 获取远端 manifest（默认 Storage 桶）：返回指定前缀下文件的 key / etag / size，
+     * 过滤目录占位对象。prefix 无前导斜杠，空串表示整桶（Hosting 桶请用 getRemoteManifestCustom）。
+     */
+    getRemoteManifest(prefix: string): Promise<IRemoteManifestItem[]>;
+    /**
+     * 获取远端 manifest，支持自定义 Bucket 和 Region。prefix 规则同 getRemoteManifest。
+     */
+    getRemoteManifestCustom(options: IGetRemoteManifestOptions): Promise<IRemoteManifestItem[]>;
+    /**
+     * 生成本地 manifest：计算每个文件的云端 Key、MD5 与 Size。
+     * - filePaths 须来自 walkLocalDir(localPath)，目录不计入
+     * - key = cloudPath + 文件相对路径；cloudPath 为空表示桶根
+     * - MD5 以受控并发计算，避免阻塞事件循环
+     */
+    buildLocalManifest(options: {
+        localPath: string;
+        cloudPath?: string;
+        filePaths: string[];
+        parallel?: number;
+    }): Promise<ILocalManifestItem[]>;
+    /**
+     * 计算本地 manifest 与远端 manifest 的差异：
+     * - added：本地有、远端无；overwritten：两边都有；removed：远端有、本地无
+     * - 两份 manifest 的 key 须基于同一 cloudPath（removed 自动排除 .cloudbase-backup/）
+     */
+    diffManifest(localManifest: ILocalManifestItem[], remoteManifest: IRemoteManifestItem[]): IManifestDiffResult;
+    /**
+     * 校验远端 manifest 与本地 manifest 是否一致：
+     * - 远端缺失 → missing；ETag 为纯 MD5 → 按 md5 比对；分块上传 ETag → 降级按 size 比对
+     */
+    verifyManifest(localManifest: ILocalManifestItem[], remoteManifest: IRemoteManifestItem[]): IManifestVerifyResult;
+    /**
+     * 将指定前缀下的远端文件服务端复制到备份前缀（不产生下载流量）。
+     * 始终跳过 .cloudbase-backup/ 下的历史备份，避免根目录发布时递归备份。
+     */
+    backupRemote(options: IBackupRemoteOptions): Promise<void>;
+    /**
+     * 从备份恢复被覆盖旧文件（服务端复制回原 Key），并删除本次新增文件。
+     * 任一阶段失败都会抛错，由上层决定是否保留备份供人工恢复。
+     */
+    restoreFromBackup(options: IRestoreFromBackupOptions): Promise<void>;
+    /**
+     * 删除备份前缀下的全部对象。
+     * 备份目录以 . 开头，内部使用空 Marker 列举，不受默认排除规则影响。
+     */
+    cleanupBackup(options: ICleanupBackupOptions): Promise<void>;
+    /**
+     * 清理发布后远端残留的冗余文件。
+     * 仅删除 removedKeys 中位于 prefix 范围内的 Key，排除 .cloudbase-backup/；
+     * 单个删除失败记入 failedKeys，不影响其他文件。
+     */
+    pruneRemote(options: IPruneRemoteOptions): Promise<IPruneResult>;
+    /**
+     * 一致性目录上传编排（safe、verify、prune）
+     *
+     * 执行流程（按顺序）：
+     * 1. 扫描本地目录，生成 manifest（key/md5/size）
+     * 2. safe 或 prune 开启时：拉取远端快照 manifest，与本地做 diff
+     *    （safe 用 diff 判定回滚范围；prune 用 diff.removed 判定待清理文件）
+     * 3. safe 开启时：将远端文件服务端复制到备份前缀 .cloudbase-backup/<时间戳>/
+     * 4. 执行目录上传（资源文件先传，入口文件 entries 最后传）
+     * 5. verify 开启时：重新拉取远端 manifest，逐文件校验 ETag/MD5 与 size
+     * 6. 上传与校验全部成功后，prune 开启时：删除 diff.removed 中仍冗余的远端文件
+     * 7. 返回 uploadedKeys / verified / backupPrefix / prune 结果
+     *
+     * 失败时的行为：
+     * - 步骤 4/5 失败且 safe 开启：自动从备份回滚（恢复被覆盖文件、删除本次新增
+     *   文件），回滚成功后抛出“已自动回滚”错误，备份保留供人工核查
+     * - 回滚失败：保留备份并在错误信息中给出备份位置，供人工恢复
+     * - 备份一律不由本编排自动清理，均需调用方确认后通过 cleanupBackup 显式删除
+     * - prune 仅在步骤 4/5 全部成功后执行，失败发布绝不会触发远端删除
+     *
+     * ⚠️ 危险参数：prune
+     * prune 会删除云端 cloudPath 前缀下、本次本地构建中不存在的全部文件。
+     * 若调用方误传了错误的 localPath/cloudPath，整目录都会被判定为“冗余”而删除。
+     * 发布成功后备份默认保留、不自动清理：prune 误删的文件可从备份前缀
+     * （.cloudbase-backup/<时间戳>/）人工恢复；调用方确认无误后应通过
+     * cleanupBackup 显式清理备份。调用方（CLI）仍须在开启 prune 前要求用户二次确认。
+     */
+    uploadDirectoryConsistent(options: IConsistentUploadOptions): Promise<IConsistentUploadResult>;
     /**
      * 上传文件
      * localPath 为文件夹时，会尝试在文件夹中寻找 cloudPath 中的文件名
@@ -311,6 +432,8 @@ export declare class StorageService {
      */
     deleteDirectoryCustom(options: {
         cloudPath: string;
+        /** 列举起始 Marker，默认 '/' 会排除 . 开头的 Key；清理备份目录时需传 '' */
+        marker?: string;
     } & ICustomOptions): Promise<{
         Deleted: {
             Key: string;
@@ -595,4 +718,3 @@ export declare class StorageService {
     private inferMimeByMagicBytes;
     private assertValidContentType;
 }
-export {};