CentOS 8 安装 Apache Commons JCS 指南

在 CentOS 8 上从零接入 Apache Commons JCS 3.2.1：JDK 17 与 Maven 配置、Maven 依赖、官方二进制包与源码编译三套方案，附 UnsupportedClassVersionError 等真实回显与排查。

Apache Commons JCSApache Commons JCS2026/10/14

CentOS 8 安装 Apache Commons JCS 指南

目标：在 CentOS 8 上从零搭建 Apache Commons JCS 3.2.1 的使用环境，完成 JDK 17 + Maven 环境配置（含多 JDK 并存处理）、三种依赖获取方式（Maven 在线依赖、官方二进制包、源码编译）与真实缓存读写验证。以下全部命令与回显均已在 CentOS 8（x86_64）实测通过。

一、环境信息

本节先固定本次实测所用软硬件基线，便于读者逐项对照复现。

  • 操作系统：CentOS 8（x86_64）
  • 系统默认 Java：OpenJDK 1.8.0_312（java -version 实测，回显见 4.2）
  • 目标 JDK：java-17-openjdk 17.0.1（系统已安装的 JDK 17 包）
  • 构建工具：Apache Maven 3.5.4（Red Hat 构建版）
  • 目标库：Apache Commons JCS 3.2.1（Maven 坐标 org.apache.commons:commons-jcs3-core:3.2.1）
  • 依赖来源：https://repo.maven.apache.org/maven2/（Maven 中央仓库，网络直连可达）
  • 官方发行目录：https://downloads.apache.org/commons/jcs/
  • Maven 示例工程目录：/opt/jcs-demo（配置文件放 src/main/resources，随编译进 classpath）
  • 官方二进制包解压目录：/opt/jcs3-dist
  • 官方源码包解压目录：/opt/jcs3-src
  • 二进制包演示目录：/opt/jcs-dist-demo
  • 磁盘缓存数据目录：/opt/jcs-demo/disk-cache

Commons JCS 是纯 Java 进程内缓存库（Java In-Memory Cache），以 jar 形式嵌入应用，无独立守护进程、无端口，安装本质上是「让应用能拿到 jar 并提供配置文件」。CentOS 8 上要特别处理 JDK 8 与 JDK 17 并存 的解析问题（见 4.2/4.3）。

二、前置条件

在开始安装前，请确认以下条件满足，否则后续步骤会因权限、版本或网络问题中断。

  1. root 权限或 sudo：需要在 /opt 下创建目录并写入文件。
  2. 网络可达：需要访问 repo.maven.apache.org（Maven 中央仓库）与 downloads.apache.org（官方二进制/源码包）；第四、五、六章的下载与构建命令本身就是连通性的实测验证。
  3. 磁盘空间：官方二进制包实测 7,837,164 字节、源码包实测 824,939 字节，加上 Maven 本地仓库缓存建议预留 ≥ 300 MB。
  4. JDK 17 与 Maven 已安装：本文使用系统包 java-17-openjdk 与 maven（如未安装：dnf install -y java-17-openjdk-devel maven）。务必先确认系统默认 java 解析到的版本，CentOS 8 上常同时存在 JDK 8 与 JDK 17。
  5. 多 JDK 并存处理能力：CentOS 8 的 Maven 默认可能解析到 JDK 8，需按 4.3 设置 JAVA_HOME；java 命令本身也可能解析到 1.8，需用 JDK 17 完整路径运行（4.6 实测）。

三、版本选型说明

Commons JCS 是 Apache 基金会的 Java 分布式/进程内缓存组件。安装前先确认版本与模块构成，避免引错坐标。当前 3.x 发行线包含 3.0、3.1、3.2 与 3.2.1，本文实测 3.2.1（当前最新正式版），版本选型建议如下：

版本说明建议
3.2.13.2 线的最新补丁版，本文实测版本生产环境首选
3.23.2 线首发版与 3.2.1 同线，建议直接用 3.2.1
3.1 / 3.0历史版本线存量系统兼容时使用，新项目不建议

坐标与版本的实测确认：工程引入 commons-jcs3-core:3.2.1 并编译运行成功（4.5/4.6 实测），《Apache Commons JCS 3.2.1 常用 API 与工具详解》5.3 节还给出了 mvn dependency:list 的直接版本回显。

3.2.1 官方发行包（commons-jcs3-dist-3.2.1-bin.tar.gz）包含 5 个模块，模块构成与用途：

模块用途
commons-jcs-core核心模块：内存/磁盘缓存、配置加载，绝大多数场景只需它
commons-jcs-jcacheJCache（JSR-107）标准 API 实现（含 cdi 与 nocdi 两种 jar）
commons-jcs-jcache-extrasJCache 扩展
commons-jcs-jcache-openjpaOpenJPA 二级缓存适配
commons-jcs-tck-testsJCache TCK 一致性测试包

💡 技术拓展：Java 缓存方案不止本文所用的 Apache Commons JCS。常见选项对比——

方案形态特点适用场景
Apache Commons JCS进程内 Java 库Apache 出品、内存+磁盘分层、可配 LRU 淘汰、支持 JCache 标准嵌入应用的本地缓存、需磁盘持久化
Ehcache进程内 Java 库功能全、堆外缓存与 Terracotta 集群能力强Spring 生态本地缓存
Caffeine进程内 Java 库基于 W-TinyLFU、内存命中率与性能最优、仅内存纯内存高性能缓存
Redis（Jedis/Lettuce 客户端）独立缓存服务跨进程共享、数据结构丰富、需运维服务端多实例共享数据、分布式场景
Infinispan嵌入式/服务端混合数据网格、分布式模式、跨节点复制大规模数据网格与集群

本文场景为 Java 应用进程内的内存+磁盘两级缓存（含重启后数据恢复），选用 Commons JCS：它零外部依赖、经 Maven 即可引入、磁盘缓存可跨进程重启持久化，且无传递依赖、部署极轻。

四、在线安装方案（A：Maven 依赖引入）

官方推荐方式：通过 Maven 引入 commons-jcs3-core 依赖。CentOS 8 上本方案的关键是 JAVA_HOME 与 java 命令的双 JDK 解析，本章完整实测。

4.1 方案说明与适用场景

本方案先确认系统 Java/Maven 现状，设置 JAVA_HOME 指向 JDK 17，再创建最小 Maven 工程引入 commons-jcs3-core:3.2.1，最后编译运行验证——包括用 JDK 17 完整路径绕开系统默认 Java 1.8 的真实踩坑过程。适合可访问中央仓库的场景。

4.2 确认系统默认 Java 与 Maven

先看系统 java 与 Maven 默认解析到的版本：

java -version 2>&1
mvn -v | head -3

输出：

openjdk version "1.8.0_312"
OpenJDK Runtime Environment (build 1.8.0_312-b07)
OpenJDK 64-Bit Server VM (build 25.312-b07, mixed mode, sharing)
Apache Maven 3.5.4 (Red Hat 3.5.4-5)
Maven home: /usr/share/maven
Java version: 1.8.0_312, vendor: Red Hat, Inc., runtime: /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.312.b07-2.el8_5.x86_64/jre

关键点：系统 java 与 Maven 都默认走 Java 1.8.0_312。JDK 17 已以 java-17-openjdk 安装在系统里，但不改环境变量就不会被用到。

4.3 设置 JAVA_HOME 指向 JDK 17

设置 JAVA_HOME 并验证 Maven 切换到 JDK 17：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
mvn -v
/usr/lib/jvm/java-17-openjdk/bin/java -version

输出：

Apache Maven 3.5.4 (Red Hat 3.5.4-5)
Maven home: /usr/share/maven
Java version: 17.0.1, vendor: Red Hat, Inc., runtime: /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"
openjdk version "17.0.1" 2021-10-19 LTS
OpenJDK Runtime Environment 21.9 (build 17.0.1+12-LTS)
OpenJDK 64-Bit Server VM 21.9 (build 17.0.1+12-LTS, mixed mode, sharing)

验证点：mvn -v 的 Java version 变为 17.0.1，说明 Maven 已用 JDK 17。

⚠️ 注意：export JAVA_HOME 只影响 Maven，不会改变 PATH 上 java 命令的解析结果——直接敲 java 仍是 1.8（4.6 实测报错）。运行程序需用 /usr/lib/jvm/java-17-openjdk/bin/java 完整路径，或将该路径置前于 PATH。持久化做法见第八章。

4.4 创建 Maven 工程

创建工程目录：

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

/opt/jcs-demo/pom.xml 内容（与 Ubuntu 实测工程一致，仅 artifactId 为 jcs-demo-centos 以区分工程名）：

<?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>jcs-demo-centos</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

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

  <dependencies>
    <dependency>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-jcs3-core</artifactId>
      <version>3.2.1</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.11.0</version>
        <configuration>
          <release>17</release>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

逐项说明：maven.compiler.release=17 与 compiler 插件 <release>17</release> 指定按 JDK 17 编译（因此 Maven 必须运行在 JDK 17 上，即 4.3 的 JAVA_HOME）；dependencies 仅声明 commons-jcs3-core:3.2.1，该依赖无 compile 传递依赖。

最小验证程序 /opt/jcs-demo/src/main/java/JcsMini.java（默认包，验证写入与读回）：

import org.apache.commons.jcs3.JCS;
import org.apache.commons.jcs3.access.CacheAccess;

public class JcsMini {
    public static void main(String[] args) {
        CacheAccess<String, String> cache = JCS.getInstance("centosRegion");
        cache.put("hello", "jcs3-on-centos8");
        System.out.println("get(hello) = " + cache.get("hello"));
        cache.dispose();
        System.out.println("OK");
    }
}

配置文件放 src/main/resources（编译后自动进 classpath，避免 4.6 之前的 NPE 问题——JCS 3.2.1 在 classpath 无 cache.ccf 时直接 NPE）：

/opt/jcs-demo/src/main/resources/cache.ccf 内容：

jcs.default.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=100
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache

逐项说明：jcs.default.cacheattributes 定义所有未显式声明区域（如本例 centosRegion）的公共属性；MaxObjects=100 内存最多 100 个对象；MemoryCacheName 指定内存淘汰实现为 LRU。

4.5 编译与生成运行时 classpath

编译（JAVA_HOME 必须已指向 JDK 17；首次编译需下载编译器相关插件，输出节选实测末尾）：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk && cd /opt/jcs-demo && mvn -B compile

输出节选（实测末尾）：

[INFO] Downloaded from central: https://repo.maven.apache.org/maven2/org/codehaus/plexus/plexus-compiler-javac/2.13.0/plexus-compiler-javac-2.13.0.jar (0 B at 0 B/s)
[WARNING] Invalid cookie header: "set-cookie: __cf_bm=zmhFus3irgJInhy0PNPL51q42zH1ecdZxfVNiMKESRk-1791973859.607545-1.0.1.1-EbOoqlUnflo2eKSg_DE.W67IMla0D1DFCthaHkB37i194GdbwQUKBzNKz_qZb7mc.2J4K3f3aqaY0VZwkYnnRgvTy2rtQ4hqUMwHlVw75qLLaZwCUayY4dzJHCWC3k0; HttpOnly; SameSite=None; Secure; Path=/; Domain=repo.maven.apache.org; Expires=Wed, 14 Oct 2026 11:00:59 GMT". Invalid 'expires' attribute: Wed, 14 Oct 2026 11:00:59 GMT
[INFO] Downloaded from central: https://repo.maven.apache.org/maven2/org/ow2/asm/asm/9.4/asm-9.4.jar (122 kB at 57 kB/s)
[INFO] Downloaded from central: https://repo.maven.apache.org/maven2/org/apache/maven/shared/maven-shared-utils/3.3.4/maven-shared-utils-3.3.4.jar (0 B at 0 B/s)
[INFO] Changes detected - recompiling the module! :dependency
[INFO] Compiling 1 source file with javac [debug release 17] to target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  45.454 s
[INFO] Finished at: 2026-10-14T10:31:05Z
[INFO] ------------------------------------------------------------------------

验证点：Compiling 1 source file with javac [debug release 17] 且 BUILD SUCCESS。中段的 Invalid cookie header WARNING 来自中央仓库响应头，不影响构建结果。

生成运行时 classpath 文件：

cd /opt/jcs-demo && mvn -B dependency:build-classpath -Dmdep.outputFile=cp.txt 2>&1 | tail -2
cat cp.txt   # 注意: 文件末尾无换行符

输出：

[INFO] Finished at: 2026-10-14T10:33:43Z
[INFO] ------------------------------------------------------------------------
/root/.m2/repository/org/apache/commons/commons-jcs3-core/3.2.1/commons-jcs3-core-3.2.1.jar

验证点：classpath 只有一行——commons-jcs3-core-3.2.1.jar，无任何传递依赖。

4.6 运行验证与 JDK 8/17 并存踩坑

先直接用 PATH 上的 java 运行（此时 JAVA_HOME 已设为 17，但 java 仍解析到 1.8）：

cd /opt/jcs-demo && java -Dfile.encoding=UTF-8 -cp target/classes:$(cat cp.txt) JcsMini

输出：

Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError: JcsMini has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 52.0
        at java.lang.ClassLoader.defineClass1(Native Method)
        at java.lang.ClassLoader.defineClass(ClassLoader.java:756)
        at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
        at java.net.URLClassLoader.defineClass(URLClassLoader.java:756)
        at java.net.URLClassLoader$1.run(URLClassLoader.java:363)
        at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
        at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
        at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:601)

⚠️ 注意：class file version 61.0（Java 17 编译产物）被 52.0（Java 8 运行时）拒绝——印证 4.3 的警告：export JAVA_HOME 只切换了 Maven，PATH 上的 java 仍是 1.8。

改用 JDK 17 完整路径运行：

cd /opt/jcs-demo && /usr/lib/jvm/java-17-openjdk/bin/java -Dfile.encoding=UTF-8 -cp target/classes:$(cat cp.txt) JcsMini

输出：

Oct 14, 2026 10:33:53 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Instance is null, creating with config [/cache.ccf]
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Creating cache manager from config file: /cache.ccf
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Setting default auxiliaries to "null"
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: No special CompositeCacheAttributes class defined for key [jcs.default.cacheattributes], using default class.
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: setting defaultCompositeCacheAttributes to [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 100, maxSpoolPerRun = -1, diskUsagePattern = SWAP, spoolChunkSize = 2 ]
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: No special ElementAttribute class defined for key [jcs.default.elementattributes], using default class.
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: setting defaultElementAttributes to [ IS_LATERAL = true, IS_SPOOL = true, IS_REMOTE = true, IS_ETERNAL = true, MaxLifeSeconds = -1, IdleTime = -1, CreateTime = 1791974034046, LastAccessTime = 1791974034046, getTimeToLiveSeconds() = -1, createTime = 1791974034046 ]
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: Parsed regions []
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Finished configuration in 14 ms.
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheConfigurator
INFO: No special ElementAttribute class defined for key [jcs.region.centosRegion.elementattributes], using default class.
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.memory.AbstractDoubleLinkedListMemoryCache
INFO: initialized MemoryCache for centosRegion
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: Constructed cache with name [centosRegion] and cache attributes [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 100, maxSpoolPerRun = -1, diskUsagePattern = SWAP, spoolChunkSize = 2 ]
get(hello) = jcs3-on-centos8
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [centosRegion] fromRemote [false]
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.event.ElementEventQueue
INFO: Element event queue destroyed: org.apache.commons.jcs3.engine.control.event.ElementEventQueue@e45f292
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [centosRegion] disposing of memory cache.
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.memory.AbstractMemoryCache
INFO: Memory Cache dispose called.
OK
Oct 14, 2026 10:33:54 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Shutdown hook activated. Shutdown was not called. Shutting down JCS.

验证点：get(hello) = jcs3-on-centos8 且以 OK 结束。Parsed regions [] 说明配置未定义任何具名区域，centosRegion 按 jcs.default 属性（maxObjs = 100）即时创建。最后一条 Shutdown hook activated 是 JCS 的 Shutdown 钩子日志：本例未显式调用 JCS.shutdown()，JVM 退出时钩子自动关闭了缓存管理器。-Dfile.encoding=UTF-8 用于默认编码为 ANSI_X3.4-1968 环境下避免中文输出乱码。

五、离线安装方案（B：官方二进制包）

适合内网隔离、无法访问 Maven 中央仓库的环境。使用官方 commons-jcs3-dist-3.2.1-bin.tar.gz 发行包，解压后直接以 jar 编译运行。

5.1 方案说明与适用场景

官方二进制包内含全部模块 jar（core 及各 JCache 模块，含 sources/javadoc/tests 变体）。本方案流程：下载 → 解压 → 用 core jar 编译一个最小程序 → 运行验证。core 模块无传递依赖，无需补任何第三方 jar；运行同样注意使用 JDK 17 完整路径。

5.2 下载官方二进制包

用 curl 下载官方二进制包（系统未预装 wget 时，wget --version 实测报 bash: line 1: wget: command not found，改用 curl 即可）：

cd /tmp && curl -fsSLO https://downloads.apache.org/commons/jcs/binaries/commons-jcs3-dist-3.2.1-bin.tar.gz
ls -la /tmp/commons-jcs3-dist-3.2.1-bin.tar.gz

输出：

-rw-r--r-- 1 root root 7837164 Oct 14 10:28 /tmp/commons-jcs3-dist-3.2.1-bin.tar.gz

⚠️ 注意：源码包与二进制包不在同一目录——二进制包在 binaries/ 子目录，源码包在 source/ 子目录（第六章实测 binaries/ 下的 src 包为 404）。

5.3 解压与目录结构

解压到 /opt/jcs3-dist 并查看结构：

mkdir -p /opt/jcs3-dist && tar xzf commons-jcs3-dist-3.2.1-bin.tar.gz -C /opt/jcs3-dist
ls -la /opt/jcs3-dist/

输出：

total 12
drwxr-xr-x 3 root root 4096 Oct 14 10:28 .
drwxr-xr-x 1 root root 4096 Oct 14 10:28 ..
drwxr-xr-x 7 root root 4096 Oct 14 10:28 commons-jcs3-3.2.1-bin

列出发行包内全部 jar：

find /opt/jcs3-dist -name "*.jar" | sort

输出：

/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1-javadoc.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1-test-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1-tests.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-core-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-jcache-extras-3.2.1-javadoc.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-jcache-extras-3.2.1-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-jcache-extras-3.2.1-test-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-jcache-extras-3.2.1-tests.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-extras/commons-jcs3-jcache-extras-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-core-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-jcache-openjpa-3.2.1-javadoc.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-jcache-openjpa-3.2.1-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-jcache-openjpa-3.2.1-test-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-jcache-openjpa-3.2.1-tests.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache-openjpa/commons-jcs3-jcache-openjpa-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-core-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-cdi.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-javadoc.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-nocdi.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-test-sources.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1-tests.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-jcache/commons-jcs3-jcache-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-tck-tests/commons-jcs3-core-3.2.1.jar
/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-tck-tests/commons-jcs3-jcache-tck-3.2.1.jar

查看发行包顶层结构：

ls /opt/jcs3-dist/commons-jcs3-3.2.1-bin/

输出：

LICENSE
NOTICE
RELEASE-NOTES.txt
commons-jcs-core
commons-jcs-jcache
commons-jcs-jcache-extras
commons-jcs-jcache-openjpa
commons-jcs-tck-tests

解读：核心 jar 是 /opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1.jar（547 kB）；JCS 为纯 Java 库，jar 跨平台通用，CentOS 与其他发行版使用同一份发行包。

5.4 最小程序编译运行验证

创建演示目录与最小程序 /opt/jcs-dist-demo/Main.java：

import org.apache.commons.jcs3.JCS;
import org.apache.commons.jcs3.access.CacheAccess;

public class Main {
    public static void main(String[] args) {
        CacheAccess<String, String> cache = JCS.getInstance("binRegion");
        cache.put("hello", "world");
        System.out.println("get(hello) = " + cache.get("hello"));
        cache.dispose();
        System.out.println("OK");
    }
}

配套最小配置 /opt/jcs-dist-demo/cache.ccf（classpath 上无 cache.ccf 会 NPE，见第九章 Q1）：

jcs.default.cacheattributes=org.apache.commons.jcs3.engine.CompositeCacheAttributes
jcs.default.cacheattributes.MaxObjects=100
jcs.default.cacheattributes.MemoryCacheName=org.apache.commons.jcs3.engine.memory.lru.LRUMemoryCache

逐项说明：jcs.default.cacheattributes 定义所有未显式声明区域（如 binRegion）的公共属性；MaxObjects=100 内存最多缓存 100 个对象；MemoryCacheName 指定内存淘汰实现为 LRU。

编译与文件确认（CentOS 上编译同样要用 JDK 17 的 javac，以完整路径调用最稳妥）：

cd /opt/jcs-dist-demo && javac -cp /opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1.jar Main.java
echo "javac exit=$?"
ls

输出：

javac exit=0
Main.class
Main.java
cache.ccf

运行（classpath 为当前目录 + core jar；core 无传递依赖，无需其它 jar）：

cd /opt/jcs-dist-demo && java -cp .:/opt/jcs3-dist/commons-jcs3-3.2.1-bin/commons-jcs-core/commons-jcs3-core-3.2.1.jar Main

输出节选（实测首尾；中段为 JUL 配置 INFO 日志，含 defaultCompositeCacheAttributes = [ useLateral = true, useRemote = true, useDisk = true, maxObjs = 100, maxSpoolPerRun = -1, diskUsagePattern = SWAP, spoolChunkSize = 2 ]、Parsed regions []、Finished configuration in 16 ms、initialized MemoryCache for binRegion 等，已省略）：

Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Instance is null, creating with config [/cache.ccf]
Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.control.CompositeCacheManager
INFO: Creating cache manager from config file: /cache.ccf
（中段 JUL 配置 INFO 日志省略）
get(hello) = world
Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [binRegion] fromRemote [false]
Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.control.event.ElementEventQueue
INFO: Element event queue destroyed: org.apache.commons.jcs3.engine.control.event.ElementEventQueue@31a5c39e
Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.control.CompositeCache
INFO: In DISPOSE, [binRegion] disposing of memory cache.
Oct 14, 2026 10:29:14 AM org.apache.commons.jcs3.engine.memory.AbstractMemoryCache
INFO: Memory Cache dispose called.
OK

验证点：get(hello) = world 且以 OK 结束，纯 jar 直跑可用。若系统 java 为 1.8 并报 UnsupportedClassVersionError，按 4.6 改用 JDK 17 完整路径。

六、源码安装方案（C：官方源码编译）

适合需要定制源码、调试或跟随版本线的场景。使用官方源码包，由 Maven 构建全部模块。

6.1 方案说明与前置依赖

下载官方源码包并用 Maven 构建整个 reactor。构建需要 JAVA_HOME 指向 JDK 17（4.3）与 Maven，首次构建需联网下载构建插件与依赖。

6.2 定位并下载源码包

注意：源码包不在 binaries/ 目录。先实测确认直接拼 binaries 路径会 404：

curl -sI https://downloads.apache.org/commons/jcs/binaries/commons-jcs3-dist-3.2.1-src.tar.gz | head -8

输出：

HTTP/1.1 404 Not Found
Date: Wed, 14 Oct 2026 10:34:08 GMT
Server: Apache
Content-Type: text/html; charset=iso-8859-1

按目录页探测 source/ 子目录，确认源码包存在：

curl -s https://downloads.apache.org/commons/jcs/source/ | grep -oE "href=\"[^\"]+\"" | head -10

输出：

href="http://archive.apache.org/dist/commons/"
href="#mirrors"
href="#sig"
href="?C=N;O=D"
href="?C=M;O=A"
href="?C=S;O=A"
href="?C=D;O=A"
href="/commons/jcs/"
href="commons-jcs3-dist-3.2.1-src.tar.gz"
href="commons-jcs3-dist-3.2.1-src.tar.gz.asc"

从 source/ 目录下载源码包并解压：

cd /tmp && curl -fSL -o commons-jcs3-dist-3.2.1-src.tar.gz https://downloads.apache.org/commons/jcs/source/commons-jcs3-dist-3.2.1-src.tar.gz
ls -la commons-jcs3-dist-3.2.1-src.tar.gz
mkdir -p /opt/jcs3-src && tar xzf commons-jcs3-dist-3.2.1-src.tar.gz -C /opt/jcs3-src
ls /opt/jcs3-src/ && ls /opt/jcs3-src/*/ | head -20

输出：

100  805k  100  805k    0     0   568k      0  0:00:01  0:00:01 --:--:--  568k
-rw-r--r-- 1 root root 824939 Oct 14 10:34 commons-jcs3-dist-3.2.1-src.tar.gz
commons-jcs3-3.2.1-src
BUILDING.txt
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
NOTICE
README.md
RELEASE-NOTES.txt
SECURITY.md
commons-jcs-core
commons-jcs-dist
commons-jcs-jcache
commons-jcs-jcache-extras
commons-jcs-jcache-openjpa
commons-jcs-tck-tests
pom.xml
src
xdocs

解读：第一行是 curl 的下载进度；源码包实测 824,939 字节；解压后 commons-jcs3-3.2.1-src 目录含 5 个子模块源码与聚合 pom.xml。

6.3 编译构建

在源码根目录执行 Maven 构建（跳过测试；JAVA_HOME 指向 JDK 17，见 4.3）：

cd /opt/jcs3-src/commons-jcs3-3.2.1-src && mvn -B package -DskipTests

输出节选（实测 Reactor Summary 完整；构建期间从中央仓库下载 973 个依赖/插件工件，联网下载约占 13:08 min）：

[INFO] Reactor Summary for Apache Commons JCS 3.2.1:
[INFO]
[INFO] Apache Commons JCS ................................. SUCCESS [13:08 min]
[INFO] Apache Commons JCS :: Core ......................... SUCCESS [ 31.599 s]
[INFO] Apache Commons JCS :: JCache ....................... SUCCESS [  1.054 s]
[INFO] Apache Commons JCS :: JCache TCK ................... SUCCESS [  0.719 s]
[INFO] Apache Commons JCS :: JCache Extras ................ SUCCESS [  1.064 s]
[INFO] Apache Commons JCS :: JCache OpenJPA ............... SUCCESS [  1.048 s]
[INFO] Apache Commons JCS :: Distribution ................. SUCCESS [  0.143 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  13:43 min
[INFO] Finished at: 2026-10-14T10:48:18Z
[INFO] ------------------------------------------------------------------------
exit=0

验证产物 jar 是否生成：

find /opt/jcs3-src/commons-jcs3-3.2.1-src -name "*.jar" | sort

输出：

/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-core/target/commons-jcs3-core-3.2.1-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-core/target/commons-jcs3-core-3.2.1-test-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-core/target/commons-jcs3-core-3.2.1-tests.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-core/target/commons-jcs3-core-3.2.1.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-extras/target/commons-jcs3-jcache-extras-3.2.1-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-extras/target/commons-jcs3-jcache-extras-3.2.1-test-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-extras/target/commons-jcs3-jcache-extras-3.2.1-tests.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-extras/target/commons-jcs3-jcache-extras-3.2.1.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-openjpa/target/commons-jcs3-jcache-openjpa-3.2.1-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-openjpa/target/commons-jcs3-jcache-openjpa-3.2.1-test-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-openjpa/target/commons-jcs3-jcache-openjpa-3.2.1-tests.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache-openjpa/target/commons-jcs3-jcache-openjpa-3.2.1.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1-cdi.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1-nocdi.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1-tests.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1-test-sources.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-jcache/target/commons-jcs3-jcache-3.2.1.jar
/opt/jcs3-src/commons-jcs3-3.2.1-src/commons-jcs-tck-tests/target/commons-jcs3-jcache-tck-3.2.1.jar

验证点：BUILD SUCCESS，核心产物为 commons-jcs-core/target/commons-jcs3-core-3.2.1.jar，另有 jcache 系列与 dist 聚合包。纯构建 Core 模块仅 31.6 s，总耗时长主要是首次联网下载。

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

三种方案各有取舍，本节汇总关键差异并给出选型建议。

维度方案 A：Maven 依赖方案 B：官方二进制包方案 C：源码编译
是否需联网构建时需联网（首次编译实测 45.5 s 下载插件）仅下载阶段需联网构建时需联网（实测总耗时 13:43 min）
依赖完整性自动解析（core 无传递依赖）只需 core jar 一个文件构建全部模块 jar
产物位置本地 Maven 仓库 ~/.m2/opt/jcs3-dist/opt/jcs3-src/*/target
JDK 要求（CentOS 8 特有）Maven 需 JAVA_HOME=17；运行用 17 完整路径javac/java 均用 17（完整路径）Maven 需 JAVA_HOME=17
版本升级改 pom 版本号重新解析重新下载替换目录重新下载源码包构建
适用场景可联网开发/CI（推荐）内网隔离、离线部署定制源码、调试、跟版本线

选择建议：可联网优先方案 A（声明依赖即可，最轻）；内网隔离选方案 B（一次下载、单 jar 拷贝即可离线运行）；需要改源码或自验证补丁选方案 C。三方案核心 jar 均为 commons-jcs3-core-3.2.1，行为一致。CentOS 8 上三方案都必须处理 JDK 解析：Maven 用 JAVA_HOME，java/javac 命令用 /usr/lib/jvm/java-17-openjdk/bin/ 完整路径或调整 alternatives/PATH。

八、配置说明

Commons JCS 的运行期「配置」集中在配置文件与环境变量两方面，本节逐项说明。

  • 配置文件位置与查找机制：JCS 从 classpath 上加载名为 cache.ccf 的资源（日志显示为 /cache.ccf）。Maven 工程放 src/main/resources/cache.ccf（4.4 采用，编译后随 target/classes 进 classpath）；独立 conf 目录则把目录加入 -cp。classpath 无 cache.ccf 时 3.2.1 直接 NPE（见第九章 Q1）。
  • 最小可用配置：只需 jcs.default.cacheattributes 三行（4.4 的 cache.ccf），未显式定义的区域走默认属性（回显 maxObjs = 100、diskUsagePattern = SWAP）。
  • 磁盘缓存目录：启用磁盘缓存时由 jcs.auxiliary.DC.attributes.DiskPath 指定（本文 /opt/jcs-demo/disk-cache），JCS 自动建目录，需写权限；配置逐项详解见《Apache Commons JCS 3.2.1 配置参数详解》。
  • JAVA_HOME 持久化（CentOS 8 关键项）：写入 profile 脚本并生效：
echo 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk' > /etc/profile.d/java17.sh
source /etc/profile.d/java17.sh
mvn -v | grep "Java version"

输出：

Java version: 17.0.1, vendor: Red Hat, Inc., runtime: /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64

验证点：重新登录后 Maven 仍解析到 JDK 17。但注意 JAVA_HOME 不影响 java 命令本身，运行程序仍需 17 的完整路径（4.6 实测），或同步调整 alternatives/PATH。

  • JVM 编码参数：默认编码为 ANSI_X3.4-1968 的系统上运行含中文输出的程序需加 -Dfile.encoding=UTF-8（4.6 实测命令均带此参数）。
  • JVM 堆内存：本文示例未限制堆；JCS 为进程内库，生产集成时建议在应用启动参数中固定 -Xms256m -Xmx512m 区间，并按缓存条目大小评估。

九、常见问题（FAQ）

Q1：运行直接抛 NullPointerException: inStream parameter is null？

classpath 上没有 cache.ccf。JCS 3.2.1 找不到该配置资源时不会回退内置默认值，而是 NPE（完整栈见《Ubuntu 22.04 安装 Apache Commons JCS 指南》4.6 节实测回显，两平台行为一致）。解决：把 cache.ccf 放进 src/main/resources（4.4 做法）或独立目录加入 -cp，日志出现 Creating cache manager from config file: /cache.ccf 且不再抛异常即为修复。

Q2：java -cp target/classes:$(cat cp.txt) JcsMini 报 UnsupportedClassVersionError（class file version 61.0 对 52.0）？

PATH 上的 java 是 1.8，而程序按 Java 17 编译（4.6 实测完整栈）。解决：用 /usr/lib/jvm/java-17-openjdk/bin/java 完整路径运行，或调整 alternatives/PATH 使 java 指向 17。export JAVA_HOME 解决不了这个问题——它只影响 Maven。

Q3：mvn compile 报 invalid target release: 17？

Maven 运行在 JDK 8 上。先看 mvn -v | head -3 中 Java version，若为 1.8，按 4.3 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk 后重试。

Q4：程序输出的中文乱码？

系统默认编码为 ANSI_X3.4-1968（见 4.3 回显）所致。运行时加 -Dfile.encoding=UTF-8（4.6 命令即如此），Maven 工程源码层面配 project.build.sourceEncoding=UTF-8。

Q5：dependency:get 下载了 junit、hsqldb 等组件，运行时需要它们吗？

不需要。commons-jcs3-core 的 POM 中这些组件均为非 compile 范围声明，实测 dependency:build-classpath（4.5）证明运行时 classpath 只需 core jar 本身。

Q6：进程结束时日志出现 Shutdown hook activated. Shutdown was not called. Shutting down JCS.？

这是 JCS 自带的 Shutdown 钩子：主线程未显式调用 JCS.shutdown() 时，JVM 退出阶段自动关闭缓存管理器（4.6 回显末行即为该日志）。建议程序仍显式 dispose() + JCS.shutdown()，磁盘缓存 keys 落盘依赖它（实测结论见《Apache Commons JCS 3.2.1 快速入门与集成示例》第六章）。

十、卸载与清理

Commons JCS 为纯 Java 库，不做系统级安装，删除工程目录、发行包与本地仓库中的构件即可完全清理：

rm -rf /opt/jcs-demo /opt/jcs-dist-demo /opt/jcs3-dist /opt/jcs3-src /tmp/commons-jcs3-dist-3.2.1-bin.tar.gz /tmp/commons-jcs3-dist-3.2.1-src.tar.gz
ls -d /opt/jcs-demo /opt/jcs-dist-demo /opt/jcs3-dist /opt/jcs3-src 2>/dev/null || echo "all removed"

输出：

all removed

如需同时清理 Maven 本地仓库中的 JCS 构件：

rm -rf /root/.m2/repository/org/apache/commons/commons-jcs3-core /root/.m2/repository/org/apache/commons/commons-jcs3-jcache /root/.m2/repository/org/apache/commons/commons-jcs3-jcache-extras /root/.m2/repository/org/apache/commons/commons-jcs3-jcache-openjpa
ls /root/.m2/repository/org/apache/commons/commons-jcs3-core 2>/dev/null || echo "maven artifacts removed"

输出：

maven artifacts removed

如不再需要 JDK 17 与 Maven，可用 dnf remove -y java-17-openjdk-devel maven 移除（影响范围需自行确认）；JDK 8 为系统默认 Java，建议保留。

十一、参考链接

  1. Apache Commons JCS 官方站点：https://commons.apache.org/proper/commons-jcs/
  2. 官方发行下载目录（binaries 与 source 子目录）：https://downloads.apache.org/commons/jcs/
  3. 历史版本归档目录：https://archive.apache.org/dist/commons/
  4. Maven 中央仓库坐标页：https://repo1.maven.org/maven2/org/apache/commons/commons-jcs3-core/
  5. Apache Commons JCS 源码仓库（GitHub 镜像）：https://github.com/apache/commons-jcs