Ubuntu 22.04 安装 Apache Anakia 指南
在 Ubuntu 22.04 从零安装 Apache Anakia：apt 与官方 tar.gz 双方案装 Ant，部署 Velocity 1.7 发行包并校验，跑通 XML 转 HTML 首次转换验证。
Ubuntu 22.04 安装 Apache Anakia 指南
目标：在 Ubuntu 22.04 服务器上从零搭建 Apache Anakia 文档转换环境——Anakia 以 Ant task 形态随 Apache Velocity 1.7 发行包分发（无独立安装包），因此完整路径是「安装 JDK + Ant → 部署 Velocity 1.7 发行包 → 验证 Anakia task 可用」，本文给出 apt 在线与官方 tar.gz 两套 Ant 安装方案并全部实测，已在 Ubuntu 22.04.5 LTS（OpenJDK 1.8.0_504、Ant 1.10.12 / 1.10.18、Velocity 1.7）实测通过。
一、环境信息
本篇所有命令与回显均在以下环境中实测采集，复现时请保持相近版本：
- 操作系统：Ubuntu 22.04.5 LTS，x86_64
- JDK：OpenJDK 1.8.0_504（
openjdk-8-jdk-headless，apt 官方仓库） - 构建工具：Apache Ant 1.10.12（apt 仓库）、Apache Ant 1.10.18（官方 tar.gz，方案 B）
- 组件版本：Apache Velocity 1.7（含 Anakia 的最后一条 1.x 线）
- 下载源：https://archive.apache.org/dist/velocity/engine/1.7/
- 安装目录：
/opt/velocity-1.7（发行包）、/opt/apache-ant-1.10.18（方案 B）、/opt/anakia-demo（验证示例） - 执行用户：root
💡 技术拓展：把 XML 文档转成 HTML 的方案不止 Anakia 一种。常见方案对比——
方案 原理 特点与适用场景 Anakia Velocity 模板 + JDOM 解析，跑在 Ant 里 模板就是熟悉的 Velocity 语法，适合已有 Velocity 团队维护文档站 XSLT W3C 标准的 XML 样式表语言 标准化最强，但语法晦涩、调试困难 AsciiDoctor AsciiDoc 文本 → HTML/PDF 写作体验好，但需改用 AsciiDoc 源格式 Pandoc 万能格式转换器 一次性转换方便，不适合工程化流水线定制 静态站点生成器（Hugo/Jekyll 等） Markdown → 站点 面向博客型站点，XML 源场景适配弱 本文因目标源是项目
xdocs目录下的 XML 文件（Apache 项目传统文档格式），且 Anakia 与 Ant 构建天然集成，采用 Anakia 方案。
二、前置条件
本节完成软件源刷新、基础工具准备。Ubuntu 22.04 的 apt 官方仓库自带 OpenJDK 8 与 Ant，无需第三方源。
apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-8-jdk-headless ant wget curl unzip
回显（实测，节选）：
Setting up openjdk-8-jdk-headless:amd64 (8u504-ga-1ubuntu1~22.04.3) ...
Setting up ant (1.10.12-1) ...
Setting up ant-optional (1.10.12-1) ...
Processing triggers for man-db (2.10.2-1) ...
安装收尾无报错即成功。验证版本：
java -version 2>&1 | head -1
ant -version
wget --version | head -1
回显（实测）：
openjdk version "1.8.0_504"
Apache Ant(TM) version 1.10.12 compiled on January 17 1970
GNU Wget 1.21.2 built on linux-gnu.
三个版本号都正确输出，前置完成。
⚠️ 注意：在极少数裁剪过的系统上安装 OpenJDK 时，dpkg 后置脚本可能报
update-alternatives: error: error creating symbolic link '/usr/share/binfmts/jar.dpkg-tmp': No such file or directory（实测复现过）。处理：先mkdir -p /usr/share/binfmts再dpkg --configure -a修复，之后重新执行安装命令即可。详见"八、常见问题"。
三、版本选型说明
Anakia 不是独立发行的产品，它随 Apache Velocity 引擎发行包一起分发（velocity-1.7.jar 内的 org.apache.velocity.anakia 包）。官方归档站 https://archive.apache.org/dist/velocity/engine/ 2026-10 实测在架版本如下：
| 版本线 | 在架版本 | 是否含 Anakia | 说明 |
|---|---|---|---|
| 1.x | 1.0 ~ 1.7 | 是（task 类在 velocity-<ver>.jar 内） | 1.7 为 1.x 最后一版，Anakia 随之停更 |
| 2.x | 2.0 ~ 2.4.1 | 否（整个 anakia 包被移除） | 引擎现代化版本，不能用于 Anakia |
关键差异：Anakia 只存在于 Velocity 1.x。要使用 Anakia 必须锁定 1.7（1.x 的最终修复版，2010 年发布后官方再无 1.x 更新）；Velocity 2.x 面向模板引擎应用场景，发行包中没有 org.apache.velocity.anakia。因此本篇选型就是 Velocity 1.7，无需追踪新版本。
💡 技术拓展：Velocity 发行包里有两个主 jar——
velocity-1.7.jar（仅引擎本体）与velocity-1.7-dep.jar（引擎 + Velocity 自身运行依赖的聚合包）。实测velocity-1.7-dep.jar中并不包含 JDOM（org/jdom类数为 0），而 Anakia 强依赖 JDOM，所以跑 Anakia 不能只放一个 dep jar，必须使用velocity-1.7.jar + lib/ 目录依赖的组合。
发行包文件清单（1.7 目录实测在架）：velocity-1.7.tar.gz、velocity-1.7.zip、velocity-1.7.jar、velocity-1.7-dep.jar、velocity-1.7-javadoc.jar、velocity-1.7-sources.jar、velocity-1.7.pom 及各自的 .asc/.md5/.sha1 校验与签名文件。
四、方案 A：apt 仓库在线安装（推荐）
方案 A 用 apt 安装 JDK 8 与 Ant 1.10.12，再部署 Velocity 1.7 发行包。适合可联网、用包管理器统一维护的机器。
4.1 安装 JDK 与 Ant
前置条件一节已通过 apt 装好 openjdk-8-jdk-headless 与 ant（1.10.12）。确认包版本与 JDK 主目录：
dpkg -l | grep -E '^ii (ant |openjdk-8-jdk-headless)' | awk '{print $2, $3}'
回显（实测）：
ant 1.10.12-1
openjdk-8-jdk-headless:amd64 8u504-ga-1ubuntu1~22.04.3
update-alternatives --list java
回显（实测，本机另装有 11 与 17 时为 3 条）：
/usr/lib/jvm/java-11-openjdk-amd64/bin/java
/usr/lib/jvm/java-17-openjdk-amd64/bin/java
/usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
把系统默认 java 固定到 8（Anakia 场景推荐 JDK 8；实测 11/17 也能跑通，但老发行包在 JDK 8 上行为最稳）：
update-alternatives --set java /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
update-alternatives --set javac /usr/lib/jvm/java-8-openjdk-amd64/bin/javac
java -version 2>&1 | head -1
回显（实测）：
update-alternatives: using /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java to provide /usr/bin/java (java) in manual mode
update-alternatives: using /usr/lib/jvm/java-8-openjdk-amd64/bin/javac to provide /usr/bin/javac (javac) in manual mode
openjdk version "1.8.0_504"
4.2 部署 Velocity 1.7 发行包
下载、校验、解压到 /opt/velocity-1.7：
mkdir -p /opt/software && cd /opt/software
wget https://archive.apache.org/dist/velocity/engine/1.7/velocity-1.7.tar.gz
wget https://archive.apache.org/dist/velocity/engine/1.7/velocity-1.7.tar.gz.md5
wget https://archive.apache.org/dist/velocity/engine/1.7/velocity-1.7.tar.gz.sha1
ls -la velocity-1.7.tar.gz
回显（实测）：
-rw-r--r-- 1 root root 5882643 Jul 6 2020 velocity-1.7.tar.gz
-rw-r--r-- 1 root root 54 Jul 6 2020 velocity-1.7.tar.gz.md5
-rw-r--r-- 1 root root 68 Jul 6 2020 velocity-1.7.tar.gz.sha1
发行包自带 md5 与 sha1 两套校验（无 .sha512）。逐项核对：
md5sum -c velocity-1.7.tar.gz.md5
sha1sum -c velocity-1.7.tar.gz.sha1
回显（实测）：
velocity-1.7.tar.gz: OK
velocity-1.7.tar.gz: OK
两个 OK 即校验通过（-c 能直接工作是因为官方校验文件带文件名格式）。解压并放到目标目录：
tar xzf velocity-1.7.tar.gz
mv velocity-1.7 /opt/velocity-1.7
ls /opt/velocity-1.7
回显（实测）：
CONTRIBUTORS LICENSE NOTICE README.txt WHY_TWO_JARS.txt
build docs examples lib src test velocity-1.7-dep.jar velocity-1.7.jar xdocs
lib/ 是 Anakia 运行的关键依赖目录：
ls /opt/velocity-1.7/lib/ | grep jar
回显（实测）：
antlr-2.7.5.jar
avalon-logkit-2.1.jar
commons-collections-3.2.1.jar
commons-lang-2.4.jar
commons-logging-1.1.jar
jdom-1.0.jar
log4j-1.2.12.jar
maven-ant-tasks-2.0.9.jar
oro-2.0.8.jar
servletapi-2.3.jar
werken-xpath-0.9.4.jar
其中 jdom-1.0.jar（XML 解析）、commons-collections-3.2.1.jar、commons-lang-2.4.jar（引擎依赖）、werken-xpath-0.9.4.jar（模板里 $xpath 工具）是 Anakia 的核心依赖；其余为引擎日志、正则等支撑依赖。
4.3 验证 Anakia task 可用
Anakia 的全部类都在 velocity-1.7.jar 内。先确认 jar 里确实带 AnakiaTask：
jar tf /opt/velocity-1.7/velocity-1.7.jar | grep anakia
回显（实测）：
org/apache/velocity/anakia/
org/apache/velocity/anakia/AnakiaElement.class
org/apache/velocity/anakia/AnakiaJDOMFactory.class
org/apache/velocity/anakia/AnakiaTask$Context.class
org/apache/velocity/anakia/AnakiaTask.class
org/apache/velocity/anakia/Escape.class
org/apache/velocity/anakia/NodeList$1.class
org/apache/velocity/anakia/NodeList$AttributeXMLOutputter.class
org/apache/velocity/anakia/NodeList.class
org/apache/velocity/anakia/OutputWrapper.class
org/apache/velocity/anakia/TreeWalker.class
org/apache/velocity/anakia/XPathCache.class
org/apache/velocity/anakia/XPathTool.class
再做一次加载级验证：写一个最小 build.xml，注册 taskdef 后执行一个空 <anakia/>。若类加载成功，会走到属性校验并报 destdir attribute must be set!；若类路径不对，报的则是 taskdef 类找不到错误——两种报错可以精确区分"环境没装好"与"构建文件没写好"：
mkdir -p /opt/anakia-demo && cat > /opt/anakia-demo/verify-taskdef.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<project name="verify" default="check" basedir=".">
<path id="anakia.classpath">
<pathelement location="/opt/velocity-1.7/velocity-1.7.jar"/>
<fileset dir="/opt/velocity-1.7/lib">
<include name="*.jar"/>
</fileset>
</path>
<target name="check">
<taskdef name="anakia"
classname="org.apache.velocity.anakia.AnakiaTask"
classpathref="anakia.classpath"/>
<anakia/>
</target>
</project>
EOF
cd /opt/anakia-demo && ant -f verify-taskdef.xml
回显（实测）：
Buildfile: /opt/anakia-demo/verify-taskdef.xml
check:
BUILD FAILED
/opt/anakia-demo/verify-taskdef.xml:9: destdir attribute must be set!
Total time: 0 seconds
报错出自第 9 行 <anakia/> 的属性校验，说明 AnakiaTask 类已通过 classpath 成功加载并实例化——环境安装全部就绪。完整的 XML→HTML 转换示例见《Apache Anakia 快速入门与集成示例》。
五、方案 B：官方 tar.gz 安装 Ant 1.10.18（离线/新版本需求）
apt 仓库的 Ant 版本可能落后于官方线。方案 B 直接使用 Apache 官方 tar.gz 安装最新 Ant 1.10.18，适合内网分发（提前下载好包）或需要新版本特性的场景。JDK 部分与方案 A 相同，本节不再重复。
5.1 下载与校验
cd /opt/software
wget https://archive.apache.org/dist/ant/binaries/apache-ant-1.10.18-bin.tar.gz
wget https://archive.apache.org/dist/ant/binaries/apache-ant-1.10.18-bin.tar.gz.sha512
ls -la apache-ant-1.10.18*
回显（实测）：
-rw-r--r-- 1 root root 7133405 Sep 6 17:33 apache-ant-1.10.18-bin.tar.gz
-rw-r--r-- 1 root root 129 Sep 6 17:33 apache-ant-1.10.18-bin.tar.gz.sha512
官方 .sha512 是 129 字节的裸哈希文本，用比对法校验：
[ "$(sha512sum apache-ant-1.10.18-bin.tar.gz | awk '{print $1}')" = "$(tr -d ' \n' < apache-ant-1.10.18-bin.tar.gz.sha512)" ] && echo "sha512 OK"
回显（实测）：
sha512 OK
5.2 解压安装与 PATH 配置
tar xzf apache-ant-1.10.18-bin.tar.gz -C /opt
ls /opt/apache-ant-1.10.18
回显（实测）：
CONTRIBUTORS INSTALL KEYS LICENSE NOTICE README WHATSNEW
bin contributors.xml etc lib manual fetch.xml get-m2.xml
把 tar 版 Ant 的 bin 目录加进 PATH（写入 /etc/profile.d 使所有登录会话生效）。注意 tar 版目录名与 apt 不同，先看 PATH 里谁排前面：
cat > /etc/profile.d/ant1818.sh << 'EOF'
export ANT_HOME=/opt/apache-ant-1.10.18
export PATH=$ANT_HOME/bin:$PATH
EOF
chmod +x /etc/profile.d/ant1818.sh
source /etc/profile.d/ant1818.sh
which ant
ant -version
回显（实测）：
/opt/apache-ant-1.10.18/bin/ant
Apache Ant(TM) version 1.10.18 compiled on September 3 2026
5.3 验证 tar 版 Ant 能加载 Anakia
/opt/apache-ant-1.10.18/bin/ant -f /opt/anakia-demo/verify-taskdef.xml
回显（实测）：
Buildfile: /opt/anakia-demo/verify-taskdef.xml
check:
BUILD FAILED
/opt/anakia-demo/verify-taskdef.xml:9: destdir attribute must be set!
Total time: 0 seconds
同样是属性校验报错，说明 1.10.18 也能正常加载 Anakia task。
六、方案对比与选择建议
| 维度 | 方案 A：apt 在线安装 | 方案 B：官方 tar.gz |
|---|---|---|
| JDK | openjdk-8-jdk-headless（8u504） | 同左（JDK 部分两方案相同） |
| Ant 版本 | 1.10.12 | 1.10.18（当前官方最新线） |
| 是否需联网 | 安装时需要 | 下载时需要，包可离线分发 |
| 升级方式 | apt upgrade 跟随仓库 | 重新下载新 tar 包覆盖 |
| 卸载方式 | apt-get purge | 删目录 + 删 profile 脚本 |
| 适用场景 | 常规联网服务器、统一运维 | 版本敏感、内网离线、多机分发 |
选择建议：常规场景选方案 A，包管理器统一管理最省心；需要最新 Ant 或内网批量部署选方案 B。两方案的 Anakia 环境验证方式完全一致（verify-taskdef.xml）。
七、配置说明
| 配置项 | 位置 | 说明 |
|---|---|---|
| 系统默认 java | update-alternatives --set java ... | apt 装多个 JDK 后手动固定；java -version 验证 |
| ANT_HOME（方案 B） | /etc/profile.d/ant1818.sh | tar 版 Ant 根目录，脚本启动时用于定位 lib |
| Anakia 类路径 | build.xml 内 <path id="anakia.classpath"> | 必须包含 velocity-1.7.jar 与 lib/ 下依赖，写法见 4.3 |
| velocity.properties | 默认在执行 ant 命令的当前目录 | Anakia 的引擎参数文件；用 templatePath 时可不提供 |
| 输出编码 | velocity.properties 的 output.encoding | 默认 ISO-8859-1，中文环境建议显式设 UTF-8 |
关键点：Anakia 没有常驻服务与全局配置文件，它的所有"配置"都落在每个工程的 build.xml 与 velocity.properties 中。JVM 堆参数同样在 ant 命令行通过 ANT_OPTS 传入（如 ANT_OPTS="-Xms256m -Xmx512m" ant docs），文档转换属于短时批处理任务，默认堆足够。
八、常见问题（FAQ）
Q1：安装 OpenJDK 时报 update-alternatives error creating symbolic link '/usr/share/binfmts/jar.dpkg-tmp'？ 实测报错原文：
update-alternatives: error: error creating symbolic link '/usr/share/binfmts/jar.dpkg-tmp': No such file or directory
dpkg: error processing package openjdk-11-jre-headless:amd64 (--configure):
installed openjdk-11-jre-headless:amd64 package post-installation script subprocess returned error exit status 2
原因：系统缺少 /usr/share/binfmts 目录，OpenJDK 包后置脚本建 binfmt 注册链接时失败。解决（实测有效）：
mkdir -p /usr/share/binfmts
DEBIAN_FRONTEND=noninteractive dpkg --configure -a
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-8-jdk-headless ant wget curl unzip
修复后安装正常完成，java -version 正常输出。
Q2：系统装了多个 JDK，ant 运行时用的哪一个？
Debian/Ubuntu 的 ant 启动脚本按 JAVA_HOME → 默认 JDK 链的顺序解析。不设 JAVA_HOME 时跟随 update-alternatives 当前指向。可用 ant -v 第一行确认（实测输出 Detected Java version: 17 in: /usr/lib/jvm/java-17-openjdk-amd64 即当前用 17）。临时指定单次运行用环境变量前缀：JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 ant docs（实测有效）。
Q3：只把 velocity-1.7-dep.jar 放上 classpath 为什么不行？
velocity-1.7-dep.jar 是引擎自身的聚合包，实测其中 org/jdom 类数为 0，而 Anakia 解析 XML 依赖 JDOM。taskdef 加载 AnakiaTask 类时不会立刻报错（AnakiaTask 本体在 dep jar 里），但执行转换时报 java.lang.NoClassDefFoundError: org/jdom/Element 类错误。正确做法：classpath 同时含 velocity-1.7.jar 与发行包 lib/ 目录全部 jar（4.3 的 path 写法）。
Q4：archive.apache.org 下载慢或中断怎么办？
归档站对国内直连偶发慢速。可用 wget 断点续传重试：wget -c <URL>；或改用与本篇相同的 md5/sha1 校验流程先下校验文件再核对。Velocity 1.7 属归档版本，各官方镜像站（如 downloads.apache.org 只放当前版本，1.7 只能走 archive.apache.org）——认准 archive.apache.org/dist/velocity/engine/1.7/ 这一个路径。
Q5：卸载 Ant tar 版后 which ant 还能找到旧版本？
/etc/profile.d/ant1818.sh 把 tar 版 bin 放在 PATH 最前。卸载后未重新登录的会话仍缓存旧 PATH。执行 hash -r 或重新登录即可；确认 which ant 指向 /usr/bin/ant（apt 版）。
九、卸载与清理
apt 方案产物清理：
apt-get purge -y ant ant-optional
回显（实测，节选）：
Removing ant-optional (1.10.12-1) ...
Removing ant (1.10.12-1) ...
tar 方案产物清理：
rm -f /etc/profile.d/ant1818.sh
rm -rf /opt/apache-ant-1.10.18
JDK 与 Velocity 发行包清理（确认无其他 Java 应用依赖后再删 JDK）：
apt-get purge -y openjdk-8-jdk-headless
rm -rf /opt/velocity-1.7 /opt/anakia-demo /opt/software/velocity-1.7* /opt/software/apache-ant-1.10.18*
验证清理结果：
which ant java 2>&1; ls /opt/velocity-1.7 2>&1
回显（实测）：
which: no ant in (/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin)
ls: cannot access '/opt/velocity-1.7': No such file or directory
ant 不在 PATH、目录不存在即清理干净。
十、参考链接
- Apache Velocity 引擎 1.7 官方文档：https://velocity.apache.org/engine/1.7/
- Velocity 1.7 官方归档下载（本文版本来源）：https://archive.apache.org/dist/velocity/engine/1.7/
- AnakiaTask Javadoc（task 属性权威说明）：https://velocity.apache.org/engine/1.7/apidocs/org/apache/velocity/anakia/AnakiaTask.html
- Apache Ant 官方手册：https://ant.apache.org/manual/
- Ant 1.10.18 下载目录：https://archive.apache.org/dist/ant/binaries/
- 完整转换示例：《Apache Anakia 快速入门与集成示例》