@cloudbase/manager-node 5.8.0 → 5.8.1

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+## @cloudbase/manager-node v5.8.0 版本发布 🚀(2026-08-20)
+
+- 新增 声明式部署编排（hosting 本地构建/gateway 域名绑定/certId 自动查询）
+- 新增 增加 HTTP 服务路由预校验和 SSL 证书查询能力
+- 新增 统一镜像配置校验契约
+- 新增 完善企业版 TCR 云构建链路
+- 新增 补强 Python 部署上下文与检查
+- 新增 validate explicit personal TCR credentials
+- 新增 纳入 database 迁移到声明式编排
+- 重构 降低配置守卫圈复杂度
+- 重构 统一 FunctionDeployer 并迁移镜像部署实现
+- 修复 clarify local default tag
+- 修复 improve cloud build preflight and TCR guidance
+- 修复 移除自动删除重建授权语义
+- 修复 python deploy lint
+- 修复 让云端镜像构建配置真实生效
+- 修复 处理 HTTP 协议规划器 AI 类型安全评审
+- 修复默认 HTTP 协议被误判为需要重建
+- 修复 修正 image 策略 imageType 字段路径导致个人版镜像误判
+- 补充 codeSecret 统一部署契约回归
+
+---
+
 ## @cloudbase/manager-node v5.7.0 版本发布 🚀(2026-08-13)
 
 

package/lib/hosting/index.js

@@ -131,7 +131,7 @@ class HostingService {
      * @param options
      */
     async uploadFiles(options) {
-        const { localPath, cloudPath, files = [], onProgress, onFileFinish, parallel = 20, ignore = ['.DS_Store'], retryCount, retryInterval } = options;
+        const { localPath, cloudPath, entryFiles, files = [], onProgress, onFileFinish, parallel = 20, ignore = ['.DS_Store'], retryCount, retryInterval, verify = false, safe = false, prune = false } = options;
         const hosting = await this.checkStatus();
         const { Bucket, Regoin } = hosting;
         const storageService = await this.environment.getStorageService();
@@ -142,9 +142,29 @@ class HostingService {
             // 检查路径是否存在
             (0, utils_1.checkReadable)(resolvePath, true);
             if ((0, utils_1.isDirectory)(resolvePath)) {
+                if (safe || verify || prune) {
+                    return storageService.uploadDirectoryConsistent({
+                        localPath: resolvePath,
+                        cloudPath,
+                        entries: entryFiles,
+                        bucket: Bucket,
+                        region: Regoin,
+                        onProgress,
+                        onFileFinish,
+                        fileId: false,
+                        ignore,
+                        parallel,
+                        retryCount,
+                        retryInterval,
+                        verify,
+                        safe,
+                        prune
+                    });
+                }
                 return storageService.uploadDirectoryCustom({
                     localPath: resolvePath,
                     cloudPath,
+                    entryFiles,
                     bucket: Bucket,
                     region: Regoin,
                     onProgress,

package/lib/storage/helper.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.md5File = md5File;
+exports.splitEntryUploadFiles = splitEntryUploadFiles;
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+/**
+ * 流式计算文件 MD5（32 位小写十六进制），不将整个文件读入内存
+ */
+function md5File(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto_1.default.createHash('md5');
+        const stream = fs_1.default.createReadStream(filePath);
+        stream.on('data', chunk => hash.update(chunk));
+        stream.on('error', reject);
+        stream.on('end', () => resolve(hash.digest('hex')));
+    });
+}
+/**
+ * 将目录上传文件拆分为资源组和入口组，确保入口文件最后上传
+ */
+function splitEntryUploadFiles(files, entryFiles) {
+    // 是否有自定义入口文件
+    const hasCustomEntryFiles = Array.isArray(entryFiles);
+    // 规范化入口文件路径，去除前导斜线
+    const normalizedEntryFiles = (entryFiles || [])
+        .map(item => String(item || '').trim().replace(/\\/g, '/').replace(/^\/+/, ''))
+        .filter(Boolean);
+    const resourceFiles = [];
+    const entryUploadFiles = [];
+    files.forEach(file => {
+        const normalizedCloudPath = file.cloudPath.replace(/\\/g, '/').replace(/^\/+/, '');
+        // 判断当前文件是否为入口文件
+        const isEntryFile = hasCustomEntryFiles
+            ? normalizedEntryFiles.some(entryFile => normalizedCloudPath === entryFile ||
+                normalizedCloudPath.endsWith(`/${entryFile}`))
+            : path_1.default.posix.basename(normalizedCloudPath) === 'index.html';
+        if (isEntryFile) {
+            entryUploadFiles.push(file);
+            return;
+        }
+        resourceFiles.push(file);
+    });
+    return {
+        resourceFiles,
+        entryUploadFiles
+    };
+}

package/lib/storage/index.js

@@ -10,7 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageService = void 0;
+exports.StorageService = exports.md5File = void 0;
 const fs_1 = __importDefault(require("fs"));
 const util_1 = __importDefault(require("util"));
 const path_1 = __importDefault(require("path"));
@@ -24,12 +24,418 @@ const error_1 = require("../error");
 const parallel_1 = require("../utils/parallel");
 const runenv_1 = require("../utils/runenv");
 const constant_1 = require("../constant");
+const helper_1 = require("./helper");
 const BIG_FILE_SIZE = 5242880; // 5MB 1024*1024*5
+// ===== hosting deploy consistency 相关能力 =====
+/** 默认 MD5 计算并发数 */
+const DEFAULT_MD5_PARALLEL = 20;
+/** 一致性发布备份前缀（用于 diff.removed 排除备份文件） */
+const CONSISTENT_DEPLOY_BACKUP_PREFIX = '.cloudbase-backup/';
+var helper_2 = require("./helper");
+Object.defineProperty(exports, "md5File", { enumerable: true, get: function () { return helper_2.md5File; } });
 class StorageService {
     constructor(environment) {
         this.environment = environment;
         this.tcbService = new utils_1.CloudService(environment.cloudBaseContext, 'tcb', '2018-06-08');
     }
+    // ==================== 一致性发布 相关能力 ====================
+    /**
+     * 获取远端 manifest（默认 Storage 桶）：返回指定前缀下文件的 key / etag / size，
+     * 过滤目录占位对象。prefix 无前导斜杠，空串表示整桶（Hosting 桶请用 getRemoteManifestCustom）。
+     */
+    async getRemoteManifest(prefix) {
+        const { bucket, region } = this.getStorageConfig();
+        return this.getRemoteManifestCustom({
+            prefix,
+            bucket,
+            region
+        });
+    }
+    /**
+     * 获取远端 manifest，支持自定义 Bucket 和 Region。prefix 规则同 getRemoteManifest。
+     */
+    async getRemoteManifestCustom(options) {
+        const fileList = await this.walkCloudDirCustom(options);
+        return fileList
+            .filter(file => file.Key && !file.Key.endsWith('/'))
+            .map(file => ({
+            key: file.Key,
+            etag: String(file.ETag || '').replace(/^"|"$/g, ''),
+            size: Number(file.Size) || 0
+        }));
+    }
+    /**
+     * 生成本地 manifest：计算每个文件的云端 Key、MD5 与 Size。
+     * - filePaths 须来自 walkLocalDir(localPath)，目录不计入
+     * - key = cloudPath + 文件相对路径；cloudPath 为空表示桶根
+     * - MD5 以受控并发计算，避免阻塞事件循环
+     */
+    async buildLocalManifest(options) {
+        const { localPath, cloudPath, filePaths, parallel = DEFAULT_MD5_PARALLEL } = options;
+        const resolvePath = path_1.default.resolve(localPath);
+        const resolveLocalPath = path_1.default.join(resolvePath, path_1.default.sep);
+        const controller = new parallel_1.AsyncTaskParallelController(parallel, 50);
+        controller.loadTasks(filePaths.map(filePath => async () => {
+            const stat = await fs_1.default.promises.stat(filePath);
+            if (stat.isDirectory()) {
+                return null;
+            }
+            const fileKeyPath = filePath.replace(resolveLocalPath, '').replace(/\\/g, '/');
+            const key = path_1.default.join(cloudPath || '', fileKeyPath).replace(/\\/g, '/');
+            return {
+                key,
+                md5: await (0, helper_1.md5File)(filePath),
+                size: stat.size,
+                localPath: filePath
+            };
+        }));
+        const results = await controller.run();
+        const isError = (res) => Object.prototype.toString.call(res) === '[object Error]';
+        const firstError = results.find(isError);
+        if (firstError) {
+            throw new error_1.CloudBaseError(`计算本地文件摘要失败：${firstError.message}`);
+        }
+        return results.filter(res => res !== null);
+    }
+    /**
+     * 计算本地 manifest 与远端 manifest 的差异：
+     * - added：本地有、远端无；overwritten：两边都有；removed：远端有、本地无
+     * - 两份 manifest 的 key 须基于同一 cloudPath（removed 自动排除 .cloudbase-backup/）
+     */
+    diffManifest(localManifest, remoteManifest) {
+        const localKeys = new Set(localManifest.map(item => item.key));
+        const remoteKeys = new Set(remoteManifest.map(item => item.key));
+        const added = [];
+        const overwritten = [];
+        localManifest.forEach(item => {
+            if (remoteKeys.has(item.key)) {
+                overwritten.push(item.key);
+                return;
+            }
+            added.push(item.key);
+        });
+        const removed = remoteManifest
+            .map(item => item.key)
+            .filter(key => !localKeys.has(key) &&
+            !key.replace(/^\/+/, '').startsWith(CONSISTENT_DEPLOY_BACKUP_PREFIX));
+        return {
+            added,
+            overwritten,
+            removed
+        };
+    }
+    /**
+     * 校验远端 manifest 与本地 manifest 是否一致：
+     * - 远端缺失 → missing；ETag 为纯 MD5 → 按 md5 比对；分块上传 ETag → 降级按 size 比对
+     */
+    verifyManifest(localManifest, remoteManifest) {
+        const remoteMap = new Map(remoteManifest.map(item => [item.key, item]));
+        const missing = [];
+        const mismatched = [];
+        const pureMd5EtagRe = /^[a-f0-9]{32}$/i;
+        localManifest.forEach(localItem => {
+            const remoteItem = remoteMap.get(localItem.key);
+            if (!remoteItem) {
+                missing.push(localItem.key);
+                return;
+            }
+            const remoteEtag = String(remoteItem.etag || '').replace(/^"|"$/g, '');
+            const shouldCompareByMd5 = pureMd5EtagRe.test(remoteEtag);
+            if (shouldCompareByMd5) {
+                if (remoteEtag.toLowerCase() !== localItem.md5.toLowerCase()) {
+                    mismatched.push(localItem.key);
+                }
+                return;
+            }
+            if (Number(remoteItem.size) !== Number(localItem.size)) {
+                mismatched.push(localItem.key);
+            }
+        });
+        return {
+            ok: missing.length === 0 && mismatched.length === 0,
+            missing,
+            mismatched
+        };
+    }
+    /**
+     * 将指定前缀下的远端文件服务端复制到备份前缀（不产生下载流量）。
+     * 始终跳过 .cloudbase-backup/ 下的历史备份，避免根目录发布时递归备份。
+     */
+    async backupRemote(options) {
+        const { bucket, region, prefix, backupPrefix, parallel = 20 } = options;
+        // COS 对象 Key 不保留前导斜杠，统一规范化为 .cloudbase-backup/... 形式
+        const normalizedBackupPrefix = backupPrefix.replace(/^\/+/, '').replace(/\/+$/, '');
+        const remoteManifest = await this.getRemoteManifestCustom({
+            bucket,
+            region,
+            prefix
+        });
+        // 过滤掉已备份的文件，避免根目录发布时递归备份旧备份，filesToBackup 存的是需要备份的文件
+        const filesToBackup = remoteManifest.filter(item => !item.key.replace(/^\/+/, '').startsWith(CONSISTENT_DEPLOY_BACKUP_PREFIX));
+        if (!filesToBackup.length) {
+            return;
+        }
+        const cos = this.getCos();
+        const putObjectCopy = util_1.default.promisify(cos.putObjectCopy).bind(cos);
+        const controller = new parallel_1.AsyncTaskParallelController(parallel, 50);
+        controller.loadTasks(
+        // 为每个文件创建一个复制任务
+        filesToBackup.map(file => async () => {
+            const destPath = `${normalizedBackupPrefix}/${file.key.replace(/^\/+/, '')}`;
+            // 拼接复制源
+            const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent(file.key)}`;
+            const res = await putObjectCopy({
+                Bucket: bucket,
+                Region: region,
+                Key: destPath,
+                CopySource: copySource
+            });
+            if (res.statusCode !== 200) {
+                throw new error_1.CloudBaseError(`备份文件失败：${file.key}`);
+            }
+            return destPath;
+        }));
+        const results = await controller.run();
+        const isError = (res) => Object.prototype.toString.call(res) === '[object Error]';
+        const firstError = results.find(isError);
+        if (firstError) {
+            throw new error_1.CloudBaseError(`远端备份失败：${firstError.message}`);
+        }
+    }
+    /**
+     * 从备份恢复被覆盖旧文件（服务端复制回原 Key），并删除本次新增文件。
+     * 任一阶段失败都会抛错，由上层决定是否保留备份供人工恢复。
+     */
+    async restoreFromBackup(options) {
+        const { bucket, region, backupPrefix, overwrittenKeys, addedKeys, parallel = 20 } = options;
+        // COS 对象 Key 不保留前导斜杠，与 backupRemote 的规范化规则保持一致
+        const normalizedBackupPrefix = backupPrefix.replace(/^\/+/, '').replace(/\/+$/, '');
+        if (overwrittenKeys.length > 0) {
+            const cos = this.getCos();
+            const putObjectCopy = util_1.default.promisify(cos.putObjectCopy).bind(cos);
+            const controller = new parallel_1.AsyncTaskParallelController(parallel, 50);
+            controller.loadTasks(overwrittenKeys.map(key => async () => {
+                const sourcePath = `${normalizedBackupPrefix}/${key.replace(/^\/+/, '')}`;
+                const copySource = `${bucket}.cos.${region}.myqcloud.com/${encodeURIComponent(sourcePath)}`;
+                const res = await putObjectCopy({
+                    Bucket: bucket,
+                    Region: region,
+                    Key: key,
+                    CopySource: copySource
+                });
+                if (res.statusCode !== 200) {
+                    throw new error_1.CloudBaseError(`恢复备份文件失败：${key}`);
+                }
+                return key;
+            }));
+            const restoreResults = await controller.run();
+            const isError = (res) => Object.prototype.toString.call(res) === '[object Error]';
+            const firstRestoreError = restoreResults.find(isError);
+            if (firstRestoreError) {
+                throw new error_1.CloudBaseError(`从备份恢复远端文件失败：${firstRestoreError.message}`);
+            }
+        }
+        if (addedKeys.length > 0) {
+            await this.deleteFileCustom(addedKeys, bucket, region);
+        }
+    }
+    /**
+     * 删除备份前缀下的全部对象。
+     * 备份目录以 . 开头，内部使用空 Marker 列举，不受默认排除规则影响。
+     */
+    async cleanupBackup(options) {
+        const { bucket, region, backupPrefix } = options;
+        // 备份目录以 . 开头，会被 walkCloudDirCustom 默认 marker='/' 排除，
+        // 必须显式传 marker='' 才能列举到备份对象
+        await this.deleteDirectoryCustom({
+            cloudPath: backupPrefix,
+            bucket,
+            region,
+            marker: ''
+        });
+    }
+    /**
+     * 清理发布后远端残留的冗余文件。
+     * 仅删除 removedKeys 中位于 prefix 范围内的 Key，排除 .cloudbase-backup/；
+     * 单个删除失败记入 failedKeys，不影响其他文件。
+     */
+    async pruneRemote(options) {
+        const { bucket, region, prefix, removedKeys, parallel = 20 } = options;
+        const normalizedPrefix = prefix.replace(/^\/+/, '').replace(/\/+$/, '');
+        const prefixWithSlash = normalizedPrefix ? `${normalizedPrefix}/` : '';
+        const backupPrefix = CONSISTENT_DEPLOY_BACKUP_PREFIX;
+        const keysToDelete = Array.from(new Set(removedKeys
+            .map(key => String(key || '').replace(/^\/+/, ''))
+            .filter(key => key &&
+            !key.startsWith(backupPrefix) &&
+            (!prefixWithSlash || key.startsWith(prefixWithSlash)) // 限制在 prefix 范围内
+        )));
+        if (!keysToDelete.length) {
+            return { deletedKeys: [], failedKeys: [] };
+        }
+        const cos = this.getCos();
+        const deleteObject = util_1.default.promisify(cos.deleteObject).bind(cos);
+        const controller = new parallel_1.AsyncTaskParallelController(parallel, 50);
+        controller.loadTasks(keysToDelete.map(key => async () => {
+            try {
+                await deleteObject({
+                    Bucket: bucket,
+                    Region: region,
+                    Key: key
+                });
+                return { key };
+            }
+            catch (error) {
+                return {
+                    key,
+                    error: (error === null || error === void 0 ? void 0 : error.message) || String(error)
+                };
+            }
+        }));
+        const results = await controller.run();
+        const deletedKeys = [];
+        const failedKeys = [];
+        results.forEach(result => {
+            if (result && typeof result.error === 'string') {
+                failedKeys.push(result);
+            }
+            else if (result === null || result === void 0 ? void 0 : result.key) {
+                deletedKeys.push(result.key);
+            }
+        });
+        return { deletedKeys, failedKeys };
+    }
+    /**
+     * 一致性目录上传编排（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 前要求用户二次确认。
+     */
+    async uploadDirectoryConsistent(options) {
+        const { localPath, cloudPath = '', bucket, region, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500, onProgress, onFileFinish, verify = false, safe = false, prune = false, entries } = options;
+        const resolvePath = path_1.default.resolve(localPath);
+        const resolveLocalPath = path_1.default.join(resolvePath, path_1.default.sep);
+        const filePaths = await this.walkLocalDir(resolveLocalPath, ignore);
+        // 生成本地 manifest
+        const localManifest = await this.buildLocalManifest({
+            localPath,
+            cloudPath,
+            filePaths,
+            parallel
+        });
+        let backupPrefix;
+        let diff;
+        if (safe || prune) {
+            const remoteSnapshot = await this.getRemoteManifestCustom({
+                bucket,
+                region,
+                prefix: cloudPath
+            });
+            // 发布前快照同时用于 safe 回滚判定和 prune 待删文件判定。
+            diff = this.diffManifest(localManifest, remoteSnapshot);
+        }
+        if (safe) {
+            // COS 对象 Key 不保留前导斜杠，备份前缀使用 .cloudbase-backup/ 形式
+            backupPrefix = `${CONSISTENT_DEPLOY_BACKUP_PREFIX}${Date.now()}/`;
+            // 备份远端
+            await this.backupRemote({
+                bucket,
+                region,
+                prefix: cloudPath,
+                backupPrefix,
+                parallel
+            });
+        }
+        try {
+            await this.uploadDirectoryCustom({
+                localPath,
+                cloudPath,
+                entryFiles: entries,
+                bucket,
+                region,
+                ignore,
+                fileId,
+                parallel,
+                retryCount,
+                retryInterval,
+                onProgress,
+                onFileFinish
+            });
+            // 上传完成后校验
+            if (verify) {
+                const remoteManifest = await this.getRemoteManifestCustom({
+                    bucket,
+                    region,
+                    prefix: cloudPath
+                });
+                const verifyResult = this.verifyManifest(localManifest, remoteManifest);
+                if (!verifyResult.ok) {
+                    throw new error_1.CloudBaseError(`一致性校验失败：missing=${verifyResult.missing.join(',') || '[]'}; mismatched=${verifyResult.mismatched.join(',') || '[]'}`);
+                }
+            }
+        }
+        catch (error) {
+            if (!safe || !backupPrefix || !diff) {
+                throw error;
+            }
+            // 失败时回滚；备份保留供人工核查，由调用方确认后通过 cleanupBackup 显式清理
+            try {
+                await this.restoreFromBackup({
+                    bucket,
+                    region,
+                    backupPrefix,
+                    overwrittenKeys: diff.overwritten,
+                    addedKeys: diff.added,
+                    parallel
+                });
+            }
+            catch (rollbackError) {
+                throw new error_1.CloudBaseError(`一致性发布失败，且回滚失败，请使用备份人工恢复：${backupPrefix}；原始错误：${error.message}；回滚错误：${rollbackError.message}`);
+            }
+            throw new error_1.CloudBaseError(`一致性发布失败，已自动回滚，备份保留于 ${backupPrefix}，确认无误后可调用 cleanupBackup 清理：${error.message}`);
+        }
+        // 上传与可选校验均成功后才允许清理远端冗余文件。
+        // 删除失败会记录在结果中，不触发已经成功发布内容的回滚。
+        const pruneResult = prune
+            ? await this.pruneRemote({
+                bucket,
+                region,
+                prefix: cloudPath,
+                removedKeys: (diff === null || diff === void 0 ? void 0 : diff.removed) || [],
+                parallel
+            })
+            : undefined;
+        // 发布成功后保留备份：prune 若误删文件，仍可从备份前缀人工恢复。
+        // 备份不由本编排自动清理，调用方确认无误后通过 cleanupBackup 显式删除。
+        return {
+            uploadedKeys: localManifest.map(item => item.key),
+            verified: verify,
+            backupPrefix,
+            prune: pruneResult
+        };
+    }
+    // ==============================================================
     /**
      * 上传文件
      * localPath 为文件夹时，会尝试在文件夹中寻找 cloudPath 中的文件名
@@ -178,7 +584,7 @@ class StorageService {
      * @returns {Promise<void>}
      */
     async uploadDirectoryCustom(options) {
-        const { localPath, cloudPath, bucket, region, onProgress, onFileFinish, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
+        const { localPath, cloudPath, entryFiles, bucket, region, onProgress, onFileFinish, ignore, fileId = true, parallel = 20, retryCount = 0, retryInterval = 500 } = options;
         // 此处不检查路径是否存在
         // 绝对路径 /var/blog/xxxx
         const resolvePath = path_1.default.resolve(localPath);
@@ -249,10 +655,26 @@ class StorageService {
             localPath: stats.filePath,
             cloudPath: stats.cloudFileKey
         }));
+        const { resourceFiles, entryUploadFiles } = (0, helper_1.splitEntryUploadFiles)(filesForUpload, entryFiles);
         // 调用 uploadFilesCustom（智能混合模式：并行→串行）
         // 不再直接调用 uploadFilesWithRetry（纯并行重试，容易 socket hang up）
+        // 第一阶段先上传资源文件；这里必须 await，确保入口文件不会与资源文件混传。
+        // 如果资源组上传失败，会直接中断，第二阶段不会开始。
+        await this.uploadFilesCustom({
+            files: resourceFiles,
+            bucket,
+            region,
+            ignore: [],
+            onProgress,
+            onFileFinish,
+            fileId,
+            parallel,
+            retryCount,
+            retryInterval
+        });
+        // 第二阶段再上传入口文件（默认各级 index.html），避免入口文件先于其依赖资源对外可见。
         return this.uploadFilesCustom({
-            files: filesForUpload,
+            files: entryUploadFiles,
             bucket,
             region,
             ignore: [],
@@ -781,7 +1203,7 @@ class StorageService {
      * @returns {Promise<void>}
      */
     async deleteDirectoryCustom(options) {
-        const { cloudPath, bucket, region } = options;
+        const { cloudPath, bucket, region, marker } = options;
         const key = this.getCloudKey(cloudPath);
         const cos = this.getCos();
         const deleteMultipleObject = util_1.default.promisify(cos.deleteMultipleObject).bind(cos);
@@ -789,7 +1211,8 @@ class StorageService {
         const files = await this.walkCloudDirCustom({
             bucket,
             region,
-            prefix: key
+            prefix: key,
+            marker
         });
         // 文件为空时，不能调用删除接口
         if (!files.length) {
@@ -2936,6 +3359,27 @@ class StorageService {
     }
 }
 exports.StorageService = StorageService;
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "getRemoteManifest", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "getRemoteManifestCustom", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "backupRemote", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "restoreFromBackup", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "cleanupBackup", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "pruneRemote", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "uploadDirectoryConsistent", null);
 __decorate([
     (0, utils_1.preLazy)()
 ], StorageService.prototype, "uploadFile", null);

package/package.json

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

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 {};

package/types/storage/type.d.ts

@@ -288,6 +288,121 @@ export interface IUploadObjectBySignHttpOptions {
 export interface IUploadObjectBySignHttpResult {
     Key: string;
 }
+/** 本地 manifest 条目：待发布文件的内容摘要 */
+export interface ILocalManifestItem {
+    /** 云端 Key */
+    key: string;
+    /** 本地文件内容 MD5（32 位小写十六进制） */
+    md5: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 本地文件绝对路径 */
+    localPath: string;
+}
+/** 远端 manifest 条目：远端 COS 对象信息 */
+export interface IRemoteManifestItem {
+    /** 云端 Key */
+    key: string;
+    /** 对象 ETag（去除首尾引号后） */
+    etag: string;
+    /** 对象大小（字节） */
+    size: number;
+}
+/** manifest 差异结果：用于回滚判定与发布后清理 */
+export interface IManifestDiffResult {
+    /** 本地有、远端无 —— 本次新增 */
+    added: string[];
+    /** 本地有、远端也有 —— 本次覆盖 */
+    overwritten: string[];
+    /** 远端有、本地无 —— 可作为 prune 候选 */
+    removed: string[];
+}
+/** manifest 校验结果：用于发布后确认远端内容是否与本地一致 */
+export interface IManifestVerifyResult {
+    /** 是否校验通过 */
+    ok: boolean;
+    /** 本地有但远端不存在的 Key */
+    missing: string[];
+    /** 远端存在但摘要或大小不匹配的 Key */
+    mismatched: string[];
+}
+/** 上传进度回调（与 StorageService 上传回调语义一致） */
+export type IConsistentUploadProgress = (progressData: {
+    loaded: number;
+    total: number;
+    speed: number;
+    percent: number;
+}) => void;
+/** 单文件上传完成回调（与 StorageService 的 onFileFinish 语义一致） */
+export type IConsistentUploadFileFinish = (error: Error, res: any, fileData: any) => void;
+/** 一致性发布上传选项 */
+export interface IConsistentUploadOptions {
+    /** 本地待发布目录（绝对或相对路径） */
+    localPath: string;
+    /** 云端目标前缀，无前导斜杠（如 'dist'）；为空表示桶根 */
+    cloudPath?: string;
+    /** 目标桶 */
+    bucket: string;
+    /** 目标地域 */
+    region: string;
+    /** 忽略规则，语义与现有 uploadDirectoryCustom 的 ignore 一致 */
+    ignore?: string | string[];
+    /** 是否获取文件 fileId */
+    fileId?: boolean;
+    /** 并发数量 */
+    parallel?: number;
+    /** 重试次数 */
+    retryCount?: number;
+    /** 重试时间间隔（毫秒） */
+    retryInterval?: number;
+    /** 上传进度回调 */
+    onProgress?: IConsistentUploadProgress;
+    /** 单文件上传完成回调（error / res / fileData，与普通上传语义一致） */
+    onFileFinish?: IConsistentUploadFileFinish;
+    /** 发布后校验远端与本地产物一致 */
+    verify?: boolean;
+    /** 安全发布：发布前快照备份 + 失败自动回滚 */
+    safe?: boolean;
+    /**
+     * ⚠️ 危险参数：发布后清理远端多余文件。
+     * 会删除云端 cloudPath 下、本地构建中不存在的全部文件。
+     * 若误传错误的 localPath/cloudPath，整个目录都会被判定为冗余而删除。
+     * 发布成功后备份默认保留，prune 误删的文件可从备份前缀人工恢复；
+     * 调用方（CLI）必须经用户二次确认后才可开启。
+     */
+    prune?: boolean;
+    /**
+     * 入口文件列表。
+     * 为相对 localPath 的相对路径，如 'index.html'、'admin/index.html'。
+     * 未指定时默认识别所有层级下的 index.html。
+     */
+    entries?: string[];
+}
+/** 远端多余文件清理结果 */
+export interface IPruneResult {
+    /** 成功删除的云端 Key */
+    deletedKeys: string[];
+    /** 删除失败的文件及原因 */
+    failedKeys: {
+        key: string;
+        error: string;
+    }[];
+}
+/** 一致性发布结果 */
+export interface IConsistentUploadResult {
+    /** 本次成功上传的云端 Key */
+    uploadedKeys: string[];
+    /** 是否执行了发布后校验 */
+    verified: boolean;
+    /**
+     * 发布前备份前缀，仅 safe 开启时返回，如 .cloudbase-backup/1724073600000/。
+     * 备份一律不由编排自动清理（发布成功与回滚后均保留）：prune 误删或需要
+     * 人工核查时可从中恢复；调用方确认无误后应通过 cleanupBackup 显式清理。
+     */
+    backupPrefix?: string;
+    /** 远端多余文件清理结果，仅 prune 开启时存在 */
+    prune?: IPruneResult;
+}
 /** 下载方法，仅支持 GET / HEAD */
 export type IDownloadObjectHttpMethod = 'GET' | 'HEAD';
 /** 下载对象公共参数 */