CentOS 8 安装 Apache XML Graphics Commons 指南

在 EOL 的 CentOS 8 上从零安装 Apache XML Graphics Commons 2.11，实测复现 mirrorlist 失效并切换阿里云 centos-vault 源，安装 JDK 17 与 Maven 3.5.4，解决未设 JAVA_HOME 触发 invalid flag: --release 的关键坑，Maven 与官方 bin 包双方案均实测通过。

Apache XML Graphics CommonsApache XML Graphics Commons2026/10/15

CentOS 8 安装 Apache XML Graphics Commons 指南

目标：在 CentOS 8 上从零搭建 Apache XML Graphics Commons 2.11 的开发与运行环境，重点处理 CentOS 8 EOL 后软件源失效（mirrorlist 解析失败）与 JDK 多版本冲突两大问题，最终跑通 PNG 编码、PostScript 生成并用 file 验证产物；本文全部命令与回显均已在 CentOS 8 实测通过。

CentOS Linux 8 已于 2021-12-31 停止维护（EOL），官方镜像与 mirrorlist 服务相继下线，因此本文的安装流程分为两段：先把软件源切换到阿里云 centos-vault 归档源，再安装 JDK 17 + Maven 并引入 xmlgraphics-commons 2.11。Apache XML Graphics Commons 是纯 Java 库，提供图像写出（PNG/TIFF）、图像加载预检管线、PostScript 生成与 Base64/ASCII85 等编码流，是 FOP 打印链路的标准底座，安装的判定标准是运行验证程序后能产出格式正确的图像文件。

一、环境信息

  • 操作系统：CentOS Linux 8（x86_64，/etc/os-release 的 VERSION="8"，centos-linux-release 包版本 8.4）
  • 软件源：阿里云 centos-vault 归档（https://mirrors.aliyun.com/centos-vault/8.5.2111/）
  • JDK：java-17-openjdk-devel 17.0.1.0.12-2.el8_5（AppStream）
  • 构建工具：Apache Maven 3.5.4（Red Hat 3.5.4-5，el8 AppStream 内置）
  • 组件版本：xmlgraphics-commons 2.11（Maven Central 当前 latest/release）
  • 传递依赖：commons-io 2.17.0、commons-logging 1.3.0
  • Maven 坐标：org.apache.xmlgraphics:xmlgraphics-commons:2.11
  • 验证用工作目录：/opt/xgc-demo（工程）、/opt/xgc-demo/output（产物）、/root/jar-run（jar 直跑）

系统确认（实时回显）：

cat /etc/os-release | head -2
uname -m

NAME="CentOS Linux"
VERSION="8"
x86_64

💡 说明：XML Graphics Commons 是库而非服务，没有端口监听与常驻进程；「安装完成」以运行最小验证程序并产出真实图像文件为准。

二、前置条件

  1. 具有 root 权限的 CentOS 8 系统。
  2. 可访问 mirrors.aliyun.com（EOL 后默认源已不可用，见第三章实测）与 Maven 中央仓库 repo1.maven.org。
  3. 至少 2 GB 可用磁盘空间。
  4. 系统未安装 JDK，或已知晓本机 JDK 多版本现状（el8 的 alternatives 默认行为是本文关键坑，见 4.4 节）。

确认默认源现状（实时回显）：

yum repolist

repo id                         repo name
appstream                       CentOS Linux 8 - AppStream
baseos                          CentOS Linux 8 - BaseOS
extras                          CentOS Linux 8 - Extras

仓库定义还在，但拉取元数据会失败——下一章先修源。

三、版本选型说明

xmlgraphics-commons 的版本谱系与选型原则在第 1 篇《Ubuntu 22.04 安装 Apache XML Graphics Commons 指南》第三章已完整实测（Maven Central 元数据 latest=release=2.11，2.x 共 12 个版本，2.11 字节码 major=52 即 Java 8 基线，官方 bin 包当前仅提供 2.11）。CentOS 8 侧没有发行版级的二进制包，选型只涉及两个问题：

  1. 库版本：与 Ubuntu 完全一致，采用 org.apache.xmlgraphics:xmlgraphics-commons:2.11。
  2. JDK 版本：el8.5 AppStream 实测可用的 openjdk-devel 有三档：
yum list available "java-*-openjdk-devel" | grep -E "^java"

Available Packages
java-1.8.0-openjdk-devel.x86_64        1:1.8.0.312.b07-2.el8_5         appstream
java-11-openjdk-devel.x86_64           1:11.0.13.0.8-4.el8_5           appstream
java-17-openjdk-devel.x86_64           1:17.0.1.0.12-2.el8_5           appstream

本文采用 java-17-openjdk-devel 17.0.1：xmlgraphics-commons 2.11 是 Java 8 字节码，JDK 8 理论上也能运行，但 2.11 配套生态（FOP 2.x 等）与本文示例均按较新 JDK 编写，且 JDK 17 的 javac 支持 --release 语义，能避开老编译器的一类报错（见 4.4 节实测）。

四、方案 A：Maven 依赖安装（在线，推荐）

4.1 方案说明

链路是：修复软件源（阿里云 vault）→ 安装 JDK 17 与 Maven → 显式设置 JAVA_HOME → pom 声明依赖 → 编译运行验证程序。与 Ubuntu 的最大差别有两点：源要手工换到归档镜像；JAVA_HOME 必须显式设置，否则 Maven 会跑到 JDK 8 上。

4.2 修复软件源：mirrorlist 失效实测与切换

先复现默认源故障。直接拉取元数据：

yum makecache

Errors during downloading metadata for repository 'appstream':
  - Curl error (6): Couldn't resolve host name for http://mirrorlist.centos.org/?release=8&arch=x86_64&repo=AppStream&infra=... [Could not resolve host: mirrorlist.centos.org]
Error: Failed to download metadata for repo 'appstream': Cannot prepare internal mirrorlist: Curl error (6): Couldn't resolve host name for http://mirrorlist.centos.org/?release=8&arch=x86_64&repo=AppStream&infra=...

定位：mirrorlist.centos.org 服务已随 EOL 下线（DNS 无法解析；部分网络环境下该域表现为 403，本质相同）。修复思路是把 mirrorlist= 行注释掉，改用固定的归档 baseurl。阿里云 vault 可用版本实测（本机 centos-linux-release 为 8.4，vault 归档最高到 8.5.2111，因此直接写死 8.5.2111）：

curl -s --max-time 20 https://mirrors.aliyun.com/centos-vault/ | grep -oE "8\.[0-9.]+/" | sort -uV | tail -6

8.1.1911/
8.2.2004/
8.3.2011/
8.4.2105/
8.5.2111/
8.2003/

执行切换（对 /etc/yum.repos.d/CentOS-*.repo 全部生效）：

sed -i -e 's|mirrorlist=|#mirrorlist=|g' \
       -e 's|#baseurl=http://mirror.centos.org/$contentdir/$releasever|baseurl=https://mirrors.aliyun.com/centos-vault/8.5.2111|g' \
       /etc/yum.repos.d/CentOS-*.repo
grep -m1 baseurl /etc/yum.repos.d/CentOS-Linux-AppStream.repo

baseurl=https://mirrors.aliyun.com/centos-vault/8.5.2111/AppStream/$basearch/os/

再次拉取元数据验证：

yum makecache

CentOS Linux 8 - BaseOS                         365 kB/s | 4.6 MB     00:12
CentOS Linux 8 - Extras                          13 kB/s |   10 kB     00:00
Metadata cache created.

验证点：Metadata cache created. 出现即源修复完成，AppStream/BaseOS/Extras 三个仓库均可正常拉取。

4.3 安装 JDK 17 与 Maven

yum install -y java-17-openjdk-devel maven

# 输出节选（实测末尾）
  xorg-x11-fonts-Type1-7.5-19.el8.noarch
Complete!

安装后查看 JVM 目录与 alternatives 现状：

ls /usr/lib/jvm/ | grep java-17
alternatives --list | grep -E "^java"

java-17
java-17-openjdk
java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
java_sdk_1.8.0_openjdk  auto    /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.312.b07-2.el8_5.x86_64
java_sdk_17             auto    /usr/lib/jvm/java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
java                    auto    /usr/lib/jvm/java-1.8.0-openjdk-1.8.0.312.b07-2.el8_5.x86_64/jre/bin/java

关键发现：java 这个 alternatives 入口默认指向 JDK 8（1.8.0_312，其注册优先级高于 17）。此时 JAVA_HOME 为空、mvn -v 显示 Maven 运行在 1.8.0_312 上（实测回显）：

echo "JAVA_HOME=[$JAVA_HOME]"
mvn -v | head -3

JAVA_HOME=[]
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

4.4 关键坑：未设 JAVA_HOME 编译失败（实测复现）

创建工程（pom 与源码内容与第 1 篇 4.3 节完全相同，此处不再重复贴出；工程路径 /opt/xgc-demo）：

mkdir -p /opt/xgc-demo/src/main/java/demo
# 写入 /opt/xgc-demo/pom.xml 与 /opt/xgc-demo/src/main/java/demo/XgcDemo.java
# （内容见第 1 篇《Ubuntu 22.04 安装 Apache XML Graphics Commons 指南》4.3 节）
cd /opt/xgc-demo

不设置 JAVA_HOME 直接编译，实测失败：

mvn -B compile 2>&1 | grep -E "ERROR|invalid|Compiling"
javac -version; java -version 2>&1 | head -1

[INFO] Compiling 1 source file with javac [debug release 17] to target/classes
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.11.0:compile (default-compile) on project xgc-demo: Fatal error compiling: invalid flag: --release -> [Help 1]
javac 1.8.0_312
openjdk version "1.8.0_312"

定位：pom 里的 maven.compiler.release=17 需要 javac --release 支持（JDK 9+），而 Maven 实际调用的是 alternatives 默认的 JDK 8 javac，不认识 --release，于是报 invalid flag: --release。修复：显式导出 JAVA_HOME 指向 17：

export JAVA_HOME=/usr/lib/jvm/java-17
export PATH=$JAVA_HOME/bin:$PATH
mvn -v | head -3

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

JAVA_HOME 持久化的推荐做法（写入 profile 脚本，所有登录会话生效）：

cat > /etc/profile.d/java17.sh <<'EOF'
export JAVA_HOME=/usr/lib/jvm/java-17
export PATH=$JAVA_HOME/bin:$PATH
EOF

4.5 编译、运行与产物验证

mvn -q -B package
echo "EXIT=$?"
ls -l target/*.jar | awk '{print $5, $9}'

EXIT=0
9725 target/xgc-demo-1.0.0.jar

运行验证程序（classpath 拼本地仓库三件套）：

CP=target/classes:/root/.m2/repository/commons-io/commons-io/2.17.0/commons-io-2.17.0.jar:/root/.m2/repository/commons-logging/commons-logging/1.3.0/commons-logging-1.3.0.jar:/root/.m2/repository/org/apache/xmlgraphics/xmlgraphics-commons/2.11/xmlgraphics-commons-2.11.jar
java -Dfile.encoding=UTF-8 -Djava.awt.headless=true -cp "$CP" demo.XgcDemo

writer 实现: org.apache.xmlgraphics.image.writer.imageio.ImageIOPNGImageWriter
writer MIME: image/png, isFunctional=true
已写入 /opt/xgc-demo/output/demo.png 字节数=14007

file 验证产物：

file output/demo.png

output/demo.png:           PNG image data, 320 x 200, 8-bit/color RGBA, non-interlaced

验证点：EXIT=0、PNG 字节数 14007（与 Ubuntu 的 14114 略有差异属正常，文字渲染所用的物理字体不同）、file 能识别 PNG 且尺寸一致。headless 组在 CentOS 上同样可用（实测 getAvailableFontFamilyNames() 返回 11 个字体族，含 Bitstream Charter、Cantarell、Courier 10 Pitch 等 el8 自带字体）。

五、方案 B：官方 bin 包 + jar 直跑（离线友好）

5.1 下载与校验

cd /root && curl -sO --max-time 120 https://downloads.apache.org/xmlgraphics/commons/binaries/xmlgraphics-commons-2.11-bin.tar.gz
curl -sO --max-time 60 https://downloads.apache.org/xmlgraphics/commons/binaries/xmlgraphics-commons-2.11-bin.tar.gz.sha512
ls -l xmlgraphics-commons-2.11-bin.tar.gz
echo "期望: $(cat xmlgraphics-commons-2.11-bin.tar.gz.sha512)"
echo "实测: $(sha512sum xmlgraphics-commons-2.11-bin.tar.gz | awk '{print $1}')"

-rw-r--r-- 1 root root 2009106 Oct 15 11:24 xmlgraphics-commons-2.11-bin.tar.gz
期望: 8ebf305f9a435fb6fbde73dc831cd7a220653ec3b7be0147c054f1aebae65b5a97076810dcdfd45351c005be4014913f74e6235ccdb2d8e6b61dc311e7dc06f2  xmlgraphics-commons-2.11-bin.tar.gz
实测: 8ebf305f9a435fb6fbde73dc831cd7a220653ec3b7be0147c054f1aebae65b5a97076810dcdfd45351c005be4014913f74e6235ccdb2d8e6b61dc311e7dc06f2

5.2 解压与 jar 直跑

bin 包结构与第 1 篇 5.3 节一致（build/ 放主 jar，lib/ 自带 commons-io 与 commons-logging）。解压并编译：

tar xzf xmlgraphics-commons-2.11-bin.tar.gz
mkdir -p /root/jar-run/out && cd /root/jar-run
JARDIR=/root/xmlgraphics-commons-2.11
javac -encoding UTF-8 -cp $JARDIR/build/xmlgraphics-commons-2.11.jar:$JARDIR/lib/commons-io-2.17.0.jar:$JARDIR/lib/commons-logging-1.3.0.jar -d out XgcDemo.java
echo "JAVAC_EXIT=$?"
java -Dfile.encoding=UTF-8 -Djava.awt.headless=true -cp out:$JARDIR/build/xmlgraphics-commons-2.11.jar:$JARDIR/lib/commons-io-2.17.0.jar:$JARDIR/lib/commons-logging-1.3.0.jar XgcDemo

JAVAC_EXIT=0
== PostScript 输出（PSGenerator） ==
formatDouble(72.0/300) = 0.24
已写入 /opt/xgc-demo/output/demo.ps 字节数=451

⚠️ 注意：若当前会话忘了设置 JAVA_HOME，上面 javac 会落到 JDK 8 上，实测报 javac: directory not found: out——JDK 8 的 javac 不自动创建 -d 指定的输出目录（JDK 9+ 会自动创建），且后续编译示例代码还会因 JDK 9+ 的 API 而报错。务必先执行 4.4 节的两行 export。

file 验证 PS 产物：

file /opt/xgc-demo/output/demo.ps

/opt/xgc-demo/output/demo.ps:      PostScript document text conforming DSC level 3.0

六、方案对比与选择建议

维度方案 A：Maven 依赖方案 B：官方 bin 包 + jar 直跑
软件源依赖需先修复 EOL 源（4.2 节）仅需能访问 downloads.apache.org
依赖管理pom 统一管控，传递依赖自动lib/ 自带三件套，手工拼 classpath
JDK 要求必须显式 JAVA_HOME（否则 JDK 8 报错）同样必须显式 JAVA_HOME（javac 行为差异）
适用场景el8 上的常规工程开发源修复困难的内网/离线服务器

选型建议：两方案在 CentOS 8 上都依赖「显式 JAVA_HOME」这一前提；源已修复则优先方案 A，长期离线环境用方案 B 并把 bin 包纳入本地制品管理。

七、基础配置说明

7.1 JAVA_HOME（el8 必配）

el8 的 alternatives 默认 java 指向 JDK 8（4.3 节实测），因此 el8 必须显式设置 JAVA_HOME=/usr/lib/jvm/java-17，并建议通过 /etc/profile.d/java17.sh 持久化。/usr/lib/jvm/java-17 是安装包提供的稳定软链，指向具体小版本目录 java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64，后续 yum 升级小版本无需改配置。

7.2 headless 与字体

服务器无图形界面，运行验证程序统一加 -Djava.awt.headless=true（本机 DISPLAY 为空时 JVM 也会自动判定，但显式声明更稳）。el8 基础环境自带 Bitstream Charter、Cantarell 等字体（实测可用字体族 11 个），drawString 直接可用；如需 DejaVu 系字体可另装 dejavu-fonts-common/dejavu-sans-fonts。

7.3 代码级「参数」

写出分辨率（ImageWriterParams.setResolution）、TIFF 压缩算法（setCompressionMethod）、ImageContext 源分辨率等均通过 API 入参控制，无外部配置文件；完整实测行为见第 4 篇《Apache XML Graphics Commons 2.11 图像编解码与 IO API 详解》。

八、验证清单

检查项预期（实测值）不符时排查
yum makecacheMetadata cache created.报 resolve mirrorlist.centos.org 失败 → 4.2 节换源
yum list java-17-openjdk-devel17.0.1.0.12-2.el8_5源未指到 8.5.2111 归档 → 4.2 节
mvn -v 的 Java version17.0.1（不是 1.8.0_312）未 export JAVA_HOME → 4.4 节
mvn -q -B packageEXIT=0报 invalid flag: --release → 4.4 节
运行输出 PNG 字节数14007报 NoClassDefFoundError → classpath 缺依赖 jar
file 识别产物PNG image data, 320 x 200, 8-bit/color RGBA输出为空 → 检查输出流 close

九、常见问题（FAQ）

Q1：yum makecache 报 Couldn't resolve host: mirrorlist.centos.org（或 HTTP 403）怎么办？ CentOS 8 EOL 后 mirrorlist 服务已下线，属预期现象。按 4.2 节把 repo 文件的 mirrorlist= 注释掉、启用指向 https://mirrors.aliyun.com/centos-vault/8.5.2111/ 的 baseurl= 即可；vault 归档里 el8 最高版本是 8.5.2111，不要再写 $releasever（本机为 8.4，归档中无此目录）。

Q2：编译报 Fatal error compiling: invalid flag: --release？ Maven 跑在 JDK 8 上（el8 alternatives 默认值）。执行 export JAVA_HOME=/usr/lib/jvm/java-17 && export PATH=$JAVA_HOME/bin:$PATH 后重试，并按 7.1 节持久化。用 mvn -v 的 Java version 行确认是否 17.0.1。

Q3：javac 报 directory not found: out？ 当前 javac 是 JDK 8：它不会自动创建 -d 指定的输出目录（JDK 9+ 会）。先 mkdir -p out，或设置 JAVA_HOME 到 17 再编译（推荐后者，源码里用了 JDK 9+ 的 InputStream.readAllBytes 等方法时 JDK 8 无法编译）。

Q4：运行时报 NoClassDefFoundError（commons-io 或 commons-logging）？ xmlgraphics-commons 2.11 依赖 commons-io 2.17.0 与 commons-logging 1.3.0。Maven 方案自动解析；jar 直跑方案必须把 bin 包 lib/ 下两个 jar 拼进 -cp。

Q5：生成的 PNG 字节数和 Ubuntu 机器上不一样？ 正常。PNG 内的文字栅格化结果依赖机器字体（el8 实测字体族 11 个，Ubuntu 12 个），图像尺寸与格式不受影响，file 验证以 320x200 RGBA 为准。

Q6：xmlgraphics-commons 2.11 需要 JDK 17 吗？ 不需要。实测其字节码主版本号为 52（Java 8），JDK 8 及以上可运行；本文用 JDK 17 是为了配合 --release 编译语义与新生态，属推荐而非硬性要求。

十、卸载与清理

移除工程与 bin 包：

rm -rf /opt/xgc-demo /root/jar-run /root/xmlgraphics-commons-2.11 /root/xmlgraphics-commons-2.11-bin.tar.gz
ls /opt/xgc-demo 2>&1

ls: cannot access '/opt/xgc-demo': No such file or directory

移除 Maven 本地仓库中的相关构件（影响所有工程，慎用）：

rm -rf /root/.m2/repository/org/apache/xmlgraphics/xmlgraphics-commons
rm -rf /root/.m2/repository/commons-io/commons-io/2.17.0
rm -rf /root/.m2/repository/commons-logging/commons-logging/1.3.0

卸载 JDK 与 Maven（先 -s 预演确认，无误后去掉 -s 执行）：

yum -s remove java-17-openjdk-devel maven | tail -4

# 输出节选（预演格式）
Removing:
 java-17-openjdk-devel  x86_64  1:17.0.1.0.12-2.el8_5  @appstream
 maven                  noarch  3.5.4-5.module_el8.5.0+...  @appstream

yum remove -y java-17-openjdk-devel maven

如需恢复系统默认源配置（放弃归档源），重新安装 centos-linux-repos 包即可覆盖被 sed 修改的 repo 文件。

十一、参考链接

  1. Apache XML Graphics Commons 官方主页：https://xmlgraphics.apache.org/commons/
  2. 官方 bin 下载目录：https://downloads.apache.org/xmlgraphics/commons/binaries/
  3. Maven 中央仓库坐标页：https://repo1.maven.org/maven2/org/apache/xmlgraphics/xmlgraphics-commons/
  4. 阿里云 CentOS Vault 归档镜像：https://mirrors.aliyun.com/centos-vault/
  5. CentOS 8 EOL 说明与归档源指引：https://www.centos.org/centos-linux-eol/