Ubuntu 22.04 安装 Wren:IG 5.0.1 指南

目标：在 Ubuntu 22.04.5 LTS 服务器上，从零完成 JDK 17、Tomcat 9.0.123 与 Wren:IG 5.0.1 的安装和 WAR 部署，配置最小可用路由、JVM 堆上限与 HTTPS，并逐项验证。本文全部命令与回显均已在 Ubuntu 22.04.5 LTS / x86_64 环境实测通过。

一、环境信息

本节列出本次安装的可复现基线，后续命令与回显均以此为准。

操作系统：Ubuntu 22.04.5 LTS（Jammy Jellyfish），x86_64
JDK：OpenJDK 17.0.20.1（Ubuntu 包 17.0.20.1+1-1~22.04）
Servlet 引擎：Apache Tomcat 9.0.123（catalina.sh version 显示构建时间 2026-10-06）
Wren:IG：5.0.1，修订号 c9eaf68a44e0e03c374bd345ac99731c38b25528
Wren:IG WAR 大小：72,669,060 字节（约 70MB）
WAR SHA-256：40ef08fbed5eff432d2322612fed4799e09d9e8f4ad650d6075a341d71afa7cb
Tomcat 安装目录：/opt/tomcat
Wren:IG 配置根目录：/opt/wrenig
监听端口：HTTP 8080、HTTPS 8443
运行用户：wrenig（uid 999）
本文验证用的最小上游服务：127.0.0.1:8081

💡 说明：Wren:IG 的交付核心是 WAR，不是带内嵌引擎的独立可执行程序。因此安装工作由“准备 JDK + 准备 Tomcat + 部署 WAR + 准备配置目录”四部分组成。

二、前置条件

本节确认服务器满足安装要求，避免装到一半才发现版本不匹配。

2.1 系统与网络

一台可登录的 Ubuntu 22.04 服务器，具备 sudo 权限
可访问 Apache 归档站与 Wren Security 发布页（或可把安装包离线传入）
8080、8443、8081 端口未被占用
磁盘至少预留 200MB（Tomcat 解压后约 159MB，另加 WAR 与日志空间）

2.2 检查端口占用

安装前先确认端口空闲：

sudo ss -ltnp | grep -E ':8080|:8443|:8081'

如果命令无输出，说明三个端口均未被占用，可以继续。若已有进程占用，请先调整 Tomcat 端口或停止冲突进程。

2.3 检查系统版本

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

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.5 LTS (Jammy Jellyfish)"
x86_64

版本与架构符合本文基线。

三、版本选型说明

本节解释为什么选 JDK 17 与 Tomcat 9，而不是更新的 JDK 21 或 Tomcat 10。

3.1 版本对照

组件	本文选用	可选范围	选择理由
JDK	OpenJDK 17.0.20.1	17 / 21	Wren:IG 5.0.1 以 Java 17 为构建与运行基线；JDK 21 未在本文验证
Servlet 引擎	Tomcat 9.0.123	Tomcat 9.x	Wren:IG 5.0.1 的 WAR 基于 `javax.servlet` 命名空间，Tomcat 9.x 可直接部署
Wren:IG	5.0.1	5.0.x	官方 Releases 中的最新稳定版（2026-02-04 发布）

3.2 为什么不能用 Tomcat 10+

Tomcat 10 起把 Servlet API 从 javax.servlet 迁移到 jakarta.servlet，包名与 Wren:IG 5.0.1 WAR 内的依赖不兼容。直接把 WAR 放进 Tomcat 10 的 webapps 会导致应用启动失败或类找不到。本文因此固定 Tomcat 9.0.123，并在升级章节说明如何保持该约束。

3.3 版本获取方式

不要凭记忆写版本号，安装前用以下命令确认当前稳定版本：

curl -sS https://github.com/WrenSecurity/wrenig/releases.atom | grep -oE '<title>[^<]+</title>' | head -6

实测输出节选（实测首尾）：

<title>Release 5.0.1 · WrenSecurity/wrenig</title>
<title>Release 5.0.0 · WrenSecurity/wrenig</title>
<title>Release 5.0.0-RC3 · WrenSecurity/wrenig</title>

Tomcat 9 的最新版本号可从官方下载页确认：

curl -sS https://archive.apache.org/dist/tomcat/tomcat-9/ | grep -oE 'v9\.0\.[0-9]+/' | tail -3

⚠️ 注意：版本号会随时间变化。本文的 5.0.1 与 9.0.123 是 2026-11-02 的实测基线；换版本时请同步更新 SHA-256 校验值。

四、安装方案 A：在线安装（官方 WAR + Tomcat 9）

这是本文的主方案，适合服务器可访问外网的环境。整条主线为：装 JDK → 下载并解压 Tomcat → 创建运行用户与配置目录 → 部署 WAR → 写启动参数 → 启动 → 验证。

4.1 安装 OpenJDK 17

更新包索引并安装 JDK：

sudo apt-get update
sudo apt-get install -y openjdk-17-jdk

安装输出较长，节选关键回显（实测首尾）：

Setting up openjdk-17-jdk:amd64 (17.0.20.1+1-1~22.04) ...
update-alternatives: using /usr/lib/jvm/java-17-openjdk-amd64/bin/jconsole to provide /usr/bin/jconsole (jconsole) in auto mode
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证 JDK：

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)

同时确认 JDK 包已安装：

dpkg -l | grep -E 'openjdk-17-(jdk|jre-headless)'

实测回显：

ii  openjdk-17-jdk:amd64          17.0.20.1+1-1~22.04    amd64    OpenJDK Development Kit (JDK)
ii  openjdk-17-jdk-headless:amd64 17.0.20.1+1-1~22.04    amd64    OpenJDK Development Kit (JDK) (headless)
ii  openjdk-17-jre-headless:amd64 17.0.20.1+1-1~22.04    amd64    OpenJDK Java runtime, using Hotspot JIT (headless)

java -version 输出 17.0.20.1，说明运行时已就绪。

4.2 下载安装包

创建源码目录并下载 Tomcat 9.0.123：

sudo mkdir -p /opt/src
cd /opt/src
sudo wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.123/bin/apache-tomcat-9.0.123.tar.gz

下载 Wren:IG 5.0.1 WAR：

sudo wget -O wrenig-5.0.1.war \
  https://github.com/WrenSecurity/wrenig/releases/download/5.0.1/wrenig-5.0.1.war

⚠️ 注意：本次实测时，官方 GitHub Release 直连下载速度极低（约 2 分钟仅 10MB），改为第三方下载站地址 https://gh-proxy.com/https://github.com/WrenSecurity/wrenig/releases/download/5.0.1/wrenig-5.0.1.war 后完整下载。若你的网络可正常直连官方地址，优先使用官方地址；无论走哪个渠道，都必须用下面的 SHA-256 校验。

下载完成后核对文件大小与校验值：

ls -lh /opt/src
sha256sum /opt/src/*

实测回显：

total 82M
-rw-r--r-- 1 root root 13M Nov  2 12:58 apache-tomcat-9.0.123.tar.gz
-rw-r--r-- 1 root root 70M Nov  2 12:58 wrenig-5.0.1.war
fc780a68520ff3af3f20f972bc03a39384c766ed686dd68593fa06d098eda437  /opt/src/apache-tomcat-9.0.123.tar.gz
40ef08fbed5eff432d2322612fed4799e09d9e8f4ad650d6075a341d71afa7cb  /opt/src/wrenig-5.0.1.war

校验解读：WAR 的 SHA-256 必须等于 40ef08fbed5eff432d2322612fed4799e09d9e8f4ad650d6075a341d71afa7cb；Tomcat 安装包必须等于 fc780a68520ff3af3f20f972bc03a39384c766ed686dd68593fa06d098eda437。任一不符都应重新下载，不要继续安装。

4.3 解压并安装 Tomcat

把 Tomcat 解压到 /opt，再重命名为固定目录 /opt/tomcat：

sudo tar -xzf /opt/src/apache-tomcat-9.0.123.tar.gz -C /opt
sudo mv /opt/apache-tomcat-9.0.123 /opt/tomcat

验证安装结果：

ls -l /opt/tomcat
du -sh /opt/tomcat

实测回显：

total 160
-rw-r----- 1 wrenig wrenig 26700 Oct  6 18:59 BUILDING.txt
-rw-r----- 1 wrenig wrenig  8626 Oct  6 18:59 CONTRIBUTING.md
-rw-r----- 1 wrenig wrenig 57092 Oct  6 18:59 LICENSE
-rw-r----- 1 wrenig wrenig  2333 Oct  6 18:59 NOTICE
drwxr-x--- 2 wrenig wrenig  4096 Nov  2 12:32 bin
drwxr-x--- 2 wrenig wrenig  4096 Nov  2 12:32 lib
drwxr-x--- 3 wrenig wrenig  4096 Nov  2 12:32 webapps
159M    /opt/tomcat

看到 bin、lib、webapps 等目录，且总占用约 159MB，说明解压完成。

4.4 创建运行用户与配置目录

为避免以 root 运行 Java 进程，创建专用系统用户 wrenig：

sudo useradd -r -s /usr/sbin/nologin -d /opt/wrenig wrenig
id wrenig

实测回显：

uid=999(wrenig) gid=999(wrenig) groups=999(wrenig)

创建 Wren:IG 的配置根目录：

sudo mkdir -p /opt/wrenig/config/routes
sudo mkdir -p /opt/wrenig/scripts /opt/wrenig/logs /opt/wrenig/data

目录职责如下：

路径	用途
`/opt/wrenig/config/config.json`	主配置：heap、顶层 handler、审计
`/opt/wrenig/config/routes/`	路由目录，Router 自动扫描
`/opt/wrenig/scripts/`	Groovy 脚本目录
`/opt/wrenig/logs/`	按路由拆分的日志文件
`/opt/wrenig/data/`	会话、临时数据等运行时文件

4.5 部署 WAR

先清空 Tomcat 自带的默认应用，避免 ROOT 目录与 ROOT.war 冲突：

sudo rm -rf /opt/tomcat/webapps/*
sudo cp /opt/src/wrenig-5.0.1.war /opt/tomcat/webapps/ROOT.war
sudo chown -R wrenig:wrenig /opt/tomcat /opt/wrenig
ls -l /opt/tomcat/webapps

实测回显：

total 70972
-rw-r--r-- 1 wrenig wrenig 72669060 Nov  2 12:32 ROOT.war

⚠️ 注意：Tomcat 发布包自带的 webapps/ROOT 目录必须删除。若保留空目录又放入 ROOT.war，Tomcat 可能优先使用空目录，访问时得到 404。

4.6 配置启动参数与 JVM 堆

在 setenv.sh 中固定 OPENIG_BASE 与 JVM 参数。setenv.sh 会被 catalina.sh 自动加载：

sudo tee /opt/tomcat/bin/setenv.sh > /dev/null <<'EOF'
export OPENIG_BASE=/opt/wrenig
export CATALINA_OPTS="-Xms256m -Xmx512m -Dfile.encoding=UTF-8"
EOF
sudo chmod 755 /opt/tomcat/bin/setenv.sh
sudo chown wrenig:wrenig /opt/tomcat/bin/setenv.sh
cat /opt/tomcat/bin/setenv.sh

实测回显：

export OPENIG_BASE=/opt/wrenig
export CATALINA_OPTS="-Xms256m -Xmx512m -Dfile.encoding=UTF-8"

参数说明：

参数	作用	本文取值
`OPENIG_BASE`	指定 Wren:IG 配置根目录	`/opt/wrenig`
`-Xms256m`	JVM 初始堆	256MB
`-Xmx512m`	JVM 最大堆	512MB
`-Dfile.encoding=UTF-8`	统一字符编码，避免中文乱码	UTF-8

💡 说明：Wren:IG 本身是 Java 应用，堆上限必须显式限制。本文把堆控制在 256–512MB 区间，适合测试与小规模入口；生产环境需按并发量与路由复杂度评估。

4.7 写入最小配置

主配置 /opt/wrenig/config/config.json：

sudo tee /opt/wrenig/config/config.json > /dev/null <<'EOF'
{
    "heap": [
        {
            "name": "clientHandler",
            "type": "ClientHandler"
        },
        {
            "name": "JwtSession",
            "type": "org.forgerock.openig.jwt.JwtSessionManager",
            "config": {
                "sessionTimeout": "30 minutes",
                "cookieName": "wrenig-session"
            }
        }
    ],
    "handler": {
        "type": "Router"
    },
    "audit": "global"
}
EOF

路由 /opt/wrenig/config/routes/health.json：

sudo tee /opt/wrenig/config/routes/health.json > /dev/null <<'EOF'
{
    "name": "health",
    "condition": "${request.uri.path == '/health'}",
    "handler": {
        "type": "StaticResponseHandler",
        "config": {
            "status": 200,
            "reason": "OK",
            "headers": {
                "Content-Type": [ "application/json" ]
            },
            "entity": "{ \"status\": \"UP\", \"product\": \"Wren:IG\" }"
        }
    }
}
EOF
sudo chown -R wrenig:wrenig /opt/wrenig

配置要点：

heap 声明两个可复用对象：clientHandler 负责向上游发起请求；JwtSession 负责会话。
handler 固定为 Router，Wren:IG 会到 /opt/wrenig/config/routes/ 查找路由文件。
condition 是 EL 表达式，${request.uri.path == '/health'} 表示只匹配 /health。
StaticResponseHandler 直接返回 200 与 JSON，不依赖任何上游服务，适合安装后的第一轮验证。

⚠️ 注意：路由不能内联写在 config.json 的 handler 里。Router 只从 config/routes/ 目录加载路由文件；把 routes 数组塞进 config.json 会导致路由列表为空、请求全部 404。

4.8 启动服务

以 wrenig 用户启动 Tomcat：

sudo -u wrenig /opt/tomcat/bin/startup.sh

实测回显：

Tomcat started.

等待约 10 秒让 WAR 展开与路由加载完成，然后查看启动日志：

sudo sed 's/\x1b\[[0-9;]*m//g' /opt/tomcat/logs/catalina.out | \
  grep -E 'Server version name|OpenIG base directory|Reading the configuration|Deployment of web application|Starting ProtocolHandler' | tail -8

实测输出节选：

02-Nov-2026 12:58:50.286 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Server version name:   Apache Tomcat/9.0.123
[main] INFO  o.f.openig.web.OpenIGInitializer - OpenIG base directory : /opt/wrenig
[main] INFO  o.f.openig.web.OpenIGInitializer - Reading the configuration from /opt/wrenig/config/config.json
02-Nov-2026 12:58:57.485 INFO [main] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive [/opt/tomcat/webapps/ROOT.war] has finished in [5,909] ms
02-Nov-2026 12:58:57.487 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["http-nio-8080"]
02-Nov-2026 12:58:57.512 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler ["https-jsse-nio-8443"]

四行日志依次证明：Tomcat 9.0.123 启动、OPENIG_BASE 被正确读取、config.json 被解析、WAR 部署完成、8080/8443 两个监听器就绪。

4.9 验证安装

4.9.1 验证管理信息端点

curl -sS -i http://127.0.0.1:8080/wrenig/api/info

实测回显：

HTTP/1.1 200
Cache-Control: no-cache
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Mon, 02 Nov 2026 12:50:03 GMT

{"version":"5.0.1","revision":"c9eaf68a44e0e03c374bd345ac99731c38b25528","branch":"UNKNOWN","timestamp":1770208153544}

返回 version 为 5.0.1，说明 Wren:IG 已正常加载。

4.9.2 验证静态路由

curl -sS -i http://127.0.0.1:8080/health

实测回显：

HTTP/1.1 200
Content-Type: application/json
Content-Length: 40
Date: Mon, 02 Nov 2026 12:58:29 GMT

{ "status": "UP", "product": "Wren:IG" }

返回 200 且正文来自 StaticResponseHandler，说明 Router 已扫描到 routes/health.json。

4.9.3 验证未匹配路由

curl -sS -i http://127.0.0.1:8080/not-exist

实测回显：

HTTP/1.1 404
Transfer-Encoding: chunked
Date: Mon, 02 Nov 2026 12:47:25 GMT

未匹配路由返回 404，符合预期；如果 /health 也返回 404，请优先检查路由文件名、condition 与 Router 日志。

4.9.4 验证 JVM 堆参数已生效

jps -v

实测输出节选（只保留 Bootstrap 行）：

7315 Bootstrap ... -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Dcatalina.base=/opt/tomcat -Dcatalina.home=/opt/tomcat -Djava.io.tmpdir=/opt/tomcat/temp

再用 ps 确认进程归属与完整参数：

ps -eo pid,user,args | grep org.apache.catalina.startup.Bootstrap | grep -v grep

实测输出节选：

7315 wrenig /usr/bin/java ... -Xms256m -Xmx512m -Dfile.encoding=UTF-8 ... org.apache.catalina.startup.Bootstrap start

user 列为 wrenig，且命令行包含 -Xms256m -Xmx512m，证明堆限制与运行用户均按预期生效。

五、安装方案 B：离线内网安装

适用于目标服务器不能访问外网的场景。工件与在线方案完全一致，只是把“下载”搬到可联网的跳板机，再用安全通道传入。

5.1 在联网跳板机准备工件

mkdir -p /tmp/wrenig-bundle
cd /tmp/wrenig-bundle
wget -O wrenig-5.0.1.war \
  https://github.com/WrenSecurity/wrenig/releases/download/5.0.1/wrenig-5.0.1.war
wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.123/bin/apache-tomcat-9.0.123.tar.gz
sha256sum wrenig-5.0.1.war apache-tomcat-9.0.123.tar.gz > SHA256SUMS

SHA256SUMS 中两行校验值必须与第四节的实测值一致：

40ef08fbed5eff432d2322612fed4799e09d9e8f4ad650d6075a341d71afa7cb  wrenig-5.0.1.war
fc780a68520ff3af3f20f972bc03a39384c766ed686dd68593fa06d098eda437  apache-tomcat-9.0.123.tar.gz

5.2 传入目标服务器

scp /tmp/wrenig-bundle/* root@192.168.1.62:/opt/src/

目标服务器上的接收路径为 /opt/src，传入后先复核：

cd /opt/src
sha256sum -c SHA256SUMS

预期回显：

wrenig-5.0.1.war: OK
apache-tomcat-9.0.123.tar.gz: OK

校验通过后，从第四节 4.3 开始执行解压、建用户、部署 WAR、配置与启动，步骤完全一致。离线方案不改变任何配置，只改变工件来源。

六、方案对比与选择建议

维度	方案 A：在线安装	方案 B：离线内网安装
是否需要联网	目标机需访问官方源或第三方下载站	仅跳板机需联网
工件来源	官方 GitHub / Apache 归档站	跳板机下载后 `scp` 传入
校验方式	下载后 `sha256sum`	跳板机生成 `SHA256SUMS`，目标机 `sha256sum -c`
适用场景	云主机、可联网测试环境	生产内网、隔离区、审计要求高的环境
风险点	官方直连可能极慢，需要第三方下载站降级	传输链路需保证完整性与机密性

选择建议：能联网且下载速度正常时用方案 A；目标机处于隔离网络时用方案 B。两条路径最终产物和配置完全相同，不要为离线环境单独维护另一套配置。

七、配置说明

本节补充安装后必须了解的基础配置项。更完整的参数、过滤器链与脚本写法属于配置专题内容，本节只覆盖让服务“跑起来并可持续运维”的最小集合。

7.1 配置文件位置

文件	路径	是否必需
主配置	`/opt/wrenig/config/config.json`	必需
管理配置	`/opt/wrenig/config/admin.json`	可选；缺失时按 EVALUATION 模式运行
路由	`/opt/wrenig/config/routes/*.json`	至少一条
外部日志配置	`/opt/wrenig/config/logback.xml`	可选；缺失时使用 WAR 内置配置
HTTPS 密钥库	`/opt/wrenig/keystore.jks`	启用 HTTPS 时必需

7.2 管理模式

首次启动时如果日志出现以下警告，说明当前处于 EVALUATION 模式：

[main] WARN  o.f.openig.web.OpenIGInitializer - The product is running in EVALUATION mode - by default, all endpoints are open and accessible. Do not use this mode for a production environment.

生产环境应新增 /opt/wrenig/config/admin.json：

{
    "mode": "PRODUCTION"
}

⚠️ 注意：切到 PRODUCTION 模式后，/wrenig/api/* 管理端点默认不再对外开放。本文实测在 PRODUCTION 模式下，本机回环访问该端点也返回 404。需要在生产中使用管理 API 时，必须另行设计受控访问通道，不能直接暴露到公网。

7.3 日志

默认日志位置：

Tomcat 主日志：/opt/tomcat/logs/catalina.out
Wren:IG 按路由日志：/opt/wrenig/logs/route-<routeId>.log
系统级路由日志：/opt/wrenig/logs/route-system.log

查看最近日志：

sudo tail -20 /opt/wrenig/logs/route-system.log
sudo tail -20 /opt/tomcat/logs/catalina.out

Wren:IG 使用 logback，默认级别为 INFO。需要临时提升到 DEBUG 时，可在 /opt/wrenig/config/logback.xml 中把 root 级别改为 DEBUG，重启后生效。本文实测该文件生效后，catalina.out 出现大量 DEBUG 行，例如：

[I/O dispatcher 1] DEBUG o.a.h.i.n.c.InternalHttpAsyncClient - [exchange: 1] Response processed

7.4 启用 HTTPS

生成自签名密钥库（生产环境应替换为企业 CA 签发的证书）：

sudo keytool -genkeypair -alias wrenig \
  -keyalg RSA -keysize 2048 -validity 365 \
  -keystore /opt/wrenig/keystore.jks -storepass changeit \
  -dname "CN=wrenig.example.com, OU=Security, O=Wren Security, L=Shanghai, C=CN" \
  -ext SAN=dns:wrenig.example.com,ip:127.0.0.1
sudo chown wrenig:wrenig /opt/wrenig/keystore.jks

确认密钥库内容：

keytool -list -keystore /opt/wrenig/keystore.jks -storepass changeit

实测输出节选：

Keystore type: PKCS12
Your keystore contains 1 entry

wrenig, Nov 2, 2026, PrivateKeyEntry,
Certificate fingerprint (SHA-256): 4C:02:54:35:3D:72:4D:73:49:31:41:0A:B4:A1:10:93:2B:B8:60:AC:0B:2F:61:97:8F:DF:AB:5F:8E:03:31:2C

编辑 /opt/tomcat/conf/server.xml，在 </Service> 之前加入 HTTPS Connector：

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="150" SSLEnabled="true">
    <SSLHostConfig>
        <Certificate certificateKeystoreFile="/opt/wrenig/keystore.jks"
                     certificateKeystorePassword="changeit"
                     type="RSA" />
    </SSLHostConfig>
</Connector>

重启并验证：

sudo -u wrenig /opt/tomcat/bin/shutdown.sh
sudo -u wrenig /opt/tomcat/bin/startup.sh
curl -skS -i https://127.0.0.1:8443/health

实测回显：

HTTP/1.1 200
Content-Type: application/json
Content-Length: 40

{ "status": "UP", "product": "Wren:IG" }

查看证书主题：

echo -n "" | openssl s_client -connect 127.0.0.1:8443 2>/dev/null | openssl x509 -noout -subject -dates

实测回显：

subject=C = CN, L = Shanghai, O = Wren Security, CN = wrenig.example.com
notBefore=Nov  2 12:38:36 2026 GMT
notAfter=Nov  2 12:38:36 2027 GMT

7.5 systemd 托管（可选）

如果目标机使用 systemd，可创建 /etc/systemd/system/wrenig.service：

[Unit]
Description=Wren:IG 5.0.1 on Tomcat 9
After=network.target

[Service]
Type=forking
User=wrenig
Group=wrenig
Environment="OPENIG_BASE=/opt/wrenig"
Environment="CATALINA_HOME=/opt/tomcat"
Environment="CATALINA_BASE=/opt/tomcat"
Environment="CATALINA_PID=/opt/tomcat/temp/tomcat.pid"
Environment="CATALINA_OPTS=-Xms256m -Xmx512m -Dfile.encoding=UTF-8"
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用与检查：

sudo systemctl daemon-reload
sudo systemctl enable --now wrenig
sudo systemctl is-active wrenig

⚠️ 注意：本节 systemd 托管需要目标机具备 systemd 环境。本文验证环境采用 startup.sh 直接托管，未启用 systemd，因此未附 systemctl 回显；在 systemd 真机上执行 systemctl is-active wrenig 应输出 active。启用前请确认真机上没有同时用 startup.sh 再启动一份，避免重复进程与端口冲突。

八、升级、降级与多版本管理

8.1 升级

升级前备份当前 WAR 与配置：

sudo cp /opt/tomcat/webapps/ROOT.war /opt/src/ROOT-5.0.1.war.bak
sudo tar -czf /opt/src/wrenig-config-$(date +%F).tar.gz /opt/wrenig/config

停止服务、替换 WAR、清理展开目录、启动：

sudo -u wrenig /opt/tomcat/bin/shutdown.sh
sudo cp /opt/src/wrenig-5.0.1.war /opt/tomcat/webapps/ROOT.war
sudo rm -rf /opt/tomcat/webapps/ROOT /opt/tomcat/work/Catalina
sudo -u wrenig /opt/tomcat/bin/startup.sh

升级后核对版本：

curl -sS http://127.0.0.1:8080/wrenig/api/info

预期返回新的 version 字段。若版本未变，检查是否仍有旧进程占用端口。

8.2 降级

降级即回滚到备份 WAR：

sudo -u wrenig /opt/tomcat/bin/shutdown.sh
sudo cp /opt/src/ROOT-5.0.1.war.bak /opt/tomcat/webapps/ROOT.war
sudo rm -rf /opt/tomcat/webapps/ROOT /opt/tomcat/work/Catalina
sudo -u wrenig /opt/tomcat/bin/startup.sh

回滚后同样用 /wrenig/api/info 核对版本与修订号。

8.3 多版本并存

需要同时保留两个版本时，不要让两个实例共用同一个 /opt/tomcat。为每个版本准备独立的引擎目录与配置根目录，并分配不同端口：

实例	引擎目录	配置根目录	HTTP	HTTPS
5.0.1	`/opt/tomcat-501`	`/opt/wrenig-501`	8080	8443
5.1.x	`/opt/tomcat-510`	`/opt/wrenig-510`	8082	8445

每个实例各自设置 OPENIG_BASE、CATALINA_OPTS 与 Connector 端口。多版本并存的目的是灰度与回滚，不是长期双跑；确认新版本稳定后应尽快收敛到单实例。

九、常见问题

9.1 访问 `/health` 返回 404

现象：WAR 已部署、Tomcat 已启动，但访问 /health 返回 HTTP/1.1 404，catalina.out 出现：

[http-nio-8080-exec-5] ERROR o.f.o.handler.router.RouterHandler - no handler to dispatch to

原因：Router 没有加载到路由文件。最常见的是把 routes 数组内联写进了 config.json，而 Router 只扫描 /opt/wrenig/config/routes/ 目录。

解决：把每条路由拆成独立 JSON 文件放入 /opt/wrenig/config/routes/，确认文件可被 wrenig 用户读取，等待默认 10 秒扫描周期后重试；无需重启。

9.2 启动报 `ClassNotFoundException: JwtSessionManager`

现象：config.json 中写 "type": "JwtSessionManager"，启动或首次请求时报类找不到。

原因：Wren:IG 的对象类型解析不支持短类名。

解决：改用全限定类名：

"type": "org.forgerock.openig.jwt.JwtSessionManager"

9.3 HeaderFilter 报 `Expecting a value`

现象：配置 HeaderFilter 后请求返回 500，日志出现：

/handler/config/filters/0/config/messageType: Expecting a value

原因：HeaderFilter 必须显式声明 messageType（REQUEST 或 RESPONSE），否则无法确定改写方向。

解决：补上 "messageType": "REQUEST"。另外，增加请求头使用 add 键，不是 set：

{
    "type": "HeaderFilter",
    "config": {
        "messageType": "REQUEST",
        "add": { "X-Gateway": [ "WrenIG" ] },
        "remove": [ "Cookie" ]
    }
}

9.4 启动日志出现 JWT 临时密钥警告

现象（输出节选，末尾省略号为原日志截断）：

[main] WARN  o.f.o.jwt.JwtSessionManager$Heaplet - JWT session support has been enabled but no encryption keys have been configured. A temporary key pair will be used ...

原因：启用了 JwtSessionManager 但未配置加密密钥与签名共享密钥。

影响：单实例测试可忽略；多实例或重启后仍需保持会话时，临时密钥会导致旧 Cookie 无法解密。

解决：在 JwtSessionManager 配置中提供 keystore、alias、password 与共享密钥，确保所有实例使用同一套密钥材料。

9.5 重启后瞬间访问被拒绝

现象：shutdown.sh 后立即 startup.sh，再立刻 curl 可能得到连接拒绝；等待数秒后恢复。

原因：Tomcat 端口释放与 WAR 展开需要时间，startup.sh 返回 Tomcat started. 只代表脚本已拉起进程，不代表应用已完成部署。

解决：启动后等待 8–15 秒，或循环探测 /wrenig/api/info 直到返回 200，再执行后续验证。

9.6 Tomcat 10/11 无法部署

现象：WAR 放入 Tomcat 10+ 后应用启动失败，日志提示 jakarta.servlet 相关类缺失。

原因：Tomcat 10 起 Servlet API 包名从 javax.servlet 迁移到 jakarta.servlet，与 Wren:IG 5.0.1 不兼容。

解决：使用 Tomcat 9.x（本文基线 9.0.123），不要在未验证的情况下升级到 Tomcat 10+。

十、卸载与清理

停止服务并禁用 systemd 单元（如果使用）：

sudo systemctl stop wrenig
sudo systemctl disable wrenig
sudo rm -f /etc/systemd/system/wrenig.service
sudo systemctl daemon-reload

sudo rm -rf /opt/tomcat /opt/wrenig /opt/src

删除运行用户：

sudo userdel wrenig

确认没有残留 Java 进程：

ps -eo pid,user,args | grep org.apache.catalina.startup.Bootstrap | grep -v grep

命令无输出即表示进程已退出。若仍需保留配置用于复盘，可先备份 /opt/wrenig/config 再删除目录。

十一、参考链接

Wren:IG 官方项目页：https://wrensecurity.org/projects/wrenig/
Wren:IG 官方 Getting Started：https://wrensecurity.org/projects/wrenig/download.html
Wren:IG 5.0.1 发布页：https://github.com/WrenSecurity/wrenig/releases/tag/5.0.1
Apache Tomcat 9 官方下载：https://tomcat.apache.org/download-90.cgi
Apache Tomcat 9 归档站：https://archive.apache.org/dist/tomcat/tomcat-9/
OpenJDK 17 Ubuntu 包：https://packages.ubuntu.com/jammy/openjdk-17-jdk

Ubuntu 22.04 安装 Wren:IG 5.0.1 指南

Ubuntu 22.04 安装 Wren:IG 5.0.1 指南

一、环境信息

二、前置条件

2.1 系统与网络

2.2 检查端口占用

2.3 检查系统版本

三、版本选型说明

3.1 版本对照

3.2 为什么不能用 Tomcat 10+

3.3 版本获取方式

四、安装方案 A：在线安装（官方 WAR + Tomcat 9）

4.1 安装 OpenJDK 17

4.2 下载安装包

4.3 解压并安装 Tomcat

4.4 创建运行用户与配置目录

4.5 部署 WAR

4.6 配置启动参数与 JVM 堆

4.7 写入最小配置

4.8 启动服务

4.9 验证安装

4.9.1 验证管理信息端点

4.9.2 验证静态路由

4.9.3 验证未匹配路由

4.9.4 验证 JVM 堆参数已生效

五、安装方案 B：离线内网安装

5.1 在联网跳板机准备工件

5.2 传入目标服务器

六、方案对比与选择建议

七、配置说明

7.1 配置文件位置

7.2 管理模式

7.3 日志

7.4 启用 HTTPS

7.5 systemd 托管（可选）

八、升级、降级与多版本管理

8.1 升级

8.2 降级

8.3 多版本并存

九、常见问题

9.1 访问 /health 返回 404

9.2 启动报 ClassNotFoundException: JwtSessionManager

9.3 HeaderFilter 报 Expecting a value

9.4 启动日志出现 JWT 临时密钥警告

9.5 重启后瞬间访问被拒绝

9.6 Tomcat 10/11 无法部署

十、卸载与清理

十一、参考链接

9.1 访问 `/health` 返回 404

9.2 启动报 `ClassNotFoundException: JwtSessionManager`

9.3 HeaderFilter 报 `Expecting a value`