CouchDB - 附件管理

CouchDB - 为文档附加文件

CouchDB 的一个强大功能是能够将二进制文件（如图片、PDF 或任何其他文件类型）直接附加到文档中。这在概念上类似于向电子邮件添加附件。每个附件都有自己的元数据（metadata），包括其名称、内容类型（MIME type）和大小。

方法一：使用 cURL 附加文件

要附加文件，您需要向一个特殊的附件URL发送 HTTP PUT 请求。一个关键的先决条件是您必须提供文档当前的修订ID（_rev）。这是 CouchDB 并发控制（concurrency control）的一部分，用于防止数据冲突。

附加文件的语法如下：

curl -u USER:PASS -X PUT http://127.0.0.1:5984/db_name/doc_id/attachment_name?rev=doc_rev_id \
--data-binary @/path/to/your/file -H "Content-Type: mime/type"

此命令的关键组成部分：

/db_name/doc_id/attachment_name：此路径指定附件的存储位置。attachment_name 是文件在文档内部的名称（例如，profile.jpg）。
?rev=doc_rev_id：文档的当前修订ID是一个强制性的查询参数。
--data-binary @/path/to/your/file：这指示 cURL 读取文件内容并将其作为请求体（request body）发送。
-H "Content-Type: mime/type"：这个 HTTP 头（header）指定了文件的 MIME 类型，这对于浏览器和应用程序正确处理文件至关重要（例如，image/jpeg）。

示例：分步操作

让我们将名为 avatar.png 的文件附加到 users 数据库中 _id 为 user001 的文档上。

步骤 1：获取文档的当前修订版本（_rev）。

$ curl -u admin:password -X GET http://127.0.0.1:5984/users/user001

{
    "_id": "user001",
    "_rev": "1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1",
    "name": "John Doe",
    "email": "john.doe@example.com"
}

当前的 _rev 是 1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1。

步骤 2：使用获取到的 _rev 上传附件。

$ curl -u admin:password -X PUT http://127.0.0.1:5984/users/user001/avatar.png?rev=1-a9a4c9c1b9b7e7e8a9f6b4d3a0c5e7b1 \
--data-binary @avatar.png -H "Content-Type: image/png"

{"ok":true,"id":"user001","rev":"2-c3f2b7b5f0d8a9e8e7c6b5a4d9f8e6a5"}

成功响应返回 {"ok": true} 并提供文档的新修订ID。

验证

要验证附件，请再次获取文档。您将看到一个新的 _attachments 对象，其中包含有关上传文件的元数据。

$ curl -u admin:password -X GET http://127.0.0.1:5984/users/user001

{
   "_id": "user001",
   "_rev": "2-c3f2b7b5f0d8a9e8e7c6b5a4d9f8e6a5",
   "name": "John Doe",
   "email": "john.doe@example.com",
   "_attachments": {
      "avatar.png": {
         "content_type": "image/png",
         "revpos": 2,
         "digest": "md5-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6==",
         "length": 18240,
         "stub": true
      }
   }
}

方法二：使用 Fauxton 附加文件

Fauxton 提供了一个直观的界面来管理附件。

1. 导航到您的数据库，并打开您想要添加附件的文档。
1. 在文档视图中，查找标题栏中带有工具提示“上传附件”（Upload Attachment）的曲别针图标。点击它。
1. 将出现一个对话框。点击“选择文件”（Choose File）以浏览本地系统并选择您要上传的文件。
1. 文件选择完成后，点击对话框中的“上传”（Upload）按钮。
1. 页面将刷新，您将在文档的“_attachments”部分下看到列出的文件。

最佳实践

虽然方便，但将大型二进制文件（数兆字节）直接存储在 CouchDB 中会显著增加数据库大小并影响复制性能。对于处理超大文件的系统，常见的架构模式是将文件存储在专门的对象存储服务中（如 AWS S3、Google Cloud Storage 或 MinIO），而在 CouchDB 文档中仅存储文件的URL或引用。这能使您的数据库保持精简和快速。