hazelcast/hazelcast-enterprise

Hazelcast Docker

本仓库包含官方Hazelcast Docker镜像的Dockerfile。

快速开始

Hazelcast

可通过以下命令启动Hazelcast Docker容器。请查看Hazelcast版本以替换$HAZELCAST_VERSION。

bash
$ docker run hazelcast/hazelcast:$HAZELCAST_VERSION

该命令将拉取Hazelcast Docker镜像并运行新的Hazelcast实例。

Hazelcast版本

最新版本

• 5, 5-jdk21, 5.6, 5.6-jdk21, 5.6.0, 5.6.0-jdk21, latest, latest-jdk21
• 5-jdk11, 5.3.7, 5.3.7-jdk11, latest-jdk11
• 5-jdk17, 5.6-jdk17, 5.6.0-jdk17, latest-jdk17
• 5-slim, 5-slim-jdk21, 5.6-slim, 5.6-slim-jdk21, 5.6.0-slim, 5.6.0-slim-jdk21, latest-slim, latest-slim-jdk21
• 5-slim-jdk11, 5.3.7-slim, 5.3.7-slim-jdk11, latest-slim-jdk11
• 5-slim-jdk17, 5.6-slim-jdk17, 5.6.0-slim-jdk17, latest-slim-jdk17
• 5.0, 5.0.5
• 5.0-slim, 5.0.5-slim
• 5.1, 5.1.7
• 5.1-slim, 5.1.7-slim
• 5.2, 5.2.5
• 5.2-slim, 5.2.5-slim
• 5.3, 5.3-jdk11, 5.3.8, 5.3.8-jdk11
• 5.3-slim, 5.3-slim-jdk11, 5.3.8-slim, 5.3.8-slim-jdk11
• 5.4, 5.4-jdk21, 5.4.0, 5.4.0-jdk21
• 5.4-slim, 5.4-slim-jdk21, 5.4.0-slim, 5.4.0-slim-jdk21
• 5.5, 5.5-jdk21, 5.5.0, 5.5.0-jdk21
• 5.5-slim, 5.5-slim-jdk21, 5.5.0-slim, 5.5.0-slim-jdk21

完整的Hazelcast版本列表可在https://store.docker.com/community/images/hazelcast/hazelcast/tags查看。

Hazelcast Hello World

对于最简单的端到端场景，可创建包含两个Docker容器的Hazelcast集群，并从客户端应用访问。

bash
$ docker run -e HZ_NETWORK_PUBLICADDRESS=<host_ip>:5701 -p 5701:5701 hazelcast/hazelcast:$HAZELCAST_VERSION
$ docker run -e HZ_NETWORK_PUBLICADDRESS=<host_ip>:5702 -p 5702:5701 hazelcast/hazelcast:$HAZELCAST_VERSION

注意：

• 每个容器必须将5701端口映射到主机的不同端口（示例中为5701和5702）
• 自定义HZ_NETWORK_PUBLICADDRESS对自动发现至关重要，否则Hazelcast将绑定到Docker内部端口
• <host_ip>需为主机地址，用于Hazelcast节点间通信

集群启动后，可启动https://github.com/hazelcast/hazelcast-code-samples/tree/master/clients/basic应用验证是否正常工作。

Hazelcast企业版

可通过以下命令启动Hazelcast企业版Docker容器。请查看Hazelcast企业版版本以替换$HAZELCAST_VERSION。

请此处申请试用许可证或联系***。

bash
$ docker run -e HZ_LICENSEKEY=<your_license_key> hazelcast/hazelcast-enterprise:$HAZELCAST_VERSION

Hazelcast企业版版本

最新版本

• 5, 5-jdk21, 5.6, 5.6-jdk21, 5.6.0, 5.6.0-jdk21, latest, latest-jdk21
• 5-jdk11, latest-jdk11
• 5-jdk17, 5.6-jdk17, 5.6.0-jdk17, latest-jdk17
• 5-slim, 5-slim-jdk21, 5.6-slim, 5.6-slim-jdk21, 5.6.0-slim, 5.6.0-slim-jdk21, latest-slim, latest-slim-jdk21
• 5-slim-jdk11, latest-slim-jdk11
• 5-slim-jdk17, 5.6-slim-jdk17, 5.6.0-slim-jdk17, latest-slim-jdk17
• 5.0, 5.0.5
• 5.0-slim, 5.0.5-slim
• 5.1, 5.1.7
• 5.1-slim, 5.1.7-slim
• 5.2, 5.2.5
• 5.2-slim, 5.2.5-slim
• 5.3, 5.3-jdk11, 5.3.8, 5.3.8-jdk11
• 5.3-slim, 5.3-slim-jdk11, 5.3.8-slim, 5.3.8-slim-jdk11
• 5.4, 5.4-jdk21, 5.4.3, 5.4.3-jdk21
• 5.4-slim, 5.4-slim-jdk21, 5.4.3-slim, 5.4.3-slim-jdk21
• 5.5, 5.5-jdk21, 5.5.7, 5.5.7-jdk21
• 5.5-slim, 5.5-slim-jdk21, 5.5.7-slim, 5.5.7-slim-jdk21
• 5.7.0-SNAPSHOT, 5.7.0-SNAPSHOT-jdk21, latest-snapshot, latest-snapshot-jdk21
• 5.7.0-SNAPSHOT-jdk17, latest-snapshot-jdk17
• 5.7.0-SNAPSHOT-slim, 5.7.0-SNAPSHOT-slim-jdk21, latest-snapshot-slim, latest-snapshot-slim-jdk21
• 5.7.0-SNAPSHOT-slim-jdk17, latest-snapshot-slim-jdk17
• latest-lts, latest-lts-jdk21
• latest-lts-jdk17
• latest-lts-slim
• latest-lts-slim-jdk17
• latest-lts-slim-jdk21

完整的Hazelcast企业版版本列表可在https://store.docker.com/community/images/hazelcast/hazelcast-enterprise/tags查看。

Hazelcast企业版Hello World

运行两个Hazelcast企业版节点，使用以下命令：

bash
$ docker run -p 5701:5701 -e HZ_LICENSEKEY=<your_license_key> -e HZ_NETWORK_PUBLICADDRESS=<host_ip>:5701 hazelcast/hazelcast-enterprise:$HAZELCAST_VERSION
$ docker run -p 5702:5701 -e HZ_LICENSEKEY=<your_license_key> -e HZ_NETWORK_PUBLICADDRESS=<host_ip>:5702 hazelcast/hazelcast-enterprise:$HAZELCAST_VERSION

注意：

• 本示例假设Hazelcast成员和客户端间使用未加密的通信通道。Hazelcast支持加密成员间及客户端与成员间的 socket 级通信，详情请参考此部分启用TLS/SSL加密。

管理中心Hello World

无论启动的是Hazelcast社区版还是企业版集群，均可使用管理中心应用监控和管理集群。

bash
docker run \
  -e MC_INIT_CMD="./bin/hz-mc conf cluster add -H=/data -ma <host_ip>:5701 -cn dev" \
  -p 8080:8080 docker.xuanyuan.run/hazelcast/management-center:$MANAGEMENT_CENTER_VERSION

现在可通过浏览器访问管理中心：https://localhost:8080。更多关于管理中心Docker镜像的信息见https://github.com/hazelcast/management-center-docker。

注意，Hazelcast 4.0起管理中心的启动方式已变更。若使用Hazelcast 3.x，请查看https://github.com/hazelcast/hazelcast-docker/tree/3.12.z的说明。

Hazelcast定义的环境变量

JAVA_OPTS

如下所示，若需向Hazelcast成员传递多个VM参数，可使用JAVA_OPTS环境变量：

bash
$ docker run -e JAVA_OPTS="-Xms512M -Xmx1024M" hazelcast/hazelcast

PROMETHEUS_PORT

JMX Prometheus代理的端口。例如，若设置PROMETHEUS_PORT=8080，则可通过http://<hostname>:8080/metrics访问指标。也可使用PROMETHEUS_CONFIG指定自定义配置路径。

LOGGING_LEVEL

可通过LOGGING_LEVEL变量修改日志级别，例如输出DEBUG日志：

bash
$ docker run -e LOGGING_LEVEL=DEBUG hazelcast/hazelcast

可用日志级别（从高到低）：OFF、FATAL、ERROR、WARN、INFO、DEBUG、TRACE和ALL。默认级别为INFO，无效级别将被视为OFF。

若需更自定义的日志配置，可指定配置文件：

bash
$ docker run -v <config-file-path>:/opt/hazelcast/config/log4j2.properties hazelcast/hazelcast

LOGGING_CONFIG

自版本5.1起

可通过LOGGING_CONFIG变量修改日志配置，例如挂载自定义Log4j2配置文件并通过该变量设置路径。默认值为/opt/hazelcast/config/log4j2.properties，支持相对或绝对路径。

镜像中还提供log4j2-json.properties文件，使用Log4j2的https://logging.apache.org/log4j/2.x/manual/json-template-layout.html模块。使用方法如下：

bash
$ docker run -e LOGGING_CONFIG=log4j2-json.properties hazelcast/hazelcast

更多信息见https://logging.apache.org/log4j/2.x/manual/。

自定义Hazelcast

内存

Hazelcast Docker镜像尊重容器内存限制，可通过-m参数指定：

bash
$ docker run -m 512M hazelcast/hazelcast:$HAZELCAST_VERSION

默认Hazelcast使用容器内存限制的80%，可通过向JAVA_OPTS添加-XX:MaxRAMPercentage调整。

通过环境变量配置Hazelcast

无需修改声明式配置文件（XML/YAML）即可覆盖集群配置项，详见覆盖配置文档章节。

假设需以下YAML配置：

yaml
hazelcast:
  cluster-name: dev
  network:
    port:
      auto-increment: true
      port-count: 100
      port: 5701

使用环境变量表示如下：

bash
$ docker run -e HZ_CLUSTERNAME=dev \
  -e HZ_NETWORK_PORT_AUTOINCREMENT=true \
  -e HZ_NETWORK_PORT_PORTCOUNT=100 \
  -e HZ_NETWORK_PORT_PORT=5701 \
  hazelcast/hazelcast

使用自定义Hazelcast配置文件

若需使用自定义hazelcast.yaml（或hazelcast.xml）配置Hazelcast，可挂载包含配置文件的主机目录，并传递hazelcast.config JVM属性。例如，假设配置文件位于/home/ubuntu/hazelcast/hazelcast.yaml：

bash
$ docker run -e JAVA_OPTS="-Dhazelcast.config=/opt/hazelcast/config_ext/hazelcast.yaml" -v /home/ubuntu/hazelcast:/opt/hazelcast/config_ext hazelcast/hazelcast

也可扩展Hazelcast基础镜像添加自定义配置文件。

扩展CLASSPATH添加JAR或文件

Hazelcast提供多个扩展点（如MapStore API），可通过添加自定义实现扩展功能。若需将自定义JAR或文件添加到容器的classpath，可使用Docker卷并在docker run命令中设置CLASSPATH环境变量。例如，假设自定义JAR位于/home/ubuntu/hazelcast/：

bash
$ docker run -e CLASSPATH="/opt/hazelcast/CLASSPATH_EXT/*" -v /home/ubuntu/hazelcast:/opt/hazelcast/CLASSPATH_EXT hazelcast/hazelcast

也可扩展Hazelcast基础镜像添加自定义JAR。

使用TLS（仅Hazelcast企业版）

HZ_NETWORK_SSL_ENABLED环境变量用于启用通信加密。需挂载密钥材料目录并通过JAVA_OPTS变量引用。

1. 生成示例密钥材料（自签名证书）：

bash
$ mkdir keystore
$ keytool -validity 365 -genkeypair -alias server -keyalg EC -keystore ./keystore/server.keystore -storepass 123456 -keypass 123456 -dname CN=localhost
$ keytool -export -alias server -keystore ./keystore/server.keystore -storepass 123456 -file ./keystore/server.crt
$ keytool -import -noprompt -alias server -keystore ./keystore/server.truststore -storepass 123456 -file ./keystore/server.crt

2. 启动启用TLS的Hazelcast企业版：

bash
$ docker run -e HZ_LICENSEKEY=<your_license_key> \
    -e HZ_NETWORK_SSL_ENABLED=true \
    -v `pwd`/keystore:/keystore \
    -e "JAVA_OPTS=-Djavax.net.ssl.keyStore=/keystore/server.keystore -Djavax.net.ssl.keyStorePassword=123456
    -Djavax.net.ssl.trustStore=/keystore/server.truststore -Djavax.net.ssl.trustStorePassword=123456" \
    hazelcast/hazelcast-enterprise

扩展Hazelcast基础镜像

如需自定义Hazelcast成员，可扩展Hazelcast基础镜像并添加配置文件或自定义JAR。需创建新Dockerfile并通过docker build构建。

以下Dockerfile示例基于Hazelcast镜像，添加自定义配置文件和主机的自定义JAR：

dockerfile
FROM docker.xuanyuan.run/hazelcast/hazelcast:$HAZELCAST_VERSION

# 添加自定义hazelcast.yaml
ADD hazelcast.yaml ${HZ_HOME}
ENV JAVA_OPTS -Dhazelcast.config=${HZ_HOME}/hazelcast.yaml

# 添加自定义JAR到classpath
ADD custom-library.jar ${HZ_HOME}

优雅关闭

可通过docker stop <containerid>命令停止成员。

默认Hazelcast配置为接收Docker的SIGTERM信号后TERMINATE，容器快速停止，集群数据安全依赖其他成员的备份。

另一种选择是GRACEFUL关闭，在停止前触发分区迁移（耗时取决于数据量）。使用此方式需配置：

• 向