couchbase/elasticsearch-connector

Couchbase Elasticsearch Connector 镜像文档

1. 镜像概述和主要用途

Couchbase Elasticsearch Connector 是一款用于在 Couchbase 数据库与 Elasticsearch 搜索引擎之间实现数据同步的工具镜像。其核心功能是建立两者间的实时或近实时数据通道，将 Couchbase 中的文档数据同步至 Elasticsearch 索引，支持数据的全量迁移与增量更新，帮助用户基于 Elasticsearch 的强大搜索能力构建高效的全文检索、数据分析及业务查询系统。

2. 核心功能和特性

2.1 数据同步能力

• 双向数据流动：支持从 Couchbase 到 Elasticsearch 的单向同步（默认），部分版本支持基于业务需求的反向同步配置。
• 同步模式灵活：提供全量同步（初始化数据迁移）与增量同步（基于 Couchbase DCP 协议的变更数据捕获，CDC），可单独或组合使用。

2.2 数据处理与转换

• 自定义文档转换：支持通过配置文件定义数据字段映射规则，实现 Couchbase 文档到 Elasticsearch 索引的字段过滤、重命名、格式转换。
• 批处理优化：支持可配置的批处理大小，减少网络交互次数，提升同步效率。

2.3 高可用性与可靠性

• 故障恢复：支持断点续传，同步中断后可从上次进度继续。
• 连接容错：内置连接超时重试机制，提升对网络波动的容忍度。

2.4 兼容性

• 支持 Couchbase Server 6.5+ 及 Elasticsearch 7.x/8.x 版本。
• 兼容 Couchbase 命名空间（Bucket/Scope/Collection）模型，支持细粒度数据同步。

3. 使用场景和适用范围

3.1 企业级全文检索

• 场景：企业内部系统（如 CRM、OA）需基于 Couchbase 业务数据提供全文搜索能力。
• 价值：通过同步至 Elasticsearch，实现关键词高亮、模糊匹配、复杂过滤等高级搜索功能。

3.2 电商商品搜索

• 场景：电商平台商品数据存储于 Couchbase，需对外提供商品搜索、分类筛选、热门推荐。
• 价值：利用 Elasticsearch 的聚合分析能力，支持实时价格排序、库存筛选、销量统计等。

3.3 日志与监控数据聚合

• 场景：应用日志写入 Couchbase，需集中存储并分析异常日志。
• 价值：同步至 Elasticsearch 后，结合 Kibana 实现日志可视化、告警监控。

3.4 数据湖与数据分析

• 场景：Couchbase 作为业务数据库，需将历史数据同步至 Elasticsearch 供数据团队分析。
• 价值：支持按时间范围、业务标签筛选数据，降低直接查询业务库的性能影响。

4. 使用方法和配置说明

4.1 环境变量配置

4.2 Docker Run 示例

bash
docker run -d \
  --name couchbase-elasticsearch-connector \
  -e COUCHBASE_HOST="couchbase-node1:8091,couchbase-node2:8091" \
  -e COUCHBASE_USER="admin" \
  -e COUCHBASE_PASSWORD="password123" \
  -e COUCHBASE_BUCKET="ecommerce_products" \
  -e COUCHBASE_SCOPE="inventory" \
  -e COUCHBASE_COLLECTION="products" \
  -e ELASTICSEARCH_HOST="elasticsearch:9200" \
  -e ELASTICSEARCH_USER="elastic" \
  -e ELASTICSEARCH_PASSWORD="es-password" \
  -e ELASTICSEARCH_INDEX="products_index" \
  -e SYNC_MODE="full+incremental" \
  -e BATCH_SIZE=2000 \
  -v /local/mapping.json:/app/index_mapping.json \  # 挂载索引映射配置文件
  couchbase/elasticsearch-connector:latest

4.3 Docker Compose 配置示例

yaml
version: '3.8'

services:
  couchbase:
    image: couchbase/server:7.2.0
    ports:
      - "8091:8091"  # Web控制台
      - "8093:8093"  # Query服务
      - "11210:11210" # 数据服务
    environment:
      - COUCHBASE_ADMIN_USER=admin
      - COUCHBASE_ADMIN_PASSWORD=password123
    volumes:
      - couchbase-data:/opt/couchbase/var

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.10.4
    environment:
      - discovery.type=single-node
      - ES_JAVA_OPTS="-Xms512m -Xmx512m"
      - xpack.security.enabled=true
      - ELASTIC_PASSWORD=es-password
    ports:
      - "9200:9200"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

  connector:
    image: couchbase/elasticsearch-connector:latest
    depends_on:
      - couchbase
      - elasticsearch
    environment:
      - COUCHBASE_HOST="couchbase:8091"
      - COUCHBASE_USER="admin"
      - COUCHBASE_PASSWORD="password123"
      - COUCHBASE_BUCKET="ecommerce_products"
      - ELASTICSEARCH_HOST="elasticsearch:9200"
      - ELASTICSEARCH_USER="elastic"
      - ELASTICSEARCH_PASSWORD="es-password"
      - SYNC_MODE="full+incremental"
      - BATCH_SIZE=1000
    volumes:
      - ./mapping.json:/app/index_mapping.json  # 索引映射配置文件

volumes:
  couchbase-data:
  elasticsearch-data:

5. 配置参数详解

5.1 同步模式（SYNC_MODE）

• full：仅执行全量同步，扫描目标 Bucket/Scope/Collection 所有文档并同步至 Elasticsearch，完成后退出。
• incremental：仅监听 Couchbase DCP 变更流，同步新增/更新/删除的文档（需 Couchbase 开启 DCP 功能）。
• full+incremental：先执行全量同步，完成后自动切换为增量模式，持续监听变更。

5.2 索引映射配置（INDEX_MAPPING_FILE）

通过挂载外部 JSON 文件定义 Elasticsearch 索引映射（如字段类型、分词器），示例 mapping.json：

json
{
  "mappings": {
    "properties": {
      "product_id": { "type": "keyword" },
      "name": { "type": "text", "analyzer": "ik_max_word" },
      "price": { "type": "double" },
      "stock": { "type": "integer" },
      "create_time": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss" }
    }
  }
}

5.3 批处理大小（BATCH_SIZE）

控制每次同步的文档数量，建议根据数据大小调整：

• 小文档（<1KB）：可设为 2000-5000，提升吞吐量。
• 大文档（>10KB）：建议设为 100-500，避免内存溢出。

6. 注意事项

1. 网络连通性：确保 Connector 容器可访问 Couchbase（8091 端口，DCP 需 *** 端口）和 Elasticsearch（9200 端口）。
2. 权限配置：Couchbase 用户需具备目标 Bucket 的 data_reader 角色；Elasticsearch 用户需具备 index:write 权限。
3. 索引初始化：首次同步前建议手动创建 Elasticsearch 索引（或通过 INDEX_MAPPING_FILE 自动创建），避免字段类型冲突。
4. Couchbase DCP 配置：增量同步依赖 Couchbase DCP，需确保 Bucket 启用 DCP（默认启用），且节点数量变化时需重新配置 COUCHBASE_HOST。
5. 资源限制：全量同步时可能占用较高 CPU/内存，建议通过 --cpus 和 -m 限制容器资源（如 --cpus 2 -m 4g）。