Apache Santuario 安装指南

目标：在 Ubuntu 22.04 服务器上完成 Apache Santuario 3.0.6（XML 签名与加密 Java 库，Maven 制品名 xmlsec）的安装与验证。Santuario 是纯 Java 类库，没有独立服务进程、端口和启动脚本，安装本质是「引入依赖」：官方推荐 Maven 依赖引入（方案 A），离线或无 Maven 环境可直接使用 jar 包（方案 B）。所有命令与输出均在 Ubuntu 22.04.5 + OpenJDK 17 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Java：OpenJDK 17.0.20.1
构建工具：Apache Maven 3.6.3
Santuario 版本：xmlsec 3.0.6（3.x 线最新稳定版）
演示账号：root
jar 存放目录（方案 B）：/opt/xmlsec/lib/

版本确认回显：

$ cat /etc/os-release | grep -E 'PRETTY|VERSION_ID'
PRETTY_NAME="Ubuntu 22.04.5 LTS"
VERSION_ID="22.04"

$ 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)

$ mvn -version
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
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

二、前置条件

2.1 更新软件源

apt-get update -qq

回显收尾：

done.

2.2 安装 JDK 17 与 Maven

apt-get install -y -qq openjdk-17-jdk maven

回显收尾：

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

安装完成后按「一、环境信息」中的回显确认 java -version 与 mvn -version 可用。

三、版本选型说明

查询 Maven Central 上 org.apache.santuario:xmlsec 的最近发布版本：

$ curl -s 'https://search.maven.org/solrsearch/select?q=g:org.apache.santuario+AND+a:xmlsec&core=gav&rows=12&wt=json' -o /tmp/mc.json && grep -o '"v":"[^"]*"' /tmp/mc.json | head -12
"v":"3.0.6"
"v":"4.0.4"
"v":"2.3.5"
"v":"3.0.5"
"v":"4.0.3"
"v":"3.0.4"
"v":"4.0.2"
"v":"4.0.1"
"v":"2.2.6"
"v":"2.3.4"
"v":"3.0.3"
"v":"4.0.0"

选型结论：

3.x 线最新稳定版为 3.0.6；列表中的 4.0.4 属于 4.x 新主线，两线 API 存在差异。本文按 xmlsec 3.0.6 安装并实测。
xmlsec 3.0.6 编译目标为 Java 8（字节码 major version 52），对运行时 JDK 要求宽松，JDK 17 可直接运行。来自 3.0.6 自带 pom 与字节码的实测证据：

$ grep -E 'maven.compiler.target|targetJdk' ~/.m2/repository/org/apache/santuario/xmlsec/3.0.6/xmlsec-3.0.6.pom
        <maven.compiler.target>1.8</maven.compiler.target>
        <targetJdk>1.8</targetJdk>

$ javap -verbose -classpath ~/.m2/repository/org/apache/santuario/xmlsec/3.0.6/xmlsec-3.0.6.jar org.apache.xml.security.Init | grep major
major version: 52

四、方案 A：Maven 项目依赖引入（官方推荐）

4.1 创建 Maven 工程

mkdir -p /root/xmlsec-demo/src/main/java/org/example

4.2 编写 pom.xml 并引入 xmlsec 依赖

写入 /root/xmlsec-demo/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>org.example</groupId>
    <artifactId>xmlsec-demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

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

    <dependencies>
        <dependency>
            <groupId>org.apache.santuario</groupId>
            <artifactId>xmlsec</artifactId>
            <version>3.0.6</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.1.0</version>
            </plugin>
        </plugins>
    </build>
</project>

4.3 编译与验证

执行依赖树解析（首次会从 Maven Central 拉取依赖，本环境直连可用，未配置镜像）：

$ cd /root/xmlsec-demo && mvn dependency:tree
...
[INFO] ----------------------< org.example:xmlsec-demo >-----------------------
[INFO] Building xmlsec-demo 1.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ xmlsec-demo ---
[INFO] org.example:xmlsec-demo:jar:1.0-SNAPSHOT
[INFO] \- org.apache.santuario:xmlsec:jar:3.0.6:compile
[INFO]    +- org.slf4j:slf4j-api:jar:1.7.36:compile
[INFO]    +- jakarta.xml.bind:jakarta.xml.bind-api:jar:3.0.1:compile
[INFO]    +- commons-codec:commons-codec:jar:1.18.0:compile
[INFO]    \- com.fasterxml.woodstox:woodstox-core:jar:6.5.1:runtime

本地仓库中的制品：

$ ls -lh ~/.m2/repository/org/apache/santuario/xmlsec/3.0.6/
total 1.2M
-rw-r--r-- 1 root root  192 Oct 12 02:39 _remote.repositories
-rw-r--r-- 1 root root 1.2M Oct 12 02:39 xmlsec-3.0.6.jar
-rw-r--r-- 1 root root   40 Oct 12 02:39 xmlsec-3.0.6.jar.sha1
-rw-r--r-- 1 root root   29K Oct 12 02:39 xmlsec-3.0.6.pom
-rw-r--r-- 1 root root   40 Oct 12 02:39 xmlsec-3.0.6.pom.sha1

再用 javap 确认核心类可从本地仓库 jar 中解析（看到类签名即安装成功）：

$ javap -classpath ~/.m2/repository/org/apache/santuario/xmlsec/3.0.6/xmlsec-3.0.6.jar org.apache.xml.security.Init
Compiled from "Init.java"
public class org.apache.xml.security.Init {
  public static final java.lang.String CONF_NS;
  public org.apache.xml.security.Init();
  public static final synchronized boolean isInitialized();
  public static synchronized void init();
  static {};
}

至此方案 A 安装完成。示例源码的构建与运行见《Apache Santuario 构建并运行示例应用指南》。

五、方案 B：直接使用 jar 包（离线 / 无 Maven 场景）

5.1 下载 jar 包

xmlsec 3.0.6 及其 4 个传递依赖（slf4j-api、jakarta.xml.bind-api、commons-codec、woodstox-core），共 5 个 jar，全部下载到同一目录：

mkdir -p /opt/xmlsec/lib /opt/xmlsec/classes /root/xmlsec-cp-test
cd /opt/xmlsec/lib
wget -q https://repo.maven.apache.org/maven2/org/apache/santuario/xmlsec/3.0.6/xmlsec-3.0.6.jar
wget -q https://repo.maven.apache.org/maven2/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar
wget -q https://repo.maven.apache.org/maven2/jakarta/xml/bind/jakarta.xml.bind-api/3.0.1/jakarta.xml.bind-api-3.0.1.jar
wget -q https://repo.maven.apache.org/maven2/commons-codec/commons-codec/1.18.0/commons-codec-1.18.0.jar
wget -q https://repo.maven.apache.org/maven2/com/fasterxml/woodstox/woodstox-core/6.5.1/woodstox-core-6.5.1.jar

下载结果：

$ ls -lh /opt/xmlsec/lib
total 3.2M
-rw-r--r-- 1 root root 365K Jan 24  2025 commons-codec-1.18.0.jar
-rw-r--r-- 1 root root 126K Mar 22  2021 jakarta.xml.bind-api-3.0.1.jar
-rw-r--r-- 1 root root  41K Feb  8  2022 slf4j-api-1.7.36.jar
-rw-r--r-- 1 root root 1.6M Apr 19  2023 woodstox-core-6.5.1.jar
-rw-r--r-- 1 root root 1.2M Apr  7  2025 xmlsec-3.0.6.jar

5.2 classpath 验证

用 javap 确认 classpath 上能解析到 Santuario 核心类：

javap -classpath '/opt/xmlsec/lib/*' org.apache.xml.security.Init

输出与 4.3 节的 javap 回显一致，即表明 5 个 jar 就位、classpath 生效。基于该 classpath 的完整签名/验签运行实测见《Apache Santuario 构建并运行示例应用指南》。

六、配置说明

Santuario 无需部署独立配置文件，运行期配置分三层：

JVM 层：堆内存建议 -Xms256m -Xmx512m 起步。Maven 场景通过环境变量注入：
```
export MAVEN_OPTS="-Xms256m -Xmx512m"
```
java 直跑场景直接附加参数，生效情况可用 jps -v 验证（示例工程实测回显，进程号以实际为准）：
```
$ jps -v | grep -F 'Xmx512m'
6855 ValidateExample -Xms256m -Xmx512m
```
库初始化层：原生 API（org.apache.xml.security.*）首次使用前由 Init.init() 读取 jar 内置配置 org/apache/xml/security/resource/config.xml，一般无需改动，详见《Apache Santuario 配置参数详解》。
上下文层：JSR-105 签名/验签上下文属性（如 org.apache.jcp.xml.dsig.secureValidation），按次设置、按次生效，详见《Apache Santuario 配置参数详解》。

七、注意事项

⚠️ 注意：

Santuario 是类库而非服务，没有启动脚本、监听端口与守护进程，不要按中间件方式安装，也不要期待安装后有独立进程。

3.x 与 4.x 两条主线并存：4.0.4 属于 4.x 线。本文全部实测基于 3.0.6，升级 4.x 前需另行验证 API 兼容性。

JDK 自带一个与 Santuario 包名相同的 XML 签名提供者（org.jcp.xml.dsig.internal.dom.XMLDSigRI）。若不显式传入 Santuario 的提供者实例，XMLSignatureFactory.getInstance("DOM") 会解析到 JDK 内置实现而非 Santuario，详见《Apache Santuario 常用工具与 API 详解》。

方案 B 的 5 个 jar 缺一不可：woodstox-core 虽为 runtime 范围依赖，仍需一并下载放置。

八、常见问题

Q1：运行示例时输出 SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder" 是什么问题？ xmlsec 依赖 slf4j-api 1.7.36 但未绑定日志实现，SLF4J 回退到 NOP（无操作）日志，不影响功能。实测提示原文：

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

如需日志输出，可自行引入 slf4j-simple 等绑定包。

Q2：Maven 拉取依赖缓慢或失败怎么办？ 本环境 Maven Central（repo.maven.apache.org）直连可用，未配置镜像。若网络受限，可为 Maven 配置镜像仓库，或改用方案 B 手动下载 5 个 jar。

Q3：如何确认安装的确实是 3.0.6？ 三种方式任选：mvn dependency:tree 查看解析结果（回显 xmlsec:jar:3.0.6:compile）；ls ~/.m2/repository/org/apache/santuario/xmlsec/ 查看本地仓库目录名；方案 B 下 ls -lh /opt/xmlsec/lib/ 查看 jar 文件名。

九、卸载方式

方案 A：删除示例工程与本地仓库中的 Santuario 制品：

rm -rf /root/xmlsec-demo
rm -rf ~/.m2/repository/org/apache/santuario

方案 B：删除 jar 目录与编译产物：

rm -rf /opt/xmlsec /root/xmlsec-cp-test

如不再需要构建环境，可一并卸载 JDK 与 Maven：

apt-get remove -y openjdk-17-jdk maven

十、参考链接

Apache Santuario 官网：http://santuario.apache.org/
Maven Central 制品检索：https://search.maven.org/search?q=g:org.apache.santuario
JSR-105（XML Digital Signature API）规范：https://www.jcp.org/en/jsr/detail?id=105