Elasticsearch 9.5.4 Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Elasticsearch 9.5.4（官方镜像 docker.elastic.co/elasticsearch/elasticsearch:9.5.4），提供带详细注释的 docker-compose.yml、常用环境变量、X-Pack 安全认证（ELASTIC_PASSWORD 自动设置 elastic 密码）、数据卷持久化与健康检查，并给出等价的 docker run 运行方式。本文档已在 /opt/data/elasticsearch-compose 目录实测通过（容器健康、认证访问、数据写入验证成功）。

1. 环境要求

项目	要求
操作系统	Ubuntu 22.04 LTS
Docker	≥ 20.10（本文实测 29.1.3）
Docker Compose	V2 插件（本文实测 2.40.3）
内存	≥ 4 GB（建议 8 GB，ES 堆按需调整）
内核参数	`vm.max_map_count >= 262144`（否则容器启动报 map count 过低）

1.1 内核参数检查与修正

sysctl vm.max_map_count
# 如低于 262144 执行:
sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" >> /etc/sysctl.conf

1.2 确认 Docker 与 Compose

docker --version
docker compose version

2. 目录规划

mkdir -p /opt/data/elasticsearch-compose
cd /opt/data/elasticsearch-compose

3. docker-compose.yml 详解

创建 /opt/data/elasticsearch-compose/docker-compose.yml：

# =============================================================================
# Elasticsearch 9.5.4 单节点 Docker Compose 部署
# 使用官方镜像 docker.elastic.co/elasticsearch/elasticsearch:9.5.4
#
# 前置要求:
#   1) 内核参数 vm.max_map_count >= 262144
#      sysctl -w vm.max_map_count=262144
#   2) 已安装 Docker 与 Docker Compose 插件 (docker compose version)
#
# 使用方法:
#   docker compose up -d        # 后台启动
#   docker compose ps           # 查看运行状态
#   docker compose logs -f es01 # 跟踪 es01 日志
#   docker compose down         # 停止并删除容器(数据卷保留)
#   docker compose down -v      # 停止并删除容器与数据卷
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # es01 : Elasticsearch 单节点服务
  # ---------------------------------------------------------------------------
  es01:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.5.4
    container_name: es01                       # 容器名称
    hostname: es01                             # 容器内主机名
    restart: unless-stopped                    # 非手动停止时自动重启
    environment:                               # 环境变量配置
      - node.name=es01                         # 节点名称
      - cluster.name=es-docker-cluster         # 集群名称
      - discovery.type=single-node             # 单节点模式,跳过集群发现机制
      - ES_JAVA_OPTS=-Xms512m -Xmx512m         # JVM 堆内存(根据机器内存调整)
      - xpack.security.enabled=true            # 启用 X-Pack 安全认证
      - ELASTIC_PASSWORD=q1w2e3r4              # elastic 超级用户初始密码
      - bootstrap.memory_lock=true             # 锁定物理内存,避免 swap 降低性能
    ulimits:                                   # 系统资源限制
      memlock:                                 # 内存锁定限制
        soft: -1                               # 软限制: 不设上限 (-1 = unlimited)
        hard: -1                               # 硬限制: 不设上限
      nofile:                                  # 文件描述符数量限制
        soft: 65536
        hard: 65536
    volumes:                                   # 数据持久化
      - esdata01:/usr/share/elasticsearch/data # 数据目录挂载到命名卷
    ports:                                     # 端口映射 (宿主机:容器)
      - "9200:9200"                            # HTTP/REST 访问端口
      - "9300:9300"                            # 节点间传输端口
    networks:                                  # 加入自定义网络
      - esnet

# ---------------------------------------------------------------------------
# 命名卷: 用于持久化 ES 数据, 容器删除后数据不丢失
# ---------------------------------------------------------------------------
volumes:
  esdata01:

# ---------------------------------------------------------------------------
# 自定义 bridge 网络, 容器间通过服务名互相解析
# ---------------------------------------------------------------------------
networks:
  esnet:
    driver: bridge

3.1 环境变量说明

环境变量	说明
`node.name`	节点名，日志与集群中显示的名称
`cluster.name`	集群名，相同集群名的节点会自动组队
`discovery.type=single-node`	单节点模式，跳过集群发现（多节点部署时移除该行）
`ES_JAVA_OPTS`	JVM 堆内存参数，如 `-Xms512m -Xmx512m`
`xpack.security.enabled`	启用 X-Pack 安全认证
`ELASTIC_PASSWORD`	首次启动时自动为 `elastic` 超级用户设置密码
`bootstrap.memory_lock`	启用内存锁，配合 `ulimits.memlock` 防止 swap

注意：ELASTIC_PASSWORD 环境变量仅在数据卷首次初始化时生效，已初始化过的数据卷后续修改该变量不会改密码。如需重置，使用 bin/elasticsearch-reset-password -u elastic 或删除数据卷后重新初始化。

3.2 卷与网络

esdata01 为命名卷，挂载 ES 数据目录 /usr/share/elasticsearch/data，docker compose down 后数据保留，docker compose down -v 才会删除数据。
esnet 为自定义 bridge 网络，容器之间可通过服务名互相访问（多节点部署时 es01/es02/es03 通过 http://es02:9200 通信）。

4. 启动与验证

4.1 启动

cd /opt/data/elasticsearch-compose
docker compose up -d

输出（节选）：

Network elasticsearch-compose_esnet  Created
Volume elasticsearch-compose_esdata01  Created
Container es01  Starting
Container es01  Started

4.2 查看状态

docker compose ps
docker logs -f es01

日志中出现集群转 green：

Cluster health status changed from [YELLOW] to [GREEN]

4.3 健康检查（认证访问）

容器内执行（镜像自带 curl 与自签证书，用 -k 跳过证书校验）：

curl -sk -u elastic:q1w2e3r4 http://localhost:9200/_cluster/health?pretty

说明：官方镜像启用 xpack.security.enabled=true 后，9200 默认仍为明文 HTTP（除非额外配置 xpack.security.http.ssl.enabled 并挂载证书）。因此访问使用 http:// 而非 https://。

输出：

{
  "cluster_name" : "es-docker-cluster",
  "status" : "green",
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_shards_percent_as_number" : 100.0
}

宿主机上同样可通过映射端口访问：

curl -s -u elastic:q1w2e3r4 http://<宿主机IP>:9200/

5. 数据写入测试

5.1 创建索引

curl -s -u elastic:q1w2e3r4 -X PUT "http://localhost:9200/compose_index" \
  -H "Content-Type: application/json" \
  -d '{"settings":{"number_of_shards":1,"number_of_replicas":0}}'

输出：

{"acknowledged":true,"shards_acknowledged":true,"index":"compose_index"}

5.2 写入文档

curl -s -u elastic:q1w2e3r4 -X POST "http://localhost:9200/compose_index/_doc/1" \
  -H "Content-Type: application/json" \
  -d '{"msg":"docker compose 部署测试","ts":"2026-10-01"}'

输出：

{"_index":"compose_index","_id":"1","_version":1,"result":"created","_shards":{"total":1,"successful":1,"failed":0},...}

5.3 搜索

curl -s -u elastic:q1w2e3r4 -X POST "http://localhost:9200/compose_index/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{"query":{"match_all":{}}}'

6. 常见操作

6.1 停止与清理

docker compose down          # 停止并删除容器（保留数据卷）
docker compose down -v       # 停止并删除容器与数据卷（数据丢失）
docker compose restart es01  # 重启服务

6.2 数据卷持久化验证

docker compose down
docker compose up -d
curl -s -u elastic:q1w2e3r4 "http://localhost:9200/_cat/indices?v"
# compose_index 仍在, 数据保留

6.3 等价的 docker run 方式

docker run -d --name es01 \
  -p 9200:9200 -p 9300:9300 \
  -e "node.name=es01" \
  -e "cluster.name=es-docker-cluster" \
  -e "discovery.type=single-node" \
  -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \
  -e "xpack.security.enabled=true" \
  -e "ELASTIC_PASSWORD=q1w2e3r4" \
  --ulimit memlock=-1:-1 \
  --ulimit nofile=65536:65536 \
  -v esdata01:/usr/share/elasticsearch/data \
  --network esnet \
  docker.elastic.co/elasticsearch/elasticsearch:9.5.4

7. 多节点 Compose 部署（扩展）

如需在 Compose 中搭建 3 节点集群，只需删除 discovery.type=single-node，复制三个 es01 服务并调整名称/端口，核心差异：

services:
  es01:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.5.4
    environment:
      - node.name=es01
      - cluster.name=es-cluster
      - discovery.seed_hosts=es02,es03
      - cluster.initial_master_nodes=es01,es02,es03
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
      - xpack.security.enabled=true
      - xpack.security.transport.ssl.enabled=true
      ...

节点间 transport 使用 9300 通过自定义网络 esnet 通信，TLS 证书需通过卷挂载到各容器 config/certs/ 并设置对应 keystore 密码。

8. 总结

本文档演示了通过 Docker Compose 以官方镜像部署 Elasticsearch 9.5.4 单节点的完整流程：

准备内核参数与 Docker/Compose 环境；
编写带详细注释的 docker-compose.yml（环境变量、ulimits、数据卷、端口映射、网络）；
docker compose up -d 一键启动；
通过 ELASTIC_PASSWORD 完成 X-Pack 安全认证初始化，认证访问健康检查；
索引创建、文档写入、检索验证；
掌握 down/down -v、数据卷持久化、等价 docker run 及多节点扩展方式。