Docker-Compose部署 EasySearch 异常问题排查

近期将原本运行在 macOS 上的 EasySearch、Console 和 Coco-server 等服务迁移至群晖 NAS 平台。在迁移过程中遇到了 EasySearch 容器无法正常启动或运行中意外终止的问题。本文记录了这些问题的具体表现及解决方案，旨在为后续类似部署提供参考。

基础部署配置

以下是官方推荐的 docker-compose 配置文件：
地址如下：

https://docs.infinilabs.com/easysearch/main/docs/getting-started/install/docker-compose/

version: "3"
services:
  easysearch-node1:
    user: "602:602"
    image: infinilabs/easysearch:1.11.1-2000
    container_name: easysearch-node1
    hostname: easysearch-node1
    environment:
      - "ES_JAVA_OPTS=-Xms1g -Xmx1g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - $PWD/ezs1/config:/app/easysearch/config
      - $PWD/ezs1/data:/app/easysearch/data
      - $PWD/ezs1/logs:/app/easysearch/logs
    ports:
      - 9201:9200
      - 9301:9300
    networks:
      - esnet

  easysearch-node2:
    user: "602:602"
    image: infinilabs/easysearch:1.11.1-2000
    container_name: easysearch-node2
    hostname: easysearch-node2
    environment:
      - "ES_JAVA_OPTS=-Xms1g -Xmx1g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - $PWD/ezs2/config:/app/easysearch/config
      - $PWD/ezs2/data:/app/easysearch/data
      - $PWD/ezs2/logs:/app/easysearch/logs
    ports:
      - 9202:9200
      - 9302:9300
    networks:
      - esnet

  console:
    image: infinilabs/console:1.29.1-2000
    container_name: console
    hostname: console
    volumes:
      - $PWD/console/data:/data
      - $PWD/console/log:/log
    networks:
      - esnet
    ports:
      - 9000:9000
    links:
      - easysearch-node1:es1
      - easysearch-node2:es2
    environment:
      - TZ=Asia/Shanghai

networks:
  esnet:
    driver: bridge
    ipam:
      config:
        - subnet: 172.24.0.0/16

常见问题及解决方案

问题 1：vm.max_map_count 参数不足

错误提示：

[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

问题分析

Lucene 搜索引擎在运行过程中需要创建大量内存映射文件(mmap)，而 Linux 系统默认的虚拟内存区域数量限制(65530)无法满足需求。

解决方案

临时设置（重启失效）：

sudo sysctl -w vm.max_map_count=262144

永久生效配置：

1. 编辑 /etc/sysctl.conf 文件
2. 添加配置项：

   vm.max_map_count=262144

3. 应用配置：

   sudo sysctl -p

问题 2：Java 堆内存溢出

错误信息：

java.lang.OutOfMemoryError: Java heap space

问题分析

容器化环境中，JVM 默认的内存分配策略往往无法正确识别可用的系统资源，导致：

1. 堆内存分配不足（默认通常仅 512MB-1GB）
2. 内存使用超出容器限制后被系统强制终止

解决方案

修改 docker-compose 配置，明确指定 JVM 堆内存：

environment:
  - ES_JAVA_OPTS=-Xms2g -Xmx2g

配置建议：

1. 堆内存设置为物理内存的 50%以内
2. 最大堆内存不超过 32GB（避免指针压缩失效）
3. 初始堆(-Xms)和最大堆(-Xmx)设为相同值，避免运行时动态调整

这次是部署过程中踩的两个坑，写出来让大家避避雷。