Apache JSPWiki 2.12.5 配置参数详解

适用版本：Apache JSPWiki 2.12.5（Tomcat 9 + JDK 17 实测环境）。本文参数默认值全部提取自发行包 jspwiki-main-2.12.5.jar 内置的 /ini/jspwiki.properties（共 164 个键），关键参数均在实测环境验证过生效方式。

一、环境信息

操作系统：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）
关键路径：
- 内置默认值：/var/lib/tomcat9/webapps/JSPWiki/WEB-INF/lib/jspwiki-main-2.12.5.jar 内 /ini/jspwiki.properties
- 覆盖文件：/var/lib/tomcat9/webapps/JSPWiki/WEB-INF/classes/jspwiki-custom.properties（安装向导生成）
- 页面数据：/var/lib/jspwiki/pages/
- 引擎日志：/var/log/tomcat9/catalina.out
参数采集方法：jar xf 解包 jar 内 /ini/jspwiki.properties（164 键），关键键均在实测环境验证生效方式

二、配置体系与加载机制

2.1 两层配置结构

JSPWiki 2.12.5 不再要求单一大而全的 jspwiki.properties，而是"内置默认值 + 覆盖文件"两层结构：

内置默认值：jspwiki-main-2.12.5.jar 内 /ini/jspwiki.properties，164 个键，覆盖所有可配置项；
覆盖文件：jspwiki-custom.properties，只需写要覆盖的键。安装向导（Install.jsp）生成的就是这个文件。

提取内置默认值的方法（实测）：

cd /tmp && jar xf /var/lib/tomcat9/webapps/JSPWiki/WEB-INF/lib/jspwiki-main-2.12.5.jar ini/
grep -cE '^[a-z]' ini/jspwiki.properties

实测输出：

2.2 加载顺序与优先级

依据 PropertyReader.loadWebAppProps() 源码（jspwiki-util 2.12.5），配置按以下顺序叠加，后者覆盖前者：

顺序	来源	说明
1	jar 内 `/ini/jspwiki.properties`	内置默认值，不可改
2	环境变量中 `jspwiki` 开头的键（键名 `_` 转 `.`、大小写保留）	实测：`jspwiki_applicationName=EnvLowerWiki` 生效；`JSPWIKI_APPLICATIONNAME=EnvUpperWiki` 大写形式不生效
3	覆盖文件	优先用 Servlet 上下文参数 `jspwiki.custom.config` 指定的路径；未指定时找 classpath 下的 `/jspwiki-custom.properties`（即 `WEB-INF/classes/jspwiki-custom.properties`）
4	级联文件	web.xml 中 `jspwiki.custom.cascade.1..N` 指定的多级覆盖文件（按序覆盖）
5	JVM 系统属性中 `jspwiki` 开头的键	`-Djspwiki.encoding=UTF-8`（下划线转点），最终优先级最高

💡 实践建议：静态配置写覆盖文件；仅环境注入类需求（部署平台/编排工具传参）用环境变量或系统属性。

2.3 变量展开

覆盖文件支持两种变量语法：

${TOMCAT_HOME} 风格：按系统属性/环境变量展开；
var.变量名=值 声明 + ${变量名} 引用：文件内自定义变量，如声明 var.tomcatHome=/opt/apache-tomcat-9.0.58 后即可在其他键的值中写 ${tomcatHome}（jspwiki.custom.config 指定的文件中同样有效；机制见 jspwiki-util PropertyReader.PARAM_VAR_DECLARATION）。

2.4 验证配置生效

启动/访问后查看引擎日志（默认输出到 Tomcat 控制台，APT 部署即 /var/log/tomcat9/catalina.out）：

grep -E "workDir|pageDir" /var/log/tomcat9/catalina.out | tail -2

实测输出：

[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

is already set to 出现即说明覆盖文件中的 workDir 已被引擎读取。

三、基础与路径参数

参数键	内置默认值	说明
`jspwiki.applicationName`	`JSPWiki`	站点名称，显示在页面标题与邮件通知中。实测向导写入 `MyWiki`
`jspwiki.baseURL`	无（未内置）	对外访问根地址，如 `https://wiki.example.org/JSPWiki/`。不设置时邮件通知、RSS、引用链接会以请求地址拼接，生产必须设置
`jspwiki.encoding`	`UTF-8`	页面内容编码，生产保持 UTF-8，不要改动
`jspwiki.workDir`	未内置（默认取 `java.io.tmpdir` 下的引擎工作目录）	搜索索引、引用缓存、向导临时文件目录。生产显式指定，如 `/var/lib/jspwiki/work`
`jspwiki.pageProvider`	`FileSystemProvider`	页面存储提供者，详见第三章
`jspwiki.fileSystemProvider.pageDir`	`${user.home}/jspwiki-files`	页面存储目录。实测 tomcat 用户家目录为 `/var/lib/tomcat`，若目录不存在引擎初始化直接失败，生产必须显式指定
`jspwiki.basicAttachmentProvider.storageDir`	未内置（跟随 pageDir）	附件存储目录，BasicAttachmentProvider 使用，通常与 pageDir 一致
`jspwiki.templateDir`	`templates`（应用内路径）	界面模板目录，一般不改

实测生效后的目录结构（VersioningFileProvider + 附件同目录）：

/var/lib/jspwiki/pages/InstallNotes.txt            # 当前版本
/var/lib/jspwiki/pages/OLD/InstallNotes/1.txt      # 历史版本
/var/lib/jspwiki/pages/OLD/InstallNotes/page.properties  # 版本元数据

四、页面与附件存储参数

4.1 页面提供者选型（jspwiki.pageProvider）

提供者	版本历史	说明
`FileSystemProvider`	无	单文件 `pages/<页面名>.txt`，最简单
`VersioningFileProvider`	有（文件式）	当前版本在 `pages/`，历史版本在 `pages/OLD/<页面名>/N.txt` + `page.properties`。安装向导默认写入项，推荐
`RCSFileProvider`	有（RCS）	依赖 rcs 工具，基本不再使用

4.2 版本元数据（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.3 附件参数

参数键	内置默认值	说明
`jspwiki.attachment.provider`	`BasicAttachmentProvider`	附件提供者，附件落盘在 storageDir
`jspwiki.attachment.forceDownload`	`.html .htm .js .pdf .svg .xml`	强制下载而非内联展示的扩展名（防 XSS）

五、安全与用户管理参数

5.1 认证

参数键	内置默认值	说明
`jspwiki.loginModule.class`	`org.apache.wiki.auth.login.UserDatabaseLoginModule`	JAAS 登录模块，配合 XMLUserDatabase
`jspwiki.login.throttling`	`true`	登录失败节流（同账号连续失败后延迟响应），生产保持开启

5.2 用户库与组库

参数键	内置默认值	说明
`jspwiki.userdatabase`	`org.apache.wiki.auth.user.XMLUserDatabase`	用户库实现；另有 JDBCUserDatabase
`jspwiki.groupdatabase`	`org.apache.wiki.auth.authorize.XMLGroupDatabase`	组库实现
`jspwiki.xmlUserDatabaseFile`	未内置（默认 WAR 内 `WEB-INF/userdatabase.xml`）	XML 用户库路径，生产建议外置到持久化目录
`jspwiki.xmlGroupDatabaseFile`	未内置（默认 `WEB-INF/groupdatabase.xml`）	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="" >

密码为加盐 SHA-256 哈希（{SHA-256}Base64 格式），不能反推明文；手工维护时通过 Web 界面改密，不要手写哈希。

5.3 授权

参数键	内置默认值	说明
`jspwiki.authorizer`	`org.apache.wiki.auth.authorize.WebContainerAuthorizer`	授权者实现（按 Web 应用部署描述符中的安全角色判断），另有 ACLAuthorizer 等
`jspwiki.aclManager`	`org.apache.wiki.auth.acl.DefaultAclManager`	页面级 ACL 管理
`jspwiki.securityProvider`	未内置	安全提供者，一般不用改

5.4 JDBC 用户库键族

改用 JDBCUserDatabase 时配置表结构与列名映射（内置默认值）：

jspwiki.userdatabase.datasource=jdbc/UserDatabase
jspwiki.userdatabase.table=users
jspwiki.userdatabase.uid=uid
jspwiki.userdatabase.email=email
jspwiki.userdatabase.fullName=full_name
jspwiki.userdatabase.loginName=login_name
jspwiki.userdatabase.password=password
jspwiki.userdatabase.wikiName=wiki_name
jspwiki.userdatabase.created=created
jspwiki.userdatabase.modified=modified
jspwiki.userdatabase.lockExpiry=lock_expiry
jspwiki.userdatabase.roleTable=roles
jspwiki.userdatabase.role=role

组库同理（jspwiki.groupdatabase.*：datasource/table/membertable/creator/name/member/modifier 等）。

六、搜索与渲染参数

6.1 搜索

参数键	内置默认值	说明
`jspwiki.searchProvider`	`LuceneSearchProvider`	搜索实现。Lucene 索引存于 workDir，页面变更增量更新

实测索引复用日志（重启后不重建索引）：

[INFO ] 2026-10-11 13:10:47.029 [JSPWiki Lucene Indexer] o.a.w.s.LuceneSearchProvider - Files found in Lucene directory, not reindexing.

6.2 渲染与标记

参数键	内置默认值	说明
`jspwiki.renderingManager.markupParser`	`org.apache.wiki.parser.JSPWikiMarkupParser`	标记解析器
`jspwiki.renderingManager.renderer`	`org.apache.wiki.render.XHTMLRenderer`	输出渲染器
`jspwiki.renderingManager.renderer.wysiwyg`	`org.apache.wiki.render.WysiwygEditingRenderer`	可视化编辑渲染器
`jspwiki.translatorReader.allowHTML`	`false`	是否允许页面内嵌原始 HTML，生产保持 false（防 XSS）
`jspwiki.translatorReader.camelCaseLinks`	`false`	CamelCase 自动成链
`jspwiki.translatorReader.matchEnglishPlurals`	`true`	链接匹配忽略英文复数
`jspwiki.translatorReader.useOutlinkImage`	`true`	外链显示外链图标
`jspwiki.breakTitleWithSpaces`	`false`	页面名驼峰处插空格显示
`jspwiki.lockExpiryTime`	`60`	编辑锁定超时（分钟）
`jspwiki.diffProvider`	`TraditionalDiffProvider`	版本差异算法
`jspwiki.refManager`	`org.apache.wiki.references.DefaultReferenceManager`	引用关系管理

七、扩展与集成参数

7.1 特殊页面映射（jspwiki.specialPage.*）

内置 11 条，把 Wiki 名字空间保留字映射到 JSP：

jspwiki.specialPage.CreateGroup = NewGroup.jsp
jspwiki.specialPage.Search = Search.jsp
jspwiki.specialPage.Login = Login.jsp
jspwiki.specialPage.NewGroup = NewGroup.jsp
jspwiki.specialPage.UserPreferences = UserPreferences.jsp
jspwiki.specialPage.Workflow = Workflow.jsp
jspwiki.specialPage.Logout = Logout.jsp
jspwiki.specialPage.CreateProfile = Login.jsp
jspwiki.specialPage.EditProfile = UserPreferences.jsp
jspwiki.specialPage.Preferences = UserPreferences.jsp
jspwiki.specialPage.FindPage = FindPage.jsp

7.2 InterWiki 链接（jspwiki.interWikiRef.*）

内置定义：JSPWiki、Edit、Raw、Reader、Group、RSS、WikiWikiWeb、TWiki、MeatballWiki、Wikipedia、Google、Location、Doc、JIRA。示例：

jspwiki.interWikiRef.JSPWiki = http://jspwiki-wiki.apache.org/Wiki.jsp?page=%s
jspwiki.interWikiRef.JIRA = https://issues.apache.org/jira/browse/JSPWIKI-%s

7.3 插件与 RSS、邮件

参数键	内置默认值	说明
`jspwiki.plugin.searchPath`	空	插件类额外搜索路径
`jspwiki.plugin.externalJars`	空	外部插件 jar 目录
`jspwiki.rss.generate`	`false`	是否生成 RSS feed
`jspwiki.rss.fileName`	`rss.rdf`	RSS 文件名（生成于 workDir）
`jspwiki.rss.interval`	`3600`	RSS 刷新间隔（秒）
`jspwiki.rss.channelDescription`	内置英文默认	频道描述
`jspwiki.rss.channelLanguage`	`en-us`	频道语言
`mail.from`	`JSPWiki <JSPWiki@localhost>`	站点发件地址（改密/通知邮件）
`mail.smtp.host`	`127.0.0.1`	SMTP 服务器
`mail.smtp.port`	`25`	SMTP 端口

7.4 缓存与界面偏好

参数键	内置默认值	说明
`jspwiki.cache.enable`	`true`	页面/附件缓存开关
`jspwiki.cache.custom-config-file`	`jspwiki-ehcache.xml`	Ehcache 自定义配置（classpath 下）
`jspwiki.defaultprefs.template.editor`	`plain`	新用户默认编辑器（plain/visualeditor）
`jspwiki.defaultprefs.template.skinname`	`PlainVanilla`	默认皮肤
`jspwiki.defaultprefs.template.layout`	`fluid`	布局
`jspwiki.defaultprefs.template.sectionediting`	`true`	段落编辑
`jspwiki.defaultprefs.template.livepreview`	`true`	实时预览

另有 jspwiki.defaultprefs.timeformat.01..37 定义用户可选时间格式列表，一般不改。

八、日志参数

8.1 内置 log4j2 属性段

JSPWiki 2.12.5 的日志配置也内置于 /ini/jspwiki.properties（log4j2 properties 风格），默认值要点：

jspwiki.use.external.logconfig = false
status = warn
name = jspwiki-log4j2-configuration

appender.console.type = Console
appender.console.name = STDOUT
appender.console.layout.type = PatternLayout
appender.console.layout.pattern = %highlight{[%-5level]} %d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %c{1.} - %msg%n %ex

appender.rolling.name = RollingFile
appender.rolling.type = RollingFile
appender.rolling.fileName = ${sys:java.io.tmpdir}/jspwiki.log
appender.rolling.filePattern = ${sys:java.io.tmpdir}/jspwiki-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
appender.rolling.append = true
appender.rolling.createOnDemand = true
appender.rolling.layout.type = PatternLayout
appender.rolling.layout.pattern = [%-5level] %d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %p %c{1.} %x - %msg%n %ex
appender.rolling.policies.type = Policies
appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
appender.rolling.policies.time.interval = 1
appender.rolling.policies.time.modulate = true
appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
appender.rolling.policies.size.size=10MB
appender.rolling.strategy.type = DefaultRolloverStrategy
appender.rolling.strategy.max = 14

logger.jspwiki.name = org.apache.wiki
logger.jspwiki.level = info
logger.jspwiki.additivity = false
logger.jspwiki.appenderRef.stdout.ref = STDOUT

rootLogger.level = warn
rootLogger.appenderRef.stdout.ref = STDOUT

解读：

logger.jspwiki（org.apache.wiki，info 级）只挂了 STDOUT——所以默认日志进 Tomcat 控制台（catalina.out）；
RollingFile appender 虽然定义了（10MB × 14 份轮转），但没有被任何 logger 引用，默认不产生文件；
${sys:java.io.tmpdir} 未解析时启动日志会出现一条 WARN，属正常现象。

8.2 启用独立文件日志（实测配方）

在覆盖文件（如 WEB-INF/classes/jspwiki-custom.properties）追加三行：

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

⚠️ 路径必须写死绝对路径，不能用 ${sys:...}（JSPWiki 对属性值做预处理时不解析 log4j2 的 lookup）；文件所在目录须对运行用户（tomcat）可写，否则改用 /var/lib/jspwiki/jspwiki.log 类数据目录路径。

九、生产环境配置模板

将以下内容作为 WEB-INF/classes/jspwiki-custom.properties（或经 jspwiki.custom.config 指定），逐项按需修改：

# ===== 站点 =====
jspwiki.applicationName=MyWiki
jspwiki.baseURL=https://wiki.example.org/JSPWiki/
jspwiki.encoding=UTF-8

# ===== 存储路径 =====
jspwiki.pageProvider=VersioningFileProvider
jspwiki.fileSystemProvider.pageDir=/var/lib/jspwiki/pages
jspwiki.basicAttachmentProvider.storageDir=/var/lib/jspwiki/pages
jspwiki.workDir=/var/lib/jspwiki/work

# ===== 用户/组库外置（随数据目录备份） =====
jspwiki.xmlUserDatabaseFile=/var/lib/jspwiki/userdatabase.xml
jspwiki.xmlGroupDatabaseFile=/var/lib/jspwiki/groupdatabase.xml

# ===== 安全 =====
jspwiki.login.throttling=true
jspwiki.translatorReader.allowHTML=false

# ===== 邮件通知（按需） =====
mail.from=wiki-noreply@example.org
mail.smtp.host=smtp.example.org
mail.smtp.port=25

# ===== 文件日志（按需） =====
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

应用步骤：写入文件 → systemctl restart tomcat9 → grep "workDir" /var/log/tomcat9/catalina.out | tail -1 确认加载（出现 is already set to 即生效）。

十、常见问题（FAQ）

Q1：修改参数后不生效？

按优先级排查：① 是否改在正确的覆盖文件（classpath 下或 jspwiki.custom.config 指向的文件）；② 是否被更高优先级来源覆盖（环境变量 / JVM 系统属性）；③ 是否重启了 Tomcat。验证加载：grep "PropertyReader" /var/log/tomcat9/catalina.out | tail -3。

Q2：jspwiki.properties 文件到底在哪？

2.12.5 没有必须存在的独立 jspwiki.properties：默认值在 jar 内 /ini/jspwiki.properties；你的自定义项写在 jspwiki-custom.properties。只有通过 jspwiki.custom.config 才能指定任意路径的覆盖文件。

Q3：环境变量方式传参的命名规则？

源码规则（PropertyReader.collectPropertiesFrom()）：过滤时忽略大小写，但键名保留原样并做 _ → . 替换；而属性键匹配区分大小写，因此环境变量必须写成小写前缀 + 与目标键一致的大小写形式。实测（重启 Tomcat 后抓取首页 meta）：

pkill -f 'org.apache.catalina.startup.Bootstrap'
su -s /bin/bash tomcat -c 'export JAVA_OPTS="-Djava.awt.headless=true -Xms256m -Xmx512m" CATALINA_BASE=/var/lib/tomcat9 CATALINA_HOME=/usr/share/tomcat9 CATALINA_TMPDIR=/tmp; export jspwiki_applicationName=EnvLowerWiki; /usr/share/tomcat9/bin/catalina.sh start'
curl -s http://localhost:8080/JSPWiki/ | grep -oE "wikiApplicationName. content=.[^\"]*." | head -1

实测输出（小写环境变量生效）：

wikiApplicationName" content='EnvLowerWiki' />

改用 export JSPWIKI_APPLICATIONNAME=EnvUpperWiki 后同样抓取，实测输出（不生效，仍为覆盖文件中的 MyWiki）：

wikiApplicationName" content='MyWiki' />

生产环境推荐优先用覆盖文件，避免命名歧义。

Q4：不设置 jspwiki.baseURL 有什么影响？

多数场景仍可访问（链接按请求地址生成），但邮件通知、RSS、引用转出的链接会基于内部地址，外网用户拿到的链接不可用。生产务必设置为对外完整路径（含 /JSPWiki/ 上下文）。

Q5：pageDir 想迁移到新磁盘？

改覆盖文件中的 jspwiki.fileSystemProvider.pageDir（与 basicAttachmentProvider.storageDir）→ cp -a 旧目录到新路径 → chown -R tomcat:tomcat 新路径 → 若 systemd 部署记得同步 ReadWritePaths= 白名单 → 重启。

Q6：日志 WARN sys:java.io.tmpdir referenced ... not found 是错误吗？

不是。见 7.1：RollingFile appender 默认无 logger 引用，其 ${sys:java.io.tmpdir} 占位未解析仅产生告警。需要文件日志时按 7.2 配方写死路径即可消除。

十一、参考链接

JSPWiki 官方 Wiki（配置文档）：https://jspwiki-wiki.apache.org/
PropertyReader 源码（2.12.5）：https://github.com/apache/jspwiki/blob/2.12.5/jspwiki-util/src/main/java/org/apache/wiki/util/PropertyReader.java
安装指南（同专栏）：《Ubuntu 22.04 安装 Apache JSPWiki 2.12.5 指南》