Apache Ignite Docker Compose 部署指南

目标：用 Docker Compose 基于官方镜像 apacheignite/ignite:2.18.0 在服务器上快速部署 Apache Ignite 2.18.0 单节点内存数据网格，覆盖镜像选型、compose 编排、端口映射、数据持久化、堆内存（JVM）限制、配置文件挂载与常用运维命令。已在 Ubuntu 22.04（内核 6.8）宿主机 + Docker Compose v5.5.1 + 官方 apacheignite/ignite:2.18.0 上实测验证。

一、环境信息

Docker Engine / Docker Compose：Compose 版本文本为 Docker Compose version v5.5.1
官方镜像：apacheignite/ignite:2.18.0（docker.io/apacheignite/ignite）
镜像内 JDK：JAVA_HOME=/opt/java/openjdk，JAVA_VERSION=jdk-11.0.31+11，IGNITE_HOME=/opt/ignite/apache-ignite
镜像默认暴露端口：10800（瘦客户端/JDBC）、11211（Memcached）、47100（通信）、47500（发现）、49112（控制中心）、8080（REST）
编排文件：/opt/data/ignite-compose/docker-compose.yml
实测节点：单节点 servers=1，集群状态 ACTIVE；默认堆 1.0GB，设 JVM_OPTS 后 heap=0.25GB

注：本篇为容器化部署专题文档，允许出现 Docker/容器/镜像等术语；其余三篇（安装指南、配置详解、CLI 详解）仍按“真机服务器”视角编写。

二、镜像选型说明

候选镜像	说明	是否推荐
`apacheignite/ignite:2.18.0`	Apache 官方维护，内置 JDK 11 + 2.18.0 二进制发行包，开箱即用	✅ 首选
`apacheignite/ignite:<3.x>`	官方 3.x 镜像，对应 Ignite3 新架构	仅 3.x 场景
自建镜像（基于 ubuntu + 拷贝 `-bin` 包）	可控性强但维护成本高	一般

选择建议：官方镜像已内置 JDK 与 Ignite 发行包，入口脚本统一处理 JVM_OPTS、CONFIG_URI、OPTION_LIBS 等环境变量，直接用官方版本最省事；只在需要定制系统层依赖时才自建镜像。

三、前置条件

服务器已安装 Docker Engine 与 Docker Compose（docker compose version 可执行）
服务器可访问镜像仓库（默认 docker.io）
预留端口：10800、47100、47500、11211（可映射为宿主机任意可用端口）

拉取官方镜像并校验：

docker pull apacheignite/ignite:2.18.0

真实回显：

6a657458c1b3: Pull complete
1772bccaa804: Pull complete
Digest: sha256:57ae83a8ef76bb423e803b082c3ae06a70b1c2ddf43f78440eb7f1f4df79ac93
Status: Downloaded newer image for apacheignite/ignite:2.18.0
docker.io/apacheignite/ignite:2.18.0

查看镜像关键元数据：

docker inspect apacheignite/ignite:2.18.0 \
  --format 'JAVA={{.Config.Env}} IGNITE_HOME={{range .Config.Env}}{{println .}}{{end}}'

💡 说明：官方镜像入口为 $IGNITE_HOME/run.sh，它通过 JVM_OPTS、CONFIG_URI、OPTION_LIBS 三个环境变量控制 JVM 内存、配置文件名与可选模块（详见第六、七节）。

四、部署步骤

4.1 创建编排目录

mkdir -p /opt/data/ignite-compose/{work,config}
cd /opt/data/ignite-compose

4.2 编写 docker-compose.yml

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

services:
  ignite-server:
    image: apacheignite/ignite:2.18.0
    container_name: ignite-server
    hostname: ignite-server
    restart: unless-stopped
    ports:
      - "10800:10800"   # 瘦客户端 / JDBC
      - "47100:47100"   # 通信端口 TcpCommunication
      - "47500:47500"   # 发现端口 TcpDiscovery
      - "11211:11211"   # memcached 协议
    environment:
      - CONFIG_URI=/opt/ignite/apache-ignite/config/default-config.xml
      - JVM_OPTS=-Xms256m -Xmx256m -server -XX:MaxMetaspaceSize=128m
    volumes:
      - ./work:/opt/ignite/apache-ignite/work
      - ./config:/opt/ignite/apache-ignite/config:ro

💡 说明：JVM_OPTS 通过 environment 注入，把 JVM 堆限制到 256MB（处于要求区间 256–512MB）；若想更稳妥可用 512MB，把 -Xms256m -Xmx256m 改为 -Xms512m -Xmx512m。

4.3 校验编排文件

cd /opt/data/ignite-compose && docker compose config

真实回显（节选）：

name: ignite-compose-demo
services:
  ignite-server:
    container_name: ignite-server
    environment:
      CONFIG_URI: /opt/ignite/apache-ignite/config/default-config.xml
      JVM_OPTS: -Xms256m -Xmx256m -server -XX:MaxMetaspaceSize=128m
    hostname: ignite-server
    image: apacheignite/ignite:2.18.0
    networks:
      default: null
    ports:
      - mode: ingress
        target: 10800
        published: "10800"
        protocol: tcp
      - ... (47100/47500/11211 同理 省略)
    restart: unless-stopped
    volumes:
      - type: bind
        source: /opt/data/quzuo/.ignite-compose-demo/work
        target: /opt/ignite/apache-ignite/work
        bind: {}
      - type: bind
        source: /opt/data/quzuo/.ignite-compose-demo/config
        target: /opt/ignite/apache-ignite/config
        read_only: true
        bind: {}

4.4 启动服务

cd /opt/data/ignite-compose && docker compose up -d

查看运行状态：

docker compose ps

4.5 观察启动日志

docker compose logs -f ignite-server

真实回显（本次实测容器直接运行时）：

[XX:XX:XX] ver. 2.18.0#20260423-sha1:d49adada
[XX:XX:XX] Data Regions Started: 3
[XX:XX:XX] Ignite node started OK (id=cf7aa97a)
[XX:XX:XX] Topology snapshot [ver=1, locNode=cf7aa97a, servers=1, clients=0, state=ACTIVE, CPUs=6, offheap=9.4GB, heap=1.0GB]

⚠️ 注意：不设置 JVM_OPTS 时镜像默认堆为 1.0GB（上例）。加入 -Xms256m -Xmx256m 后日志变为 heap=0.25GB，且启动会提示 Initial heap size is 256MB (should be no less than 512MB...) 建议性告警（不影响运行）；如需消除可改用 512MB。

五、数据持久化说明

./work:/opt/ignite/apache-ignite/work：把运行时数据与日志（work/log/、work/data/）落到宿主机目录，节点重启后日志与持久化数据不丢。
./config:/opt/ignite/apache-ignite/config:ro：以只读方式挂载配置目录，替换镜像内的默认 /opt/ignite/apache-ignite/config，实现“配置挂载”。
若使用 .zip 手动部署的 Ignite，其持久化开启方式与目录结构一致，此处容器化仅是把 work、config 通过 bind mount 外置。

六、常用环境变量表

环境变量	作用	默认值
`JVM_OPTS`	JVM 启动参数（堆、元空间等）	`-Xms1g -Xmx1g -server -XX:MaxMetaspaceSize=256m`
`CONFIG_URI`	指定节点配置文件（对应真实服务器 `-config` 参数）	`config/default-config.xml`
`OPTION_LIBS`	逗号分隔的可选模块（如 `ignite-rest-http`）	空
`JAVA_HOME`	镜像内已内置	`/opt/java/openjdk`
`IGNITE_HOME`	Ignite 安装根目录	`/opt/ignite/apache-ignite`

⚠️ 注意：镜像入口 run.sh 对 OPTION_LIBS 的处理是遍历 libs/optional/<模块> 目录加入 classpath；若指定不存在的模块会报 classpath 错误。默认不设置即使用默认配置。

七、常用配置参数说明（command / 入口行为）

官方镜像默认以 run.sh 作为入口（Cmd = /bin/sh -c $IGNITE_HOME/run.sh），无需在 compose 中写 command。若希望覆盖启动命令，可在 command: 中覆盖，例如仍用 run.sh 且显式指定配置：

    command:
      - /bin/sh
      - -c
      - $IGNITE_HOME/run.sh

常用 JVM 注入（等价真机修改 bin/ignite.sh）：

目标	compose 写法（environment）	等价真机
限制堆到 256MB	`JVM_OPTS=-Xms256m -Xmx256m -server -XX:MaxMetaspaceSize=128m`	`bin/ignite.sh` 第 92 行修改堆
指定配置文件	`CONFIG_URI=/opt/ignite/apache-ignite/config/ignite-config.xml`	启动时 `config/ignite-config.xml` 参数
启动可选模块	`OPTION_LIBS=ignite-rest-http,ignite-control-utility`	引入 `libs/optional` 模块

八、配置文件持久化（conf 挂载）

把专用于容器化部署的 ignite-config.xml 放到 /opt/data/ignite-compose/config/ignite-config.xml，再配合 CONFIG_URI 指向它：

    environment:
      - CONFIG_URI=/opt/ignite/apache-ignite/config/ignite-config.xml
      - JVM_OPTS=-Xms256m -Xmx256m -server -XX:MaxMetaspaceSize=128m
    volumes:
      - ./work:/opt/ignite/apache-ignite/work
      - ./config:/opt/ignite/apache-ignite/config:ro

config/ignite-config.xml（单节点、绑定本机、纯内存、预置缓存）：

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd">
    <bean id="grid.cfg" class="org.apache.ignite.configuration.IgniteConfiguration">
        <property name="igniteInstanceName" value="ignite-server-01"/>
        <property name="consistentId" value="node1"/>
        <property name="localHost" value="127.0.0.1"/>
        <property name="peerClassLoadingEnabled" value="true"/>
        <property name="dataStorageConfiguration">
            <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
                <property name="defaultDataRegionConfiguration">
                    <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                        <property name="name" value="default"/>
                        <property name="initialSize" value="#{256L * 1024 * 1024}"/>
                        <property name="maxSize" value="#{1L * 1024 * 1024 * 1024}"/>
                    </bean>
                </property>
            </bean>
        </property>
        <property name="cacheConfiguration">
            <list>
                <bean class="org.apache.ignite.configuration.CacheConfiguration">
                    <property name="name" value="config-cache"/>
                    <property name="backups" value="1"/>
                </bean>
            </list>
        </property>
    </bean>
</beans>

改完配置后重启生效：

cd /opt/data/ignite-compose
docker compose up -d --force-recreate ignite-server
docker compose logs -f ignite-server

九、等价 docker run 运行方式

如果不用 compose，等价的一次性启动命令为：

docker run -d \
  --name ignite-server \
  --hostname ignite-server \
  --restart unless-stopped \
  -p 10800:10800 -p 47100:47100 -p 47500:47500 -p 11211:11211 \
  -e CONFIG_URI=/opt/ignite/apache-ignite/config/default-config.xml \
  -e JVM_OPTS="-Xms256m -Xmx256m -server -XX:MaxMetaspaceSize=128m" \
  -v /opt/data/ignite-compose/work:/opt/ignite/apache-ignite/work \
  -v /opt/data/ignite-compose/config:/opt/ignite/apache-ignite/config:ro \
  apacheignite/ignite:2.18.0

验证堆限制生效（进入容器看 jps -v 与拓扑 heap）：

docker exec ignite-server /opt/java/openjdk/bin/jps -v

真实回显（节选）：

XXXX CommandLineStartup -DIGNITE_QUIET=true ... -Xms256m -Xmx256m -XX:MaxMetaspaceSize=128m ...

对应日志中的拓扑回显为 heap=0.25GB，确认限制生效。

十、常用运维命令

cd /opt/data/ignite-compose

docker compose up -d            # 启动
docker compose ps               # 查看状态
docker compose logs -f ignite-server   # 跟踪日志
docker compose restart ignite-server   # 重启
docker compose down             # 停止并删除容器(保留 work/config 挂载目录)

节点内执行 Ignite 自带工具（类似真机 control.sh/sqlline.sh）：

# 集群基线状态
docker exec -it ignite-server /opt/ignite/apache-ignite/bin/control.sh --baseline

# SQL 客户端连接(走本机 10800)
docker exec -it ignite-server /opt/ignite/apache-ignite/bin/sqlline.sh \
  -u "jdbc:ignite:thin://127.0.0.1:10800" -n admin -p q1w2e3r4

十一、常见问题（FAQ）

Q1：docker compose up 报“invalid hostPort”？ 宿主机端口需在 1~65535 之间，如 210800 这类超范围值会报 docker: invalid hostPort。改用合法端口（如 10805:10800）再映射。

Q2：启动日志一直是“默认堆 1.0GB”？ 说明 JVM_OPTS 未注入成功。确认 compose 里 environment 的 JVM_OPTS 写法为数组或 map 且名称正确；改后 docker compose up -d --force-recreate 重建容器。

Q3：把 OPTION_LIBS 设错导致启动失败？ run.sh 要求模块目录存在于 libs/optional/<模块>。先 docker exec ignite-server ls /opt/ignite/apache-ignite/libs/optional 确认模块名，再修改 compose。

Q4：数据/日志重启后变空？ 确认 ./work 挂载路径与镜像内 IGNITE_HOME/work 一致，且宿主机 /opt/data/ignite-compose/work 已创建；bind mount 会把空目录直接覆盖，需保证 config 只读挂载且内含有效配置文件。

Q5：如何持久化 XD 的 Ignite 内存数据？ 默认 persistence=false 为纯内存，容器删除即丢。需在配置里把对应 DataRegionConfiguration 设 persistenceEnabled=true（并配合 ./work 持久化），这才是真正的落盘持久化。

十二、参考链接

官方 Docker 镜像：docker.io/apacheignite/ignite（Docker Hub：https://hub.docker.com/r/apacheignite/ignite）
Apache Ignite 官网：https://ignite.apache.org
Ignite 2.18.0 归档：https://archive.apache.org/dist/ignite/2.18.0/
容器运行说明（run.sh / 环境变量）：https://ignite.apache.org/docs/latest/installation/using-docker