CesiumCloud - Node.js CLI和SDK

版本0.2.41·Node.js 22+·Windows， macOS和Linux

从终端或从Node.js管理云文件和文件夹。支持上传、下载、导航、列表、搜索、移动、重命名、删除和可选的本地加密文件。

Web应用程序: https://cloud.cesiummc.space/app/ ·npm: https://www.npmjs.com/package/cesiumcloud · 完整的参考

安装并登录

npm install -g [email protected]
cesiumcloud --version
cesiumcloud authenticate
cesiumcloud whoami

遵循浏览器/设备授权说明。本地保存的凭据用于后续命令。您不需要将令牌粘贴到终端命令中。

在Windows PowerShell或CMD中使用 npm.cmd 和 cesiumcloud.cmd 如果shell命令解析需要它们。始终引用包含空格、特殊字符或括号的完整Windows路径。

npm.cmd install -g [email protected]
cesiumcloud.cmd authenticate
cesiumcloud.cmd upload "E:\Downloads\My project (1).zip"

cesiumcloud upgrade (或 update)从官方的NPM注册表安装当前版本。 cesiumcloud logout 删除保存的本地凭据；通过您的CesiumCloud帐户单独撤销设备。

命令参考

你可以跑 cesiumcloud help COMMAND 或者 cesiumcloud COMMAND --help 获取特定于命令的帮助。 [and] 和 [to] 是文字分隔符，而不是文件名。对于多源命令，请引用 每一个 路径分别。

上传文件和目录

cesiumcloud upload "./backup.zip"
cesiumcloud upload "./Projects"
cesiumcloud upload "./backup.zip" --replace
cesiumcloud upload "./a.zip" [and] "./b.zip" -simultaneous 2
cesiumcloud upload "./My Folder" -simultaneous 20

单文件上传使用下面描述的标准配置。上传目录时，保留其嵌套路径和空文件夹。多个源和目录上传运行独立的文件传输，最多可达 40个活动文件上传 默认情况下，对于目录； -simultaneous N 或者 --simultaneous N 控制并发性（可接受的N: 1-64；活动上传限制40）。当容量可用时，允许上传。现有的云路径要求 --replace.

下载文件，目录和整个帐户

cesiumcloud download "archive.zip"
cesiumcloud download "archive.zip" --location "./Restored"
cesiumcloud download "photos" --location "./Restored"
cesiumcloud download "first.zip" [and] "second.zip" --location "./Restored" -simultaneous 2
cesiumcloud download --all "./RestoredAccount" -simultaneous 8

没有 --location，命名下载使用操作系统下载目录，不一定是当前终端目录。通过选择一个编号的备选项来保留现有的本地文件名。下载文件夹时，将在所选目标下创建文件夹，并使用其嵌套结构和空文件夹。 --all 还原所选本地目录下面的帐户层次结构。下载并发是1 - 64（默认：1）。

浏览，组织和删除

cesiumcloud dir /
cesiumcloud dir "photos"
cesiumcloud dir ..
cesiumcloud list
cesiumcloud list -a
cesiumcloud list -n 20 -sort name
cesiumcloud list -next 15
cesiumcloud list -sort datecreated -long
cesiumcloud search ext:png
cesiumcloud search "holiday" [and] "2026"
cesiumcloud rename "old.txt" "new.txt"
cesiumcloud rename "old.txt" "newname" -ne
cesiumcloud move "a.txt" [and] "b.txt" [to] "archive"
cesiumcloud delete "archive/a.txt"

dir 不带参数显示当前云目录； dir / 返回到root帐户。 list 默认为按大小排序的前15个文件； -a 递归地列出, -n N (或 N / -N)控制计数； -next N 移动已保存的光标， -sort 需要 size， name， datecreated， lastmodified 或者 reset； -long 显示的元数据。 search 使用不区分大小写的路径匹配； ext:png 匹配扩展。 rename 当新名称没有扩展名时，保留现有文件的扩展名，除非 -ne 提供。 delete 是永久的。

取消转移

自从0.2.41， Ctrl+C报告永久取消完成后，远程上传会话和它的保留已被删除；如果无法确认删除，它会显式报告待处理的清理 在将远程删除和队列清理处理给分离的进程后立即执行。 这个消息意味着清理是 在进步，而不是服务器删除 已经确认了。检查 cesiumcloud uploads 如果需要的话。

• 在Node.js CLI传输过程中， Ctrl + C 请求取消。v0.2.29增加了Windows Ctrl+C和Ctrl+Break控制台处理；仍然支持正常的Unix SIGINT行为。如果选择文本时终端将Ctrl+C视为复制，则清除所选内容。
• 从一个 同一台计算机上的第二个终端,使用 cesiumcloud upload cancel 或者 cesiumcloud download cancel． 当控制台中断键被截获时，这些命令也可以工作。它们仅影响相同CesiumCloud CLI配置中的作业，而不影响其他设备或网站上的作业。
• cesiumcloud cancel-upload UPLOAD_ID 可以取消特定的未完成的服务器上传。使用 cesiumcloud uploads 检查需要清理的条目。
• 上传被取消或失败 不保存以备以后恢复． 它未完成的服务器数据被删除；已经完成的云文件将被保存。如果服务器正在确认清除，则取消可能需要更长的时间。强制终止的进程可能需要自动恢复和清理。
• 取消下载将删除不完整的临时本地文件；已经完成的下载仍然存在。取消下载不会删除远程文件。

上传设置

单个文件（Node.js）的默认值： 99,876,864字节的块（100,000,000字节下最大的256 kb对齐大小），1 MiB HTTP流块和一个块预读。不需要任何环境变量。这些默认值是从实际传输测量中选择的；吞吐量取决于您的连接和存储容量。

预读可能会使用大约100 MB的额外内存块。并发文件夹上传使用较小的每个文件块来控制内存使用。

PowerShell:

$env:CESIUMCLOUD_UPLOAD_PREFETCH = "0"
cesiumcloud.cmd upload "E:\Backups\archive.zip"
Remove-Item Env:\CESIUMCLOUD_UPLOAD_PREFETCH

Bash:

CESIUMCLOUD_UPLOAD_PREFETCH=0 cesiumcloud upload "./archive.zip"

文件夹/批传输使用单独的文件上传路径，不等同于单个大文件传输。

JavaScript SDK

包导出 IsolatedTransferClient 用于文件管理和 CesiumCloudClient 用于高级设备授权和cli支持的操作。在Node.js 22+中：

const { IsolatedTransferClient } = require("cesiumcloud");
const client = new IsolatedTransferClient(process.env.CESIUMCLOUD_API_KEY);
async function example() {
  await client.uploadFile("./notes.txt", "docs/notes.txt");
  const files = await client.allFiles();
  const doc = files.find(file => file.path === "docs/notes.txt");
  if (doc) await client.download(doc.id, "./notes-restored.txt");
}
example().catch(console.error);

SDK操作需要一个有效的授权令牌。底层客户端支持 uploadFile， uploadPath， download， downloadPath， list， allFiles， byPath， delete， rename， renameFolder， mkdir， rmdir， directoryExists， pendingUploads， cancelUpload 和更多;看到 SDK参考． 默认情况下，SDK下载拒绝现有目标，除非显式启用覆盖，这与选择编号文件名的CLI下载不同。

可选端到端加密

cesiumcloud e2ee keygen
cesiumcloud e2ee encrypt "./notes.txt" --location "./Encrypted"
cesiumcloud e2ee decrypt "./Encrypted/notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee upload "./notes.txt"
cesiumcloud e2ee download "notes.txt.ccenc" --location "./Restored"
cesiumcloud e2ee migrate "old.txt"

keygen 创建本地存储的恢复密钥。 离线备份，永远不要泄露。 正常的 upload 仍是未加密的。加密的 .ccenc 格式保护内容，而不是路径、文件名、大小或活动元数据。 e2ee migrate 创建并验证加密副本，同时默认保留原始副本；原要求移除 两个 --purge-original 和 --i-backed-up-key． 在没有保留可用恢复键的情况下，不要设置清除标志。

故障排除和兼容性

寻求帮助 cesiumcloud --help 和 cesiumcloud e2ee help． 有关命令示例、环境变量和历史更改，请参阅源代码发行版附带的文档。

安全: CLI删除使用可恢复的48小时Trash；明确的SDK删除是永久性的，上传替换可以改变现有内容。保留重要文件和加密密钥的独立备份。

Windows版本和软件包升级

使用 where cesiumcloud 来检查哪个可执行Windows启动。Python的脚本可执行文件可能位于npm CLI的PATH上。使用 cesiumcloud.cmd version 对于NPM全局客户端或 python -m cesiumcloud version Python。这个 upgrade 和 update 当两个包都安装时，命令会更新这两个包类型。对于npm全局安装使用 npm install -g cesiumcloud； 没有 -g NPM安装到当前项目中。

在传输字节之前，通过队列允许上传。该服务强制允许，以防止通过直接请求跳过队列。上传块的大小上限为100 MB。

在0.2.41中删除文件夹

使用带有引号的云文件夹路径的delete命令。它将该目录及其所有内容移动到48小时可恢复的垃圾桶中，包括空文件夹；它从不调用永久删除。支持后面的Windows反斜杠。