Apache Ignite 配置参数详解

目标：系统讲解 Apache Ignite 2.18.0 的配置载体（config/ignite-config.xml）与关键参数，覆盖参数查看/修改方式、参数总览、节点/网络/数据区域/缓存/持久化/内存等分类详解、生产配置模板与常见问题。所引默认值与生效回显均来自 Ubuntu 22.04 单节点实测。相关命令需在已按《Ubuntu 22.04 安装 Apache Ignite 2.18.0 指南》安装好的环境上执行（部署目录 /opt/data/ignite/apache-ignite-2.18.0）。

一、环境信息

部署版本：Apache Ignite 2.18.0（2.18.0#20260423-sha1:d49adada）
部署目录：/opt/data/ignite/apache-ignite-2.18.0
配置文件：/opt/data/ignite/apache-ignite-2.18.0/config/ignite-config.xml
JDK：OpenJDK 11.0.32.1，JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
JVM 堆：-Xms512m -Xmx512m
端口实测：10800（瘦客户端/JDBC）、47101（通信）、47500（发现）、11211（Memcached）
数据区域实测：默认区域 initCfg=256MB / maxCfg=1024MB，内部区域 sysMemPlc、volatileDsMemPlc 各 40MB/100MB，offheap=1.0GB

二、前置条件

已按安装指南完成 Ignite 2.18.0 部署且节点处于运行状态（Topology snapshot ... state=ACTIVE）。
修改配置后需重启节点生效；重启命令见《安装指南》九、或下方“修改方式”。

三、参数查看与修改方式

3.1 查看当前配置

配置文件即 config/ignite-config.xml，直接查看：

cd /opt/data/ignite/apache-ignite-2.18.0
cat config/ignite-config.xml

3.2 运行期参数/状态查看

运行期参数无法在线改，但可通过 control.sh、端口、拓扑日志确认生效值：

cd /opt/data/ignite/apache-ignite-2.18.0
export IGNITE_HOME=/opt/data/ignite/apache-ignite-2.18.0
./bin/control.sh --baseline

ss -tln | grep -E '10800|11211|47101|47500'

/usr/lib/jvm/java-11-openjdk-amd64/bin/jps -v | grep CommandLineStartup | grep -oE '\-Xm[sx][0-9a-z]+'

3.3 修改方式

编辑 config/ignite-config.xml 后重建/重启节点生效；JVM 相关参数直接改 bin/ignite.sh 的 JVM_OPTS（第 92 行），改完用 jps -v 复核。

# 修改配置文件(示例)
vi /opt/data/ignite/apache-ignite-2.18.0/config/ignite-config.xml
# 重启节点
export IGNITE_HOME=/opt/data/ignite/apache-ignite-2.18.0
pkill -f CommandLineStartup && sleep 3
nohup ./bin/ignite.sh config/ignite-config.xml > /opt/data/ignite/ignite-console.log 2>&1 &

💡 说明：部分可选参数模块化，需先在 libs/optional/ 引入对应 JAR（如 REST）再重启；安全/认证参数见第八节说明。

四、参数总览

分类	关键属性	作用	实测/默认值
节点	`igniteInstanceName`	节点名称，用于日志/实例标识	`ignite-server-01`（默认不设）
节点	`consistentId`	集群中稳定标识本节点	`node1`
节点	`localHost`	节点的本地绑定地址	绑定时 `127.0.0.1`
网络	TcpDiscoverySpi	发现端口	监听 `47500`
网络	TcpCommunicationSpi	通信端口	监听 `47101`
瘦客户端	监听器（ClientListener）	瘦客户端/JDBC 端口	`10800`
Memcached	监听器	Memcached 协议端口	`11211`
内存	`dataStorageConfiguration`	数据区域(off-heap)配置	见 5.x
数据区域	`defaultDataRegionConfiguration.maxSize`	默认区域最大容量	实测最大 `1024MB`
缓存	`cacheConfiguration`	启动即创建的缓存	`config-cache`
持久化	`DataRegionConfiguration.persistenceEnabled`	是否落盘持久化	实测默认 `false`
部署	`peerClassLoadingEnabled`	是否对等类加载	`true`

说明：官方 config/ignite-config.xml 用 Spring <beans> 描述，绝大多数参数以 <property name="igniteInstanceName" value="ignite-server-01"/> 这类 name/value 表达，或嵌套子 <bean> 表达。

五、核心参数分类详解

5.1 节点与身份段

<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"/>

igniteInstanceName：节点实例名，默认不设；设置后日志出现 instance name=ignite-server-01，便于区分同机多节点。
consistentId：一致性 ID，默认取主机名+网卡信息；显式设置后在 control.sh --baseline 中显示为 ConsistentId=node1（实测）。
localHost：本地绑定地址，默认全接口；单机测试常用 127.0.0.1，多节点组网需改为内网地址。
peerClassLoadingEnabled：默认 false；置 true 后同一集群各节点 peerClassLoading 必须一致，否则错误 Remote node has peer class loading enabled flag different from local（实测）。

5.2 网络段（发现/通信/瘦客户端端口）

Ignite 通过 SPI（TcpDiscoverySpi、TcpCommunicationSpi）与瘦客户端监听器管理端口。启动后实测监听如下：

LISTEN 0  50  [::ffff:127.0.0.1]:47500   *:*
LISTEN 0  50  [::ffff:127.0.0.1]:47101   *:*
LISTEN 0  50  [::ffff:127.0.0.1]:10800   *:*
LISTEN 0  50  [::ffff:127.0.0.1]:11211   *:*

端口	默认范围	归属	说明
`47500`	`47500-47510`	TcpDiscovery	集群节点互发现
`47100`（实测 `47101`）	`47100-47110`	TcpCommunication	节点间数据/任务通信
`10800`	`10800`	ClientListener	瘦客户端 / JDBC
`11211`	`11211`	监听器	Memcached 协议兼容

连接地址（真机）：jdbc:ignite:thin://<服务器IP或localhost>:10800。

5.3 内存与数据区域段（off-heap）

dataStorageConfiguration 定义 NamedCache/数据区域，默认区域实测回显如下：

Data Regions Started: 3
    default region [type=default, persistence=false, lazyAlloc=true,
      ...  initCfg=256MB, maxCfg=1024MB, usedRam=0MB, freeRam=100%, allocRam=0MB]
    sysMemPlc region [type=internal, persistence=false, ..., initCfg=40MB, maxCfg=100MB]
    volatileDsMemPlc region [type=user, persistence=false, ..., initCfg=40MB, maxCfg=100MB]
Off-heap memory [used=16MB, free=98.62%, allocated=296MB]

关键配置（放在 dataStorageConfiguration 内）：

<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>

initialSize：区域初始分配量（实测 256MB）。
maxSize：区域最大容量（实测 1024MB）；对应拓扑日志 offheap=1.0GB。
persistenceEnabled（在 DataRegionConfiguration 上）：是否落盘，实测默认 false（persistence=false）。
sysMemPlc / volatileDsMemPlc：系统内部与易失（volatile）区域，一般无需改动。

5.4 缓存段

<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>

name：缓存名；也可运行时用 IgniteClient.getOrCreateCache("name") 动态创建。
backups：副本数，布到多个节点时该值为 1 表示保留 1 份备份，默认 0。
cacheMode：PARTITIONED（默认）/ REPLICATED / LOCAL，分区模式是按 key 分布存储。

注：通过 SQL CREATE TABLE ... WITH "CACHE_NAME=City,..." 建的缓存相当于运行时创建的缓存组，自行建表时 maxSize 默认沿用默认区域。

5.5 持久化段

配置在 DataRegionConfiguration 上：<property name="persistenceEnabled" value="true"/>。
开启后启用 WAL，数据落盘到 IGNITE_HOME/work/db 及 work/db/wal。
落盘数据只有配置了持久化的区域才保留；纯内存区域重启即清空。
开启持久化后 control.sh --baseline 会出现 Baseline 语义（把基线固定为持久化数据集）。

六、JVM 堆与元空间限制

bin/ignite.sh 第 92 行控制 JVM 内存（详见安装指南七、）：

JVM_OPTS="${JVM_OPTS} -Xms512m -Xmx512m -server -XX:MaxMetaspaceSize=256m"

-Xms / -Xmx：堆初始/最大 512MB（256–512MB 要求区间上沿，避免告警）。
-XX:MaxMetaspaceSize=256m：元空间上限。
生效复核：jps -v 输出包含 -Xms512m -Xmx512m -XX:MaxMetaspaceSize=256m（实测）。

七、生产配置模板（16GB 内存 / NVMe SSD / OLTP 场景）

单实例 OLTP 场景（内存主要给 off-heap 数据区域）：

<?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="prod-ignite-01"/>
        <property name="consistentId" value="prod-node1"/>
        <property name="localHost" value="192.168.10.11"/>
        <property name="peerClassLoadingEnabled" value="false"/>
        <property name="dataStorageConfiguration">
            <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
                <!-- OLTP 高频小对象:默认区域 8GiB、落盘启用,WAL 到 NVMe -->
                <property name="defaultDataRegionConfiguration">
                    <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
                        <property name="name" value="default"/>
                        <property name="initialSize" value="#{2L * 1024 * 1024 * 1024}"/>
                        <property name="maxSize" value="#{8L * 1024 * 1024 * 1024}"/>
                        <property name="persistenceEnabled" value="true"/>
                    </bean>
                </property>
                <property name="walPath" value="/data/ignite/wal"/>
                <property name="walArchivePath" value="/data/ignite/wal-archive"/>
            </bean>
        </property>
        <property name="cacheConfiguration">
            <list>
                <bean class="org.apache.ignite.configuration.CacheConfiguration">
                    <property name="name" value="order"/>
                    <property name="backups" value="1"/>
                </bean>
            </list>
        </property>
    </bean>
</beans>

配套 JVM（bin/ignite.sh 第 92 行）：

JVM_OPTS="${JVM_OPTS} -Xms512m -Xmx512m -server -XX:MaxMetaspaceSize=256m"

💡 适用说明：16GB 内存机型建议 -Xmx512m（堆） + 数据区域 8GiB off-heap；/data/ignite/wal 放 NVMe SSD。若集群规模 >1 节点，还需为每个节点分别配置 localHost 与内网端口，并通过 TcpDiscovery 组网。

八、说明与安全参数

认证：dataStorageConfiguration 与节点层 AuthenticationEnabled（在 IgniteConfiguration 上配置 auth），默认关闭（实测 Security status [authentication=off]）；生产建议开启并配置统一的 admin（密码示例 q1w2e3r4，生产务必更换）。
Attach/Marshaller：默认 BinaryMarshaller；开启对等类加载或使用 Java 类时注意类加载一致性。
SSL/TLS：涉及 IgniteSslContextFactory，需要单独提供证书与密钥，本文不展开。

九、常见问题

Q1：peerClassLoadingEnabled 改动后节点连不起来？ Remote node has peer class loading enabled flag different from local（实测错误）。集群内所有节点（含客户端）该配置必须一致，统一改成 true 或 false 再重启。

Q2：改了 maxSize 后拓扑日志不变？ 数据区域 maxSize 只能在 cache 数据存在前/启动前确定，运行时多数参数不可在线改。确认改的是 config/ignite-config.xml 绑定启动的那个文件，且重启了节点。

Q3：通信端口为什么是 47101 而不是 47100？ 端口分配是 47100-47110 范围按需占用，同机并发实例会递增使用。以 ss -tln 实测为准，连接配置按实际监听端口。

Q4：想限制 JVM 堆但 jps -v 不见 -Xms/-Xmx？ parseargs.sh 已把 JVM_OPTS 置为非空，若修改落在 if [ -z "$JVM_OPTS" ] 分支内不生效。需用无条件追加 JVM_OPTS="${JVM_OPTS} -Xms512m -Xmx512m ..."。

Q5：内存区域上限设得比 JVM 堆还大安全吗？ 安全。off-heap 数据区域独立于 JVM 堆，maxSize 是数据区域上限，JVM 堆上限由 -Xmx 单独约束；两者合计需小于物理内存，否则开持久化/大区域时可能 OOM。

十、参考链接

Ignite 配置参考：https://ignite.apache.org/docs/latest/configuring-cluster
内存架构与调优：https://ignite.apache.org/docs/latest/perf-and-troubleshooting/memory-tuning
官方示例配置：/opt/data/ignite/apache-ignite-2.18.0/config/default-config.xml 与 docs/