Ubuntu 22.04 安装 Apache CarbonData 2.3.0 指南

目标：在 Ubuntu 22.04 上从零搭建 Apache CarbonData 2.3.0 索引列式存储运行环境，覆盖 JDK 8 与 Maven 校验、基于 Maven 的 carbondata-core 依赖工程构建、JVM 256-512MB 堆限制配置与 jps -v 生效验证，并完成建表、写入、查询的端到端实测。

一、环境信息

Apache CarbonData 是构建在 Hadoop/Spark 生态之上的索引列式存储格式，核心组件全部基于 Java 实现，运行需要 JDK 8 及以上版本，工程构建使用 Maven。本机已预装 JDK 与 Maven（服务器重启后仍可用），无需重复安装。

项目	值
操作系统	Ubuntu 22.04.5 LTS
OpenJDK	1.8.0_504（64 位 Server VM）
Apache Maven	3.6.3
Apache CarbonData	2.3.0（carbondata-spark_3.1）
Apache Spark	3.1.3（spark-sql_2.12 / spark-hive_2.12）
snappy-java	1.1.2.6（按 CarbonData 期望版本强制对齐）
安装位置	/opt/carbondata
运行用户	root
Maven 仓库	阿里云公共镜像（maven.aliyun.com/repository/public）

CarbonData 属于列式存储家族，与 ORC、Parquet 同属大数据列式格式，理解其与行式存储的差异是选型的前提：

💡 技术拓展：列式存储按列组织数据，同一列的相邻值连续存放，配合压缩与索引可大幅减少扫描量；行式存储（如 MySQL、PostgreSQL 的普通表）整行连续存放，适合点查与小事务。与 ORC、Parquet 相比，CarbonData 内置多维索引（Blocklet/Page 级 min-max、倒排索引、布隆索引）与 Segment 化增量写入、Compaction 合并机制，过滤下推更快，增量写入与更新场景更友好。

1.1 JDK 8 校验

java -version

实测回显：

openjdk version "1.8.0_504"
OpenJDK Runtime Environment (build 1.8.0_504-8u504-ga-1ubuntu1~22.04.3-b01)
OpenJDK 64-Bit Server VM (build 25.504-b01, mixed mode)

同时确认编译工具链：

javac -version

实测回显：

javac 1.8.0_504

1.2 Maven 校验

mvn -version

实测回显：

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 1.8.0_504, vendor: Ubuntu, runtime: /usr/lib/jvm/java-8-openjdk-amd64/jre

验证结果：JDK 8 与 Maven 3.6.3 均可用，满足 CarbonData 2.3.0 的运行与构建要求。

二、创建工程并配置 Maven 依赖

2.1 创建工程目录

mkdir -p /opt/carbondata/demo/src/main/java/demo

2.2 配置 Maven 镜像加速

国内网络访问 Maven 中央仓库较慢，配置阿里云公共镜像，写入 /opt/carbondata/demo/maven-settings.xml：

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <mirror>
      <id>aliyun-public</id>
      <name>Aliyun Public Repository</name>
      <url>https://maven.aliyun.com/repository/public</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
</settings>

2.3 编写 pom.xml

依赖三个关键包：spark-sql_2.12 与 spark-hive_2.12（3.1.3）提供 Spark SQL 运行环境，carbondata-spark_3.1（2.3.0）提供 CarbonData 集成实现。carbondata-spark 需排除其传递引入的 Spark 依赖，避免版本冲突。snappy-java 固定为 1.1.2.6，否则压缩器初始化会抛出 ClassCastException。

<?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>carbondata-demo</artifactId>
  <version>1.0</version>
  <packaging>jar</packaging>

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

  <dependencies>
    <dependency>
      <groupId>org.apache.spark</groupId>
      <artifactId>spark-sql_2.12</artifactId>
      <version>3.1.3</version>
    </dependency>
    <dependency>
      <groupId>org.apache.spark</groupId>
      <artifactId>spark-hive_2.12</artifactId>
      <version>3.1.3</version>
    </dependency>
    <dependency>
      <groupId>org.apache.carbondata</groupId>
      <artifactId>carbondata-spark_3.1</artifactId>
      <version>2.3.0</version>
      <exclusions>
        <exclusion>
          <groupId>org.apache.spark</groupId>
          <artifactId>*</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    <dependency>
      <groupId>org.xerial.snappy</groupId>
      <artifactId>snappy-java</artifactId>
      <version>1.1.2.6</version>
    </dependency>
  </dependencies>
</project>

2.4 编写建表写入查询 Demo

CarbonData 通过 Spark SQL 扩展接入，必须在 SparkSession 上声明 org.apache.spark.sql.CarbonExtensions 扩展，建表时指定 USING carbondata 并提供数据路径。写入采用 INSERT INTO VALUES，随后执行全表查询与分组聚合验证。

package demo;

import org.apache.spark.sql.SparkSession;

public class CarbonDemo {
    public static void main(String[] args) {
        SparkSession spark = SparkSession.builder()
                .master("local[2]")
                .appName("CarbonDemo")
                .config("spark.sql.extensions", "org.apache.spark.sql.CarbonExtensions")
                .config("spark.sql.warehouse.dir", "file:///opt/carbondata/warehouse")
                .config("spark.driver.host", "localhost")
                .getOrCreate();
        spark.sparkContext().setLogLevel("ERROR");

        spark.sql("DROP TABLE IF EXISTS carbon_table");
        spark.sql("CREATE TABLE IF NOT EXISTS carbon_table (id INT, name STRING, city STRING) "
                + "USING carbondata "
                + "OPTIONS('PATH'='file:///opt/carbondata/data/carbon_table')").show();
        spark.sql("INSERT INTO carbon_table VALUES "
                + "(1,'Jack','Beijing'),(2,'Lucy','Shanghai'),(3,'Tom','Beijing')").show();

        System.out.println("=== SELECT ALL ===");
        spark.sql("SELECT * FROM carbon_table ORDER BY id").show();
        System.out.println("=== GROUP BY city ===");
        spark.sql("SELECT city, COUNT(*) AS cnt FROM carbon_table GROUP BY city").show();

        spark.stop();
    }
}

三、Maven 构建

3.1 构建工程

cd /opt/carbondata/demo
mvn -s maven-settings.xml package -DskipTests

实测回显：

[INFO] Building jar: /opt/carbondata/demo/target/carbondata-demo-1.0.jar
[INFO] BUILD SUCCESS
[INFO] Total time: 1.913 s

3.2 生成运行 Classpath

cd /opt/carbondata/demo
mvn -s maven-settings.xml dependency:build-classpath -Dmdep.outputFile=/opt/carbondata/cp.txt

生成 /opt/carbondata/cp.txt，将全部依赖 jar 路径导出，供 java 直接启动。

验证结果：BUILD SUCCESS，编译产物与依赖 Classpath 就绪。

四、配置 JVM 内存并运行验证

4.1 JVM 参数位置与堆限制

CarbonData 是 Java 进程，堆内存通过启动命令中的 JVM 参数控制。本机可用内存有限，按 256-512MB 堆限制运行：-Xms256m 设定初始堆 256MB，-Xmx512m 限定最大堆 512MB。JVM 参数位置在 java 启动命令中、类名之前：

java -Djava.io.tmpdir=/opt/carbondata/tmp -Xms256m -Xmx512m \
  -cp "target/classes:$(cat /opt/carbondata/cp.txt)" demo.CarbonDemo

其中 -Djava.io.tmpdir 必须指向可执行目录 /opt/carbondata/tmp：系统 /tmp 挂载为 tmpfs 且带 noexec 属性，snappy 原生库解压到 /tmp 后会报 failed to map segment from shared object，改用 /opt/carbondata/tmp 后正常。

4.2 jps -v 验证 JVM 参数生效

后台启动 Demo，运行期间用 jps -v 核对 JVM 参数：

cd /opt/carbondata/demo
java -Djava.io.tmpdir=/opt/carbondata/tmp -Xms256m -Xmx512m \
  -cp "target/classes:$(cat /opt/carbondata/cp.txt)" demo.CarbonDemo > /opt/carbondata/run.log 2>&1 &
sleep 12
jps -v

实测回显：

761 CarbonDemo -Djava.io.tmpdir=/opt/carbondata/tmp -Xms256m -Xmx512m

验证结果：jps -v 显示 CarbonDemo 进程携带 -Xms256m -Xmx512m，堆限制 512MB 生效。

五、端到端实测回显

5.1 建表与写入

运行日志中 CarbonData 审计（AUDIT）记录：

AUDIT {"time":"October 13, 2026 4:24:57 PM GMT","username":"root","opName":"CREATE TABLE","opStatus":"SUCCESS","opTime":"322 ms","table":"NA","extraInfo":{}}
AUDIT {"time":"October 13, 2026 4:25:00 PM GMT","username":"root","opName":"INSERT INTO","opStatus":"SUCCESS","opTime":"2246 ms","table":"default.carbon_table","extraInfo":{"SegmentId":"0","DataSize":"1.70KB","IndexSize":"1.06KB"}}

写入完成后返回新段（Segment）ID：

+----------+
|Segment ID|
+----------+
|         0|
+----------+

5.2 全表查询

+---+----+--------+
| id|name|    city|
+---+----+--------+
|  1|Jack| Beijing|
|  2|Lucy|Shanghai|
|  3| Tom| Beijing|
+---+----+--------+

5.3 分组聚合

+--------+---+
|    city|cnt|
+--------+---+
| Beijing|  2|
|Shanghai|  1|
+--------+---+

验证结果：建表、写入、查询、聚合全部成功，每次写入产生一个独立 Segment，聚合结果与数据一致。

六、常见问题

6.1 snappy 原生库加载失败

现象：INSERT 时报 UnsatisfiedLinkError，failed to map segment from shared object。原因：/tmp 挂载为 noexec。解决：启动参数加 -Djava.io.tmpdir=/opt/carbondata/tmp。

6.2 表元数据跨会话丢失

现象：新建 SparkSession 后 SHOW TABLES 为空、SHOW SEGMENTS 报 Table not found。原因：未配置 Hive Metastore 时 Spark 内存 Catalog 不持久化表元数据。解决：建表、写入、段管理与查询放在同一会话内执行。此为 Spark 集成链在本环境的真实限制，生产环境应接入外部 Metastore。

6.3 Maven 依赖下载缓慢

现象：首次构建长时间停留在下载阶段。解决：使用 maven-settings.xml 中的阿里云镜像，或将已缓存的 /root/.m2/repository 保留复用。

七、参考链接

Apache CarbonData 官方文档：https://carbondata.apache.org/
Apache CarbonData 下载页：https://carbondata.apache.org/download/
CarbonData Spark 集成指南：https://carbondata.apache.org/spark-quick-start-guide.html
Apache Spark 3.1.3 下载页：https://spark.apache.org/downloads.html
Maven 阿里云镜像仓库：https://maven.aliyun.com/repository/public