本页内容
- 前提条件
- 第 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 继续。

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

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

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

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

按 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://
$ sudo ufw allow 5984/tcp
在浏览器中打开 URL http://

第 5 步 - 访问 CouchDB
CouchDB 附带一个基于 Web 的 GUI,名为 Fauxton,用于管理和创建数据库。你可以通过 URL http://

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

在这里,你将看到安装过程中创建的两个数据库。_users 数据库如预期那样处理 CouchDB 平台用户的信息,而 _replicator 数据库保存有关任何复制数据库或操作的信息。
你还会看到一个侧边栏,其中包含可用于 CouchDB 的各种选项。
第 6 步 - 使用 CouchDB 界面进行基本数据库操作
CouchDB 的 Fauxton 界面允许我们执行基本的 CRUD 操作(创建、读取、更新和删除)。让我们从创建一个新数据库开始。
创建数据库
要创建一个新数据库,点击主屏幕上的 Create Database 链接。它将打开以下弹出窗口。

输入你要创建的数据库名称,然后点击 Create 按钮。
这将创建一个新数据库并打开以下屏幕。

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

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

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

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

要编辑文档,你可以点击右侧显示的铅笔图标,或切换回 Metadata 视图并点击文档链接。更改任意项目的值,然后点击 Save Document 完成。
删除文档
要删除文档,点击文档前面的勾号,然后如下所示选择顶部的删除按钮。

第 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 公开到互联网上。如果你有任何问题,请在下面的评论中发表。