Ignite配置入门

1.配置方式

本章节会介绍在Ignite集群中设定配置参数的不同方式。

.NET、Python、Node.js等其他语言的配置

• .NET开发者：请参见.NET配置相关章节的介绍；
• Python、Node.js等其他语言开发者：请参见瘦客户端中相关章节的内容。

1.1.概述

可以通过在启动节点时向Ignite提供IgniteConfiguration类的实例来指定自定义配置参数。使用编程方式或通过XML配置文件都可以，这两种方式是完全可以互换的。

XML配置文件是必须包含IgniteConfigurationbean的Spring Bean定义文件。从命令行启动节点时，可以将配置文件作为参数传递给ignite.sh|bat脚本，如下所示：

ignite.sh ignite-config.xml

如果未指定配置文件，会使用默认文件{IGNITE_HOME}/config/default-config.xml。

1.2.基于Spring的XML配置

要创建一个Spring XML格式的配置文件，需要定义一个IgniteConfigurationbean，然后配置不同于默认值的参数，关于如何使用基于XML模式的配置的更多信息，可以看官方的Spring文档。

在下面的示例中，创建了IgniteConfigurationbean，配置了workDirectory属性，然后配置了一个分区模式的缓存。

<?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 class="org.apache.ignite.configuration.IgniteConfiguration">
        <property name="workDirectory" value="/path/to/work/directory"/>

        <property name="cacheConfiguration">
            <bean class="org.apache.ignite.configuration.CacheConfiguration">
                <!-- Set the cache name. -->
                <property name="name" value="myCache"/>
                <!-- Set the cache mode. -->
                <property name="cacheMode" value="PARTITIONED"/>
                <!-- Other cache parameters. -->
            </bean>
        </property>
    </bean>
</beans>

1.3.编程式配置

创建一个IgniteConfiguration类的实例，然后配置必要的参数，如下所示：

IgniteConfiguration igniteCfg = new IgniteConfiguration();
//setting a work directory
igniteCfg.setWorkDirectory("/path/to/work/directory");

//defining a partitioned cache
CacheConfiguration cacheCfg = new CacheConfiguration("myCache");
cacheCfg.setCacheMode(CacheMode.PARTITIONED);

igniteCfg.setCacheConfiguration(cacheCfg);

var igniteCfg = new IgniteConfiguration
{
    WorkDirectory = "/path/to/work/directory",
    CacheConfiguration = new[]
    {
        new CacheConfiguration
        {
            Name = "myCache",
            CacheMode = CacheMode.Partitioned
        }
    }
};

IgniteConfiguration cfg;

cfg.igniteHome = "/path/to/work/directory";

完整参数的列表，可以参见IgniteConfiguration的javadoc。

2.Ignite Java配置

.NET、Python、Node.js等其他语言的配置

• .NET开发者：请参见.NET配置相关章节的介绍；
• Python、Node.js等其他语言开发者：请参见瘦客户端中相关章节的内容。

2.1.环境要求

Apache Ignite官方在如下环境中进行了测试：

• JDK：Oracle JDK8、11或17，Open JDK8、11或17，IBM JDK8、11或17；
• OS：Linux（任何版本），Mac OS X（10.6及以上），Windows(XP及以上)，Windows Server（2008及以上），Oracle Solaris；
• 网络：没有限制（建议10G甚至更快的网络带宽）；
• 架构：x86，x64，SPARC，PowerPC。

2.2.在Java11及后续版本中使用Ignite

要在Java11及后续版本中运行Ignite，需按照如下步骤操作：

1. 配置JAVA_HOME环境变量，指向Java的安装目录；

2. Ignite使用了专有的SDK API，这些API默认并未开启，因此需要向JVM传递额外的专有标志来让这些API可用。如果使用的是ignite.sh或者ignite.bat，那么什么都不需要做，因为脚本已经提前配置好了，否则就需要向应用的JVM添加下面的参数：

   --add-exports=java.base/jdk.internal.misc=ALL-UNNAMED
   --add-exports=java.base/sun.nio.ch=ALL-UNNAMED
   --add-exports=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED
   --add-exports=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED
   --add-exports=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED
   --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED
   --illegal-access=permit
   

   --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED \
   --add-opens=java.base/jdk.internal.misc=ALL-UNNAMED \
   --add-opens=java.base/sun.nio.ch=ALL-UNNAMED \
   --add-opens=java.management/com.sun.jmx.mbeanserver=ALL-UNNAMED \
   --add-opens=jdk.internal.jvmstat/sun.jvmstat.monitor=ALL-UNNAMED \
   --add-opens=java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED \
   --add-opens=java.base/java.io=ALL-UNNAMED \
   --add-opens=java.base/java.nio=ALL-UNNAMED \
   --add-opens=java.base/java.util=ALL-UNNAMED \
   --add-opens=java.base/java.util.concurrent=ALL-UNNAMED \
   --add-opens=java.base/java.util.concurrent.locks=ALL-UNNAMED \
   --add-opens=java.base/java.lang=ALL-UNNAMED
   

2.3.使用二进制包

• 下载最新版本的Ignite压缩包；
• 将该包解压到操作系统的一个文件夹；
• （可选）配置IGNITE_HOME环境变量或者Windows的PATH指向Ignite的安装文件夹，路径不要以/（Windows为\）结尾。

2.4.使用Maven

使用Ignite的最简单的方式是将其加入项目的pom.xml文件。

<properties>
    <ignite.version>2.15.0</ignite.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.apache.ignite</groupId>
        <artifactId>ignite-core</artifactId>
        <version>${ignite.version}</version>
    </dependency>
</dependencies>

ignite-core模块包含了Ignite的核心功能，其他的功能都是由各种Ignite模块提供的。

下面两个是最常用的模块：

• ignite-spring：支持基于XML的配置；
• ignite-indexing：支持SQL索引。

<dependency>
    <groupId>org.apache.ignite</groupId>
    <artifactId>ignite-spring</artifactId>
    <version>${ignite.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.ignite</groupId>
    <artifactId>ignite-indexing</artifactId>
    <version>${ignite.version}</version>
</dependency>

2.5.使用Docker

如果希望在Docker环境中运行Ignite，请参见Docker部署章节的内容。

2.6.配置工作目录

Ignite会使用一个工作目录来保存应用的数据（如果使用了原生持久化功能）、索引文件、元数据信息、日志以及其他文件，默认的工作目录为：

• $IGNITE_HOME/work：如果定义了IGNITE_HOME系统属性，如果使用二进制包的bin/ignite.sh脚本启动，就是这种情况；
• ./ignite/work：这个路径相对于应用启动时的目录。

修改默认的工作目录有几种方式：

• 环境变量方式：

export IGNITE_WORK_DIR=/path/to/work/directory

• 在节点的配置中：

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="workDirectory" value="/path/to/work/directory"/>
    <!-- other properties -->
</bean>

IgniteConfiguration igniteCfg = new IgniteConfiguration();
igniteCfg.setWorkDirectory("/path/to/work/directory");

var cfg = new IgniteConfiguration
{
    WorkDirectory = "/path/to/work/directory"
};

IgniteConfiguration cfg;

cfg.igniteHome = "/path/to/work/directory";

2.7.启用模块

Ignite包含了很多的模块和扩展，提供了各种各样的功能，开发者可以根据需要，一个个引入。

Ignite的二进制包里面包含了所有的模块，但是默认都是禁用的（除了ignite-core、ignite-spring、ignite-indexing模块），可选库位于二进制包的libs/optional文件夹，每个模块是一个单独的子目录。

另外，可以下载任意需要的扩展。

根据使用Ignite的方式，可以使用下述方式之一启用模块/扩展：

• 如果使用的是二进制包，那么可以在启动节点之前将libs/optional/{module-dir}移动到libs目录；
• 将libs/optional/{module-dir}中的库文件加入应用的类路径；
• 将一个模块添加到工程的依赖中：

<dependency>
    <groupId>org.apache.ignite</groupId>
    <artifactId>ignite-log4j2</artifactId>
    <version>${ignite.version}</version>
</dependency>

下面的模块有LGPL依赖，因此无法部署在Maven中央仓库中：

• ignite-hibernate（Apache Ignite扩展）；
• ignite-geospatial（Apache Ignite扩展）；
• ignite-schedule（废弃）。

要使用这些模块，需要从源代码进行构建然后添加到工程中，比如要将ignite-hibernate模块安装到本地仓库并创建二进制包，可以在Ignite的源代码包中执行下面的命令：

mvn clean install -DskipTests -f modules/hibernate-ext -Pextension-release

下面的模块都是可用的：

模块的构件	描述
ignite-cassandra-serializers	该模块提供了在Cassandra中将对象保存为BLOB格式的附加序列化器，该模块可以和Ignite的Cassandra存储模块一起使用。
ignite-cassandra-store	该模块提供了一个基于Cassandra数据库的CacheStore实现。
ignite-direct-io	该模块提供了一个以O_DIRECT模式进行缓存分区读写的页面存储。
ignite-indexing	SQL查询和索引。
ignite-jcl	支持Jakarta Common Logging (JCL)框架。
ignite-jta	Ignite事务与JTA的集成。
ignite-kubernetes	Ignite Kubernetes模块提供了一个基于TCP发现的IP探测器，其使用专用的Kubernetes服务来查找由Kubernetes容器化的Ignite Pod的IP地址。
ignite-log4j2	支持log4j2。
ignite-ml	Ignite的机器学习模块，其提供了机器学习功能以及线性代数的相关数据结构和方法，包括堆内和堆外，密集和稀疏，本地和分布式实现。详细信息请参见机器学习文档。
ignite-rest-http	该模块在节点内启动了一个基于Jetty的服务器，该服务器可用于在集群中使用基于HTTP的RESTful API执行任务和/或缓存命令。
ignite-schedule	该模块提供了在本地节点使用基于UNIX CRON表达式语法的作业调度能力。
ignite-slf4j	支持SLF4J日志框架。
ignite-urideploy	提供了从不同来源（例如文件系统、HTTP甚至电子邮件）部署任务的功能。
ignite-visor-console	开源的命令行管理和监控工具。
ignite-web	该模块允许基于Servlet和Servlet上下文监听器在任何Web容器内启动节点。此外该模块还提供了将Web会话缓存在Ignite缓存中的功能。
ignite-zookeeper	ZooKeeper发现实现。

可用的扩展如下：

扩展的构件ID	描述
ignite-aop-ext	Ignite AOP模块通过添加@Gridify注解，可以将任何Java方法转换为分布式闭包
ignite-aws-ext	基于AWS S3的集群发现
ignite-azure-ext	基于Azure Blob存储的集群发现
ignite-cloud-ext	该模块提供了TCP发现中IP探测器的Apache Jclouds实现
ignite-osgi-ext	该模块提供了桥接组件，以使Ignite可以在OSGi容器（例如Apache Karaf）内无缝运行
ignite-osgi-karaf-ext	模块包含功能特性库，以方便将Ignite安装到Apache Karaf容器中
ignite-gce-ext	基于Google云存储的集群发现
ignite-spark-ext	该模块提供了SparkRDD抽象的实现，可轻松访问Ignite缓存
ignite-spring-data-ext	Ignite与Spring Data框架的集成
ignite-spring-data_2.0-ext	Ignite与Spring Data2.0框架的集成
ignite-spring-data_2.2-ext	Ignite与Spring Data2.2框架的集成
ignite-zookeeper-ip-finder-ext	使用ZooKeeper的TCP发现IP探测器，其会使用ZooKeeper目录来定位要接入的其他Ignite节点的
ignite-ssh-ext	该模块提供了通过SSH在远程主机上启动Ignite节点的功能

2.8.配置JVM选项

当通过ignite.sh脚本启动节点时，设置JVM参数有几个方法，这些方法下面的章节会介绍。

2.8.1.JVM_OPTS系统变量

可以配置JVM_OPTS环境变量：

export JVM_OPTS="$JVM_OPTS -Xmx6G -DIGNITE_TO_STRING_INCLUDE_SENSITIVE=false"; $IGNITE_HOME/bin/ignite.sh

2.8.2.命令行参数

还可以通过-J前缀传递JVM参数：

./ignite.sh -J-Xmx6G -J-DIGNITE_TO_STRING_INCLUDE_SENSITIVE=false

.\ignite.bat -J-Xmx6G -J-DIGNITE_TO_STRING_INCLUDE_SENSITIVE=false

2.9.配置Ignite系统属性

除了公开的配置参数，还可以使用内部系统属性来调整某个（通常是底层的）Ignite行为。可以使用以下命令找到所有属性及其说明和默认值：

./ignite.sh -systemProps

.\ignite.bat -systemProps

输出示例：

ignite.sh -systemProps
IGNITE_AFFINITY_HISTORY_SIZE                                    - [Integer] Maximum size for affinity assignment history. Default is 25.
IGNITE_ALLOW_ATOMIC_OPS_IN_TX                                   - [Boolean] Allows atomic operations inside transactions. Default is true.
IGNITE_ALLOW_DML_INSIDE_TRANSACTION                             - [Boolean] When set to true, Ignite will allow executing DML operation (MERGE|INSERT|UPDATE|DELETE) within transactions for non MVCC mode. Default is false.
IGNITE_ALLOW_START_CACHES_IN_PARALLEL                           - [Boolean] Allows to start multiple caches in parallel. Default is true.
...

2.10.配置建议

以下是一些推荐的配置技巧，旨在使开发者更轻松地操作Ignite集群或使用Ignite开发应用。

配置工作目录

如果要使用二进制包或Maven，建议为Ignite设置工作目录。工作目录用于存储元数据信息、索引文件、应用程序数据（如果使用原生持久化功能）、日志和其他文件。建议一定要设置工作目录。

建议的日志配置

日志在故障排除和查找错误方面起着重要作用，以下是有关如何管理日志文件的一些一般提示：

• 以verbose模式启动Ignite；

  • 如果使用ignite.sh，请指定-v选项；
  • 如果从Java代码启动Ignite，请设置IGNITE_QUIET=false系统变量；

• 不要将日志文件存储在/tmp文件夹中，每次重启服务器时都会清除此文件夹；

• 确保在存储日志文件的磁盘上有足够的可用空间；

• 定期存档旧的日志文件以节省存储空间。

3.配置日志

3.1.概述

Ignite支持各种常见的日志库和框架：

• JUL (默认)；
• Log4j2；
• JCL；
• SLF4J。

本章节会介绍如何使用它们。

Ignite节点启动之后，会在控制台中输出启动信息，包括了配置的日志库信息。每个日志库都有自己的配置参数，需要分别进行配置。除了库特有的配置，还有一些系统属性可以对日志进行调整，如下表所示：

系统属性	描述	默认值
IGNITE_LOG_INSTANCE_NAME	如果该属性存在，Ignite会在日志消息中包含实例名	未配置
IGNITE_QUIET	配置为false可以禁用静默模式，启用详细模式，其会输出更多的信息	true
IGNITE_LOG_DIR	该属性会指定Ignite日志的输出目录	$IGNITE_HOME/work/log
IGNITE_DUMP_THREADS_ON_FAILURE	如果配置为true，在捕获严重错误时会在日志中输出线程堆栈信息	true

3.2.默认日志

Ignite默认会使用java.util.logging（JUL框架），如果节点是通过二进制包的ignite.sh|bat脚本启动，Ignite会使用$IGNITE_HOME/config/java.util.logging.properties作为默认的配置文件，然后将日志写入$IGNITE_HOME/work/log文件夹中的日志文件，要修改这个日志目录，可以使用IGNITE_LOG_DIR系统属性。

如果将Ignite作为应用中的库文件引入，默认的日志配置只包括控制台日志处理器，级别为INFO，可以通过java.util.logging.config.file系统属性提供一个自定义的配置文件。

3.3.使用Log4j2

提示

在使用Log4j之前，需要先启用ignite-log4j2模块。

要使用Log4j2进行日志记录，需要配置IgniteConfiguration的gridLogger属性，如下所示：

<bean class="org.apache.ignite.configuration.IgniteConfiguration" id="ignite.cfg">
    <property name="gridLogger">
        <bean class="org.apache.ignite.logger.log4j2.Log4J2Logger">
            <!-- log4j2 configuration file -->
            <constructor-arg type="java.lang.String" value="log4j2-config.xml"/>
        </bean>
    </property>

    <!-- other properties -->

</bean>

IgniteConfiguration cfg = new IgniteConfiguration();

IgniteLogger log = new Log4J2Logger("log4j2-config.xml");

cfg.setGridLogger(log);

// Start a node.
try (Ignite ignite = Ignition.start(cfg)) {
    ignite.log().info("Info Message Logged!");
}

.NET目前还不支持这个API，需要使用基于XML的配置。

C++目前还不支持这个API，需要使用基于XML的配置。

在上面的配置中，log4j2-config.xml的路径要么是绝对路径，要么是相对路径，可以相对于META-INF，也可以相对于IGNITE_HOME。在Ignite的二进制包中有一个log4j2配置文件的示例（$IGNITE_HOME/config/ignite-log4j.xml）。

提示

Log4j2的配置支持运行时调整，即配置文件的变更会即时生效而不需要重启应用。

提示

log4j2-config.xml默认启用控制台输出的着色。除Windows外，此功能在许多操作系统上都是直接可以用的。如果想在Windows上启用此功能，请按照官方的log4j2说明进行操作。

3.4.使用JCL

提示

在使用Log4j之前，需要先启用ignite-jcl模块。

提示

注意JCL只是简单地将日志消息转发给底层的日志系统，该日志系统是需要正确配置的，更多的信息，请参见JCL官方文档。比如，如果要使用Log4j2，就需要把必要的库文件加入类路径中。

要使用JCL进行日志记录，需要配置IgniteConfiguration的gridLogger属性，如下所示：

<bean class="org.apache.ignite.configuration.IgniteConfiguration" id="ignite.cfg">
    <property name="gridLogger">
        <bean class="org.apache.ignite.logger.jcl.JclLogger">
        </bean>
    </property>

    <!-- other properties -->

</bean>

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setGridLogger(new JclLogger());

// Start a node.
try (Ignite ignite = Ignition.start(cfg)) {
    ignite.log().info("Info Message Logged!");
}

.NET目前还不支持这个API，需要使用基于XML的配置。

C++目前还不支持这个API，需要使用基于XML的配置。

3.5.使用SLF4J

提示

在使用Log4j之前，需要先启用ignite-slf4j模块。

要使用SLF4J进行日志记录，需要配置IgniteConfiguration的gridLogger属性，如下所示：

<bean class="org.apache.ignite.configuration.IgniteConfiguration" id="ignite.cfg">
    <property name="gridLogger">
        <bean class="org.apache.ignite.logger.slf4j.Slf4jLogger">
        </bean>
    </property>

    <!-- other properties -->

</bean>

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setGridLogger(new Slf4jLogger());

// Start a node.
try (Ignite ignite = Ignition.start(cfg)) {
    ignite.log().info("Info Message Logged!");
}

.NET目前还不支持这个API，需要使用基于XML的配置。

C++目前还不支持这个API，需要使用基于XML的配置。

更多的信息，请参见SLF4J用户手册。

3.6.限制敏感信息

日志可以包括缓存数据、系统属性、启动选项等内容。在某些情况下，这些日志可能包含敏感信息。可以通过将IGNITE_TO_STRING_INCLUDE_SENSITIVE系统属性设置为false来阻止将此类信息写入日志。

./ignite.sh -J-DIGNITE_TO_STRING_INCLUDE_SENSITIVE=false

请参见配置JVM选项以了解设置系统属性的不同方式。

3.7.日志配置示例

下面的步骤可以指导开发者配置日志的过程，这个过程会适用大多数场景。

1. 使用Log4j2作为日志框架，使用方式见前述的说明；
2. 如果使用了默认的配置文件（ignite-log4j.xml），需要取消CONSOLEAppender的注释；
3. 在log4j2配置文件中，需要配置日志文件的路径，默认位置为${IGNITE_HOME}/work/log/ignite.log；
4. 使用verbose模式启动节点：
   • 如果使用ignite.sh启动节点，加上-v选项；
   • 如果从Java代码启动节点，需要使用IGNITE_QUIET=false系统变量。

4.资源注入

4.1.概述

Ignite中，预定义的资源都是可以进行依赖注入的，同时支持基于属性和基于方法的注入。任何加注正确注解的资源都会在初始化之前注入相对应的任务、作业、闭包或者SPI。

4.2.基于属性和基于方法

可以通过在一个属性或者方法上加注注解来注入资源。当加注在属性上时，Ignite只是在注入阶段简单地设置属性的值（不会理会该属性的访问修饰符）。如果在一个方法上加注了资源注解，它会访问一个与注入资源相对应的输入参数的类型，如果匹配，那么在注入阶段，就会将适当的资源作为输入参数，然后调用该方法。

Ignite ignite = Ignition.ignite();

Collection<String> res = ignite.compute().broadcast(new IgniteCallable<String>() {
  // Inject Ignite instance.
  @IgniteInstanceResource
  private Ignite ignite;

  @Override
  public String call() throws Exception {
    IgniteCache<Object, Object> cache = ignite.getOrCreateCache(CACHE_NAME);

    // Do some stuff with cache.
     ...
  }
});

public class MyClusterJob implements ComputeJob {
    ...
    private Ignite ignite;
    ...
    // Inject Ignite instance.
    @IgniteInstanceResource
    public void setIgnite(Ignite ignite) {
        this.ignite = ignite;
    }
    ...
}

4.3.预定义的资源

有很多的预定义资源可供注入：

资源	描述
CacheNameResource	由CacheConfiguration.getName()提供，注入缓存名
CacheStoreSessionResource	注入当前的CacheStoreSession实例
IgniteInstanceResource	注入当前的Ignite实例
JobContextResource	注入ComputeJobContext的实例。作业的上下文持有关于一个作业执行的有用的信息。比如，可以获得包含与作业并置的条目的缓存的名字。
LoadBalancerResource	注入ComputeLoadBalancer的实例，注入后可以用于任务的负载平衡。
ServiceResource	通过指定服务名注入Ignite的服务。
SpringApplicationContextResource	注入Spring的ApplicationContext资源。
SpringResource	从Spring的ApplicationContext注入资源，当希望访问在Spring的ApplicationContext XML配置中指定的一个Bean时，可以用它。
TaskContinuousMapperResource	注入一个ComputeTaskContinuousMapper的实例，持续映射可以在任何时点从任务中发布作业，即使过了map的初始化阶段。
TaskSessionResource	注入ComputeTaskSession资源的实例，它为某个任务执行定义了一个分布式的会话。

18624049226