@cloudant/couchbackup

中文文档

2.11.21发布于 2026/11/10Apache-2.0CommonJS构建来源已验证近 30 天下载 1.1万

CouchBackup - Cloudant/ CouchDB 的命令行备份工具

文档目录34 节

限制
安装
所需资源
抓图
使用量
URL 网络
数据库名称
备份
日志恢复备份( A)
兼容性说明
恢复
兼容性说明
压缩备份
加密备份
备份文件中有什么?
日志文件中有什么?
什么是浅模式?
为什么用CouchBackup?
选项参考
环境变量
命令行参数
在方案方面
实例
备份
恢复
处理错误
API 密码
CLI 退出代码
双方共有 couchbackup 财务报告和审定财务报表 couchrestore
couchbackup
couchrestore
关于附件的说明
有实验 attachments 选项
没有实验 attachments 选项

库克备份

 _____                  _    ______            _
/  __ \                | |   | ___ \          | |
| /  \/ ___  _   _  ___| |__ | |_/ / __ _  ___| | ___   _ _ __
| |    / _ \| | | |/ __| '_ \| ___ \/ _` |/ __| |/ / | | | '_ \
| \__/\ (_) | |_| | (__| | | | |_/ / (_| | (__|   <| |_| | |_) |
 \____/\___/ \__,_|\___|_| |_\____/ \__,_|\___|_|\_\\__,_| .__/
                                                         | |
                                                         |_|

CouchBackup是一个命令行工具,可以备份 Cloudant 或 CouchDB 数据库到文本文件. 它带有一个可以还原备份数据的配套命令行工具.

限制

CouchBackup在它能够备份的数据中有一些限制:

couchbackup 不做 CouchDB 复制本身, 它只是通过数据库的流 _changes 种子和用途 POST /db/_bulk_get 以获取文档,将其找到的文档存储在磁盘上.
couchbackup 不支持备份或恢复包含附加文件的数据库。建议直接将附件存储在对象商店中。 "附件"选项是按原样提供的,不支持. 这个选项仅供Apache CouchDB使用,并且是实验性的. 别用IBM Cloudant的备份. 说明

安装

要安装最新发布的版本, 请使用 npm :

npm install -g @cloudant/couchbackup

所需资源

节点.js LTS版本22,24或26.
最低要求的 CouchDB 版本为 2.0.0.

抓图

最新建筑 main 分支与 npm snapshot 标签。使用 snapshot 如果您想要尝试未释放的固定功能或新功能, 标记, 但请注意快照版本是 不支持。。。 .

使用量

使用环境变量或命令行选项指定 CouchDB 或 Cloudant 实例的 URL, 以及要与之合作的数据库 .

URL 网络

要定义 CouchDB 实例的 URL 设置 COUCH_URL 环境变量 :

export COUCH_URL=http://localhost:5984

或者说

export COUCH_URL=https://myusername:[email protected]

或者用那个 --url 命令行参数.

在 URL 用户信息子组件中传递证书时他们一定是编码百分比。。。 . 具体而言,在用户名或密码内,字符 : / ? # [ ] @ % 必须以cent-encode 编码,其他字符 5月(简体中文) 以百分比编码.

例如,对于用户名 user123 密码 colon:at@321数字 :

https://user123:colon%3aat%40321@localhost:5984

注意要额外注意, 当设置环境变量或命令行参数.

数据库名称

要定义要备份或恢复的数据库名称,请设置 COUCH_DATABASE 环境变量 :

export COUCH_DATABASE=animaldb

或者用那个 --db 命令行参数

备份

要备份数据库到文本文件,请使用 couchbackup 命令,引导输出到文本文件:

couchbackup > backup.txt

另一种支持方式是建立 COUCH_URL 仅提供命令行上的数据库名称:

couchbackup --db animaldb > animaldb.txt

日志恢复备份( A)

您也可以创建一个记录备份进度的日志文件 --log 参数,例如:

couchbackup --db animaldb --log animaldb.log > animaldb.txt

使用此日志文件以恢复备份 --resume true数字 :

couchbackup --db animaldb --log animaldb.log --resume true >> animaldb.txt

这个 --resume true 选项用于完成拼接变化的备份,但尚未完成所有必要批次文档的下载。这个 不是递增备份 解决方案.

您也可以指定输出文件的名称,而不是引导备份数据到静态数字 :

couchbackup --db animaldb --log animaldb.log --resume true --output animaldb.txt

兼容性说明

使用时 --resume 使用同一版本的 couchbackup 启动备份.

恢复

现在使用 couchrestore数字 :

cat animaldb.txt | couchrestore

或指定命令行上的数据库名称:

cat animaldb.txt | couchrestore --db animaldb2

兼容性说明

不要使用旧版本的 couchbackup 以恢复使用新版本创建的备份.

较新的版本 couchbackup 可以恢复旧版本在同一主要版本内创建的备份.

压缩备份

在存储到磁盘管道之前压缩备份数据 gzip数字 :

couchbackup --db animaldb | gzip > animaldb.txt.gz

并用 :

cat animaldb.tar.gz | gunzip | couchdbrestore --db animaldb2

加密备份

类似压缩也可以通过一个加密或解密工具。例如与 openssl数字 :

couchbackup --db animaldb | openssl aes-128-cbc -pass pass:12345 > encrypted_animal.db

openssl aes-128-cbc -d -in encrypted_animal.db -pass pass:12345 | couchrestore --db animaldb2

注意内容未加密于连接到加密工具前的备份工具.

备份文件中有什么?

备份文件是文本文件,每行要么是备份元数据的JSON对象或 JSON 系列备份文档修订对象,例如:

{"name":"@cloudant/couchbackup","version":"2.9.10","mode":"full"}
[{"_id": "1","a":1},{"_id": "2","a":2},...]
[{"_id": "501","a":501},{"_id": "502","a":502}]

备份阵列中的文档修订次数不同。通常它会 buffer_size 元素,但如果还有叶片修改,则可能更多如果是最后一批,则从服务器发送或更少.

日志文件中有什么?

日志文件有行 :

每批文件编号 couchbackup 需要获取,例如: :t batch56 [{"id":"a"},{"id":"b"}]
每批货 couchbackup 已获取和存储,例如: :d batch56
以表明这些变化的饲料已全部消耗,例如: :changes_complete

什么是浅模式?

当你跑的时候 couchbackup 与 --mode shallow couchbackup 执行更简单的备份. 它只支持胜出的修改,而忽略了任何相冲突的修订. 这是一个更快但不太完整的备份.

说明: 这个 --log, (中文(简体) ), --resume,以及 --parallelism 无效 --mode shallow 备份.

为什么用CouchBackup?

备份 CouchDB 数据库的最简单方法是复制". couch"文件. 单节点实例可以, 但当运行多节点时 Cloudant 或使用 CouchDB 2.0 或更高,".couch"文件只有单一的硬度数据. 此工具允许简单的 CouchDB 备份或使用 HTTP API 的 Cloudant 数据库.

此工具可以脚本您的数据库备份。将备份和日志文件移动到廉价对象存储器, 以便您拥有贵重数据的复制件 .

选项参考

环境变量

COUCH_URL - CouchDB/Cloudant服务器的URL,例如: http://127.0.0.1:5984
COUCH_DATABASE - 拟采取行动的数据库名称,例如: mydb (默认) test(中文(简体) )
COUCH_PARALLELISM - 恢复备份时并行执行的HTTP请求数量,例如: 10 (过失) 5(中文(简体) )
COUCH_BUFFER_SIZE - 一次性取回的文档数量,例如: 100 (默认) 500) (中文(简体) ).
COUCH_REQUEST_TIMEOUT - 在重试请求之前等待对 HTTP 请求的答复的毫秒数, 例如 : 10000 (过失) 120000(中文(简体) )
COUCH_LOG - 备份时存储日志信息的文件
COUCH_RESUME - 狦 true,恢复其最后一个已知位置的较早备份(需要日志文件)
COUCH_OUTPUT - 存储备份数据的文件名( 默认为 stdout)
COUCH_MODE - 狦 shallow,只做表面备份忽略冲突。默认为 full - 一个完整的备份.
COUCH_QUIET - 狦 true,在 CLI 备份时将单个批次消息压制到控制台并恢复
CLOUDANT_IAM_API_KEY - 可选 IAM API 密钥用于访问 Cloudant 数据库,而不是URL中的用户信息证书。用于取出默认符号的终点 https://iam.cloud.ibm.com/identity/token,但在必要时可使用 CLOUDANT_IAM_TOKEN_URL 环境变量.
COUCH_ATTACHMENTS - 说吧 警告和不适用 (见说明如果 true 将包含附件作为备份或恢复进程的一部分.
DEBUG - 如果设置为 couchbackup,所有调试信件打印在 stderr 在备份或恢复过程中

说明: 环境变量仅用于CLI. 何时利用方案使用该 opts 词典.

命令行参数

--url - 一样 COUCH_URL 环境变量
--db - 一样 COUCH_DATABASE
--parallelism - 一样 COUCH_PARALLELISM
--buffer-size - 一样 COUCH_BUFFER_SIZE
--request-timeout - 一样 COUCH_REQUEST_TIMEOUT
--log - 一样 COUCH_LOG
--resume - 一样 COUCH_RESUME
--output - 一样 COUCH_OUTPUT
--mode - 一样 COUCH_MODE
--iam-api-key - 一样 CLOUDANT_IAM_API_KEY
--quiet - 一样 COUCH_QUIET
--attachments - 说吧 警告和不适用 (见说明与 COUCH_ATTACHMENTS

在方案方面

你用得着 couchbackup 在方案方面。首先安装 couchbackup 输入您的项目 npm install --save @cloudant/couchbackup。。。 . 然后您可以将库导入您的代码 :

  const couchbackup = require('@cloudant/couchbackup');

图书馆输出两个主要功能:

backup - 从数据库备份到可写流.
restore - 从可读流恢复到空数据库.

实例

见示例文件夹例如脚本显示如何使用使用图书馆.

备份

这个 backup 函数需要源数据库 URL,要写入的流, 备份选项并调用以完成 .

backup: function(srcUrl, targetStream, opts, callback) { /* ... */ }

这个 opts 字典可以包含映射到上文定义的环境变量。与来源和不需要目标地点.

parallelism: 见 COUCH_PARALLELISM。。。 .
bufferSize: 见 COUCH_BUFFER_SIZE。。。 .
requestTimeout: 见 COUCH_REQUEST_TIMEOUT。。。 .
log: 见 COUCH_LOG。。。 .
resume: 见 COUCH_RESUME。。。 .
mode: 见 COUCH_MODE。。。 .
iamApiKey: 见 CLOUDANT_IAM_API_KEY。。。 .
iamTokenUrl: 可选使用 iamApiKey 以覆盖默认 URL 获取 IAM 的标志 .
attachments数字 : 警告和不适用 (见说明,参见 CLOUDANT_ATTACHMENTS。。。 .

当备份完成或失败时,调用调用函数标准 err, data 参数.

这个 backup 函数返回事件发送器。您可以订阅 :

changes - 当一批更改被写入日志流时.
written - 当一批文件被写入备份流时.
finished - 当所有文件都备份后就释放一次.

备份数据到流 :

couchbackup.backup(
  'https://examples.cloudant.com/animaldb',
  process.stdout,
  {parallelism: 2},
  function(err, data) {
    if (err) {
      console.error("Failed! " + err);
    } else {
      console.error("Success! " + data);
    }
  });

或者文件 :

couchbackup.backup(
  'https://examples.cloudant.com/animaldb',
  fs.createWriteStream(filename),
  {parallelism: 2},
  function(err, data) {
    if (err) {
      console.error("Failed! " + err);
    } else {
      console.error("Success! " + data);
    }
  });

恢复

这个 restore 函数需要包含数据流的可读流编辑 backup 函数并上传到 Cloudant 数据库.

说明: 目标数据库必须是 新建和空 数据库.

restore: function(srcStream, targetUrl, opts, callback) { /* ... */ }

这个 opts 字典可以包含映射到上文定义的环境变量。与来源和不需要目标地点.

parallelism: 见 COUCH_PARALLELISM。。。 .
bufferSize: 见 COUCH_BUFFER_SIZE。。。 .
requestTimeout: 见 COUCH_REQUEST_TIMEOUT。。。 .
iamApiKey: 见 CLOUDANT_IAM_API_KEY。。。 .
iamTokenUrl: 可选使用 iamApiKey 以覆盖默认 URL 获取 IAM 的标志 .
attachments数字 : 警告和不适用 (见说明,参见 CLOUDANT_ATTACHMENTS。。。 .

当恢复完成或失败时,调用回调函数标准 err, data 参数.

这个 restore 函数返回事件发送器。您可以订阅 :

restored - 当一批文件被恢复时.
finished - 恢复所有文件后就释放一次.

这个 srcStream 因为恢复是一个备份文件。。。 . 如果备份不全,文件可能会被损坏复出为 BackupFileJsonError。。。 .

从流中恢复数据 :

couchbackup.restore(
  process.stdin,
  'https://examples.cloudant.com/new-animaldb',
  {parallelism: 2},
  function(err, data) {
    if (err) {
      console.error("Failed! " + err);
    } else {
      console.error("Success! " + data);
    }
  });

或从文件:

couchbackup.restore(
  fs.createReadStream(filename),
  'https://examples.cloudant.com/new-animaldb',
  {parallelism: 2},
  function(err, data) {
    if (err) {
      console.error("Failed! " + err);
    } else {
      console.error("Success! " + data);
    }
  });

处理错误

这个 couchbackup 财务报告和审定财务报表 couchrestore 即使在一个不可靠的网络上,进程也能够容忍许多错误. 在后退延迟后请求重试至少两次失败 . 然而,某些错误无法容忍失败:

无效的配置
验证检查失败( 例如: auth, 数据库存在 ,), _bulk_get 终止点的活性)

API 密码

在出现致命错误时程序化使用库回调函数被调用 null, error 参数.

CLI 退出代码

致命错误, couchbackup 财务报告和审定财务报表 couchrestore 以非零退出代码退出。本节细节.

双方共有 `couchbackup` 财务报告和审定财务报表 `couchrestore`

1:未知的 CLI 选项或通用错误.
2:无效的 CLI 选项 .
10: 备份源或恢复目标数据库不存在.
11: 未经授权的数据库证书.
12: 数据库权限无效 .
40: 数据库返回了致命的 HTTP 错误 .

`couchbackup`

20数字 : --resume 没有日志文件.
21: 恢复日志文件不存在 .
22:日志文件有不完整的更改.
23: 日志文件已经存在, 但是 --resume 未使用.
30: 数据库中的错误拼接变化.
50: 源数据库不支持 /_bulk_get 终点.

`couchrestore`

13:恢复目标数据库不是新建和空的.
60数字 : attachments 选项用于备份,但没有用于恢复.
61数字 : attachments 用于恢复的选项,但没有用于备份.

关于附件的说明

热带木材数据库; 如果您备份一个不使用附件的数据库 attachments 选项 couchbackup 无法恢复.

如上所述 couchbackup 不支持备份或恢复包含附加文件的数据库.

建议直接将附件存储在JSON文档中链接的对象商店中,而不是使用原生附件 API.

有实验 `attachments` 选项

这个 attachments 选项是按原样提供的,不支持。这个选项仅供Apache CouchDB使用,并且是实验性的. 请不要使用 IBM Cloudant 备份的选项 .

没有实验 `attachments` 选项

备份包含带有附件的文件的数据库似乎已成功完成。然而,附件内容不下载,备份文件包含附件元数据。所以试图恢复备份导致错误, 因为附件元数据引用附件不存在在恢复的数据库中.

版本与发布记录

@cloudant/couchbackup 共发布 714 个版本，首次发布于 2017/06/07；过去 12 个月发布了 101 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`2.11.21`latest	2026/11/10	今天
`2.11.21-SNAPSHOT-485`snapshot	2026/11/05	4 天前
`2.11.21-SNAPSHOT-484`	2026/11/05	4 天前
`2.11.21-SNAPSHOT-482`	2026/11/03	6 天前
`2.11.21-SNAPSHOT-479`	2026/10/29	11 天前
`2.11.21-SNAPSHOT-478`	2026/10/29	12 天前

关于 @cloudant/couchbackup 的常见问题

@cloudant/couchbackup 是什么？

CouchBackup - Cloudant/ CouchDB 的命令行备份工具

如何安装 @cloudant/couchbackup？

在项目目录运行 npm install @cloudant/couchbackup，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：axios（1.20.0）、ibm-cloud-sdk-core（5.9.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 couchbackup、couchrestore，可以用 npx couchbackup 直接运行。

@cloudant/couchbackup 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cloudant__couchbackup 是否存在。

@cloudant/couchbackup 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@cloudant/couchbackup 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^22 || ^24 || ^26.13.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@cloudant/couchbackup 可以商用吗？

@cloudant/couchbackup 使用 Apache-2.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

@cloudant/couchbackup 的下载量有多少？

根据 npm 官方下载统计，@cloudant/couchbackup 在 2026/10/10 – 2026/11/08 这 30 天内被下载 10,789 次，日均约 360 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@cloudant/couchbackup 还在维护吗？

最新版本 2.11.21 发布于 2026/11/10（今天）；至今共发布 714 个版本，其中过去 12 个月发布了 101 个；首次发布于 2017/06/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @cloudant/couchbackup

pnpmpnpm add @cloudant/couchbackup
yarnyarn add @cloudant/couchbackup
bunbun add @cloudant/couchbackup

peer 依赖axios 1.20.0ibm-cloud-sdk-core 5.9.2

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

命令行npx couchbackupnpx couchrestore

在你的项目目录中运行此命令。

近 30 天下载

10,789

约 1.1万次日均 360 次

统计周期 2026/10/10 – 2026/11/08
数据来自 npm 官方下载统计，今天更新

最新版本2.11.21发布于今天

开源许可Apache-2.0宽松许可

包体积129 kB22 个文件 · 解压后

运行依赖3 个另有 2 个 peer 依赖

模块格式CommonJS

TypeScript未声明类型可查找 @types/cloudant__couchbackup

Node.js^22 || ^24 || ^26.13.0

发布版本714 个近 12 个月 101 个

首次发布2017/06/079 年前

元数据更新2026/11/10

每一个软件包背后，
都有分享与创造的人。

@cloudant/couchbackup

库克备份

限制

安装

所需资源

抓图

使用量

URL 网络

数据库名称

备份

日志恢复备份( A)

兼容性说明

恢复

兼容性说明

压缩备份

加密备份

备份文件中有什么?

日志文件中有什么?

什么是浅模式?

为什么用CouchBackup?

选项参考

环境变量

命令行参数

在方案方面

实例

备份

恢复

处理错误

API 密码

CLI 退出代码

双方共有 couchbackup 财务报告和审定财务报表 couchrestore

couchbackup

couchrestore

关于附件的说明

有实验 attachments 选项

没有实验 attachments 选项

版本与发布记录

关于 @cloudant/couchbackup 的常见问题

@cloudant/couchbackup 是什么？

如何安装 @cloudant/couchbackup？

@cloudant/couchbackup 支持 TypeScript 吗？

@cloudant/couchbackup 支持 ESM 还是 CommonJS？

@cloudant/couchbackup 需要什么版本的 Node.js？

@cloudant/couchbackup 可以商用吗？

@cloudant/couchbackup 的下载量有多少？

@cloudant/couchbackup 还在维护吗？

双方共有 `couchbackup` 财务报告和审定财务报表 `couchrestore`

`couchbackup`

`couchrestore`

有实验 `attachments` 选项

没有实验 `attachments` 选项