# @cloudant/couchbackup 中文文档

规范地址：https://npmcn.com/package/%40cloudant/couchbackup/

版本：2\.11\.21
npm 元数据更新时间：2026-11-09T17:02:36.758Z
中文译文更新时间：2026-11-10T02:34:51.561Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cloudant/couchbackup
原文对照：https://npmcn.com/package/%40cloudant/couchbackup/?lang=original
项目主页：https://github.com/IBM/couchbackup
源码仓库：https://github.com/IBM/couchbackup

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：129 kB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^22 \|\| ^24 \|\| ^26\.13\.0
- 运行依赖：3 个
- peer 依赖：axios 1\.20\.0，ibm-cloud-sdk-core 5\.9\.2
- 首次发布：2017-06-07T08:30:36.945Z
- 最新版本发布：2026-11-09T17:02:36.349Z
- 近 30 天下载量：10789（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：714（近 12 个月 101 个）

## 中文简介

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

## 安装

```sh
npm install @cloudant/couchbackup
```

也可以使用：`pnpm add @cloudant/couchbackup`、`yarn add @cloudant/couchbackup`、`bun add @cloudant/couchbackup`

## README

# 库克备份

[![npm (scoped)](https://img.shields.io/npm/v/@cloudant/couchbackup.svg?colorB=0000ff)](https://www.npmjs.com/package/@cloudant/couchbackup) [![npm (scoped with tag)](https://img.shields.io/npm/v/@cloudant/couchbackup/snapshot.svg?colorB=666699)](https://www.npmjs.com/package/@cloudant/couchbackup)

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

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

## 限制

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

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

## 安装

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

```sh
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` 环境变量 :

```sh
export COUCH_URL=http://localhost:5984
```

或者说

```sh
export COUCH_URL=https://myusername:mypassword@myhost.cloudant.com
```

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

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

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

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

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

### 数据库名称

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

```sh
export COUCH_DATABASE=animaldb
```

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

## 备份

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

```sh
couchbackup > backup.txt
```

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

```sh
couchbackup --db animaldb > animaldb.txt
```

## 日志恢复备份( A)

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

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

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

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

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

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

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

### 兼容性说明

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

## 恢复

现在使用 `couchrestore`数字 :

```sh
cat animaldb.txt | couchrestore
```

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

```sh
cat animaldb.txt | couchrestore --db animaldb2
```

### 兼容性说明

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

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

## 压缩备份

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

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

并用 :

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

## 加密备份

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

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

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

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

## 备份文件中有什么?

备份文件是文本文件,每行要么是备份元数据的JSON对象 或 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 密钥](https://console.bluemix.net/docs/services/Cloudant/guides/iam.html#ibm-cloud-identity-and-access-management) 用于访问 Cloudant 数据库,而不是URL中的用户信息证书。 用于取出默认符号的终点 `https://iam.cloud.ibm.com/identity/token`,但在必要时可使用 `CLOUDANT_IAM_TOKEN_URL` 环境变量.
-   `COUCH_ATTACHMENTS` - 说吧 _警告和不适用_ (见 [说明](https://npmcn.com/package/%40cloudant/couchbackup/#readme-note-on-attachments)如果 `true` 将包含附件作为备份或恢复进程的一部分.
-   `DEBUG` - 如果设置为 `couchbackup`,所有调试信件打印在 `stderr` 在备份或恢复过程中

_说明:_ 环境变量仅用于CLI. 何时 [利用方案](https://npmcn.com/package/%40cloudant/couchbackup/#readme-using-programmatically) 使用该 `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` - 说吧 _警告和不适用_ (见 [说明](https://npmcn.com/package/%40cloudant/couchbackup/#readme-note-on-attachments)与 `COUCH_ATTACHMENTS`

## 在方案方面

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

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

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

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

### 实例

见 [示例文件夹](https://npmcn.com/package/%40cloudant/couchbackup/examples) 例如脚本显示如何使用 使用图书馆.

### 备份

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

```javascript
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`数字 : _警告和不适用_ (见 [说明](https://npmcn.com/package/%40cloudant/couchbackup/#readme-note-on-attachments),参见 `CLOUDANT_ATTACHMENTS`。 。 。 .

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

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

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

备份数据到流 :

```javascript
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);
    }
  });
```

或者文件 :

```javascript
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 数据库.

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

```javascript
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`数字 : _警告和不适用_ (见 [说明](https://npmcn.com/package/%40cloudant/couchbackup/#readme-note-on-attachments),参见 `CLOUDANT_ATTACHMENTS`。 。 。 .

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

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

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

这个 `srcStream` 因为恢复是一个 [备份文件](https://npmcn.com/package/%40cloudant/couchbackup/#readme-whats-in-a-backup-file)。 。 。 . 如果备份不全,文件可能会被损坏 复出为 `BackupFileJsonError`。 。 。 .

从流中恢复数据 :

```javascript
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);
    }
  });
```

或从文件:

```javascript
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 是什么？

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 和提交记录判断。