Apache JSPWiki 2.12.5 常用 CLI 命令与工具详解

适用环境：Ubuntu 22.04 + OpenJDK 17.0.20.1 + Tomcat 9.0.58（APT 部署）+ JSPWiki 2.12.5。全部命令在实测环境执行并逐行照抄回显。目录约定：应用 /var/lib/tomcat9/webapps/JSPWiki/，数据 /var/lib/jspwiki/，日志 /var/log/tomcat9/。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
JDK：OpenJDK 17.0.20.1（APT 安装 openjdk-17-jdk-headless）
Servlet 服务器：Apache Tomcat 9.0.58（APT 安装 tomcat9）
JSPWiki：2.12.5（官方 WAR 包部署，应用上下文 /JSPWiki）
关键路径：
- Web 应用：/var/lib/tomcat9/webapps/JSPWiki/
- 页面数据：/var/lib/jspwiki/pages/（工作目录 /var/lib/jspwiki/work/）
- 用户库/组库：/var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml、groupdatabase.xml
- Tomcat 日志：/var/log/tomcat9/（控制台日志 catalina.out）
- systemd 单元：tomcat9.service
演示管理账号：admin / q1w2e3r4

本篇全部命令在上述环境实测执行，回显逐行照抄；CentOS 8 环境仅包管理器与 Tomcat 路径不同，命令形态一致。

二、服务启停与状态

2.1 systemctl 管理（推荐）

systemctl start tomcat9
systemctl stop tomcat9
systemctl restart tomcat9

状态确认：

systemctl is-active tomcat9
systemctl is-enabled tomcat9

实测输出：

active
enabled

systemctl status tomcat9 --no-pager | head -8

实测输出：

● tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 13:25:30 UTC; 43s ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
    Process: 46 ExecStartPre=/usr/libexec/tomcat9/tomcat-update-policy.sh (code=exited, status=0/SUCCESS)
   Main PID: 52 (java)
      Tasks: 40 (limit: 5753)
     Memory: 292.8M

修改 /etc/default/tomcat9（JVM 参数）或 systemd drop-in 后必须 systemctl daemon-reload && systemctl restart tomcat9。

2.2 catalina.sh 脚本管理

APT 版 Tomcat 9 的 catalina.sh 需要 CATALINA_BASE/CATALINA_HOME 环境变量，典型用法（前台调试用 run）：

su -s /bin/bash tomcat -c "export CATALINA_BASE=/var/lib/tomcat9 CATALINA_HOME=/usr/share/tomcat9; /usr/share/tomcat9/bin/catalina.sh start"

实测输出：

Tomcat started.

⚠️ Debian 包禁用了 shutdown 端口（/etc/tomcat9/server.xml 第 22 行 <Server port="-1" shutdown="SHUTDOWN">），catalina.sh stop 无法停服，实测输出：

NOTE: Picked up JDK_JAVA_OPTIONS:  --add-opens=java.base/java.lang=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
Oct 11, 2026 7:06:20 PM org.apache.catalina.startup.Catalina stopServer
SEVERE: No shutdown port configured. Shut down server through OS signal. Server not shut down.

停服一律用 systemctl stop tomcat9；无 systemd 的环境可用 pkill -f 'org.apache.catalina.startup.Bootstrap' 后再 catalina.sh start。

三、WAR 部署与卸载

3.1 部署 WAR

cp /tmp/JSPWiki.war /var/lib/tomcat9/webapps/JSPWiki.war
chown tomcat:tomcat /var/lib/tomcat9/webapps/JSPWiki.war
ls /var/lib/tomcat9/webapps/

实测输出（Tomcat 自动解包出 JSPWiki/ 目录）：

JSPWiki
JSPWiki.war
ROOT

ls /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/

实测输出：

classes
geronimo-web.xml
groupdatabase.xml
groupdatabase.xml.old
jspwiki.policy
lib
userdatabase.xml
userdatabase.xml.old
web.xml

验证（首次部署含解包与引擎初始化，约 30–60 秒）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/JSPWiki/

实测输出：

3.2 升级 WAR

cp JSPWiki-new.war /var/lib/tomcat9/webapps/JSPWiki.war
rm -rf /var/lib/tomcat9/work/Catalina/localhost/JSPWiki
systemctl restart tomcat9

同大版本内升级保留 WEB-INF/classes/jspwiki-custom.properties、WEB-INF/userdatabase.xml 与数据目录即可；注意确认新 WAR 解包后上述文件未被覆盖。

3.3 卸载 WAR

rm -f /var/lib/tomcat9/webapps/JSPWiki.war
rm -rf /var/lib/tomcat9/webapps/JSPWiki
rm -rf /var/lib/tomcat9/work/Catalina/localhost/JSPWiki

四、日志排查

4.1 控制台日志（catalina.out）

tail -f /var/log/tomcat9/catalina.out                 # 实时跟踪
grep -cE "ERROR|FATAL" /var/log/tomcat9/catalina.out  # 错误计数
grep "PropertyReader" /var/log/tomcat9/catalina.out | tail -3   # 配置加载情况

实测输出（配置加载确认）：

[INFO ] 2026-10-11 13:08:12.180 [main] o.a.w.u.PropertyReader - jspwiki.workDir is already set to: /var/lib/jspwiki/work
[INFO ] 2026-10-11 13:08:25.907 [http-nio-8080-exec-1] o.a.w.u.PropertyReader - jspwiki.workDir is already set to: /var/lib/jspwiki/work

常见错误样例（数据目录不可写时）：

[ERROR] 2026-10-11 13:25:34.375 [main] o.a.w.WikiEngine - JSPWiki: Unable to load and setup properties from jspwiki.properties. No permission to write to work directory: /var/lib/jspwiki/work

4.2 systemd 日志（journalctl）

journalctl -u tomcat9 --no-pager -n 50
journalctl -u tomcat9 --no-pager | grep -E "ERROR|FATAL"

实测输出（摘录一行）：

[ERROR] 2026-10-11 13:25:34.375 [main] o.a.w.WikiEngine - JSPWiki: Unable to load and setup properties from jspwiki.properties. No permission to write to work directory: /var/lib/jspwiki/work

4.3 独立文件日志（jspwiki.log，默认关闭）

默认日志全部进控制台；需要独立文件时在 WEB-INF/classes/jspwiki-custom.properties 追加（完整原理见《Apache JSPWiki 2.12.5 配置参数详解》日志参数一节）：

appender.rolling.fileName=/var/log/tomcat9/jspwiki.log
appender.rolling.filePattern=/var/log/tomcat9/jspwiki-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
logger.jspwiki.appenderRef.rolling.ref = RollingFile

重启后验证：

ls -l /var/log/tomcat9/jspwiki.log
tail -1 /var/log/tomcat9/jspwiki.log | cut -c1-90

实测输出：

-rw-r--r-- 1 root root 6029 Oct 11 19:10 /var/log/tomcat9/jspwiki.log
[INFO ] 2026-10-11 19:10:12.451 [main] o.a.w.WikiEngine - JSPWiki: Servlet container is Apache Tomcat/9.0.58

轮转规则（内置默认）：单文件 10MB，按时间+序号归档为 .gz，最多保留 14 份。

五、页面文件管理

5.1 页面存储结构

find /var/lib/jspwiki/pages -type f | sort

实测输出（VersioningFileProvider）：

/var/lib/jspwiki/pages/InstallNotes.txt
/var/lib/jspwiki/pages/OLD/InstallNotes/1.txt
/var/lib/jspwiki/pages/OLD/InstallNotes/page.properties

当前版本是 pages/<页面名>.txt；历史版本在 OLD/<页面名>/ 下按版本号命名；page.properties 记录各版本作者与变更说明（实测）：

# JSPWiki page properties for InstallNotes. DO NOT MODIFY!
#Sun Oct 11 13:23:54 GMT 2026
2.author=Administrator
1.author=Administrator
1.changenote=create by admin
2.changenote=update by admin

5.2 直接编辑页面内容

用任意编辑器修改 pages/<页面名>.txt（保持 UTF-8、文件名与页面名完全一致，区分大小写），保存即时生效，无需重启：

curl -s "http://localhost:8080/JSPWiki/Wiki.jsp?page=InstallNotes" | grep -c "JSPWiki 2.12.5"

5.3 重命名页面

同时移动当前版本与历史目录（实测以 RenameMe → RenamedPage 为例）：

mv /var/lib/jspwiki/pages/RenameMe.txt /var/lib/jspwiki/pages/RenamedPage.txt
mv /var/lib/jspwiki/pages/OLD/RenameMe /var/lib/jspwiki/pages/OLD/RenamedPage
find /var/lib/jspwiki/pages -name "*RenamedPage*" -o -name "*RenameMe*" | sort

实测输出：

/var/lib/jspwiki/pages/OLD/RenamedPage
/var/lib/jspwiki/pages/RenamedPage.txt

curl -s "http://localhost:8080/JSPWiki/Wiki.jsp?page=RenamedPage" | grep -c "renamed by file operations"

实测输出：

新名页面正常可访问；旧名页面变为"不存在"，可重新创建。

5.4 删除页面

rm /var/lib/jspwiki/pages/RenamedPage.txt
rm -rf /var/lib/jspwiki/pages/OLD/RenamedPage
curl -s "http://localhost:8080/JSPWiki/Wiki.jsp?page=RenamedPage" | grep -oE "does not exist" | head -1

实测输出：

does not exist

页面删除后访问返回"不存在"提示（HTTP 200），可随时重建。

5.5 页面全文检索

grep -rl "Ubuntu 22.04" /var/lib/jspwiki/pages/ --include="*.txt"

实测输出：

/var/lib/jspwiki/pages/InstallNotes.txt
/var/lib/jspwiki/pages/OLD/InstallNotes/1.txt

六、用户与组库管理

6.1 库文件位置与格式

默认位于 WEB-INF/ 下（若配置了 jspwiki.xmlUserDatabaseFile 则在指定路径）：

grep -o "<user[^>]*>" /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml

实测输出：

<user uid="8c052867-641c-438d-845d-74205a5149ab" loginName="admin" wikiName="Administrator" fullName="Administrator" email="admin@example.org" password="{SHA-256}rOooN5FoB5IuV+bU5BLv6F3FqxAXfOtMGkOE2NlOt0sXhMpPLuvSsQ==" created="2026.10.11 at 13:02:36:021 GMT" lastModified="2026.10.11 at 13:08:34:816 GMT" lockExpiry="" >

grep -o "<group[^>]*>" /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/groupdatabase.xml

实测输出：

<group name="Admin" creator="127.0.0.1" created="2026.10.11 at 13:02:36:029 GMT" modifier="127.0.0.1" lastModified="2026.10.11 at 13:02:36:029 GMT">

字段说明：loginName 登录名、wikiName/fullName 显示名、password 为加盐 SHA-256 哈希（{SHA-256}Base64，不可反推）、lockExpiry 账号锁定截止时间。文件修改会自动生成 *.xml.old 备份（实测存在）。

6.2 修改用户密码

Web 界面路径：UserPreferences.jsp?tab=profile（需登录，表单含 loginname/password0/password/password2/action=saveProfile）。curl 自动化全流程（含 CSRF Token 提取）见《Ubuntu 22.04 安装 Apache JSPWiki 2.12.5 指南》方案 B，实测输出 saveProfile: 302。

6.3 重建 admin 账号

密码丢失时，从用户库删除该条目并重新提交安装向导（会生成新的随机密码）：

systemctl stop tomcat9
sed -i '/loginName="admin"/d' /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml
systemctl start tomcat9
# 浏览器访问 http://<服务器IP>:8080/JSPWiki/Install.jsp 重新提交向导

七、备份与恢复

7.1 备份范围与命令

必备内容：页面数据 /var/lib/jspwiki/（pages + work）+ 配置与用户库三件（WEB-INF/jspwiki-custom.properties、WEB-INF/userdatabase.xml、WEB-INF/groupdatabase.xml）。

tar czf /root/jspwiki-full-backup-20261012.tar.gz /var/lib/jspwiki /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/jspwiki-custom.properties /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/groupdatabase.xml 2>&1 | head -2
ls -lh /root/jspwiki-full-backup-20261012.tar.gz

实测输出：

tar: Removing leading `/' from member names
tar: Removing leading `/' from hard link targets
-rw-r--r-- 1 root root 4.8K Oct 11 19:11 /root/jspwiki-full-backup-20261012.tar.gz

⚠️ tar: Removing leading '/' 是 tar 对绝对路径的正常提示，非错误。

仅备页面数据的轻量版（实测）：

tar czf /root/jspwiki-backup-20261012.tar.gz /var/lib/jspwiki 2>/dev/null
ls -lh /root/jspwiki-backup-20261012.tar.gz

实测输出：

-rw-r--r-- 1 root root 3.6K Oct 11 19:06 /root/jspwiki-backup-20261012.tar.gz

7.2 恢复

systemctl stop tomcat9
tar xzf /root/jspwiki-full-backup-20261012.tar.gz -C /
chown -R tomcat:tomcat /var/lib/jspwiki /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/groupdatabase.xml
systemctl start tomcat9
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/JSPWiki/

7.3 定时备份

crontab -e
# 每日 02:30 全量备份，保留 14 天
30 2 * * * tar czf /root/jspwiki-backup-$(date +\%Y\%m\%d).tar.gz /var/lib/jspwiki /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/jspwiki-custom.properties /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/groupdatabase.xml 2>/dev/null; find /root -name "jspwiki-backup-*.tar.gz" -mtime +14 -delete

八、健康检查与功能冒烟

8.1 端口与进程

ss -tlnp | grep 8080
ps -eo user,pid,cmd | grep [o]rg.apache.catalina.startup.Bootstrap | head -1 | cut -c1-60

实测输出：

LISTEN 0      100                *:8080            *:*
tomcat      9133 /usr/bin/java -Djava.util.logging.config.fi

8.2 JVM 堆参数确认

/usr/lib/jvm/java-17-openjdk-amd64/bin/jps -v | grep Bootstrap | grep -oE "\-Xms[0-9]+m|\-Xmx[0-9]+m"

实测输出：

-Xms256m
-Xmx512m

8.3 页面与搜索冒烟

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/JSPWiki/
curl -s "http://localhost:8080/JSPWiki/Search.jsp?query=InstallNotes" | grep -c "InstallNotes"
curl -s "http://localhost:8080/JSPWiki/Wiki.jsp?page=NoSuchPage" | grep -oE "does not exist" | head -1

实测输出：

200
4
does not exist

三项分别验证：首页可达、全文搜索命中、缺页提示正常。

九、常见问题（FAQ）

Q1：catalina.sh stop 后进程还在？

Debian 包 shutdown 端口为 -1，stop 无效（见 1.2 实测回显）。用 systemctl stop tomcat9，或 pkill -f 'org.apache.catalina.startup.Bootstrap'。

Q2：按配方开启文件日志后 /var/log/tomcat9/jspwiki.log 没生成？

三点检查：① 路径必须是写死的绝对路径（${sys:...} 不被解析）；② 目录对运行用户 tomcat 可写（/var/log/tomcat9/ 属 tomcat 组，或改用 /var/lib/jspwiki/ 下路径）；③ 三行配置（fileName/filePattern/logger 引用）缺一不可，改完需重启。

Q3：直接修改 pages/*.txt 后页面没变化？

检查文件名大小写是否与页面名完全一致（区分大小写）、文件编码是否 UTF-8、运行用户对该文件是否有读权限。页面名与文件名一一对应，InstallNotes.txt 对应页面 InstallNotes。

Q4：备份包恢复后登录不上了？

恢复包必须包含 WEB-INF/userdatabase.xml 与 groupdatabase.xml（仅备 /var/lib/jspwiki 不含用户库）；若用户库外置（配置了 jspwiki.xmlUserDatabaseFile），确认恢复路径与配置一致且属主为 tomcat。

Q5：重启后访问 404？

首次部署/升级后 WAR 解包与引擎初始化需 30–60 秒；若持续 404，按顺序查 grep -E "ERROR|FATAL" /var/log/tomcat9/catalina.out，常见为数据目录权限（No permission to write to work directory）与 tomcat 家目录缺失（Failed to create page directory），修复方法见《Ubuntu 22.04 安装 Apache JSPWiki 2.12.5 指南》FAQ。

十、参考链接

JSPWiki 官方 Wiki：https://jspwiki-wiki.apache.org/
Tomcat 9 文档：https://tomcat.apache.org/tomcat-9.0-doc/index.html
同专栏：《Ubuntu 22.04 安装 Apache JSPWiki 2.12.5 指南》《Apache JSPWiki 2.12.5 配置参数详解》