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-2000container_name: easysearch-node1hostname: easysearch-node1environment:- "ES_JAVA_OPTS=-Xms1g -Xmx1g"ulimits:memlock:soft: -1hard: -1nofile:soft: 65536hard: 65536volumes:- $PWD/ezs1/config:/app/easysearch/config- $PWD/ezs1/data:/app/easysearch/data- $PWD/ezs1/logs:/app/easysearch/logsports:- 9201:9200- 9301:9300networks:- esneteasysearch-node2:user: "602:602"image: infinilabs/easysearch:1.11.1-2000container_name: easysearch-node2hostname: easysearch-node2environment:- "ES_JAVA_OPTS=-Xms1g -Xmx1g"ulimits:memlock:soft: -1hard: -1nofile:soft: 65536hard: 65536volumes:- $PWD/ezs2/config:/app/easysearch/config- $PWD/ezs2/data:/app/easysearch/data- $PWD/ezs2/logs:/app/easysearch/logsports:- 9202:9200- 9302:9300networks:- esnetconsole:image: infinilabs/console:1.29.1-2000container_name: consolehostname: consolevolumes:- $PWD/console/data:/data- $PWD/console/log:/lognetworks:- esnetports:- 9000:9000links:- easysearch-node1:es1- easysearch-node2:es2environment:- TZ=Asia/Shanghainetworks:esnet:driver: bridgeipam: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)设为相同值，避免运行时动态调整

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