本页内容

  • 前提条件
  • 第 1 步 - 安装工具
  • 第 2 步 - 添加 CouchDB 仓库
  • 第 3 步 - 安装 CouchDB
  • 第 4 步 - 验证 CouchDB 安装
  • 第 5 步 - 访问 CouchDB
  • 第 6 步 - 使用 CouchDB 界面进行基本数据库操作 创建数据库 创建文档 删除文档
  • 第 7 步 - 使用命令行进行基本数据库操作 创建数据库 创建文档 批量创建文档 读取文档 编辑文档 删除文档 查看数据
  • 第 8 步 - 安装 Caddy Server
  • 第 9 步 - 配置 Caddy
  • 结论
  • 创建数据库
  • 创建文档
  • 删除文档
  • 创建数据库
  • 创建文档
  • 批量创建文档
  • 读取文档
  • 编辑文档
  • 删除文档
  • 查看数据

Apache CouchDB 是由 Apache Software Foundation 开发的开源 NoSQL 数据库。每个数据库都是 JSON 格式文档的集合。每个文档由若干字段和附件组成。它带有 restful API,可用于创建、编辑和删除数据库文档。它支持两种模式 - standalone 和 clustered。如果你在单台服务器上使用它,可以使用 standalone 模式。如果你使用多台服务器,clustered 模式会很有用。

本教程将教你如何在 Debian 11 服务器上安装 Apache CouchDB Database Server。你还将学习如何执行一些基本的数据库操作,以及如何使用 Caddy web server 通过公共 URL 访问 CouchDB。

前提条件

  • 一台运行 Debian 11 的服务器。
  • 已安装 Sudo 软件包。$ apt install sudo
  • 一个具有 sudo 权限的非 root 用户。
  • 所有内容均已更新。$ sudo apt update && sudo apt upgrade
  • 一个完全限定域名(FQDN),例如 couchdb.example.com,用于通过带 HTTPS 的公共 URL 访问 CouchDB。

一台运行 Debian 11 的服务器。

已安装 Sudo 软件包。

$ apt install sudo

一个具有 sudo 权限的非 root 用户。

所有内容均已更新。

$ sudo apt update && sudo apt upgrade

一个完全限定域名(FQDN),例如 couchdb.example.com,用于通过带 HTTPS 的公共 URL 访问 CouchDB。

第 1 步 - 安装工具

在继续安装之前,我们需要安装本教程所需的一些工具。运行以下命令来安装它们。

$ sudo apt install -y curl apt-transport-https gnupg nano lsb-release 

第 2 步 - 添加 CouchDB 仓库

第一步是导入 CouchDB 的 GPG 密钥。运行以下命令来导入该密钥。

$ curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null 2>&1

将 CouchDB 的仓库添加到系统仓库列表中。

$ echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ `lsb_release -cs` main" \
    | sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null

更新系统仓库列表。

$ sudo apt update

第 3 步 - 安装 CouchDB

运行以下命令来安装 CouchDB。

$ sudo apt install couchdb -y

CouchDB 安装程序会自动提示你配置基本设置。在第一步中,它会询问你是要在单服务器设置还是多节点中使用它。由于我们是在单台服务器上安装,保持该选项为选中状态并按 Enter 继续。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

接下来,系统会要求你设置一个 cookie 名称。选择任意你想要的名称。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

接下来,系统会要求你为 CouchDB 的服务设置一个绑定地址。由于我们是在服务器上安装,并且需要通过 UI 控制面板访问它,因此将 0.0.0.0 设置为绑定地址。如果你打算将对 CouchDB 服务器的访问限制为某个 IP 地址,则使用该地址。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

接下来,系统会要求你为其默认 admin 账户创建一个管理员密码。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

系统会要求你再次验证该密码。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

按 Enter 完成安装过程。

第 4 步 - 验证 CouchDB 安装

要验证安装是否成功,运行以下命令。

$ curl http://127.0.0.1:5984/

它将返回包含 CouchDB 信息的 JSON 格式输出。

{"couchdb":"Welcome","version":"3.2.2","git_sha":"d5b746b7c","uuid":"7a20b1eadd803f1c0d77fb9617c7f3de","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

shell 输出是未格式化的。下面是格式化后的样子。

{
   "couchdb":"Welcome",
   "version":"3.2.2",
   "git_sha":"d5b746b7c",
   "uuid":"7a20b1eadd803f1c0d77fb9617c7f3de",
   "features":[
      "access-ready",
      "partitioned",
      "pluggable-storage-engines",
      "reshard",
      "scheduler"
   ],
   "vendor":{
      "name":"The Apache Software Foundation"
   }
}

你也可以通过 Web 访问 URL http://:5984/ 来访问它。但在此之前,我们需要在防火墙中打开该端口。假设你使用的是 Uncomplicated Firewall(ufw),运行以下命令来打开该端口。

$ sudo ufw allow 5984/tcp

在浏览器中打开 URL http://:5984。你将看到以下屏幕。以下输出是在 Firefox 上截取的。在其他浏览器中,你只会看到在终端中得到的原始输出。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

第 5 步 - 访问 CouchDB

CouchDB 附带一个基于 Web 的 GUI,名为 Fauxton,用于管理和创建数据库。你可以通过 URL http://:5984/_utils/ 访问它。在你常用的浏览器中打开该 URL,你将看到以下登录屏幕。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

输入 admin 作为用户名,以及之前创建的密码。按 Log in 按钮继续。接下来,你将进入 CouchDB 仪表板。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

在这里,你将看到安装过程中创建的两个数据库。_users 数据库如预期那样处理 CouchDB 平台用户的信息,而 _replicator 数据库保存有关任何复制数据库或操作的信息。

你还会看到一个侧边栏,其中包含可用于 CouchDB 的各种选项。

第 6 步 - 使用 CouchDB 界面进行基本数据库操作

CouchDB 的 Fauxton 界面允许我们执行基本的 CRUD 操作(创建、读取、更新和删除)。让我们从创建一个新数据库开始。

创建数据库

要创建一个新数据库,点击主屏幕上的 Create Database 链接。它将打开以下弹出窗口。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

输入你要创建的数据库名称,然后点击 Create 按钮。

这将创建一个新数据库并打开以下屏幕。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

创建文档

现在我们有了一个数据库,让我们在其中创建一个文档。点击 Create Document 按钮开始。你将看到以下新文档屏幕,其中预填充了一个 JSON 对象和一个带有全局唯一标识符(GUID)的 _id。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

让我们按以下方式添加更多字段来加入一些数据。如果你想更改 _id 字段的值,可以,但只能在创建文档之前更改。文档创建后,你无法更改其值。不过你可以随时编辑其他字段。

{
  "_id": "0b4ad0d607479c09bb9121b146007363",
  "Name": "Navjot Singh",
  "role": "writer",
  "skills": "linux"
}

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

添加完字段后,点击 Create Document 按钮以保存新文档。你将返回到以下 All Documents 页面。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

要查看文档的内容,你可以点击 {} JSON 链接。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

要编辑文档,你可以点击右侧显示的铅笔图标,或切换回 Metadata 视图并点击文档链接。更改任意项目的值,然后点击 Save Document 完成。

删除文档

要删除文档,点击文档前面的勾号,然后如下所示选择顶部的删除按钮。

在 Debian 11 上安装 Apache CouchDB 数据库服务器完整教程

第 7 步 - 使用命令行进行基本数据库操作

虽然使用 Web 界面是使用 CouchDB 的更简单方式,但通过命令行执行相同的操作可以获得更高的效率。

创建数据库

在开始创建数据库之前,让我们为要连接的 URL 定义一个变量。我们的示例将使用简单的纯文本身份验证。由于我们需要对每条命令进行身份验证,最好为此使用一个预定义的变量。你可以使用 localhost 或 127.0.0.1 来连接 CouchDB 安装。

$ HOST="http://admin:
[email protected]
:5984"

注意:使用纯文本密码并不是最好的方法,不应在生产环境中使用。你可以查看 CouchDB 的官方文档以了解更安全的身份验证方法。

现在我们已经定义了主机 URL,让我们尝试使用以下命令创建另一个数据库。

$ curl -X PUT $HOST/another_db

数据库的名称是 another_db 。并且我们需要为该命令提供管理员密码。

创建文档

要创建文档,运行以下命令。

$ curl -X POST -d '{"todo":"task 1", "done":false}' $HOST/another_db -H "Content-Type:application/json"

-X 标志表示我们正在执行 HTTP POST 操作。-H 标志指定我们推送的内容类型,这里是 JSON。而 -d 标志指定我们添加的实际 JSON 内容。

上述命令将自动为文档生成一个 ID。它将生成以下输出,表明命令执行成功。

{"ok":true,"id":"0b4ad0d607479c09bb9121b14600c6ee","rev":"1-2fc1d70532433c39c9f61480607e3681"}

如你所见,文档的 ID 是自动生成的。如果你想指定自定义 ID,可以按以下方式进行。

$ curl -X POST -d '{"_id":"random_task", "todo":"task 2", "done":false}' $HOST/another_db -H "Content-Type:application/json"
{"ok":true,"id":"random_task","rev":"1-bceeae3c4a9154c87db1649473316e44"}

批量创建文档

你也可以批量添加文档。

$ curl -X POST -d '{"docs": [{"todo":"task 3", "done":false}, {"todo":"task 4", "done":false}]}' $HOST/another_db/_bulk_docs -H "Content-Type:application/json"

如你所见,当我们插入多个文档时,POST 正文包含一个带有 docs 字段的对象。该字段携带要插入数据库的文档数组。插入单个文档时,POST 请求被发送到数据库( $HOST/another_db )。但当我们需要插入多个文档时,请求必须发送到 $HOST/another_db/_bulk_docs URL。

你将收到类似的输出。

[{"ok":true,"id":"0b4ad0d607479c09bb9121b14600cb04","rev":"1-778fd61f8f460d0c1df1bb174279489d"},{"ok":true,"id":"0b4ad0d607479c09bb9121b14600d9ef","rev":"1-dc9e84861bba58e5cfefeed8f5133636"}]

在这里你可以看到,输出包含两个新文档的 ID。

读取文档

要从数据库读取文档,你需要指定其 ID。运行以下命令来检索 random_task 文档。由于我们使用了 HTTP POST 请求来添加数据,因此要检索它,需要使用 GET 请求是理所当然的。

$ curl -X GET $HOST/another_db/random_task

你将收到以下输出。

{"_id":"random_task","_rev":"1-bceeae3c4a9154c87db1649473316e44","todo":"task 2","done":false}

在这里,记下文档的 _rev 字段。当你需要编辑或删除文档时,此字段很有用。

编辑文档

要编辑文档,你需要使用 _rev 字段。在编辑时,任何不包含 _rev 字段的请求都会被 CouchDB 自动拒绝。由于 CouchDB 会更新整个文档,因此在编辑操作期间必须在请求正文中发送整个文档。

让我们使用以下命令更新 random_task 文档。

$ curl -X PUT -d '{"_rev":"1-bceeae3c4a9154c87db1649473316e44", "todo":"task 2", "done":true}' $HOST/another_db/random_task

确保将 _rev 字段的值替换为你读取文档时得到的值。它应与实际文档中的值匹配。

你将收到类似于下面的输出。

{"ok":true,"id":"random_task","rev":"2-4cc3dfb6e76befd665faf124b36b7f1c"}

如果你留意,会发现 rev 字段的数据已更改。对文档的任何进一步更改都需要你使用这个新的 rev 值。

删除文档

要删除文档,你需要指定 ID 和更新后的 rev 值。让我们删除 random-task 文档。

$ curl -X DELETE $HOST/another_db/random_task?rev=2-4cc3dfb6e76befd665faf124b36b7f1c

确保命令中 rev 字段的值与你实际文档中的值匹配。你将得到类似如下的输出。

{"ok":true,"id":"random_task","rev":"3-07d6cde68be2a559497ec263045edc9d"}

查看数据

让我们检查服务器上所有数据库的列表。

$  curl -X GET $HOST/_all_dbs

列出特定数据库下的所有文档。

$ curl -X GET $HOST/another_db/_all_docs

第 8 步 - 安装 Caddy Server

到目前为止,我们一直使用服务器 IP 地址访问 CouchDB。如果你想用域名替换它,并在其前面使用 SSL 以使其更安全,有一个简单的方法。在本教程中,我们将使用 Caddy Server,因为它轻量、只需最少的配置即可工作,并且内置 SSL 创建功能。

运行以下命令来安装 Caddy 所需的一些软件包。它们可能已经安装在你的服务器上。

$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

安装 Caddy 的 GPG 密钥,并将官方仓库添加到 Debian 的仓库列表中。

$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

安装 Caddy server。

$ sudo apt update
$ sudo apt install caddy

运行以下命令来验证安装。

$ caddy version
v2.5.1 h1:bAWwslD1jNeCzDa+jDCNwb8M3UJ2tPa8UZFFzPVmGKs=

第 9 步 - 配置 Caddy

要将 Caddy 配置为反向代理服务器,你需要配置 Caddyfile 。打开 Caddyfile 进行编辑。

$ sudo nano /etc/caddy/Caddyfile

用以下代码替换其中的代码。

couchdb.example.com {
        reverse_proxy localhost:5984

        tls 
[email protected]


        log {
                output file /var/log/caddy/couchdb.log
        }
}

按 Ctrl + X 并在提示时输入 Y 来保存文件。

运行 Caddy 验证器来检查是否存在任何问题。

$ caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile

如果遇到任何与格式有关的错误,运行以下命令来修复它。

$ sudo caddy fmt --overwrite /etc/caddy/Caddyfile

再次运行验证器。

重启 Caddy server 以使更改生效。

$ sudo systemctl restart caddy

你现在可以在浏览器中通过 URL https://couchdb.example.com/_utils/ 访问 CouchDB。

结论

你已经学习了如何在 Debian 11 机器上安装 Apache CouchDB Database server。你还学习了如何通过命令行和 Fauxton UI 执行基本的数据库操作。最后但同样重要的是,你还学习了如何使用 Caddy 作为反向代理服务器将 Fauxton UI 公开到互联网上。如果你有任何问题,请在下面的评论中发表。