Wren:IG 5.0.1 常用 CLI 命令与工具详解

目标：把 Wren:IG 5.0.1 日常运维会用到的命令与工具集中成一份可查手册，覆盖启停、版本核验、配置检查、进程与 JVM 核验、Admin API、HTTP 探测、日志级别切换、路由热加载与 TLS 检查。本文已在 Ubuntu 22.04.5 LTS + Tomcat 9.0.123 + Wren:IG 5.0.1 环境逐条实测。

一、环境信息

本节列出命令所处的运行基线，换版本后参数含义可能变化。

操作系统：Ubuntu 22.04.5 LTS，x86_64
JDK：OpenJDK 17.0.20.1
Servlet 引擎：Apache Tomcat 9.0.123
Wren:IG：5.0.1，修订号 c9eaf68a44e0e03c374bd345ac99731c38b25528
Tomcat 安装目录：/opt/tomcat
Wren:IG 配置根目录：/opt/wrenig
HTTP/HTTPS 端口：8080 / 8443
运行用户：wrenig
验证用上游服务：127.0.0.1:8081

二、工具概览

2.1 Wren:IG 的命令面在哪里

Wren:IG 本身不附带独立 CLI。它的运维命令面由三部分组成：

Servlet 引擎生命周期脚本：startup.sh、shutdown.sh、catalina.sh；
JDK 与系统工具：jps、ps、curl、openssl；
Wren:IG 自身的管理 REST API：/wrenig/api/*，以及日志文件与路由文件的热加载。

因此本文按 D1 组织，而不是 D5。D5 只写 API 会遗漏启停、JVM、日志这些每天都会用的操作；把 API 作为 D1 的一节，既能覆盖开箱命令，也能覆盖程序化管理。这个决策的理由是：读者需要的是“怎么把服务跑起来、停下去、查清楚”，而不是只看接口文档。

2.2 工具清单

工具	路径/入口	主要用途	本文实测
`catalina.sh`	`/opt/tomcat/bin/catalina.sh`	启动、停止、版本、配置检查	是
`startup.sh`	`/opt/tomcat/bin/startup.sh`	后台启动 Tomcat	是
`shutdown.sh`	`/opt/tomcat/bin/shutdown.sh`	优雅停止 Tomcat	是
`jps`	JDK `bin` 目录	查 Java 进程与 JVM 参数	是
`ps`	系统命令	查进程用户与完整命令行	是
`curl`	系统命令	探测 HTTP/HTTPS、调用 Admin API	是
Admin API	`/wrenig/api/*`	查版本、路由对象	是
日志文件	`/opt/wrenig/logs`、`/opt/tomcat/logs`	排障与审计	是
`openssl s_client`	系统命令	检查 TLS 证书	是
`systemctl`	系统命令	systemd 托管	否（本文环境未启用）

三、前置条件

本节确认命令可以执行，避免把“权限不足”误判为“组件故障”。

已安装 JDK 17，java -version 可执行
Tomcat 安装在 /opt/tomcat，Wren:IG WAR 已部署为 webapps/ROOT.war
/opt/wrenig 已存在且对 wrenig 用户可读写
执行启停命令的用户具备切换/提权到 wrenig 的能力
8080/8443 未被其它进程占用

先确认 Java 可用：

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)

四、各工具详解

4.1 catalina.sh：总入口

catalina.sh 是所有 Tomcat 生命周期命令的总入口。不带参数执行会打印完整用法：

/opt/tomcat/bin/catalina.sh

实测回显：

Usage: catalina.sh ( commands ... )
commands:
  debug             Start Catalina in a debugger
  debug -security   Debug Catalina with a security manager
  jpda start        Start Catalina under JPDA debugger
  run               Start Catalina in the current window
  run -security     Start in the current window with security manager
  start             Start Catalina in a separate window
  start -security   Start in a separate window with security manager
  stop              Stop Catalina, waiting up to 5 seconds for the process to end
  stop n            Stop Catalina, waiting up to n seconds for the process to end
  stop -force       Stop Catalina, wait up to 5 seconds and then use kill -KILL if still running
  stop n -force     Stop Catalina, wait up to n seconds and then use kill -KILL if still running
  configtest        Run a basic syntax check on server.xml - check exit code for result
  version           What version of tomcat are you running?
Note: Waiting for the process to end and use of the -force option require that $CATALINA_PID is defined

解读：日常用 start、stop、version、configtest 四个子命令即可。run 会占用当前终端，适合前台调试；stop n -force 需要先定义 CATALINA_PID，否则强制停止不生效。

4.2 catalina.sh version：核对引擎版本

/opt/tomcat/bin/catalina.sh version

实测回显：

NOTE: Picked up JDK_JAVA_OPTIONS:  --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED
Server version: Apache Tomcat/9.0.123
Server built:   Oct 6 2026 18:59:20 UTC
Server number:  9.0.123.0
OS Name:        Linux
OS Version:     7.0.0-38-generic
Architecture:   amd64
JVM Version:    17.0.20.1+1-1-22.04-Ubuntu
JVM Vendor:     Ubuntu
APR loaded:     false

Third-party libraries:
  ecj-4.20.jar: 3.26.0.v20210609-0549

解读：Server version 用于核对是否仍在 Tomcat 9 线上；JVM Version 用于核对 JDK；APR loaded: false 说明未启用 APR，本文的 HTTPS 走 JSSE，配置中的 Http11NioProtocol 与此一致。

4.3 catalina.sh configtest：检查 server.xml

configtest 只检查 server.xml 的基本语法与连接器初始化，不检查 Wren:IG 的 config.json 与路由文件。正确用法是先停止实例，再执行检查：

/opt/tomcat/bin/shutdown.sh
sleep 4
/opt/tomcat/bin/catalina.sh configtest

实测回显（节选）：

INFO: Connector [https-jsse-nio-8443], TLS virtual host [_default_], certificate type [RSA] configured from keystore [/opt/wrenig/keystore.jks] using alias [tomcat] with trust store [null]
Nov 02, 2026 1:09:54 PM org.apache.catalina.startup.Catalina load
INFO: Server initialization in [610] milliseconds

解读：出现 Server initialization in [610] milliseconds 且没有 SEVERE，说明 server.xml 配置可被引擎解析，8443 的密钥库也被正确读取。

⚠️ 注意：如果实例仍在运行，configtest 会尝试绑定 8080/8443，输出如下错误：
SEVERE: Failed to initialize component [Connector["http-nio-8080"]]
org.apache.catalina.LifecycleException: Protocol handler initialization failed
Caused by: java.net.BindException: Address already in use
更要注意：本文实测此时脚本退出码仍为 0。不能只看退出码判断成败，必须检查输出中是否含 SEVERE 或 Exception。这也是 configtest 最容易误判的地方。

4.4 startup.sh：后台启动

以 wrenig 用户启动：

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

实测回显：

Tomcat started.

⚠️ 注意：Tomcat started. 只代表启动脚本已拉起 Java 进程，不代表 Wren:IG 已完成 WAR 展开与路由加载。本文实测需要再等约 8–15 秒，/health 才会返回 200。启动后立即探测失败时，不要急着回滚配置。

4.5 shutdown.sh：优雅停止

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

实测回显（除 JDK 提示外无业务输出）：

NOTE: Picked up JDK_JAVA_OPTIONS:  --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED

解读：shutdown.sh 成功时通常没有“Stopping”之类的中文提示，必须用进程或端口验证：

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

停止后该命令无输出。若仍有进程，说明停止未完成，可等待几秒再查，或用 catalina.sh stop 10 -force（需先设置 CATALINA_PID）。

4.6 jps -v：查 Java 进程与 JVM 参数

jps -v

实测回显（节选）：

7315 Bootstrap ... -Xms256m -Xmx512m -Dfile.encoding=UTF-8 -Dcatalina.base=/opt/tomcat -Dcatalina.home=/opt/tomcat -Djava.io.tmpdir=/opt/tomcat/temp
7402 Jps -Dapplication.home=/usr/lib/jvm/java-17-openjdk-amd64 -Xms8m -Djdk.module.main=jdk.jcmd

解读：第一行是 Tomcat 的 Bootstrap 进程，-Xms256m -Xmx512m 是 setenv.sh 设置的值；第二行是 jps 自己，不是业务进程。用 jps 可以快速回答“进程在不在、堆参数是多少”。

4.7 ps：查进程用户与完整命令行

jps -v 不显示进程用户，需要 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，说明没有以 root 运行；命令行中能看到堆参数与 catalina.base。如果 user 是 root，说明启动方式不符合最小权限要求。

4.8 Admin API：查版本

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

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

解读：version 用于确认升级/回滚是否生效；revision 用于确认构建来源。脚本化巡检时可直接解析这两个字段。

4.9 Admin API：查路由列表

curl -sS 'http://127.0.0.1:8080/wrenig/api/system/objects/router-handler/routes?_queryFilter=true'

实测回显（节选，保留 app 路由）：

{"result":[{"_id":"app","name":"app","condition":"${request.uri.path == '/app'}","baseURI":"http://127.0.0.1:8081","session":"JwtSession","handler":{"type":"Chain","config":{"filters":[{"type":"ScriptableFilter","config":{"type":"application/x-groovy","file":"/opt/wrenig/scripts/auth.groovy"}},{"type":"HeaderFilter","config":{"messageType":"REQUEST","add":{"X-Authenticated-User":["admin"],"X-Gateway":["WrenIG"]}},"remove":["Cookie"]}}],"handler":"clientHandler"}}}],"resultCount":2 ...

解读：resultCount 为 2，说明 app 与 health 两条路由都已加载。用这个接口可以在不登录服务器的情况下核对线上路由配置。

4.10 Admin API：查单条路由

curl -sS http://127.0.0.1:8080/wrenig/api/system/objects/router-handler/routes/app

实测回显：

{"_id":"app","name":"app","condition":"${request.uri.path == '/app'}","baseURI":"http://127.0.0.1:8081","session":"JwtSession","handler":{"type":"Chain","config":{"filters":[{"type":"ScriptableFilter","config":{"type":"application/x-groovy","file":"/opt/wrenig/scripts/auth.groovy"}},{"type":"HeaderFilter","config":{"messageType":"REQUEST","add":{"X-Authenticated-User":["admin"],"X-Gateway":["WrenIG"]}},"remove":["Cookie"]}}],"handler":"clientHandler"}}}

解读：单条查询返回该路由的完整对象，适合排障时确认“线上到底加载了哪份配置”。若返回 404，检查路由 ID 是否拼错，或 Router 是否尚未扫描到。

4.11 curl：业务与健康探测

健康检查：

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

实测回显：

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

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

未认证访问业务路由：

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

实测回显：

HTTP/1.1 401
WWW-Authenticate: Basic realm="WrenIG"
Transfer-Encoding: chunked

带正确凭据：

curl -sS -i -u admin:q1w2e3r4 http://127.0.0.1:8080/app

实测回显（节选，Cookie 值已省略）：

HTTP/1.1 200
Set-Cookie: wrenig-session=...; Expires=Mon, 02 Nov 2026 13:21:32 GMT; Path=/
Content-Type: application/json

{"method": "GET", "path": "/app", "headers": {"accept": "*/*", "authorization": "Basic YWRtaW46cTF3MmUzcjQ=", "host": "127.0.0.1:8080", "user-agent": "curl/7.81.0", "X-Authenticated-User": "admin", "X-Gateway": "WrenIG", "Connection": "Keep-Alive"}}

解读：三个探测分别验证了健康路由、401 挑战、认证通过后的头注入。日常巡检用第一条即可；排障认证链路时按 401 → 200 顺序执行。

4.12 日志查看

Wren:IG 的日志分为控制台与按路由文件两部分：

日志	路径	用途
Tomcat 控制台	`/opt/tomcat/logs/catalina.out`	启动、部署、框架异常
系统路由日志	`/opt/wrenig/logs/route-system.log`	Wren:IG 框架与路由加载
业务路由日志	`/opt/wrenig/logs/route-app.log`	单条路由的请求处理与 DEBUG

查看启动与路由加载：

tail -8 /opt/wrenig/logs/route-system.log

实测回显（输出节选）：

12:58:56:473 | WARN  | main | o.f.o.h.GenericHeaplet | The heap object name ('{Router}/handler') has been transformed to a URL-friendly name ('router-handler') that is exposed in endpoint URLs. ...
12:58:56:481 | INFO  | main | o.f.o.h.r.RouterHandler | Routes endpoint available at '/wrenig/api/system/objects/router-handler/routes'
12:58:57:415 | INFO  | main | o.f.o.h.r.RouterHandler | Loaded the route with id 'app' registered with the name 'app'
12:58:57:417 | INFO  | main | o.f.o.h.r.RouterHandler | Loaded the route with id 'health' registered with the name 'health'
13:04:57:421 | INFO  | pool-1-thread-1 | o.f.o.h.r.RouterHandler | Unloaded the route with id 'health'
13:04:57:428 | INFO  | pool-1-thread-1 | o.f.o.h.r.RouterHandler | Loaded the route with id 'health' registered with the name 'health'

解读：Loaded the route 出现即说明路由已加载；pool-1-thread-1 表示运行期热加载。GenericHeaplet 的 WARN 是对象名被转换成 URL 友好名的提示，不影响功能，但生产配置可显式命名 router-handler 以避免该警告。

查看业务路由的 DEBUG：

tail -5 /opt/wrenig/logs/route-app.log

实测回显：

12:51:32:513 | DEBUG | http-nio-8080-exec-6 | o.a.h.i.n.c.MainClientExec | [exchange: 1] start execution
12:51:32:522 | DEBUG | http-nio-8080-exec-6 | o.a.h.c.p.RequestAuthCache | Auth cache not set in the context
12:51:32:522 | DEBUG | http-nio-8080-exec-6 | o.a.h.i.n.c.InternalHttpAsyncClient | [exchange: 1] Request connection for {}->http://127.0.0.1:8081
12:51:32:523 | DEBUG | http-nio-8080-exec-6 | o.a.h.i.n.c.PoolingNHttpClientConnectionManager | Connection request: [route: {}->http://127.0.0.1:8081][total kept alive: 0; route allocated: 0 of 64; total allocated: 0 of 64]

4.13 日志级别切换

默认 root 级别是 INFO。排障需要更详细的上游连接日志时，把 /opt/wrenig/config/logback.xml 的 root 改为 DEBUG：

<root level="DEBUG">
    <appender-ref ref="SIFT" />
    <appender-ref ref="STDOUT" />
</root>

修改后重启，验证确实出现 DEBUG 行：

sudo -u wrenig /opt/tomcat/bin/shutdown.sh
sleep 4
sudo -u wrenig /opt/tomcat/bin/startup.sh
sleep 13
grep -c DEBUG /opt/tomcat/logs/catalina.out

实测回显：

并抽查一行：

grep DEBUG /opt/tomcat/logs/catalina.out | tail -1

实测回显：

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

解读：计数从 0 变为 998，证明外部 logback.xml 覆盖生效。排障结束后应把 root 改回 INFO 并重启，避免日志量持续增长。

4.14 路由热加载

新增或修改 /opt/wrenig/config/routes/*.json 后，不需要重启。本文用 touch 触发重新扫描，等待 13 秒后验证：

touch /opt/wrenig/config/routes/health.json
sleep 13
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/health

实测回显：

再看日志中的非 main 线程加载记录：

grep "Loaded the route with id" /opt/tomcat/logs/catalina.out | tail -1

实测回显：

[pool-1-thread-1] INFO  o.f.o.handler.router.RouterHandler - Loaded the route with id 'health' registered with the name 'health'

解读：线程名 pool-1-thread-1 是扫描线程，证明没有重启；200 证明新配置已生效。默认扫描间隔约 10 秒，实际受文件数量与解析耗时影响。

⚠️ 注意：config.json、admin.json、logback.xml、setenv.sh 都不支持热加载，必须重启；只有 config/routes/ 下的路由文件与 Groovy 脚本是运行期生效。

4.15 TLS 证书检查

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

实测回显：

subject=C = CN, L = Shanghai, O = Wren Security, CN = wrenig.example.com
issuer=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

解读：subject 与 issuer 相同，说明是自签名证书；notAfter 是有效期终点。生产环境应换成企业 CA 证书，并检查证书链是否完整。

验证 HTTPS 业务端点：

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" }

4.16 systemctl（可选）

如果服务由 systemd 托管，常用命令为：

sudo systemctl start wrenig
sudo systemctl stop wrenig
sudo systemctl restart wrenig
sudo systemctl is-active wrenig
sudo journalctl -u wrenig -n 50 --no-pager

⚠️ 注意：本文验证环境未启用 systemd，上述命令未取到实测回显；在 systemd 真机上 systemctl is-active wrenig 应输出 active。启用前确认没有同时用 startup.sh 启动第二份实例。

五、注意事项

启动完成不等于服务就绪：startup.sh 返回 Tomcat started. 后仍需等待 WAR 展开与路由扫描，建议用 /wrenig/api/info 轮询确认。
停止成功不等于进程立即退出：shutdown.sh 可能无输出，必须用 ps 或端口验证。
configtest 的退出码不可信：端口占用时仍可能返回 0，必须检查输出中的 SEVERE。
不要以 root 启动：用 sudo -u wrenig；否则日志与数据文件会变成 root 所有，后续切换用户会失败。
DEBUG 日志量很大：排障后必须改回 INFO，并关注 /opt/wrenig/logs 的滚动上限。
Admin API 受管理模式影响：EVALUATION 模式开放，PRODUCTION 模式下管理端点会收紧，脚本巡检前先确认模式。
路由热加载只针对目录：config.json 的变更必须重启，不要误以为所有配置都热加载。

六、常见问题

6.1 执行 startup.sh 后 curl 连接被拒绝

现象：脚本输出 Tomcat started.，紧接着 curl 得到 Connection refused，几秒后恢复。

原因：Java 进程已拉起，但 Tomcat 连接器与 WAR 尚未完成初始化。

解决：等待 8–15 秒后重试。实测可直接等待 15 秒再探测管理端点：

sleep 15
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/wrenig/api/info

实测回显：

若 15 秒后仍失败，再检查 catalina.out 是否有 WAR 展开异常或端口占用，而不是继续缩短等待时间。

6.2 shutdown.sh 执行后进程还在

现象：shutdown.sh 无输出，ps 仍能看到 Bootstrap 进程。

原因：Tomcat 的 shutdown 端口未响应，或进程正在等待长请求结束。

解决：先等待 5–10 秒；仍不退出时，设置 CATALINA_PID 后使用：

/opt/tomcat/bin/catalina.sh stop 10 -force

若仍未退出，定位 PID 后手工结束进程，并检查 server.xml 的 shutdown 端口是否被改动。

6.3 jps 命令不存在

现象：jps: command not found。

原因：只安装了 JRE，没有安装 JDK；jps 属于 JDK 工具。

解决：安装 openjdk-17-jdk，并确认 JAVA_HOME 指向 JDK 而非 JRE。

6.4 Admin API 返回 404

现象：/wrenig/api/info 返回 404，但 /health 正常。

原因：admin.json 设置为 PRODUCTION 模式，管理端点被收紧；或访问路径写错（前缀不是 /wrenig）。

解决：检查 /opt/wrenig/config/admin.json；确认前缀与路由日志中的 Routes endpoint available at '/wrenig/api/system/objects/router-handler/routes' 一致。

6.5 修改路由后长时间不生效

现象：路由文件已更新，请求仍按旧规则处理。

原因：文件不在 /opt/wrenig/config/routes/，或权限不足导致扫描线程读不到，或 JSON 语法错误。

解决：检查路径、权限与 JSON 语法；查看 route-system.log 中是否有 Loaded/Unloaded 记录。

6.6 修改 logback.xml 后没有 DEBUG 日志

现象：root 已改为 DEBUG，日志仍是 INFO。

原因：logback.xml 只在启动时读取；未重启或文件不在 /opt/wrenig/config/logback.xml。

解决：确认路径后重启，再用 grep -c DEBUG catalina.out 验证计数。

6.7 日志文件权限错误

现象：启动或请求时报无法写入 /opt/wrenig/logs/route-*.log。

原因：曾用 root 启动，日志文件变成 root 所有；之后切换到 wrenig 用户无法追加。

解决：统一运行用户，并修正权限：

sudo chown -R wrenig:wrenig /opt/wrenig /opt/tomcat

七、参考链接

Wren:IG 官方项目页：https://wrensecurity.org/projects/wrenig/
Wren:IG 5.0.1 发布页：https://github.com/WrenSecurity/wrenig/releases/tag/5.0.1
Apache Tomcat 9 运行脚本说明：https://tomcat.apache.org/tomcat-9.0-doc/RUNNING.txt
Apache Tomcat 9 配置参考：https://tomcat.apache.org/tomcat-9.0-doc/config/
Logback 配置参考：https://logback.qos.ch/manual/configuration.html
OpenSSL s_client 文档：https://www.openssl.org/docs/man3.0/man1/openssl-s_client.html