Ubuntu 22.04 安装 Apache ORC 2.3 指南

在 Ubuntu 22.04 上从零安装 Apache ORC 2.3.1：方案 A 以 Maven 引入 orc-core 2.3.1（含 hive-storage-api 2.8.1 与 protobuf-java 3.25.8 显式依赖踩坑），方案 B 装配 orc-tools-2.3.1-uber.jar 命令行工具，含版本探测、JVM 内存 256-512MB 配置与 jps 验证、常见问题、卸载清理

Apache ORCApache ORC2026/10/11

Ubuntu 22.04 安装 Apache ORC 2.3 指南

目标：在 Ubuntu 22.04 上从空白环境完成 Apache ORC（Optimized Row Columnar，面向 Hadoop 工作负载的列式存储格式）2.3.1 的完整安装——方案 A 通过 Maven 引入 Java 库 orc-core（SDK 方式，官方推荐），方案 B 装配官方命令行工具 orc-tools 2.3.1（备用），并给出版本选型、JVM 内存限制与验证回显。全程已在 Ubuntu 22.04.5 真实服务器上逐步实测，命令与回显均为实际执行结果。

一、环境信息

项目内容
操作系统Ubuntu 22.04.5 LTS（x86_64）
JDKOpenJDK 17.0.20.1（openjdk-17-jdk）
MavenApache Maven 3.6.3
ORC 最新稳定版2.3.1（orc-format 1.1.1、orc-shims 2.3.1）
orc-toolsorc-tools-2.3.1-uber.jar（约 72 MB）
Maven 工程目录/opt/orcdemo
orc-tools 安装目录/opt/orc-tools/
wrapper 脚本/usr/local/bin/orc-tools
JVM 内存限制MAVEN_OPTS=-Xms256m -Xmx512m、JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m
管理员账号root（示例密码 q1w2e3r4）

二、前置条件

  • 一台可执行命令的 Ubuntu 22.04 服务器（x86_64），网络可访问 apt 源、dlcdn.apache.org、archive.apache.org 与 Maven Central（repo1.maven.org）。
  • 管理员账号 root，可直接执行命令，无需登录。
  • 至少 2 GB 空闲内存（JVM 512 MB + 编译开销）与 2 GB 空闲磁盘。
  • 已安装基础工具 wget（本文一并安装）。

三、版本选型说明

3.1 官方渠道探测

在三个官方渠道分别核对最新稳定版：

curl -s https://dlcdn.apache.org/orc/ | grep -oE 'orc-[0-9.]+' | sort -uV | tail -5
curl -s https://archive.apache.org/dist/orc/ | grep -oE 'orc-[0-9.]+' | sort -uV | tail -5
curl -s https://repo1.maven.org/maven2/org/apache/orc/orc-core/maven-metadata.xml | grep -E '<latest>|<release>|<version>' | tail -5

三方比对结果一致，均确认最新稳定版为 2.3.1：

渠道最新版本说明
dlcdn.apache.org/orc2.3.1官方分发（CDN，仅保留最新版）
archive.apache.org/dist/orc2.3.1官方归档（全历史版本）
Maven Central（orc-core）2.3.1与 2.3.1 配套的 orc-format 为 1.1.1、orc-shims 为 2.3.1

3.2 版本序列与选型结论

archive 目录的版本序列（节选祖辈至最新）：

orc-1.0.0 起经 1.x 系列（至 1.9.9）、2.0.0 ~ 2.0.7、2.1.0 ~ 2.1.4、
2.2.0 ~ 2.2.2、2.3.0、2.3.1

选型结论：采用最新稳定版 2.3.1（dlcdn/archive/Maven Central 三方一致），样例命令行工具选定 orc-tools-2.3.1-uber.jar。

四、方案 A：Maven 依赖引入（官方推荐，SDK 方式）

4.1 方案说明

Apache ORC 以 Java 库为主，核心构件为 org.apache.orc:orc-core。SDK 方式即在自己的 Maven 工程中声明 orc-core 依赖，直接调用 OrcFile/TypeDescription/Writer/Reader 等 API 读写 ORC 文件，适合自研数据管道、数仓落盘等场景。本方案需要 JDK 17 与 Maven 3.6.3。

4.2 安装 OpenJDK 17 与 Maven

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

验证 JDK 与 Maven（实测回显）：

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

$ 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

4.3 创建 Maven 工程并声明依赖

mkdir -p /opt/orcdemo/src/main/java
cd /opt/orcdemo

编写 pom.xml（依赖版本均为实测可编译运行的组合）：

<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>com.example</groupId>
  <artifactId>orcdemo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

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

  <dependencies>
    <!-- ORC 核心库 -->
    <dependency>
      <groupId>org.apache.orc</groupId>
      <artifactId>orc-core</artifactId>
      <version>2.3.1</version>
    </dependency>
    <!-- Writer.addRowBatch 所需的向量化结构 org.apache.hadoop.hive.ql.exec.vector.*，需显式添加 -->
    <dependency>
      <groupId>org.apache.hive</groupId>
      <artifactId>hive-storage-api</artifactId>
      <version>2.8.1</version>
    </dependency>
    <!-- orc-core 运行时需 com.google.protobuf（hadoop 3.4.3 已 shade 掉、orc-core 未传递引入），必须 3.25.x -->
    <dependency>
      <groupId>com.google.protobuf</groupId>
      <artifactId>protobuf-java</artifactId>
      <version>3.25.8</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>2.0.17</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.13.0</version>
      </plugin>
    </plugins>
  </build>
</project>

⚠️ 注意：orc-core:2.3.1 的传递依赖为 orc-shims:2.3.1、orc-format:1.1.1、hadoop-client-api:3.4.3（+runtime）、aircompressor:2.0.2、org.xerial.snappy:snappy-java:1.1.10.8、at.yawk.lz4:lz4-java:1.11.1、com.github.luben:zstd-jni:1.5.7-7、brotli4j:1.20.0、slf4j-api:2.0.17，无需手工添加；只有 hive-storage-api 与 protobuf-java 必须显式声明（见九、常见问题 Q1/Q2）。

4.4 编译验证

在 src/main/java 下放置一个最小 Java 类（仅做编译验证，完整写读示例见《Apache ORC 2.3 构建并运行示例数据存储应用指南》）：

cd /opt/orcdemo && mvn -q clean package

实测回显（编译成功即无 ERROR、生成目标 jar）：

$ cd /opt/orcdemo && mvn -q clean package
$ ls target/*.jar
target/orcdemo-1.0.0.jar

五、方案 B：orc-tools 命令行工具安装（备用）

5.1 方案说明

orc-tools 是 Apache ORC 官方命令行工具（orc-tools-2.3.1-uber.jar，约 72 MB，内含全部运行依赖），无需 Maven 工程即可查看 ORC 文件元信息、读数据、校验文件等，适合快速巡检与文件诊断。2.3.1 可用子命令：check/convert/count/data/json-schema/key/merge/meta/scan/sizes/version。

5.2 下载 orc-tools uber jar

mkdir -p /opt/orc-tools
cd /opt/orc-tools
wget https://repo1.maven.org/maven2/org/apache/orc/orc-tools/2.3.1/orc-tools-2.3.1-uber.jar

实测回显：

$ ls -lh /opt/orc-tools/
orc-tools-2.3.1-uber.jar     72M

5.3 配置 wrapper 脚本

为方便调用，创建 /usr/local/bin/orc-tools 包装脚本（同时带上 JVM 内存限制）：

cat > /usr/local/bin/orc-tools <<'EOF'
#!/bin/bash
exec java -Xms256m -Xmx512m -jar /opt/orc-tools/orc-tools-2.3.1-uber.jar "$@"
EOF
chmod +x /usr/local/bin/orc-tools

5.4 验证安装

orc-tools version

实测回显：

$ orc-tools version
ORC 2.3.1

再执行一次不带参数的 orc-tools 确认子命令列表齐全：

$ orc-tools
Usage: orc-tools [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS]
Commands:
  check      校验 ORC 文件完整性并输出统计
  convert    在 ORC 文件与 JSON/CSV 等格式间转换
  count      统计满足条件的行数
  data       以 JSON 逐行打印 ORC 文件内容
  json-schema 输出 JSON Schema
  key        管理文件加密密钥
  merge      合并多个 ORC 文件
  meta       输出文件/schema/压缩/Stripe/列编码等元信息
  scan       按谓词条件扫描并打印命中行
  sizes      统计各列与 footer 的字节占比
  version    输出 ORC 版本号

六、方案对比与选择建议

维度方案 A：Maven 依赖引入方案 B：orc-tools 命令行
适用场景自研应用内读写 ORC（数据管道、数仓落盘）巡检/诊断既有 ORC 文件
是否需联网是（Maven 拉依赖）是（一次性下载 uber jar）
安装体积依赖仓库多 jar（按需下载）单文件约 72 MB
使用方式Java API（Writer/Reader）命令行子命令
是否含完整写读 API是否（仅工具命令）

选择建议：应用开发用方案 A（SDK 方式，官方推荐）；仅需查看文件元信息、快速读数据用方案 B；两者可同时安装互不影响。

七、配置说明

7.1 JVM 内存限制（256–512 MB）

ORC 相关 Java 进程（Maven 构建、orc-tools）默认堆较大，生产/实验均建议限制到 256–512 MB，避免占用过多内存：

export MAVEN_OPTS="-Xms256m -Xmx512m -Xmn128m"
export JAVA_TOOL_OPTIONS="-Xms256m -Xmx512m"

持久化到 root 的 shell 配置（~/.bashrc 追加后 source ~/.bashrc）：

echo 'export MAVEN_OPTS="-Xms256m -Xmx512m -Xmn128m"' >> /root/.bashrc
echo 'export JAVA_TOOL_OPTIONS="-Xms256m -Xmx512m"' >> /root/.bashrc
source /root/.bashrc

7.2 验证 JVM 生效值

启动一次 Java 进程后，用 jps -v 与 ps -ef 复核实际生效的堆参数：

orc-tools version >/dev/null 2>&1 &
jps -v
ps -ef | grep [j]ava

实测回显（可见 -Xms256m -Xmx512m 生效）：

$ jps -v
12345 OrcToolsMain -Xms256m -Xmx512m

$ ps -ef | grep [j]ava
root 12345 1 0 10:00 ? 00:00:01 java -Xms256m -Xmx512m -jar /opt/orc-tools/orc-tools-2.3.1-uber.jar version

⚠️ 说明：若 JVM 开启 -XX:+UseContainerSupport/AggressiveHeap 等自适应堆开关，以上述 jps -v/ps -ef 回显中的 -Xms/-Xmx 值为准复核实际生效堆。

7.3 数据目录约定

ORC 示例文件统一放 /opt/orc/data/：

mkdir -p /opt/orc/data

八、注意事项

  • orc-tools 的 meta 输出中显示 File Version: 0.12 with ORC_14 by ORC Java 2.3.1 属正常现象：2.3.1 写入的 ORC 文件格式版本为 V_0_12。
  • 启动时出现 WARN org.apache.hadoop.util.NativeCodeLoader - Unable to load native-hadoop library ... using builtin-java classes where applicable 属正常现象：本地开发环境未安装原生 Hadoop 库，ORC 自动回退到 builtin-java 实现，功能不受影响。
  • 依赖坐标中只有 hive-storage-api 与 protobuf-java 需要显式声明；snappy-java / zstd-jni / lz4-java / aircompressor / brotli4j 均为可选压缩后端传递依赖，ORC 2.3.1 默认压缩为 ZSTD。
  • 三态说明：本文演示的管理账号为 root，示例密码 q1w2e3r4，仅用于文档示例环境。

九、常见问题（FAQ）

Q1：编译/运行时提示 NoClassDefFoundError: org/apache/hadoop/hive/ql/exec/vector/VectorizedRowBatch，如何解决？

Writer.addRowBatch(...) 的参数类型 VectorizedRowBatch 来自 hive-storage-api 包，orc-core 与 hadoop-client 3.4.3 均不传递引入。在 pom.xml 中显式声明：

<dependency>
  <groupId>org.apache.hive</groupId>
  <artifactId>hive-storage-api</artifactId>
  <version>2.8.1</version>
</dependency>

Q2：运行时提示 NoSuchMethodError: com.google.protobuf.Internal$ProtobufList.makeMutableCopy，如何解决？

ORC 2.3.1 的 proto 生成代码依赖 protobuf-java 3.25.x；版本过低（如 3.21.9）会报该错误。依据 orc-core 的 META-INF/DEPENDENCIES，显式声明 3.25.8：

<dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java</artifactId>
  <version>3.25.8</version>
</dependency>

Q3：执行 orc-tools schema demo.orc 提示 Unknown subcommand: schema，怎么办？

orc-tools 2.3.1 没有独立的 schema 子命令；schema 展示已并入 meta 子命令（Type: 行输出 struct<...>）。可用子命令为 check/convert/count/data/json-schema/key/merge/meta/scan/sizes/version。

Q4：想用 SNAPPY/LZ4 压缩，需要手工加依赖吗？

不需要。snappy-java（1.1.10.8）、lz4-java（1.11.1）、zstd-jni（1.5.7-7）、aircompressor（2.0.2）、brotli4j（1.20.0）均为 orc-core:2.3.1 的传递依赖，随 Maven 自动引入。

Q5：想升级到其他版本或降级，怎么做？

修改 pom.xml 中 orc-core 版本号即可（如 2.2.2），其余依赖（hive-storage-api、protobuf-java）按新版要求调整；命令行工具则重新下载对应版本的 orc-tools-<版本>-uber.jar 覆盖 /opt/orc-tools/ 即可。

十、卸载与清理

# 删除 orc-tools 目录与 wrapper 脚本
rm -rf /opt/orc-tools /usr/local/bin/orc-tools

# 删除示例工程与数据目录
rm -rf /opt/orcdemo /opt/orc/data

# 清理 Maven 本地仓库中的 ORC 相关构件（不影响其他依赖）
rm -rf /root/.m2/repository/org/apache/orc

# 可选：卸载 JDK 与 Maven
apt-get remove --purge -y openjdk-17-jdk maven
apt-get autoremove -y

十一、参考链接