Apache CouchDB Docker 镜像文档

镜像概述和主要用途

Apache CouchDB 是一个面向文档的数据库，使用 JSON 存储文档，通过 HTTP API 进行交互，并支持 JavaScript/声明式索引。其核心特性是定义了 Couch 复制协议，使数据能够在全球分布式服务器集群、移动设备和 Web 浏览器等各种计算环境中无缝同步，提供离线优先的用户体验，同时保持高性能和可靠性。

该 Docker 镜像是 Apache CouchDB 官方镜像的 amd64 架构版本，用于简化 CouchDB 的部署和运行，适用于开发、测试和生产环境。

核心功能和特性

• JSON 文档存储：原生支持 JSON 格式文档，无需预定义模式，灵活适应数据结构变化。
• HTTP API：通过标准 HTTP 方法（GET、PUT、POST 等）操作数据库，易于集成到 Web 应用。
• JavaScript/声明式索引：支持使用 JavaScript 编写视图和索引，实现复杂数据查询。
• Couch 复制协议：跨设备、跨平台的数据同步机制，支持双向复制和增量同步。
• 分布式集群：可部署为集群模式，支持水平扩展，提升可用性和负载能力。
• 离线优先：结合 PouchDB 等客户端实现，支持离线数据操作，重新联网后自动同步。
• MapReduce 支持：内置 MapReduce 框架，用于高效的批量数据处理和聚合查询。

使用场景和适用范围

• 分布式系统：适用于需要跨地域、多节点数据同步的全球分布式应用。
• 移动应用后端：支持移动设备离线数据存储与同步，提升移动端用户体验。
• Web 应用数据存储：作为后端数据库，提供灵活的 JSON 数据模型和 HTTP API，简化前后端交互。
• 离线优先应用：如协作工具、内容管理系统等，需在无网络环境下保持功能可用的场景。
• 原型开发与快速迭代：无需复杂配置即可启动，支持动态调整数据结构，加速开发流程。

支持的标签及 Dockerfile 链接

详细使用方法和配置说明

快速启动 CouchDB 实例

通过以下命令启动一个基本的 CouchDB 容器：

$ docker run -d --name my-couchdb amd64/couchdb:latest

• --name my-couchdb：指定容器名称为 my-couchdb。
• amd64/couchdb:latest：使用最新版本的 amd64 架构 CouchDB 镜像。

从其他 Docker 容器连接 CouchDB

CouchDB 默认暴露 5984 端口，可通过容器链接使其他应用容器访问。例如，启动一个依赖 CouchDB 的应用容器：

$ docker run --name my-app --link my-couchdb:couchdb -d app-that-uses-couchdb

• --link my-couchdb:couchdb：将 my-couchdb 容器链接到当前应用容器，并以 couchdb 为别名，应用可通过 couchdb:5984 访问数据库。

暴露端口到外部网络

若需从宿主机或外部网络访问 CouchDB，需映射容器端口到宿主机：

$ docker run -p 5984:5984 -d amd64/couchdb:latest

警告：暴露端口前需确保已创建管理员用户并正确配置数据库权限，避免未授权访问。

部署 CouchDB 集群

单节点启动（含管理员用户）

通过环境变量 COUCHDB_USER 和 COUCHDB_PASSWORD 创建管理员用户：

$ docker run -d \
  -e COUCHDB_USER=admin \
  -e COUCHDB_PASSWORD=securepassword \
  -p 5984:5984 \
  --name couchdb-node1 \
  amd64/couchdb:latest

多节点集群配置

1. 启动多个节点：每个节点需指定 NODENAME（节点名称）和 Erlang Cookie（集群节点间通信密钥）：

# 节点 1
$ docker run -d \
  -e NODENAME=couchdb@node1 \
  -e ERL_FLAGS="-setcookie myclustercookie" \
  -p 5984:5984 \
  --name couchdb-node1 \
  amd64/couchdb:latest

# 节点 2（假设宿主机 IP 为 192.168.1.100）
$ docker run -d \
  -e NODENAME=couchdb@node2 \
  -e ERL_FLAGS="-setcookie myclustercookie" \
  -p 5985:5984 \
  --name couchdb-node2 \
  amd64/couchdb:latest

2. 完成集群配置：通过 CouchDB 集群设置向导 或 集群 API 加入节点并创建系统数据库（_global_changes、_replicator、_users）。

Docker Compose 示例（单节点）

创建 docker-compose.yml 文件：

version: '3'
services:
  couchdb:
    image: amd64/couchdb:latest
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=securepassword
    volumes:
      - couchdb-data:/opt/couchdb/data
    restart: always

volumes:
  couchdb-data:  # 使用 Docker 卷持久化数据

启动集群：

$ docker-compose up -d

容器访问与日志查看

进入容器 Shell

通过 docker exec 进入容器命令行：

$ docker exec -it my-couchdb bash

访问 Erlang 运行时

直接与 CouchDB 的 Erlang 运行时交互：

$ docker exec -it my-couchdb /opt/couchdb/bin/remsh

查看容器日志

CouchDB 日志输出到标准输出，可通过 docker logs 查看：

$ docker logs my-couchdb

环境变量配置

数据持久化

CouchDB 数据默认存储在容器内 /opt/couchdb/data 目录，需通过以下方式持久化：

1. Docker 卷（推荐）

使用 Docker 托管卷，自动管理存储路径和权限：

$ docker run -d \
  -v couchdb-data:/opt/couchdb/data \
  --name my-couchdb \
  amd64/couchdb:latest

2. 宿主机目录绑定

将宿主机目录直接挂载到容器（需确保宿主机目录权限正确，CouchDB 运行用户 UID 为 5984）：

$ mkdir -p /home/couchdb/data
$ chown -R 5984:5984 /home/couchdb/data  # 设置目录所有者为容器内 CouchDB 用户
$ docker run -d \
  -v /home/couchdb/data:/opt/couchdb/data \
  --name my-couchdb \
  amd64/couchdb:latest

自定义配置文件

CouchDB 配置文件位于 /opt/couchdb/etc，推荐通过以下方式自定义配置：

1. 挂载配置目录

将宿主机配置目录挂载到容器 /opt/couchdb/etc/local.d（动态配置文件目录）：

$ docker run -d \
  -v /home/couchdb/etc:/opt/couchdb/etc/local.d \
  --name my-couchdb \
  amd64/couchdb:latest

在宿主机 /home/couchdb/etc 下创建 .ini 文件（如 custom.ini），配置会被自动加载。

2. 基于镜像构建自定义镜像

创建 Dockerfile 复制自定义配置文件：

FROM amd64/couchdb:latest
COPY custom.ini /opt/couchdb/etc/local.d/

构建并运行：

$ docker build -t my-custom-couchdb .
$ docker run -d -p 5984:5984 my-custom-couchdb

注意事项

系统数据库创建

CouchDB 不会自动创建系统数据库（_global_changes、_replicator、_users），需通过以下方式创建：

• 使用 集群设置向导 或 集群 API 完成集群配置后自动创建。
• 手动创建：通过 HTTP API 发送请求创建，例如：

  curl -X PUT http://admin:securepassword@localhost:5984/_users
  curl -X PUT http://admin:securepassword@localhost:5984/_replicator
  curl -X PUT http://admin:securepassword@localhost:5984/_global_changes
  

管理员模式（Admin Party Mode）

默认情况下，CouchDB 启动时处于“管理员模式”（无认证访问），必须立即创建管理员用户。可通过以下方式：

• 启动时设置 COUCHDB_USER 和 COUCHDB_PASSWORD 环境变量。
• 通过集群设置向导或 API 创建管理员。

日志配置

默认日志输出到 stdout，可通过配置文件启用文件日志：

1. 在自定义配置文件（如 log.ini）中添加：

   [log]
   writer = file
   file = /opt/couchdb/log/couch.log
   level = info  # 日志级别：debug, info, warn, error
   

2. 挂载日志目录到宿主机（避免容器内日志占用过多空间）：

   $ docker run -d \
     -v /home/couchdb/log:/opt/couchdb/log \
     -v /home/couchdb/etc:/opt/couchdb/etc/local.d \
     --name my-couchdb \
     amd64/couchdb:latest
   

许可证

Apache CouchDB 采用 Apache 许可证。Docker 镜像中可能包含其他软件（如基础系统组件、依赖库等），其许可证需参考各软件自身的许可协议。

镜像元数据和许可证信息可参考 repo-info 仓库的 couchdb 目录。使用前请确保遵守所有包含软件的许可条款。

维护与支持

• 维护者：Apache CouchDB 项目
• 问题反馈：GitHub Issues
• 支持架构：amd64、arm64v8、s390x
• 获取帮助：Docker 社区 Slack、Server Fault、Stack Overflow