Apache Ratis 安装指南

目标：在 Ubuntu 22.04 服务器上完成 Apache Ratis 3.3.1（当前最新稳定版）的安装，覆盖版本选型核验、Maven 依赖引入与官方二进制发行包两种方案，并给出 JVM 堆内存限制与常见问题处置。所有命令与回显均来自实测，未做任何虚构。

一、环境信息

项目	值
操作系统	Ubuntu 22.04.5 LTS（jammy）
内核	6.8.0-138-generic，x86_64，12 核
演示账号	root
JDK	OpenJDK 17.0.20.1（apt 安装）
构建工具	Apache Maven 3.6.3（apt 安装）
Ratis 版本	3.3.1（Maven Central 与 Apache 官方目录核验的最新稳定版）
演示目录	/root/ratis-demo（Maven 工程）、/opt/ratis（二进制包）

二、前置条件

2.1 基础软件安装

Ratis 是 Java 库，安装前先备好 JDK 与构建工具：

sudo apt-get update
sudo apt-get install -y openjdk-17-jdk maven wget curl

2.2 版本确认

$ java -version
openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

$ javac -version
javac 17.0.20.1

$ mvn -version
Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

三、版本选型说明

3.1 版本序列核验

拉取 repo1.maven.org 上 ratis-server 的 maven-metadata.xml，版本序列尾部如下（实测截取）：

      <version>3.0.0</version>
      <version>3.0.1</version>
      <version>3.1.0</version>
      <version>3.1.1</version>
      <version>3.1.2</version>
      <version>3.1.3</version>
      <version>3.2.0</version>
      <version>3.2.1</version>
      <version>3.2.2</version>
      <version>3.3.0</version>
      <version>3.3.1</version>
    </versions>
    <lastUpdated>20260920185858</lastUpdated>
  </versioning>
</metadata>

3.3.1 即当前最新稳定版。核验制品真实存在（返回 200）：

$ curl -s -o /dev/null -w "%{http_code}" https://repo1.maven.org/maven2/org/apache/ratis/ratis-server/3.3.1/ratis-server-3.3.1.pom
200
$ curl -s -o /dev/null -w "%{http_code}" https://repo1.maven.org/maven2/org/apache/ratis/ratis-grpc/3.3.1/ratis-grpc-3.3.1.jar
200

3.2 版本对照与选型建议

版本线	代表版本	JDK 基线	定位	建议
2.x	2.5.1	Java 8+	旧稳定线，Ozone 等组件在用	存量项目维持 2.x，不新选
3.2.x	3.2.2	Java 8+	3.x 前期稳定线	已上线 3.x 的项目可沿用
3.3.x	3.3.1	Java 8+（实测 JDK 17 编译运行正常）	最新稳定版，metrics 模块已拆分	新项目首选

Ratis 3.x 相对 2.x 的关键变化：把 metrics 实现从核心包中拆出，使用方必须显式引入 ratis-metrics-default，否则运行时报 NoClassDefFoundError（见 9.1）。

四、方案 A：Maven 依赖引入（推荐）

4.1 创建工程目录

mkdir -p /root/ratis-demo/src/main/java/demo
cd /root/ratis-demo

4.2 pom.xml 完整内容

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>demo</groupId>
    <artifactId>ratis-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.apache.ratis</groupId>
            <artifactId>ratis-server</artifactId>
            <version>3.3.1</version>
        </dependency>
        <dependency>
            <groupId>org.apache.ratis</groupId>
            <artifactId>ratis-grpc</artifactId>
            <version>3.3.1</version>
        </dependency>
        <!-- Ratis 3.x 必须显式引入，否则启动抛 NoClassDefFoundError -->
        <dependency>
            <groupId>org.apache.ratis</groupId>
            <artifactId>ratis-metrics-default</artifactId>
            <version>3.3.1</version>
        </dependency>
        <!-- 日志绑定，实际项目按需选择 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.18</version>
        </dependency>
    </dependencies>
</project>

依赖坐标速查：

模块	groupId	作用
ratis-server	org.apache.ratis	服务端核心（含 server、server-api、proto 等）
ratis-grpc	org.apache.ratis	gRPC RPC 实现
ratis-metrics-default	org.apache.ratis	3.x 必备的 metrics 默认实现
ratis-shell	org.apache.ratis	管理命令行（可选，详见 API 篇）

4.3 依赖下载与编译

$ cd /root/ratis-demo && mvn -B clean compile
（首次运行从 Maven Central 下载依赖，过程无报错）
[INFO] BUILD SUCCESS

4.4 本地仓库落盘清单

编译完成后 ~/.m2/repository/org/apache/ratis/ 下会落盘以下模块目录：ratis-client、ratis-common、ratis-grpc、ratis-metrics-api、ratis-metrics-default、ratis-proto、ratis-server、ratis-server-api、ratis-thirdparty-misc（另含 slf4j、grpc 第三方包）。ratis-shell 若引入管理命令行依赖后也会出现在该目录。

4.5 依赖树核验

$ mvn -B org.apache.maven.plugins:maven-dependency-plugin:3.6.1:tree
[INFO] --- maven-dependency-plugin:3.6.1:tree (default-cli) @ ratis-demo ---
[INFO] demo:ratis-demo:jar:1.0-SNAPSHOT
[INFO] +- org.apache.ratis:ratis-server:jar:3.3.1:compile
[INFO] |  +- org.apache.ratis:ratis-thirdparty-misc:jar:1.1.0:compile
[INFO] |  +- org.apache.ratis:ratis-proto:jar:3.3.1:compile
[INFO] |  +- org.apache.ratis:ratis-common:jar:3.3.1:compile
[INFO] |  +- org.apache.ratis:ratis-client:jar:3.3.1:compile
[INFO] |  +- org.apache.ratis:ratis-server-api:jar:3.3.1:compile
[INFO] |  +- org.slf4j:slf4j-api:jar:2.0.18:compile
[INFO] |  \- org.apache.ratis:ratis-metrics-api:jar:3.3.1:compile
[INFO] +- org.apache.ratis:ratis-grpc:jar:3.3.1:compile
[INFO] +- org.apache.ratis:ratis-metrics-default:jar:3.3.1:compile
[INFO] \- org.slf4j:slf4j-simple:jar:2.0.18:compile

可见 ratis-grpc 自身无传递依赖，gRPC 运行时由 ratis-thirdparty-misc 统一提供（包名带 org.apache.ratis.thirdparty 前缀，避免与业务方 grpc 版本冲突）。

五、方案 B：官方二进制发行包

适合不带 Maven 的环境直接使用 CLI 与官方示例。

5.1 下载

Apache 官方目录 downloads.apache.org/ratis/3.3.1/ 提供 apache-ratis-3.3.1-bin.tar.gz、apache-ratis-3.3.1-src.tar.gz 及 .asc、.sha512 校验文件：

mkdir -p /opt/ratis && cd /opt/ratis
wget https://downloads.apache.org/ratis/3.3.1/apache-ratis-3.3.1-bin.tar.gz

$ ls -lh apache-ratis-3.3.1-bin.tar.gz
-rw-r--r-- 1 root root 80M Sep  8 02:16 apache-ratis-3.3.1-bin.tar.gz

5.2 解压与目录结构

tar xzf apache-ratis-3.3.1-bin.tar.gz

解压后目录占 91M，关键结构：

路径	说明
bin/ratis	管理命令行脚本
conf/	日志等默认配置
jars/	ratis 全部模块 jar
lib/trace/	可观测性 agent（自动注入）
examples/	FileStore 等官方示例（bin、lib、conf）

5.3 验证 ratis 脚本

$ ./apache-ratis-3.3.1-bin/bin/ratis sh
Usage: ratis sh [generic options]
         [election [transfer] [stepDown] [pause] [resume]]
         [group [info] [list]]
         [local [raftMetaConf]]
         [peer [add] [remove] [setPriority]]
         [snapshot [create]]

能看到该帮助即安装成功。示例工程的完整用法见《Apache Ratis 构建并运行示例应用指南》。

六、配置说明

6.1 JDK 与编译配置

Ratis 3.3.1 制品字节码基线为 Java 8，JDK 8 及以上均可运行；实测使用 JDK 17 编译与运行均正常。
Maven 工程建议显式声明 maven.compiler.source/target（本例为 17），并设置 project.build.sourceEncoding 为 UTF-8。
若需要在工程内直接调用 ratis-shell 主类，注意 ratis-shell-3.3.1.jar 无 Main-Class 清单项，必须用 java -cp 指定 org.apache.ratis.shell.cli.sh.RatisShell。

6.2 JVM 堆内存限制

演示与小型部署建议把堆限制在 256-512MB。Maven 运行方式：

MAVEN_OPTS="-Xms256m -Xmx512m" mvn -B exec:java

发行包脚本运行方式（脚本内部读取 JAVA_TOOL_OPTIONS）：

JAVA_TOOL_OPTIONS="-Xms256m -Xmx512m" bin/server.sh filestore server ...

实测启动日志首行会回显：Picked up JAVA_TOOL_OPTIONS: -Xms256m -Xmx512m；进程核验：

$ jps -v | grep -v -E "Jps|Launcher"
8467 ServeDemo -Xms256m -Xmx512m

6.3 Maven 仓库镜像（可选）

受限网络或办公网环境直连 Maven Central 偶有缓慢，可改用阿里云镜像。两者在本次实测中均可达（repo1 返回 200 约 0.92 秒，阿里云 public 返回 200 约 0.44 秒），按需选择。settings.xml 配置：

<settings>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>central</mirrorOf>
      <name>aliyun public</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

七、多方案对照与选择建议

维度	方案 A：Maven 依赖	方案 B：二进制发行包
适用对象	将 Ratis 嵌入 Java 应用	直接使用 ratis CLI、跑官方示例
升级方式	改 pom 版本号重新构建	替换解压目录
体积	按需拉取传递依赖	固定 80M 包，解压 91M
可脚本化	高	高
建议	生产集成首选	运维巡检与演练首选

生产实践中两种方案常并行：应用侧走 Maven 依赖，运维侧用发行包的 bin/ratis 做巡检。

八、注意事项

全文回显基于 3.3.1，其他版本默认值与类名可能不同，升级前先在测试环境跑通。
ratis-metrics-default 在 3.x 是必需依赖，缺省会导致启动失败（见 9.1），2.x 则不需要。
ratis-grpc 无传递依赖，gRPC 运行时来自 ratis-thirdparty-misc，不要自行叠加原生 grpc-netty 以免冲突。
限堆时同时留意 metaspace：Ratis 使用动态代理与 gRPC，小堆演示环境建议至少 256MB 堆上限。
生产部署至少 3 个 RaftPeer 组成多数派，写入才能在单点故障后继续。

九、常见问题

9.1 启动抛 NoClassDefFoundError: MetricRegistries

3.3.1 只引 ratis-server 与 ratis-grpc 时实测报错：

java.lang.NoClassDefFoundError: Could not initialize class org.apache.ratis.metrics.MetricRegistries$LazyHolder
Caused by: java.lang.IllegalStateException: Failed to load org.apache.ratis.metrics.impl.MetricRegistriesImpl

原因：3.x 将 metrics 实现拆分为 ratis-metrics-default，需要显式引入；补齐后恢复正常。

9.2 Maven 下载缓慢或停滞

优先确认到 repo1.maven.org 的连通性；必要时配置 6.3 的镜像。若进程长时间无下载进度，可终止后重跑 mvn 命令，Maven 会从已下载的 .m2 缓存续传。

9.3 重启报 Failed to FORMAT

复用旧存储目录但组 ID 不匹配时报 Failed to FORMAT: One or more existing directories found。首次启动会格式化存储目录；如目录属于同一 group，用原有 group 与 peers 配置重启即可，否则清理该目录。

9.4 从 2.x 升级到 3.x

除补 ratis-metrics-default 外，注意 3.x 的 API 调整（如 BaseStateMachine.getServer() 返回 CompletableFuture），老代码需按编译报错逐个适配；建议先升 3.2.2 再升 3.3.1。

十、卸载方式

# Maven 方案：删除工程与本地缓存
rm -rf /root/ratis-demo
rm -rf ~/.m2/repository/org/apache/ratis

# 发行包方案：删除解压目录与安装包
rm -rf /opt/ratis

# 可选：卸载基础软件
sudo apt-get remove -y openjdk-17-jdk maven

十一、参考链接

官网：https://ratis.apache.org/
源码仓库：https://github.com/apache/ratis
Maven Central：https://central.apache.org/（org.apache.ratis）
官方下载目录：https://downloads.apache.org/ratis/3.3.1/
版本发布说明：https://ratis.apache.org/post/3.3.1/