Ubuntu 22.04 安装 Apache CycloneDX Ant Library 指南

目标：在 Ubuntu 22.04 上从零搭建 Apache CycloneDX Ant Library 0.2 的使用环境（JDK 17 + Ant + 依赖 jar），并跑通一次真实的 CycloneDX SBOM 生成；本文全部命令与回显均已在 Ubuntu 22.04 实测通过。

Apache CycloneDX Ant Library（官方名 "Apache CycloneDX Antlib"，Maven 坐标 org.apache.ant:ant-cyclonedx）是 Apache Ant 官方发布的一套 Antlib，用于在 Ant 构建中生成 CycloneDX 格式的 SBOM（软件物料清单）。它是纯 Java 任务库，没有独立进程与常驻服务，安装的本质就是「装好 JDK 与 Ant → 备齐 antlib jar 与其依赖 → 在 build.xml 里装配 antlib → 跑通一次生成」。本文给出两种落地方式：方案 A 通过 Maven 中央仓库自动拉齐全部依赖（在线，推荐）；方案 B 使用官方 bin-withdeps 二进制包（离线友好，但实测需手工补齐 5 个缺失的依赖 jar，排坑过程完整收录）。

一、环境信息

本节先固定可复现的基线环境，后续所有命令均在此环境执行。

操作系统：Ubuntu 22.04.5 LTS
架构：x86_64
JDK：OpenJDK 17.0.20.1（apt 包 openjdk-17-jdk）
构建工具：Apache Ant 1.10.12（apt 包 ant）、Apache Maven 3.6.3（apt 包 maven）
组件版本：ant-cyclonedx 0.2（Maven 坐标 org.apache.ant:ant-cyclonedx:0.2）
核心依赖：cyclonedx-core-java 13.2.0、packageurl-java 1.5.0、Jackson 2.22.2、networknt json-schema-validator 2.0.4
Antlib 安装目录：/opt/cyclonedx-antlib/lib（方案 A）、/opt/cyclonedx-antlib/bin（方案 B）
验证用工程目录：/root/hello-app

系统与架构确认（实时回显）：

cat /etc/os-release | head -3

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

uname -m

x86_64

💡 说明：CycloneDX Antlib 是 Ant 任务库而非服务，环境中不存在需要常驻的守护进程；「安装完成」的判定标准是用 Ant 跑通一次 componentbom 任务并产出合法的 SBOM 文件，而不是某个端口处于监听状态。

二、前置条件

本节说明安装前必须满足的条件。Ubuntu 22.04 自带可用的软件源，联网即可通过 apt 获取 JDK、Ant 与 Maven。

具有 root 或 sudo 权限的 Ubuntu 22.04 系统。
可访问 Ubuntu 官方软件源（apt update 能正常拉取索引）。
可访问 Apache 下载站 downloads.apache.org 与 Maven 中央仓库 repo1.maven.org（本文实测网络直连可达）。
至少 2 GB 可用磁盘空间（JDK + Ant + Maven + 依赖 jar 合计约 600 MB）。
运行期 JDK 版本要求：Java 9 及以上。官方手册明确 CycloneDX Core（Java）要生成 SHA3 哈希，Java 8 无法支持；本文实测 JDK 1.8.0_312 下运行任务报 Algorithm not available: SHA3-256（回显见第九章 FAQ Q2），因此本文统一使用 JDK 17。

网络连通性确认（实时回显）：

curl -sI --max-time 20 https://downloads.apache.org/ant/antlibs/cyclonedx/binaries/ | head -3

HTTP/1.1 200 OK
Date: Wed, 15 Oct 2026 05:20:31 GMT
Server: Apache

curl -sI --max-time 20 https://repo1.maven.org/maven2/org/apache/ant/ant-cyclonedx/ | head -1

HTTP/1.1 200 OK

三、版本选型说明

本节给出 ant-cyclonedx 的版本谱系与选型依据。版本事实来自 Maven 中央仓库的元数据，实测查询如下：

curl -s --max-time 30 https://repo1.maven.org/maven2/org/apache/ant/ant-cyclonedx/maven-metadata.xml

<?xml version="1.0" encoding="UTF-8"?>
<metadata>
  <groupId>org.apache.ant</groupId>
  <artifactId>ant-cyclonedx</artifactId>
  <versioning>
    <latest>0.2</latest>
    <release>0.2</release>
    <versions>
      <version>0.1</version>
      <version>0.2</version>
    </versions>
    <lastUpdated>20260925153836</lastUpdated>
  </versioning>
</metadata>

版本	发布形态	运行要求	适用场景
0.1	中央仓库 + 官方 bin 包	Java 9+，Ant 1.10.x	老版本兼容，不建议新用
0.2（当前主线）	中央仓库 + 官方 bin 包	Java 9+，官方建议 Ant 1.10.18+（实测 1.10.12 与 1.10.5 均可运行）	所有新项目默认选择

关键差异与选型：0.2 是当前 latest 与 release（2026-09-25 更新），新增固定 serialNumber、依赖排序器等能力，默认输出 CycloneDX 1.7 规范（0.1 时代默认 1.4）；其 POM 声明的依赖为 org.apache.ant:ant 1.10.18（provided）、org.apache.ant:ant-launcher 1.10.18（provided）、org.cyclonedx:cyclonedx-core-java 13.2.0（compile）、org.apache.ivy:ivy 2.6.0（provided，仅 Ivy 集成需要）。本文实际采用 0.2，理由是它是官方当前唯一 release 版本，且对 Ant 1.10.12（Ubuntu 22.04 apt 源自带）实测兼容。

⚠️ 注意：官方手册写道「不保证在 1.10.18 之前的 Ant 上工作」。实测结论是 Ubuntu 22.04 的 ant 1.10.12 与 CentOS 8 的 ant 1.10.5 都能正常跑通 0.2 的核心任务，兼容性比手册表述乐观；但若遇到怪异行为，优先升级 Ant 到 1.10.18 再排查。

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

本节面向常规环境，通过 apt 安装 JDK、Ant、Maven，再用 Maven 坐标把 ant-cyclonedx 及其全部依赖拉到统一目录，最后建一个 Ant 工程跑通 SBOM 生成。这是最贴合工程实践的方式。

4.1 方案说明

方案 A 的链路是：apt 安装 openjdk-17-jdk、ant、maven → 用一个仅含依赖声明的 pom.xml 执行 mvn dependency:copy-dependencies，把 ant-cyclonedx 0.2 与全部传递依赖复制到 /opt/cyclonedx-antlib/lib → 在 build.xml 中以 taskdef 装配 antlib → 运行生成 SBOM。优点是依赖自动解析、版本统一管控；缺点是首次拉取需要联网。

4.2 安装 JDK 17、Ant 与 Maven

Ubuntu 22.04 官方源内置三件套，一条命令安装（回显节选，实测首尾）：

apt-get update -qq && apt-get install -y openjdk-17-jdk ant maven

Processing triggers for libgdk-pixbuf-2.0-0:amd64 (2.42.8+dfsg-1ubuntu0.5) ...

安装后确认版本：

java -version

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

ant -version

Apache Ant(TM) version 1.10.12 compiled on January 17 1970

mvn -version | head -3

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64

验证点：java -version 输出 17.0.x、ant -version 输出 1.10.x、mvn -version 的 Java version 一行显示 17.0.20.1，说明三者就绪且 Maven 已绑定 JDK 17，无需额外设置 JAVA_HOME。

4.3 用 Maven 拉取 antlib 与全部依赖

ant-cyclonedx 0.2 的 POM 把 Ant 本体、ant-launcher、ivy 声明为 provided 范围，直接 copy-dependencies 会漏掉它们，因此先写一个显式声明四个依赖的 pom：

mkdir -p /opt/cyclonedx-antlib/fetch /opt/cyclonedx-antlib/lib

/opt/cyclonedx-antlib/fetch/pom.xml（完整内容）：

<?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>cdx-antlib-fetch</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <dependencies>
    <dependency>
      <groupId>org.apache.ant</groupId>
      <artifactId>ant-cyclonedx</artifactId>
      <version>0.2</version>
    </dependency>
    <dependency>
      <groupId>org.apache.ant</groupId>
      <artifactId>ant</artifactId>
      <version>1.10.18</version>
    </dependency>
    <dependency>
      <groupId>org.apache.ant</groupId>
      <artifactId>ant-launcher</artifactId>
      <version>1.10.18</version>
    </dependency>
    <dependency>
      <groupId>org.apache.ivy</groupId>
      <artifactId>ivy</artifactId>
      <version>2.6.0</version>
    </dependency>
  </dependencies>
</project>

逐项说明关键配置：

org.apache.ant:ant-cyclonedx:0.2：antlib 本体，Maven 会连带解析 cyclonedx-core-java 13.2.0 及其全部传递依赖。
org.apache.ant:ant 与 ant-launcher 1.10.18：POM 中为 provided，运行期必须显式补上；Ant 1.10.12 环境下它们也不会与系统 Ant 冲突（taskdef 的 classpath 优先）。
org.apache.ivy:ivy 2.6.0：仅 ivyModule 组件解析器需要，先备齐以便后续集成。

执行拉取（回显节选，实测尾行）：

cd /opt/cyclonedx-antlib/fetch && mvn -q -B dependency:copy-dependencies -DoutputDirectory=/opt/cyclonedx-antlib/lib

ls /opt/cyclonedx-antlib/lib

ant-1.10.18.jar
ant-cyclonedx-0.2.jar
ant-launcher-1.10.18.jar
cyclonedx-core-java-13.2.0.jar
itu-1.14.0.jar
ivy-2.6.0.jar
jackson-annotations-2.22.jar
jackson-core-2.22.2.jar
jackson-databind-2.22.2.jar
jackson-dataformat-xml-2.22.2.jar
jackson-dataformat-yaml-2.18.4.jar
json-schema-validator-2.0.4.jar
packageurl-java-1.5.0.jar
slf4j-api-2.0.17.jar
snakeyaml-2.3.jar
stax2-api-4.3.0.jar
woodstox-core-7.2.0.jar

共 17 个 jar。核心几个的角色：ant-cyclonedx-0.2.jar 是任务与类型定义；cyclonedx-core-java-13.2.0.jar 负责 SBOM 模型与序列化；json-schema-validator-2.0.4.jar（组 com.networknt）是 cyclonedx-core-java 的必需依赖——注意官方 bin 包恰恰漏了它（见第五章 5.3 节）；woodstox-core-7.2.0.jar 与 stax2-api-4.3.0.jar 服务于 XML 输出。

4.4 创建验证工程并装配 antlib

建一个最小 Ant 工程，先写一个 Java 类，再在 build.xml 里完成「编译 → 打 jar → 生成 SBOM」三步：

mkdir -p /root/hello-app/src/com/example/hello

/root/hello-app/src/com/example/hello/Hello.java（完整内容）：

package com.example.hello;

public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, CycloneDX!");
    }
}

/root/hello-app/build.xml（完整内容，直接照抄）：

<?xml version="1.0" encoding="UTF-8"?>
<project name="hello-app" default="sbom" xmlns:cdx="antlib:org.apache.ant.cyclonedx">

  <target name="compile">
    <mkdir dir="/root/hello-app/build/classes"/>
    <javac srcdir="/root/hello-app/src" destdir="/root/hello-app/build/classes" includeantruntime="false"/>
  </target>

  <target name="jar" depends="compile">
    <mkdir dir="/root/hello-app/dist"/>
    <jar destfile="/root/hello-app/dist/hello-app-1.0.0.jar" basedir="/root/hello-app/build/classes"/>
  </target>

  <target name="sbom" depends="jar">
    <taskdef uri="antlib:org.apache.ant.cyclonedx"
             resource="org/apache/ant/cyclonedx/antlib.xml">
      <classpath>
        <fileset dir="/opt/cyclonedx-antlib/lib" includes="*.jar"/>
      </classpath>
    </taskdef>

    <mkdir dir="/root/hello-app/bom"/>

    <cdx:componentbom format="all"
                      bomName="hello-app-1.0.0"
                      outputDirectory="/root/hello-app/bom">
      <cdx:component type="application"
                     name="hello-app"
                     group="com.example"
                     version="1.0.0"
                     purl="pkg:maven/com.example/hello-app@1.0.0"
                     description="Demo application for CycloneDX Antlib">
        <file file="/root/hello-app/dist/hello-app-1.0.0.jar"/>
        <cdx:license licenseId="Apache-2.0"/>
        <cdx:tag>release</cdx:tag>
      </cdx:component>
    </cdx:componentbom>
  </target>
</project>

逐项说明关键配置：

xmlns:cdx="antlib:org.apache.ant.cyclonedx"：antlib 命名空间，此后所有任务与类型以 cdx: 前缀调用。
taskdef 的 resource 指向 jar 内的 org/apache/ant/cyclonedx/antlib.xml 描述符，classpath 用 fileset 收全 /opt/cyclonedx-antlib/lib 下全部 jar——只给 ant-cyclonedx-0.2.jar 一个 jar 会因依赖缺失报错（实测回显见 FAQ Q4）。
componentbom 的 format="all" 表示同时输出 JSON 与 XML；bomName 决定文件基名；outputDirectory 必须已存在。
cdx:component 是 SBOM 的主组件，<file> 嵌套元素指向构建产物，任务会自动计算 MD5/SHA-1/SHA-256/SHA-512/SHA3 等哈希。
specVersion 未写时默认 1.7。

4.5 运行与验证

cd /root/hello-app && ant

Buildfile: /root/hello-app/build.xml

compile:
    [mkdir] Created dir: /root/hello-app/build/classes
    [javac] Compiling 1 source file to /root/hello-app/build/classes

jar:
    [mkdir] Created dir: /root/hello-app/dist
      [jar] Building jar: /root/hello-app/dist/hello-app-1.0.0.jar

sbom:
    [mkdir] Created dir: /root/hello-app/bom
[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.xml
[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.json

BUILD SUCCESSFUL
Total time: 1 second

验证点：BUILD SUCCESSFUL 且 bom 目录出现两个文件，表示 antlib 已完整可用。查看生成的 SBOM 片段（实时回显）：

head -8 /root/hello-app/bom/hello-app-1.0.0.json

{
  "bomFormat" : "CycloneDX",
  "specVersion" : "1.7",
  "serialNumber" : "urn:uuid:ac67ca6d-1c1f-4228-aa31-91a5fc1c8592",
  "version" : 1,
  "metadata" : {
    "timestamp" : "2026-10-15T06:05:48Z",
    "lifecycles" : [

grep -A6 '"hashes"' /root/hello-app/bom/hello-app-1.0.0.json | tail -6

        {
          "alg" : "MD5",
          "content" : "f85ad6b189282d730dad60680fcdc364"
        },
        {
          "alg" : "SHA-1",

主组件的 MD5 哈希来自 <file> 指向的构建产物，可与 md5sum 校验对照：

md5sum /root/hello-app/dist/hello-app-1.0.0.jar

f85ad6b189282d730dad60680fcdc364  /root/hello-app/dist/hello-app-1.0.0.jar

两个哈希一致，SBOM 内容可信。SBOM 的完整字段与更多任务参数见本专栏《Apache CycloneDX Ant Library 0.2 常用 API 与任务详解》。

💡 技术拓展：Java 生态里给 Ant 工程产 SBOM 的途径不止这一家，常见方案对比如下——

方案定位特点适用场景
Apache CycloneDX Ant Library Ant 任务库官方 antlib，手写或 Ivy 集成，控制粒度最细 Ant 工程、发布流水线
CycloneDX Maven plugin Maven 插件从 pom 依赖树自动生成，零手写 Maven 工程
CycloneDX Gradle plugin Gradle 插件从 Gradle 依赖解析自动生成 Gradle 工程
syft / trivy 等扫描器独立 CLI 扫文件系统/镜像，无需构建集成事后审计、镜像分析

本文采用 Apache CycloneDX Ant Library，理由是它与 Ant 原生集成（同一构建文件内完成打包与 SBOM 产出），且由 Apache Ant 项目官方维护，与 cyclonedx-core-java 同源升级。

方案	定位	特点	适用场景
Apache CycloneDX Ant Library	Ant 任务库	官方 antlib，手写或 Ivy 集成，控制粒度最细	Ant 工程、发布流水线
CycloneDX Maven plugin	Maven 插件	从 pom 依赖树自动生成，零手写	Maven 工程
CycloneDX Gradle plugin	Gradle 插件	从 Gradle 依赖解析自动生成	Gradle 工程
syft / trivy 等扫描器	独立 CLI	扫文件系统/镜像，无需构建集成	事后审计、镜像分析

五、方案 B：官方 bin 包 + 手工补依赖（离线友好）

本节面向无 Maven 或离线场景，使用 Apache 官方发布的 bin-withdeps 二进制包。实测发现该包缺失 5 个运行期必需依赖，本节完整记录排坑与补齐过程。

5.1 方案说明

链路是：从 downloads.apache.org 下载 apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz → 校验 sha512 → 解压到 /opt/cyclonedx-antlib/bin → 用 ant -lib 指向该目录运行 → 遇到缺依赖报错后，从 Maven 中央仓库补齐缺失的 5 个 jar → 再次运行验证。

5.2 下载与完整性校验

cd /tmp && curl -s --max-time 120 -O https://downloads.apache.org/ant/antlibs/cyclonedx/binaries/apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz
curl -s --max-time 30 -O https://downloads.apache.org/ant/antlibs/cyclonedx/binaries/apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz.sha512
echo "期望: $(awk '{print $1}' apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz.sha512)"
echo "实测: $(sha512sum apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz | awk '{print $1}')"

期望: d64e5d67d1c077560a41a3fe0fc355e9d96d1448c349437b70a8d6112fec19d46490af1579f542806fef05cebe9cc2f90e1eb09d9e302ead76c7b64bd1c05e77
实测: d64e5d67d1c077560a41a3fe0fc355e9d96d1448c349437b70a8d6112fec19d46490af1579f542806fef05cebe9cc2f90e1eb09d9e302ead76c7b64bd1c05e77

⚠️ 注意：若 sha512 不一致，说明下载包损坏或被篡改，须删除后重新下载；切勿跳过校验直接使用。

解压到安装目录：

mkdir -p /opt/cyclonedx-antlib/bin
tar xzf /tmp/apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz -C /opt/cyclonedx-antlib/bin --strip-components=1

ls /opt/cyclonedx-antlib/bin/*.jar

/opt/cyclonedx-antlib/bin/ant-cyclonedx-0.2.jar
/opt/cyclonedx-antlib/bin/cyclonedx-core-java-13.2.0.jar
/opt/cyclonedx-antlib/bin/itu-1.14.0.jar
/opt/cyclonedx-antlib/bin/jackson-annotations-2.22.jar
/opt/cyclonedx-antlib/bin/jackson-core-2.22.2.jar
/opt/cyclonedx-antlib/bin/jackson-databind-2.22.2.jar
/opt/cyclonedx-antlib/bin/jackson-dataformat-xml-2.22.2.jar
/opt/cyclonedx-antlib/bin/jackson-dataformat-yaml-2.22.2.jar
/opt/cyclonedx-antlib/bin/json-schema-validator-2.0.4.jar
/opt/cyclonedx-antlib/bin/packageurl-java-1.5.0.jar
/opt/cyclonedx-antlib/bin/slf4j-api-2.0.17.jar
/opt/cyclonedx-antlib/bin/snakeyaml-2.3.jar
/opt/cyclonedx-antlib/bin/stax2-api-4.3.0.jar
/opt/cyclonedx-antlib/bin/woodstox-core-7.2.0.jar

目录里除 jar 外还带 docs/（每个任务与类型的官方手册页）与 ant-cyclonedx-0.2.cdx.json（发布物自带的 SBOM，可直接当参考样例）。

💡 注意：上表是补齐后的清单。纯净解压只有 9 个 jar（没有 itu、jackson-dataformat-yaml-2.22.2 版本仲裁差异之外的 json-schema-validator、snakeyaml、stax2-api、woodstox-core），直接使用会报错，见 5.3 节。

5.3 实测排坑：withdeps 包并不全

直接用官方包运行第四章的验证工程（回显节选）：

cd /root/hello-app && rm -rf bom build dist && ant -lib /opt/cyclonedx-antlib/bin

BUILD FAILED
/root/hello-app/build.xml:30: java.lang.NoClassDefFoundError: com/networknt/schema/keyword/Keyword
Caused by: java.lang.ClassNotFoundException: com.networknt.schema.keyword.Keyword

原因：0.2 的 bin-withdeps 打包清单漏掉了 cyclonedx-core-java 13.2.0 的 5 个传递依赖（json-schema-validator 2.0.4、itu 1.14.0、snakeyaml 2.3、stax2-api 4.3.0、woodstox-core 7.2.0）。从 Maven 中央仓库补齐：

cd /opt/cyclonedx-antlib/bin
curl -s --max-time 60 -O https://repo1.maven.org/maven2/com/networknt/json-schema-validator/2.0.4/json-schema-validator-2.0.4.jar
curl -s --max-time 60 -O https://repo1.maven.org/maven2/com/ethlo/time/itu/1.14.0/itu-1.14.0.jar
curl -s --max-time 60 -O https://repo1.maven.org/maven2/org/yaml/snakeyaml/2.3/snakeyaml-2.3.jar
curl -s --max-time 60 -O https://repo1.maven.org/maven2/org/codehaus/woodstox/stax2-api/4.3.0/stax2-api-4.3.0.jar
curl -s --max-time 60 -O https://repo1.maven.org/maven2/com/fasterxml/woodstox/woodstox-core/7.2.0/woodstox-core-7.2.0.jar

ls /opt/cyclonedx-antlib/bin/*.jar | wc -l

5.4 补齐后运行与验证

cd /root/hello-app && rm -rf bom && ANT_OPTS='-Xms256m -Xmx256m' ant -lib /opt/cyclonedx-antlib/bin

Buildfile: /root/hello-app/build.xml

compile:
    [mkdir] Created dir: /root/hello-app/build/classes
    [javac] Compiling 1 source file to /root/hello-app/build/classes

jar:
    [mkdir] Created dir: /root/hello-app/dist
      [jar] Building jar: /root/hello-app/dist/hello-app-1.0.0.jar

sbom:
    [mkdir] Created dir: /root/hello-app/bom
[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.xml
[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.json

BUILD SUCCESSFUL
Total time: 1 second

head -5 /root/hello-app/bom/hello-app-1.0.0.json

{
  "bomFormat" : "CycloneDX",
  "specVersion" : "1.7",
  "serialNumber" : "urn:uuid:0624ed5d-8875-4833-b41c-c0d4cf43b6c3",
  "version" : 1,

验证点：BUILD SUCCESSFUL 且 JSON/XML 双文件落盘，方案 B 与方案 A 产出等价。

六、方案对比与选择建议

本节汇总两种方案的差异，给出选型建议。两种方案装配的是同一份 ant-cyclonedx 0.2，差别仅在依赖的获取与补齐方式。

维度	方案 A：Maven 依赖	方案 B：官方 bin 包 + 手工补齐
依赖完整性	自动解析，17 个 jar 一次到位	打包清单缺 5 个 jar，须手工补
是否联网	首次拉取需联网	下载与补 jar 需联网，之后可离线复用
版本管控	pom 统一声明，可锁版本	靠文件名区分，升级靠手工替换
升级成本	改 pom 版本号重跑	重新下载新 bin 包并重补缺失 jar
适用场景	常规开发与 CI	离线服务器、分发到无构建体系机器

选型建议：有 Maven 或任何联网条件，一律选方案 A；只有当目标机器完全离线且不允许引入 Maven 时选方案 B，并按 5.3 节把 5 个缺失 jar 一次性补齐后打包分发。官方后续版本若修复打包清单，可先用 ls 安装目录/*.jar | wc -l 与本文 14 对照快速判断是否仍需补齐。

七、基础配置

本节说明 antlib 使用中真正需要配置的项。它是任务库而非服务，没有独立配置文件，全部行为通过 Ant 装配方式与 JVM 环境变量控制。

7.1 antlib 的两种装配方式

其一，build.xml 内 taskdef + classpath（本文 4.4 节用法），优点是随工程分发、不污染全局；其二，运行期 -lib 全局注入（ant -lib /opt/cyclonedx-antlib/bin），此时 build.xml 里的 taskdef 可省略 classpath，但要求机器上每个用户都能访问该目录。两种方式取其一即可，同时使用时以 taskdef 的 classpath 优先。

7.2 JVM 堆参数

SBOM 生成过程中的哈希计算与 JSON/XML 序列化都在 Ant 的 JVM 内完成，组件特别多时默认堆可能吃紧。位置与修改方法：在运行 ant 前设置环境变量 ANT_OPTS，它会被 Ant 启动脚本透传给 JVM。本文实测限制为 256 MB：

cd /root/hello-app && ANT_OPTS='-Xms256m -Xmx256m' ant

[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.xml
[cdx:componentbom] creating CycloneDX SBOM /root/hello-app/bom/hello-app-1.0.0.json

BUILD SUCCESSFUL

验证点：-Xms256m -Xmx256m 下任务正常完成。需要长期生效可把 export ANT_OPTS='-Xms256m -Xmx256m' 写入 /root/.bashrc；临时调大在命令前改参数即可，如 -Xmx512m。

7.3 JAVA_HOME

apt 安装的 Ant 会自动探测 JDK 17，JAVA_HOME 为空（实测回显 echo "JAVA_HOME=$JAVA_HOME" 输出 JAVA_HOME=）也能正常工作。仅当机器上并存多个 JDK 时才需要显式导出：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64

八、多版本管理

多版本共存靠「隔离目录 + taskdef 指向不同 classpath」实现，无需切换全局软链。

ant-cyclonedx 中央仓库上 0.1 与 0.2 并列存放于 Maven 本地仓库（实时回显）：

ls -1 /root/.m2/repository/org/apache/ant/ant-cyclonedx/

0.1
0.2

要点：工程要用哪个版本，只改 fetch pom 里的 <version> 重新 copy-dependencies 到不同输出目录（如 /opt/cyclonedx-antlib/lib-0.1），再让对应 build.xml 的 taskdef 指向它即可；方案 B 场景则把 0.1、0.2 的 bin 包解压到不同目录，运行时 ant -lib 指向对应目录。

九、常见问题（FAQ）

Q1：运行报 java.lang.NoClassDefFoundError: com/networknt/schema/keyword/Keyword？ 使用官方 bin-withdeps 包导致——0.2 的打包清单缺 5 个依赖。按 5.3 节从 Maven 中央仓库补齐 json-schema-validator-2.0.4、itu-1.14.0、snakeyaml-2.3、stax2-api-4.3.0、woodstox-core-7.2.0 五个 jar 后重跑即可。

Q2：报 java.lang.IllegalArgumentException: Algorithm not available: SHA3-256（或 NoSuchAlgorithmException: SHA3-256 MessageDigest not available）？ 运行 JDK 低于 9 导致——antlib 计算 SHA3 哈希依赖 JDK 9+ 的算法支持。实测在 JDK 1.8.0_312 上的完整回显：

BUILD FAILED
/root/hello-app/build.xml:30: java.lang.IllegalArgumentException: Algorithm not available: SHA3-256
        at org.cyclonedx.util.BomUtils.getDigestForAlgorithm(BomUtils.java:145)
Caused by: java.security.NoSuchAlgorithmException: SHA3-256 MessageDigest not available

解法是切换到 JDK 17（本文 4.2 节）；CentOS 8 环境下该问题的完整排障过程见本专栏 CentOS 8 安装指南第九章。

Q3：报 only one nested component element is permitted？ componentbom 下写了两个 cdx:component。主组件只能有一个；其余组件应写成 cdx:additionalComponent（顶层附加组件）或主组件内部的嵌套 cdx:component（子组件），三者用途不同，详见本专栏参数详解篇。

Q4：taskdef 后报 A class needed by class org.apache.ant.cyclonedx.ComponentBomTask cannot be found: org/cyclonedx/exception/GeneratorException？ taskdef 的 classpath 只给了 ant-cyclonedx-0.2.jar 一个 jar。把 classpath 改为 fileset 收全安装目录的全部 jar（本文 4.4 节写法）即可。同理，Ant 属性 classpath 的路径分隔符在 Linux 上是冒号，写成 Windows 分号会导致整个 classpath 解析失败。

Q5：报 outputDirectory must point to a directory？ componentbom 的 outputDirectory 指向了不存在的路径。该参数不会自动建目录，先在 build.xml 里 <mkdir dir="/root/hello-app/bom"/>（本文 4.4 节写法）再运行任务。

十、卸载与清理

antlib 本身不产生系统级安装，卸载即移除目录与依赖缓存。

移除验证工程与 antlib 安装目录：

rm -rf /root/hello-app /opt/cyclonedx-antlib /tmp/apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz /tmp/apache-ant-cyclonedx-0.2-bin-withdeps.tar.gz.sha512

ls /opt/cyclonedx-antlib 2>&1

ls: cannot access '/opt/cyclonedx-antlib': No such file or directory

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

rm -rf /root/.m2/repository/org/apache/ant/ant-cyclonedx /root/.m2/repository/org/cyclonedx

卸载 JDK、Ant 与 Maven（仅当不再需要）。先以 -s 预演确认将删除的包，无误后去掉 -s 真正执行：

apt-get -s purge -y openjdk-17-jdk ant maven

# 输出节选（实测首尾）
The following packages will be REMOVED:
  ant* maven* openjdk-17-jdk*

确认无误后真正卸载：

apt-get purge -y openjdk-17-jdk ant maven && apt-get autoremove -y

十一、参考链接

Apache CycloneDX Ant Library 官方主页：https://ant.apache.org/antlibs/cyclonedx/
官方手册（任务与类型）：https://ant.apache.org/antlibs/cyclonedx/manual/
官方二进制下载目录（bin 与 bin-withdeps）：https://downloads.apache.org/ant/antlibs/cyclonedx/binaries/
Maven 中央仓库坐标：https://repo1.maven.org/maven2/org/apache/ant/ant-cyclonedx/
Apache Ant 二进制下载（1.10.18）：https://downloads.apache.org/ant/binaries/
CycloneDX 规范：https://cyclonedx.org/specs/