CentOS 8 安装 Apache Anakia 指南

目标：在 CentOS 8 服务器上从零安装 Apache Anakia（基于 Apache Velocity 1.7 的 XML 转文本 Ant 任务），覆盖 vault 归档源切换、JDK 17 安装、Ant 1.10.18 部署、velocity-1.7 及依赖 jar 校验、RPM 版 ant 的 -lib 失效排障实录与最小 XML→HTML 转换验收，已在 CentOS 8.4.2105（OpenJDK 17.0.1、Ant 1.10.18）实测通过。

一、环境信息

本篇所有命令与回显均在以下环境中实测采集，复现时请保持相近版本：

操作系统：CentOS Linux 8.4.2105，x86_64
JDK：OpenJDK 17.0.1（java-17-openjdk-devel，AppStream 仓库）
构建工具：Apache Ant 1.10.18（官方 dlcdn 发行包，2026-10 实测当前最新）
组件版本：Apache Anakia（随 org.apache.velocity:velocity:1.7 jar 发布，无独立发行包；jar 449505 字节）
依赖 jar：commons-lang-2.6（284220 字节）、commons-collections-3.2.2（588337 字节）、jdom-1.1.3（151304 字节），均取自 Maven 中央仓库
安装目录：/opt/apache-ant-1.10.18（Ant 主目录）、/opt/anakia-lib（Anakia 运行时 jar 库）
实验目录：/opt/anakia-demo（验收测试工程）
执行用户：root

💡 技术拓展：Anakia 是 Apache Velocity 项目内置的 XML→文本转换工具，把 JDOM 解析出的 XML 树交给 Velocity 模板渲染。它不是独立发行包，而是 velocity-1.7.jar 里 org.apache.velocity.anakia 包的一部分——「安装 Anakia」实际是「装 Velocity 1.7 运行时并注册 Ant 任务」。Velocity 2.x 已移除该包，Anakia 止步于 1.7 线（判定依据与实测回显见《Ubuntu 22.04 安装 Apache Anakia 指南》第三章）。

二、前置条件

Anakia 以 Ant 任务形态工作，安装链路是「JDK → Ant → Anakia 运行时 jar」。CentOS 8 已于 2021 年底停止维护，官方源下线后需先切换归档源。

2.1 确认系统版本并切换 vault 归档源

cat /etc/redhat-release

回显（实测）：

CentOS Linux release 8.4.2105

若机器源仍指向已下线的 mirror.centos.org，整体切换到阿里云归档源（8.5.2111 为 CentOS 8 最终版本目录）：

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-Linux-*.repo && dnf clean all && dnf repolist

回显（实测节选）：

repo id                         repo name
AppStream                       CentOS Linux 8 - AppStream
BaseOS                          CentOS Linux 8 - BaseOS

2.2 安装基础工具

dnf install -y wget curl which unzip

回显（实测节选）：

Installed:
  unzip-6.0-43.el8.x86_64            which-2.21-12.el8.x86_64
Complete!

⚠️ 注意：which 必须装。Ant 官方启动脚本靠 which 命令定位 java，CentOS 8 最小环境不带它，缺了会导致 ant 报 “We cannot run Java”（排障实录见 FAQ 8.1）。

2.3 安装 JDK 17

dnf install -y java-17-openjdk-devel

回显（实测节选）：

Installed:
  java-17-openjdk-17.0.1.0.12-2.el8_5.x86_64
  java-17-openjdk-devel-17.0.1.0.12-2.el8_5.x86_64
  java-17-openjdk-headless-17.0.1.0.12-2.el8_5.x86_64

Complete!

java -version && rpm -q java-17-openjdk-devel

回显（实测）：

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)
java-17-openjdk-devel-17.0.1.0.12-2.el8_5.x86_64

三、版本选型说明

Anakia 本体不分操作系统：Maven 中央仓库的 org.apache.velocity:velocity:1.7 是唯一构件来源，anakia 包在其中（构建日期 2010-11-19，13 个 class）；Velocity 2.x 线（velocity-engine-core 2.4.1，515658 字节）实测 unzip -l | grep -ci anakia 计数为 0，需要 Anakia 只能回 1.7。

组件	实测版本	说明	获取渠道
Anakia（velocity）	1.7（2010-11-19 构建）	anakia 包所在构件，1.x 线最终版	Maven 中央仓库 `org.apache.velocity:velocity:1.7`
velocity-engine-core	2.4.1（2024-10 构建）	Velocity 2.x 已移除 anakia 包	Maven 中央仓库
commons-lang	2.6（2011-01-16 构建）	Velocity 1.7 运行依赖（1.7 pom 声明 2.4，实测 2.6 兼容）	Maven 中央仓库 `commons-lang:commons-lang:2.6`
commons-collections	3.2.2（2015-11-12 构建）	Velocity 1.7 运行依赖（含反序列化漏洞修复的最终版）	Maven 中央仓库 `commons-collections:commons-collections:3.2.2`
JDOM	1.1.3（2012-02-27 构建）	XML 解析依赖（1.7 pom 声明 1.0，实测 1.1.3 兼容）	Maven 中央仓库 `org.jdom:jdom:1.1.3`
Apache Ant	1.10.18（方案 A） / 1.10.5（方案 B）	AnakiaTask 的宿主	dlcdn.apache.org / AppStream
JDK	OpenJDK 17.0.1（17.0.1.0.12-2.el8_5）	运行 Ant 与转换正常	AppStream 仓库

💡 技术拓展：XML 解析器选型——JDOM 是面向 Java 惯用法的树形解析器（对比 W3C DOM 更贴近 Java 集合风格、对比 SAX 免写事件回调），Anakia 选择它是因为模板里要直接遍历元素树（$root.getChildren("section")）。同类选择还有 dom4j、XOM；标准解析路线则交给 Xerces 系实现。

选型建议：新环境用「Velocity 1.7 + 依赖三件套 + Ant 1.10.18」组合；commons-collections 务必选 3.2.2（官方修复版）；CentOS 8 仓库里的 ant 只有 1.10.5，追求新版本走方案 A 的官方发行包。

四、安装方案 A：官方 Ant + Maven Central 依赖 jar（推荐）

4.1 安装 Ant 1.10.18 并校验 sha512

cd /opt && wget https://dlcdn.apache.org/ant/binaries/apache-ant-1.10.18-bin.tar.gz && wget https://dlcdn.apache.org/ant/binaries/apache-ant-1.10.18-bin.tar.gz.sha512 && printf '%s  %s\n' "$(cat apache-ant-1.10.18-bin.tar.gz.sha512)" apache-ant-1.10.18-bin.tar.gz | sha512sum -c - && tar xzf apache-ant-1.10.18-bin.tar.gz

回显（实测）：

apache-ant-1.10.18-bin.tar.gz: OK

校验 OK 说明下载完整（官方 sha512 值为 c510d744876d8da48dabc9495b023b6ec5284a0f18b40ee50d98ce099e791ca5c73e3cd4c80d3c90d3efc03f9620be43aad0a373ed47198284f7e3373e0db2c3）。

4.2 配置环境变量与 JVM 参数

写入 /etc/profile.d/ant.sh，所有登录会话生效：

printf 'export JAVA_HOME=/usr/lib/jvm/java-17-openjdk\nexport ANT_HOME=/opt/apache-ant-1.10.18\nexport PATH=$ANT_HOME/bin:$JAVA_HOME/bin:$PATH\nexport ANT_OPTS="-Xms256m -Xmx512m"\n' > /etc/profile.d/ant.sh && source /etc/profile.d/ant.sh

回显（实测，无输出）：

配置项说明：JAVA_HOME=/usr/lib/jvm/java-17-openjdk 是 AppStream 包维护的版本无关符号链接（实测指向 /etc/alternatives/java_sdk_17_openjdk），升级小版本无需改配置；ANT_HOME 供 Ant 启动脚本定位 lib 目录；ANT_OPTS 传给 Ant 进程的 JVM——-Xms256m -Xmx512m 控制堆大小（站点文档量大时可再调大），按需可追加 -Dfile.encoding=UTF-8（Anakia 输出编码由 velocity.properties 控制，见 FAQ 8.3）。

验证 ANT_OPTS 确实进入 JVM 启动命令行（--execdebug 打印启动器实际执行的命令）：

ant --execdebug 2>&1 | grep -oE '\-Xms256m -Xmx512m'

回显（实测）：

-Xms256m -Xmx512m

ant -version

回显（实测）：

Apache Ant(TM) version 1.10.18 compiled on September 3 2026

4.3 下载 Anakia 运行时 jar 并校验

四个 jar 统一放到 /opt/anakia-lib，逐个记录 sha256 便于审计与重放：

mkdir -p /opt/anakia-lib && cd /opt/anakia-lib && wget -q https://repo1.maven.org/maven2/org/apache/velocity/velocity/1.7/velocity-1.7.jar && wget -q https://repo1.maven.org/maven2/commons-lang/commons-lang/2.6/commons-lang-2.6.jar && wget -q https://repo1.maven.org/maven2/commons-collections/commons-collections/3.2.2/commons-collections-3.2.2.jar && wget -q https://repo1.maven.org/maven2/org/jdom/jdom/1.1.3/jdom-1.1.3.jar && sha256sum velocity-1.7.jar commons-lang-2.6.jar commons-collections-3.2.2.jar jdom-1.1.3.jar

回显（实测）：

ec92dae810034f4b46dbb16ef4364a4013b0efb24a8c5dd67435cae46a290d8e  velocity-1.7.jar
50f11b09f877c294d56f24463f47d28f929cf5044f648661c0f0cfbae9a2f49c  commons-lang-2.6.jar
eeeae917917144a68a741d4c0dff66aa5c5c5fd85593ff217bced3fc8ca783b8  commons-collections-3.2.2.jar
02bd61a725e8af9b0176b43bf29816d0c748b8ab951385bd127be37489325a0a  jdom-1.1.3.jar

ls -l /opt/anakia-lib/

回显（实测）：

total 1444
-rw-r--r-- 1 root root 588337 Nov 12  2015 commons-collections-3.2.2.jar
-rw-r--r-- 1 root root 284220 Jan 16  2011 commons-lang-2.6.jar
-rw-r--r-- 1 root root 151304 Feb 27  2012 jdom-1.1.3.jar
-rw-r--r-- 1 root root 449505 Nov 29  2010 velocity-1.7.jar

Anakia 没有独立发行包，jar 部署到任意目录后由构建文件的 taskdef 挂载即可，方案 A 到此完成（验收见第七章）。

五、安装方案 B：dnf 系统仓库 Ant（备选）与 RPM 版排障实录

方案 B 直接用 dnf 装 Ant，一条命令完成，但版本停留在 1.10.5，且 RPM 版启动脚本的类路径机制与官方发行包不同。

5.1 安装 Ant

dnf install -y ant

回显（实测节选）：

Installed:
  ant-1.10.5-1.module_el8.0.0+47+197dca37.noarch
  ant-lib-1.10.5-1.module_el8.0.0+47+197dca37.noarch
  javapackages-tools-5.3.0-1.module_el8.0.0+11+5b8c10bd.noarch

Complete!

/bin/ant -version

回显（实测）：

Apache Ant(TM) version 1.10.5 compiled on June 24 2019

5.2 RPM 版 ant 的 `-lib` 失效排障实录

官方发行版的启动脚本支持 ant -lib <路径> 追加 jar 搜索路径，但 RHEL/CentOS 的 RPM 版脚本用 build-classpath 拼固定类路径清单。实测验证——准备一个不带 taskdef classpath 的构建文件（build-lib.xml，taskdef 仅写 classname），用 -lib 指向 jar 目录：

cd /opt/anakia-demo && /bin/ant -lib /opt/anakia-lib -f build-lib.xml

回显（实测）：

BUILD FAILED
/opt/anakia-demo/build-lib.xml:7: taskdef class org.apache.velocity.anakia.AnakiaTask cannot be found
 using the classloader AntClassLoader[]

Total time: 0 seconds

AntClassLoader[] 为空，证明 -lib 传进去的路径没有进入任务加载器。

5.3 RPM 版 ant 的可用姿势：taskdef 显式 classpath

构建文件内 taskdef 的嵌套 <classpath> 由 Ant 自身在任务执行时解析，不依赖启动脚本，RPM 版同样有效：

cd /opt/anakia-demo && /bin/ant -f build.xml

回显（实测节选）：

   [anakia] Transforming into: /opt/anakia-demo/docs
   [anakia] Input:  index.xml
   [anakia] Output: /opt/anakia-demo/docs/index.html

BUILD SUCCESSFUL
Total time: 0 seconds

结论：RPM 版 ant 跑 Anakia，用 build.xml 内 taskdef classpath 挂 jar（本篇验收工程默认写法），不要依赖 -lib。

六、方案对比与选择建议

维度	方案 A：官方 tar.gz + Maven Central jar	方案 B：dnf 系统仓库
Ant 版本	1.10.18（官方最新）	1.10.5-1（AppStream 当前）
`-lib` 追加 jar	支持	不支持（RPM 启动脚本固定清单，实测 5.2）
Anakia 运行时	velocity-1.7.jar + 3 个依赖 jar（自管）	同左（Anakia 不随 dnf 分发）
升级方式	手动替换 jar/目录	dnf 随模块仓库升级
适合场景	生产文档站点构建，版本可控可审计	快速验证、已有 RPM ant 的存量机器

选择建议：生产环境选方案 A（Ant 新、-lib 可用、jar 自管审计友好）；存量机器上已有 RPM ant 时用方案 B，但必须写 taskdef classpath。

七、安装验收：最小 XML→HTML 转换

本节跑一个最小的 Anakia 转换工程作为安装完成的最终验收。三件套：XML 源、Velocity 模板（.vsl）、Ant 构建文件。

7.1 编写工程文件

mkdir -p /opt/anakia-demo/styles /opt/anakia-demo/src/xml && cat > /opt/anakia-demo/src/xml/index.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<document>
  <title>Apache Anakia 快速上手</title>
  <section name="简介">
    <p>Anakia 使用 JDOM 解析 XML 文档，再用 Velocity 模板引擎渲染输出。</p>
  </section>
  <section name="特性">
    <p>模板完全控制输出格式，VTL 指令全部可用。</p>
  </section>
</document>
EOF

回显（实测，无输出）：

cat > /opt/anakia-demo/styles/site.vsl << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>$root.getChild("title").getTextTrim()</title>
  </head>
  <body>
    <h1>$root.getChild("title").getTextTrim()</h1>
#foreach ($node in $root.getChildren("section"))
    <h2>$node.getAttributeValue("name")</h2>
#foreach ($para in $node.getChildren("p"))
    <p>$para.getTextTrim()</p>
#end
#end
    <hr/>
    <p>Generated by Apache Anakia / Velocity 1.7</p>
  </body>
</html>
EOF
printf 'output.encoding=UTF-8\ninput.encoding=UTF-8\n' > /opt/anakia-demo/styles/velocity.properties

回显（实测，无输出）：

cat > /opt/anakia-demo/build.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project name="anakia-demo" default="docs" basedir=".">

  <property name="docs.src" location="${basedir}/src/xml"/>
  <property name="docs.dest" location="${basedir}/docs"/>

  <taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask">
    <classpath>
      <pathelement location="/opt/anakia-lib/velocity-1.7.jar"/>
      <pathelement location="/opt/anakia-lib/commons-lang-2.6.jar"/>
      <pathelement location="/opt/anakia-lib/commons-collections-3.2.2.jar"/>
      <pathelement location="/opt/anakia-lib/jdom-1.1.3.jar"/>
    </classpath>
  </taskdef>

  <target name="docs" description="Transform XML docs to HTML with Anakia">
    <mkdir dir="${docs.dest}"/>
    <anakia basedir="${docs.src}" destdir="${docs.dest}"
            extension=".html"
            style="site.vsl"
            templatePath="${basedir}/styles"
            velocityPropertiesFile="${basedir}/styles/velocity.properties"
            lastModifiedCheck="true"/>
  </target>
</project>
EOF

回显（实测，无输出）：

配置说明：taskdef 把 org.apache.velocity.anakia.AnakiaTask 注册为 <anakia> 任务，嵌套 <classpath> 挂上四个 jar（RPM 版 ant 下这是唯一可靠挂法，见 5.2）；style 用相对 templatePath 的文件名（绝对路径会报错，见 FAQ 8.2）；velocityPropertiesFile 指定输出编码（见 FAQ 8.3）。

7.2 运行验收

cd /opt/anakia-demo && ant

回显（实测）：

Buildfile: /opt/anakia-demo/build.xml

docs:
    [mkdir] Created dir: /opt/anakia-demo/docs
   [anakia] Transforming into: /opt/anakia-demo/docs
   [anakia] Input:  index.xml
   [anakia] Output: /opt/anakia-demo/docs/index.html

BUILD SUCCESSFUL
Total time: 0 seconds

cat /opt/anakia-demo/docs/index.html

回显（实测）：

<?xml version="1.0" encoding="UTF-8"?>
<html>
  <head>
    <title>Apache Anakia 快速上手</title>
  </head>
  <body>
    <h1>Apache Anakia 快速上手</h1>
    <h2>简介</h2>
    <p>Anakia 使用 JDOM 解析 XML 文档，再用 Velocity 模板引擎渲染输出。</p>
    <h2>特性</h2>
    <p>模板完全控制输出格式，VTL 指令全部可用。</p>
    <hr/>
    <p>Generated by Apache Anakia / Velocity 1.7</p>
  </body>
</html>

BUILD SUCCESSFUL 且生成的 HTML 中文、标题、段落齐全，Anakia 环境安装验收通过。

八、常见问题（FAQ）

8.1 ant 报 “We cannot run Java”，但 java -version 正常

现象（实测，最小环境未装 which 时）：

We cannot run Java, please ensure you have Java installed.
  We have tried to execute java but failed.
If you have installed Java in a unusual place you can set JAVA_HOME
to the directory containing the Java installation.

排障过程（跟踪启动脚本实际执行行）：

bash -x /opt/apache-ant-1.10.18/bin/ant -version 2>&1 | grep -E 'which java|JAVACMD'

回显（实测）：

++ which java
+ JAVACMD=

原因与解决：Ant 启动脚本靠 which 定位 java，CentOS 8 最小环境没有 which，定位结果为空。两条路任选：dnf install -y which；或在环境变量里显式设置 JAVA_HOME=/usr/lib/jvm/java-17-openjdk（本篇 4.2 节两者都做了）。

8.2 style 用绝对路径报 ResourceNotFoundException

现象（实测，style="/opt/anakia-demo/styles/site.vsl"）：

BUILD FAILED
/opt/anakia-demo/build.xml:22: org.apache.velocity.exception.ResourceNotFoundException: Unable to find resource '/opt/anakia-demo/styles/site.vsl'

原因与解决：style 会被 Velocity 文件资源加载器按 templatePath 相对解析，绝对路径会被拼进加载器根目录下导致找不到。写成相对 templatePath 的文件名 style="site.vsl" 即可。

8.3 生成的 HTML 中文变问号

现象（实测，未配置 velocity.properties 时）：HTML 中的中文全部输出为 ?。Anakia 写 HTML 时使用 Velocity 的 output.encoding 属性，缺省回退 ISO-8859-1（实测把 JVM 的 file.encoding 调成 UTF-8 并无效）。解决：velocity.properties 里声明 output.encoding=UTF-8 与 input.encoding=UTF-8，并通过 <anakia> 的 velocityPropertiesFile 属性显式挂载（写法见 7.1，实测生成中文正常的 HTML 见 7.2）。

8.4 dnf 装的 ant 找不到 anakia 任务

RPM 版 ant 启动脚本用 build-classpath 拼固定类路径，不响应 -lib 参数（实测回显与结论见 5.2/5.3）。解决：在 build.xml 的 <taskdef> 里用嵌套 <classpath> 显式列出四个 jar。

九、卸载与清理

卸载 Ant 主目录、Anakia 运行时 jar 与配置：

rm -rf /opt/apache-ant-1.10.18 /opt/anakia-lib /opt/anakia-demo && rm -f /opt/apache-ant-1.10.18-bin.tar.gz* && rm -f /etc/profile.d/ant.sh

回显（实测，无输出）：

若曾按方案 B 装过 dnf 版 Ant，一并移除：

dnf remove -y ant

回显（实测节选）：

Removing:
 ant                     noarch      1.10.5-1.module_el8.0.0+47+197dca37
Removed:
  ant-1.10.5-1.module_el8.0.0+47+197dca37.noarch

验证清理干净：

bash -lc 'which ant; echo exit=$?'

回显（实测）：

exit=1

which ant 无输出且退出码为 1，说明 ant 命令已不存在，卸载完成。

十、参考链接

Apache Velocity 官方主页：https://velocity.apache.org/
Anakia 官方文档（Velocity 引擎站点内）：https://velocity.apache.org/engine/devel/anakia.html
Maven 中央仓库 velocity 1.7：https://repo1.maven.org/maven2/org/apache/velocity/velocity/1.7/
Maven 中央仓库 JDOM 1.1.3：https://repo1.maven.org/maven2/org/jdom/jdom/1.1.3/
阿里云 CentOS vault 归档源：https://mirrors.aliyun.com/centos-vault/
Apache Ant 官方手册：https://ant.apache.org/manual/
Ant taskdef 任务手册：https://ant.apache.org/manual/Tasks/taskdef.html

CentOS 8 安装 Apache Anakia 指南

CentOS 8 安装 Apache Anakia 指南

一、环境信息

二、前置条件

2.1 确认系统版本并切换 vault 归档源

2.2 安装基础工具

2.3 安装 JDK 17

三、版本选型说明

四、安装方案 A：官方 Ant + Maven Central 依赖 jar（推荐）

4.1 安装 Ant 1.10.18 并校验 sha512

4.2 配置环境变量与 JVM 参数

4.3 下载 Anakia 运行时 jar 并校验

五、安装方案 B：dnf 系统仓库 Ant（备选）与 RPM 版排障实录

5.1 安装 Ant

5.2 RPM 版 ant 的 -lib 失效排障实录

5.3 RPM 版 ant 的可用姿势：taskdef 显式 classpath

六、方案对比与选择建议

七、安装验收：最小 XML→HTML 转换

7.1 编写工程文件

7.2 运行验收

八、常见问题（FAQ）

8.1 ant 报 “We cannot run Java”，但 java -version 正常

8.2 style 用绝对路径报 ResourceNotFoundException

8.3 生成的 HTML 中文变问号

8.4 dnf 装的 ant 找不到 anakia 任务

九、卸载与清理

十、参考链接

5.2 RPM 版 ant 的 `-lib` 失效排障实录