Ubuntu 22.04 安装 Apache JSPWiki 2.12.5 指南

目标：在 Ubuntu 22.04 服务器上从零安装并运行 Apache JSPWiki 2.12.5（官方 WAR 包 + Tomcat 9），完成初始化安装向导、systemd 开机自启与功能验证。已在 Ubuntu 22.04（JDK 17.0.20.1 + Tomcat 9.0.58 + JSPWiki 2.12.5）环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
JDK：OpenJDK 17.0.20.1（openjdk-17-jdk-headless 17.0.20.1+1-1~22.04）
Servlet 服务器：Apache Tomcat 9.0.58（tomcat9 9.0.58-1ubuntu0.2，APT 安装）
JSPWiki：2.12.5（官方 WAR 包，36752001 字节）
服务端口：Tomcat HTTP 连接器 8080
部署上下文：http://<服务器IP>:8080/JSPWiki/
关键路径：
- Tomcat 配置：/etc/tomcat9/
- Web 应用目录：/var/lib/tomcat9/webapps/
- Tomcat 日志：/var/log/tomcat9/
- JSPWiki 页面存储：/var/lib/jspwiki/pages/
- JSPWiki 工作目录（索引/缓存）：/var/lib/jspwiki/work/
- systemd 单元：/lib/systemd/system/tomcat9.service
演示管理账号：admin / q1w2e3r4

二、前置条件

一台 Ubuntu 22.04 服务器，拥有 root 权限（本文以 root 执行）。
服务器可访问外网（下载 APT 包与官方 WAR；离线环境可将 WAR 提前下载后上传）。
内存 ≥ 2GB（本文将 JVM 堆限制在 256–512MB，1GB 内存亦可运行）。
端口 8080 未被占用（如需调整见"配置说明"）。

三、版本选型说明

Apache JSPWiki 官方当前维护两条版本线（发布日期均为 2026-08-22）：

版本线	最新版本	Servlet 命名空间	配套服务器	说明
2.12.x	2.12.5	javax.servlet	Tomcat 9.x	传统稳定线，生态兼容性最好，本文选择
3.0.x	3.0.0	jakarta.servlet	Tomcat 10.x+	新一代版本，包名迁移至 jakarta，配套服务器不同

💡 JSPWiki 2.12.x 使用 javax.servlet 命名空间，必须部署在 Tomcat 9（或更早的 javax 系服务器）上；放在 Tomcat 10+ 会因命名空间不匹配而无法运行。本文按官方 2.12.5 发行包 + Ubuntu APT 源的 Tomcat 9 组合实测。

获取最新稳定版本号的方式（以官方下载目录实际列表为准）：

curl -fsSL https://dlcdn.apache.org/jspwiki/ | grep -oE 'href="[0-9.]+/"' | sort -u

实测输出（撰写本文时）：

href="2.12.5/"
href="3.0.0/"

四、部署方案 A：APT 安装 JDK 与 Tomcat 9 + 官方 WAR 部署（推荐）

4.1 更新软件源并安装基础工具

apt-get update
apt-get install -y curl

4.2 安装 OpenJDK 17 与 Tomcat 9

apt-get install -y openjdk-17-jdk-headless tomcat9

安装完成后确认版本：

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)

/usr/share/tomcat9/bin/version.sh | grep -E "Server version|JVM Version"

实测输出：

Server version: Apache Tomcat/9.0.58 (Ubuntu)
JVM Version:    17.0.20.1+1-1-22.04-Ubuntu

dpkg -l | grep -E "openjdk-17-jdk-headless|tomcat9 "

实测输出：

ii  openjdk-17-jdk-headless:amd64 17.0.20.1+1-1~22.04                     amd64        OpenJDK Development Kit (JDK) (headless)
ii  tomcat9                       9.0.58-1ubuntu0.2                       all          Apache Tomcat 9 - Servlet and JSP engine

💡 APT 安装的 Tomcat 9 自带 systemd 单元 /lib/systemd/system/tomcat9.service，运行用户为 tomcat（uid/gid 999），目录布局为 Debian 风格：配置在 /etc/tomcat9/，应用在 /var/lib/tomcat9/webapps/，日志在 /var/log/tomcat9/。

4.3 配置 JVM 堆内存（256–512MB）

编辑 /etc/default/tomcat9，将 JAVA_OPTS 修改为如下（限制堆上限为 512MB，初始 256MB）：

sed -i 's|^JAVA_OPTS=.*|JAVA_OPTS="-Djava.awt.headless=true -Xms256m -Xmx512m"|' /etc/default/tomcat9
grep "^JAVA_OPTS" /etc/default/tomcat9

实测输出：

JAVA_OPTS="-Djava.awt.headless=true -Xms256m -Xmx512m"

💡 systemd 方式启动 Tomcat 时会加载 /etc/default/tomcat9 中的 JAVA_OPTS（启动脚本 /usr/libexec/tomcat9/tomcat-start.sh 中有 . /etc/default/tomcat9）。修改后重启 tomcat9 服务生效，验证方法见 4.10。

4.4 创建 JSPWiki 数据目录与首次启动前置目录

创建页面存储与工作目录，并赋予 tomcat 用户属主：

mkdir -p /var/lib/jspwiki/pages /var/lib/jspwiki/work
chown -R tomcat:tomcat /var/lib/jspwiki

再创建 tomcat 用户的家目录 /var/lib/tomcat（该目录默认不在磁盘上创建，但必须存在，原因见下方说明与 FAQ）：

mkdir -p /var/lib/tomcat
chown tomcat:tomcat /var/lib/tomcat

⚠️ JSPWiki 2.12.5 的内置默认页面目录为 ${user.home}/jspwiki-files，而 tomcat 用户家目录为 /var/lib/tomcat（可用 getent passwd tomcat 确认）。若该目录不存在，JSPWiki 引擎首次初始化会因无法创建默认页面目录而启动失败，访问 http://<服务器IP>:8080/JSPWiki/ 将得到 404，详见 FAQ 问题 1。

4.5 下载 JSPWiki 2.12.5 WAR 包并校验

cd /tmp
curl -fsSLO https://dlcdn.apache.org/jspwiki/2.12.5/binaries/webapp/JSPWiki.war
curl -fsSLO https://dlcdn.apache.org/jspwiki/2.12.5/binaries/webapp/JSPWiki.war.sha512

官方 .sha512 文件只包含裸哈希值（无文件名），用 cat 查看：

cat JSPWiki.war.sha512

实测输出：

b9436587cca6a29c1e2fb56496d304f977e22c51f1e391bf83724b7ff106e149f55573cfba93fe2e03773f052d206f85ebf6e0cac7fabccce2ed29de13548d4f

手动比对本地文件哈希：

sha512sum JSPWiki.war

实测输出：

b9436587cca6a29c1e2fb56496d304f977e22c51f1e391bf83724b7ff106e149f55573cfba93fe2e03773f052d206f85ebf6e0cac7fabccce2ed29de13548d4f  JSPWiki.war

ls -l /tmp/JSPWiki.war

实测输出：

-rw-r--r-- 1 root root 36752001 Oct 11 12:49 /tmp/JSPWiki.war

两个哈希值一致即校验通过。

4.6 部署 WAR 包

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

实测输出：

total 35896
-rw-r--r-- 1 tomcat tomcat 36752001 Oct 11 12:49 JSPWiki.war
drwxr-xr-x 3 root   root       4096 Oct 11 12:31 ROOT

4.7 配置 systemd 写路径白名单并启动 Tomcat

Ubuntu 的 tomcat9.service 使用 ProtectSystem=strict 加固，仅允许写入 /etc/tomcat9/Catalina/、/var/lib/tomcat9/webapps/、/var/log/tomcat9/ 三个目录。JSPWiki 的数据目录 /var/lib/jspwiki/ 不在白名单内，必须通过 systemd drop-in 追加放行，否则启动后访问 404（日志报 No permission to write to work directory，见 FAQ 问题 2）：

mkdir -p /etc/systemd/system/tomcat9.service.d
cat > /etc/systemd/system/tomcat9.service.d/jspwiki.conf <<'EOF'
[Service]
ReadWritePaths=/var/lib/jspwiki/
EOF
cat /etc/systemd/system/tomcat9.service.d/jspwiki.conf

实测输出：

[Service]
ReadWritePaths=/var/lib/jspwiki/

重载 systemd 并启动服务：

systemctl daemon-reload
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

💡 APT 安装时已自动 enable tomcat9（开机自启）。若 is-enabled 结果不是 enabled，执行 systemctl enable tomcat9 即可。

4.8 打开初始化安装向导并完成配置

首次部署后用浏览器访问：

http://<服务器IP>:8080/JSPWiki/Install.jsp

向导表单共 3 个配置项，按下表填写（本文实测值）：

表单项	表单 name	本文填写值	说明
Application Name	`jspwiki.applicationName`	`MyWiki`	Wiki 站点名称，页面标题会显示
Page storage directory	`jspwiki.fileSystemProvider.pageDir`	`/var/lib/jspwiki/pages`	页面（含附件）存储目录，即 4.4 创建的目录
Working directory	`jspwiki.workDir`	`/var/lib/jspwiki/work`	搜索索引、引用缓存等工作文件目录

点击 Configure! 提交后，向导页面会显示配置结果，实测关键回显如下：

Good news:
Your new properties have been saved to /var/lib/tomcat9/work/Catalina/localhost/JSPWiki/jspwiki-custom.properties. Copy this file to a directory that is on the classpath of your servlet engine (e.g. the WEB-INF/classes directory of your web application), and delete or rename the old file.
Because no administrator account exists yet, JSPWiki created one for you, with a random password. You can change this password later, of course. The account's id is admin and the password is sQGCntQE. Please write this information down and keep it in a safe place. JSPWiki also created a wiki group called Admin that contains this user.

按提示把生成的配置文件复制到 Web 应用的 WEB-INF/classes/ 目录（JSPWiki 会从 classpath 读取 jspwiki-custom.properties）：

cp /var/lib/tomcat9/work/Catalina/localhost/JSPWiki/jspwiki-custom.properties \
   /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties
chown tomcat:tomcat /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties
cat /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties

实测输出（向导实际写入的内容）：

#Sun Oct 11 13:02:36 GMT 2026
jspwiki.applicationName=MyWiki
jspwiki.workDir=/var/lib/jspwiki/work
jspwiki.fileSystemProvider.pageDir=/var/lib/jspwiki/pages
jspwiki.basicAttachmentProvider.storageDir=/var/lib/jspwiki/pages
jspwiki.pageProvider=VersioningFileProvider

⚠️ jspwiki.pageProvider=VersioningFileProvider 是向导默认写入的页面提供者，带版本历史（旧版本存于 pages/OLD/<页面名>/）。

⚠️ 向导同时会把 admin 账号写入 WEB-INF/userdatabase.xml（随机密码），把 Admin 组写入 WEB-INF/groupdatabase.xml。

重启 Tomcat 使配置生效：

systemctl restart tomcat9

4.9 设置管理员密码

向导生成的 admin 密码是随机的（如上文实测为 sQGCntQE），登录后立即改为固定口令（本文统一使用 q1w2e3r4，生产环境请使用强密码）：

访问 http://<服务器IP>:8080/JSPWiki/Login.jsp，输入账号 admin 与向导给出的随机密码登录。
访问 http://<服务器IP>:8080/JSPWiki/UserPreferences.jsp?tab=profile。
在 Profile 表单中填写：Login name 保持 admin，Current Password 填随机密码，New Password 与 Password verify 填 q1w2e3r4，补充 E-mail 后点击 Update your wiki profile.。

保存成功后用新密码退出重登即可确认生效。

4.10 功能验证

（1）首页可访问

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

实测输出：

（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

（3）创建页面：浏览器访问 http://<服务器IP>:8080/JSPWiki/Edit.jsp?page=InstallNotes，输入内容后点击 Save。保存成功后确认磁盘落盘：

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

实测输出：

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

再次编辑该页并保存后，OLD/ 下会保留历史版本（1.txt 为第一版），page.properties 记录每版作者与变更说明：

cat /var/lib/jspwiki/pages/OLD/InstallNotes/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

（4）搜索验证

curl -s "http://localhost:8080/JSPWiki/Search.jsp?query=InstallNotes" | grep -c "InstallNotes"

实测输出：

搜索结果页能命中刚创建的 InstallNotes 页面，全文搜索正常。

五、部署方案 B：命令行自动化初始化（免浏览器）

方案 A 的向导步骤可用 curl 完全自动化，适合批量部署或无图形终端的环境。以下命令与方案 A 的向导完全等价（CSRF Token 从页面动态提取，随取随用）：

（1）提交安装向导（用户名/密码等信息与 4.8 表格一致，admin 账号由此创建）：

rm -f /tmp/w.jar
TOKEN=$(curl -s -c /tmp/w.jar http://localhost:8080/JSPWiki/Install.jsp | grep -oE "X-XSRF-TOKEN\" id=\"X-XSRF-TOKEN\" value=\"[a-f0-9-]+" | grep -oE "[a-f0-9-]{20,}" | head -1)
curl -s -b /tmp/w.jar -X POST http://localhost:8080/JSPWiki/Install.jsp \
  --data-urlencode "X-XSRF-TOKEN=$TOKEN" \
  --data-urlencode "jspwiki.applicationName=MyWiki" \
  --data-urlencode "jspwiki.fileSystemProvider.pageDir=/var/lib/jspwiki/pages" \
  --data-urlencode "jspwiki.workDir=/var/lib/jspwiki/work" \
  --data-urlencode "submit=Configure!" -o /tmp/wiz.html
grep -oE "account's id is admin and the password is [A-Za-z0-9]+" /tmp/wiz.html

实测输出（随机密码每次不同，务必记录）：

account's id is admin and the password is sQGCntQE

（2）配置文件归位（同方案 A 4.8）：

cp /var/lib/tomcat9/work/Catalina/localhost/JSPWiki/jspwiki-custom.properties \
   /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties
chown tomcat:tomcat /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties
systemctl restart tomcat9

（3）登录并修改 admin 密码为 q1w2e3r4（把命令中的 sQGCntQE 替换为上一步记录的随机密码）：

rm -f /tmp/a.jar
TOKEN=$(curl -s -c /tmp/a.jar http://localhost:8080/JSPWiki/Login.jsp | grep -oE "X-XSRF-TOKEN\" id=\"X-XSRF-TOKEN\" value=\"[a-f0-9-]+" | grep -oE "[a-f0-9-]{20,}" | head -1)
curl -s -b /tmp/a.jar -c /tmp/a.jar -X POST "http://localhost:8080/JSPWiki/Login.jsp?redirect=Main" \
  --data-urlencode "X-XSRF-TOKEN=$TOKEN" \
  --data-urlencode "j_username=admin" \
  --data-urlencode "j_password=sQGCntQE" \
  --data-urlencode "redirect=Main" \
  --data-urlencode "submitlogin=Login" -o /dev/null -w "login: %{http_code}\n"

实测输出：

login: 302

curl -s -b /tmp/a.jar "http://localhost:8080/JSPWiki/UserPreferences.jsp?tab=profile" -o /tmp/prefs.html
TOKEN=$(grep -A3 'id="editProfile"' /tmp/prefs.html | grep -oE "X-XSRF-TOKEN\" id=\"X-XSRF-TOKEN\" value=\"[a-f0-9-]+" | grep -oE "[a-f0-9-]{20,}" | head -1)
curl -s -b /tmp/a.jar -X POST "http://localhost:8080/JSPWiki/UserPreferences.jsp?tab=profile" \
  --data-urlencode "redirect=" \
  --data-urlencode "X-XSRF-TOKEN=$TOKEN" \
  --data-urlencode "loginname=admin" \
  --data-urlencode "password0=sQGCntQE" \
  --data-urlencode "password=q1w2e3r4" \
  --data-urlencode "password2=q1w2e3r4" \
  --data-urlencode "fullname=Administrator" \
  --data-urlencode "email=admin@example.org" \
  --data-urlencode "action=saveProfile" -o /dev/null -w "saveProfile: %{http_code}\n"

实测输出：

saveProfile: 302

⚠️ 表单字段 loginname、password0（当前密码）必须携带，缺项会被服务端拒绝并提示 Login name cannot be blank。提交后可用 grep -o "<user[^>]*>" /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/userdatabase.xml 查看 lastModified 是否更新来确认保存成功。

六、方案对比与选择建议

维度	方案 A（浏览器向导）	方案 B（curl 自动化）
版本来源	官方 WAR（dlcdn.apache.org）	官方 WAR（dlcdn.apache.org）
是否需联网	需（下载 WAR）	需（下载 WAR）
初始化方式	浏览器填写 3 项表单	curl 提交同一表单
systemd 来源	APT 包自带 tomcat9.service	同左
优点	直观、官方流程	可脚本化、适合批量/无浏览器环境
缺点	不易自动化	需处理 CSRF Token 提取

选择建议：单台/首次部署用方案 A；批量部署、CI 初始化或只能 SSH 的环境用方案 B。两者最终配置完全一致。

七、systemd 开机自启配置

APT 安装的 Tomcat 9 自带单元文件 /lib/systemd/system/tomcat9.service（WantedBy=multi-user.target），安装后已自动 enabled，无需手工编写单元。与本方案相关的两个要点：

（1）JVM 参数入口：单元通过 /usr/libexec/tomcat9/tomcat-start.sh 启动，该脚本会 . /etc/default/tomcat9 加载 JAVA_OPTS（本文已在 4.3 设置 -Xms256m -Xmx512m）。

（2）写路径白名单：单元默认 ProtectSystem=strict，本文已通过 drop-in /etc/systemd/system/tomcat9.service.d/jspwiki.conf 放行 /var/lib/jspwiki/（见 4.7）。如日后把页面目录迁移到其他路径（如 /opt/data/jspwiki），需同步在该 drop-in 中追加对应 ReadWritePaths= 一行。

开机自启确认：

systemctl is-enabled tomcat9

实测输出：

enabled

八、配置说明

（1）配置文件体系：JSPWiki 2.12.5 不再使用单一大而全的 jspwiki.properties，而是"内置默认值（jar 内 /ini/jspwiki.properties，164 个键）+ 覆盖文件 jspwiki-custom.properties"两层结构。覆盖文件的位置按优先级：

优先级	来源	说明
1	JVM 系统属性 `jspwiki.custom.config=<绝对路径>`	指向任意绝对路径的覆盖文件
2	classpath 下的 `/jspwiki-custom.properties`	即 `WEB-INF/classes/jspwiki-custom.properties`（本文 4.8 位置）
3	环境变量 / 系统属性中 `jspwiki` 开头的键（`_` 转为 `.`）	如环境变量 `JSPWIKI_ENCODING=UTF-8` 等价于 `jspwiki.encoding=UTF-8`

完整的参数分类详解见《Apache JSPWiki 2.12.5 配置参数详解》。

（2）调整监听端口：编辑 /etc/tomcat9/server.xml 中的 HTTP 连接器（默认 8080）：

69:    <Connector port="8080" protocol="HTTP/1.1"

修改后 systemctl restart tomcat9 生效。

（3）日志位置：默认 JSPWiki 日志走 Tomcat 控制台，即 /var/log/tomcat9/catalina.out；独立日志文件 /var/log/tomcat9/jspwiki.log 默认不落盘，开启方法见《Apache JSPWiki 2.12.5 常用 CLI 命令与工具详解》"日志排查"一节。

（4）数据目录迁移：如需将页面目录从 /var/lib/jspwiki/pages 迁走，修改 WEB-INF/classes/jspwiki-custom.properties 中的 jspwiki.fileSystemProvider.pageDir，同步更新 4.7 drop-in 的 ReadWritePaths，再把旧目录内容整体 cp -a 到新路径并 chown -R tomcat:tomcat，重启服务即可。

九、注意事项

升级到同一版本线的更新版（如 2.12.x 下一版）时，用新 WAR 覆盖 /var/lib/tomcat9/webapps/JSPWiki.war 并重启即可；/var/lib/jspwiki（页面）与 WEB-INF/classes/jspwiki-custom.properties（配置）、WEB-INF/userdatabase.xml（用户）均保留。重大跨版本升级（2.12 → 3.0）涉及 jakarta 命名空间与更换 Servlet 服务器，需另行评估。
WEB-INF/userdatabase.xml 与 groupdatabase.xml 是用户/组数据库（XMLUserDatabase 默认位置在 war 解压目录内），备份时必须一并纳入。
Tomcat 9 的 Debian 包禁用了 shutdown 端口（/etc/tomcat9/server.xml 中 <Server port="-1">），catalina.sh stop 无效（输出 SEVERE: No shutdown port configured），停服一律使用 systemctl stop tomcat9。
直接编辑 pages/ 下的 .txt 文件即可修改页面内容（立即生效，JSPWiki 实时读盘），但注意保持 UTF-8 编码；OLD/ 下的历史版本不要手工改动。
生产环境建议：管理员密码改强口令、jspwiki.baseURL 显式设置为对外访问地址、限制 8080 仅内网可达或前置 Nginx 反代加 HTTPS。

十、常见问题（FAQ）

Q1：首次访问 http://<IP>:8080/JSPWiki/ 返回 404，/var/log/tomcat9/catalina.out 报 Failed to create page directory /var/lib/tomcat/jspwiki-files？

A：JSPWiki 2.12.5 内置默认页面目录是 ${user.home}/jspwiki-files，tomcat 用户家目录为 /var/lib/tomcat，而该目录默认未创建且 tomcat 用户无权在 /var/lib 下新建目录，导致引擎初始化失败、整个 Web 应用不可用。修复：

mkdir -p /var/lib/tomcat
chown tomcat:tomcat /var/lib/tomcat
systemctl restart tomcat9

（本文 4.4 步骤已包含该修复；也可在首次启动前就按 4.8 方式预置 jspwiki-custom.properties，跳过默认目录探测。）

Q2：systemd 方式启动后访问 404，日志报 No permission to write to work directory: /var/lib/jspwiki/work？

A：tomcat9.service 的 ProtectSystem=strict 只放行 /etc/tomcat9/Catalina/、/var/lib/tomcat9/webapps/、/var/log/tomcat9/，JSPWiki 数据目录被拒绝写入。按 4.7 添加 drop-in ReadWritePaths=/var/lib/jspwiki/ 后执行 systemctl daemon-reload && systemctl restart tomcat9 即可。

实测修复前日志（journalctl -u tomcat9 摘录）：

[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

修复后：

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

active
200

Q3：向导提交后页面提示属性文件已保存，重启后配置没生效？

A：向导把 jspwiki-custom.properties 写到工作目录（如 /var/lib/tomcat9/work/Catalina/localhost/JSPWiki/），该路径不在 classpath 中，重启后不会被读取。必须按 4.8 把文件复制到 /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/ 下。确认方法：重启后查看 /var/log/tomcat9/catalina.out，出现 jspwiki.workDir is already set to: /var/lib/jspwiki/work 即说明覆盖文件已加载。

Q4：admin 随机密码丢了怎么办？

A：删除 WEB-INF/userdatabase.xml 中的 <user ... loginName="admin" ... /> 条目并重启 Tomcat，再访问 Install.jsp 重新提交向导即可重建 admin（会再次生成随机密码）。注意 WEB-INF/groupdatabase.xml 中 Admin 组成员引用的是全名 Administrator，重建后自动恢复关联。

Q5：访问搜索/编辑时报 SessionExpired 或被重定向到 Forbidden？

A：两类防护导致：① 编辑保存表单必须携带页面里的隐藏反垃圾字段（形如 name='hlajwk' value='...'，字段名每 24 小时轮换）与 X-XSRF-TOKEN；② X-XSRF-TOKEN 校验失败会重定向到 /error/Forbidden.html。用浏览器正常操作不会遇到；做自动化时务必从当次 GET 的页面 HTML 中提取这两个值再提交（见方案 B）。

Q6：内存不足，Tomcat 频繁 Full GC？

A：本方案堆已限制在 256–512MB。用 jps -v 确认实际生效值（见 4.10），如需调整，改 /etc/default/tomcat9 的 JAVA_OPTS 后重启；同时可用 systemctl status tomcat9 观察 Memory: 一行的实际占用（实测约 290MB）。

十一、卸载方式

systemctl stop tomcat9
systemctl disable tomcat9
rm -f /etc/systemd/system/tomcat9.service.d/jspwiki.conf
systemctl daemon-reload
apt-get purge -y tomcat9 tomcat9-common
apt-get autoremove -y
rm -rf /var/lib/jspwiki /var/lib/tomcat /etc/tomcat9 /var/log/tomcat9 /var/lib/tomcat9 /var/cache/tomcat9 /usr/share/tomcat9
rm -f /root/jspwiki-backup-*.tar.gz

如需一并卸载 JDK：

apt-get purge -y openjdk-17-jdk-headless
apt-get autoremove -y

十二、参考链接

Apache JSPWiki 官网：https://jspwiki.apache.org/
JSPWiki 2.12.5 发行包：https://dlcdn.apache.org/jspwiki/2.12.5/binaries/webapp/
JSPWiki 官方 Wiki（文档/FAQ）：https://jspwiki-wiki.apache.org/
Tomcat 9 文档：https://tomcat.apache.org/tomcat-9.0-doc/index.html
Apache 归档（历史版本）：https://archive.apache.org/dist/jspwiki/