Apache Roller 配置参数详解

目标：详解 Apache Roller 6.1.3 的配置体系——roller-custom.properties（数据库连接、搜索索引与媒体目录等覆盖项）、/etc/default/tomcat9 托管参数（JVM 堆 256-512MB）与数据库内 roller_properties 站点运行参数，并给出可直接套用的生产模板。参数与默认值均基于 Ubuntu 22.04 + Tomcat 9.0.58 + MariaDB 10.6.23 真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache Roller：6.1.3（WAR 部署于 /var/lib/tomcat9/webapps/roller.war）
• Servlet 服务器：Apache Tomcat 9.0.58（tomcat9）
• 数据库：MariaDB 10.6.23（库名 rollerdb）
• Java：OpenJDK 11.0.32.1
• Roller 自定义配置文件：/var/lib/tomcat9/lib/roller-custom.properties
• Tomcat 启动参数文件：/etc/default/tomcat9
• Roller 日志：/var/log/tomcat9/roller.log
• 访问端口：8080（前缀 /roller）

二、前置条件

• 已按《Apache Roller 安装指南》完成 Roller 6.1.3 部署并能访问首页。
• Roller 配置生效需重启服务：systemctl restart tomcat9；数据库内站点参数（roller_properties）则在管理后台保存后即时生效。
• 参数核对手段：/var/log/tomcat9/roller.log（启动时回显实际生效的连接与目录）、ps -ef | grep java（核验 JVM 参数）。

三、参数查看与修改方式

Roller 的参数分三层，查找优先级从高到低：

1. roller-custom.properties（推荐入口）：位于 Tomcat 共享类路径 /var/lib/tomcat9/lib/，键值格式 key=value，用于覆盖默认属性。启动日志会回显关键覆盖项是否生效：

INFO  2026-10-12 00:53:30 [main] DatabaseProvider - SUCCESS: Got parameters. Using configuration type JDBC_PROPERTIES
INFO  2026-10-12 00:53:30 [main] DatabaseProvider - -- Using JDBC connection URL: jdbc:mysql://localhost:3306/rollerdb?autoReconnect=true&useSSL=false&characterEncoding=utf8&serverTimezone=UTC
INFO  2026-10-12 00:53:31 [main] LuceneIndexManager - index dir: /var/lib/tomcat/roller_data/search-index

2. WAR 内置 roller.properties 默认值：位于 roller.war 的 WEB-INF/classes/roller.properties，是全部属性的出厂默认，不要直接改 WAR 内文件，一律用 roller-custom.properties 覆盖。

3. 数据库 roller_properties 表（站点运行参数）：由管理后台（Server Admin → Configuration）读写，首次启动时按默认值自动初始化，修改即时生效、无需重启。查看实际值：

mariadb rollerdb -e "SHOW COLUMNS FROM roller_properties;"
mariadb rollerdb -e "SELECT name,value FROM roller_properties LIMIT 10;"

修改文件层参数的标准流程：

vi /var/lib/tomcat9/lib/roller-custom.properties
systemctl restart tomcat9
grep -E "index dir|configuration type" /var/log/tomcat9/roller.log   # 核对生效

四、参数总览

五、核心参数分类详解

5.1 数据库连接参数

5.1.1 database.configurationType

数据库配置方式，三选一：

• jdbc：直连数据库（本指南实测采用，最简单）；
• jndi：服务器数据源，需在 Tomcat 配置 JNDI 资源 jdbc/roller；
• jpa：由 JPA 属性决定。

database.configurationType=jdbc

⚠️ 默认 jndi，若只写 jdbc.* 而忘了切 configurationType，启动会去找 JNDI 数据源并失败。

5.1.2 database.jdbc.driverClass 与 connectionURL

MySQL/MariaDB 8.x 驱动类为 com.mysql.cj.jdbc.Driver；连接串建议固定带上时区与编码参数（实测可用值）：

database.jdbc.driverClass=com.mysql.cj.jdbc.Driver
database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollerdb?autoReconnect=true&useSSL=false&characterEncoding=utf8&serverTimezone=UTC
database.jdbc.username=roller
database.jdbc.password=q1w2e3r4

启动成功时 roller.log 回显：

INFO  2026-10-12 00:53:30 [main] DatabaseProvider - SUCCESS: Got parameters. Using configuration type JDBC_PROPERTIES
INFO  2026-10-12 00:53:30 [main] DatabaseProvider - -- Using JDBC username: roller
INFO  2026-10-12 00:53:30 [main] DatabaseProvider - -- Using JDBC password: [hidden]
INFO  2026-10-12 00:53:30 [main] DatabaseProvider - SUCCESS: loaded JDBC driver class [com.mysql.cj.jdbc.Driver]

5.1.3 hibernate.dialect

MariaDB 10.6 兼容 MySQL 5.x 方言，实测配置：

hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect

生效回显（roller.log）：

INFO  2026-10-12 00:53:30 [main] JPAPersistenceStrategy - hibernate.dialect: org.hibernate.dialect.MySQL5InnoDBDialect

5.2 数据目录参数

5.2.1 search.index.dir

Lucene 全文检索索引目录。默认落在运行用户家目录 ~/roller_data/search-index（tomcat 用户即 /var/lib/tomcat/roller_data/search-index）。目录不可写时启动即失败（空指针），务必显式指定并保证 tomcat 用户可写：

search.index.dir=/var/lib/tomcat/roller_data/search-index

生效回显（roller.log）：

INFO  2026-10-12 00:53:31 [main] LuceneIndexManager - search enabled: true
INFO  2026-10-12 00:53:31 [main] LuceneIndexManager - index dir: /var/lib/tomcat/roller_data/search-index

5.2.2 mediafile.storage.dir

媒体文件（图片、附件上传）存储目录，语义同上：

mediafile.storage.dir=/var/lib/tomcat/roller_data/mediafiles

⚠️ Ubuntu 的 tomcat9 服务由 systemd 沙箱限制可写路径（ReadWritePaths），数据目录必须放行，例如在 /etc/systemd/system/tomcat9.service.d/override.conf 中加 ReadWritePaths=/var/lib/tomcat/ 后 systemctl daemon-reload。否则即使目录存在，写入仍报 Read-only file system。

5.3 JVM 与 Tomcat 托管参数

5.3.1 JAVA_OPTS（堆内存 256-512MB）

编辑 /etc/default/tomcat9，把默认行：

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

改为：

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

核验实际生效值（应看到 -Xms256m -Xmx512m）：

systemctl restart tomcat9
ps -ef | grep "[j]ava" | grep -oE "\-Xms[0-9]+m \-Xmx[0-9]+m"

回显：

-Xms256m -Xmx512m

💡 单机博客站点 512MB 堆足够；堆大小影响的主要是页面渲染与缓存（cache.weblogpage 默认 400 条、cache.salt 5000 条），流量增大后再按监控上调。

5.4 站点运行参数（roller_properties）

以下参数存于数据库 roller_properties 表，通过管理后台（Server Admin → Configuration）修改，保存即时生效。实测初始默认值：

直接 SQL 只读查看（改值建议走管理后台，避免绕过校验）：

mariadb rollerdb -e "SELECT name,value FROM roller_properties WHERE name IN ('site.name','users.registration.enabled','uploads.file.maxsize');"

回显：

name                          value
site.name                     Roller Site
users.registration.enabled    false
uploads.file.maxsize          2.00

六、生产配置模板

适用场景：8-16GB 内存、SSD 磁盘、Tomcat 9 + MariaDB 10.6 同机或近机部署、数百用户规模的企业内部博客/知识站点，关闭自注册、由管理员统一开户。

/var/lib/tomcat9/lib/roller-custom.properties：

# --- 数据库直连 ---
database.configurationType=jdbc
database.jdbc.driverClass=com.mysql.cj.jdbc.Driver
database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollerdb?autoReconnect=true&useSSL=false&characterEncoding=utf8&serverTimezone=UTC
database.jdbc.username=roller
database.jdbc.password=q1w2e3r4
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
# --- 数据目录（独立数据盘时指向挂载点） ---
search.index.dir=/var/lib/tomcat/roller_data/search-index
mediafile.storage.dir=/var/lib/tomcat/roller_data/mediafiles
# --- 单点登录（对接公司 SSO 时开启） ---
users.sso.enabled=false

/etc/default/tomcat9：

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

/etc/systemd/system/tomcat9.service.d/override.conf：

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

数据库侧配套（utf8mb4 建库、专用账号）：

mariadb -e "CREATE DATABASE rollerdb DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER 'roller'@'localhost' IDENTIFIED BY 'q1w2e3r4'; GRANT ALL PRIVILEGES ON rollerdb.* TO 'roller'@'localhost'; FLUSH PRIVILEGES;"

管理后台建议项：site.adminemail 填运维邮箱、uploads.types.forbid 追加 sh,bat 等脚本扩展名、users.comments.plugins 保留 HTMLSubset（评论 HTML 白名单净化）。

七、常见问题

7.1：改了 roller-custom.properties 不生效

排查：确认文件在 /var/lib/tomcat9/lib/（Tomcat common 类路径）而不是 WAR 解包目录内；确认已 systemctl restart tomcat9；用 grep "index dir" /var/log/tomcat9/roller.log 看启动回显的实际值。

7.2：启动报 Read-only file system / NPE（indexExists）

原因：搜索索引目录不可写（systemd 沙箱未放行或目录属主不对）。实测错误链：

ERROR 2026-10-12 00:47:32 [main] LuceneIndexManager - java.io.IOException: No such file or directory
java.nio.file.FileSystemException: /var/lib/tomcat: Read-only file system

解决：search.index.dir/mediafile.storage.dir 指向真实可写目录，mkdir -p 后 chown -R tomcat:tomcat，并在 systemd drop-in 中 ReadWritePaths 放行后 daemon-reload + 重启。

7.3：数据库连接认证失败（Access denied）

排查：核对 database.jdbc.username/password 与 mariadb -e "SELECT User,Host FROM mysql.user;" 中账号主机段（roller@localhost 只能本机连接；Roller 与数据库分机时改授权 'roller'@'%' 并收紧防火墙）。

7.4：roller.log 出现 mail-session JNDI 告警

回显：

WARN  2026-10-12 00:47:29 [main] WebloggerStartup - Failed to setup mail provider, continuing anyways.
Reason: ERROR looking up mail-session with JNDI name: java:comp/env/mail/Session

说明：未配置邮件会话时的预期警告，不影响博客运行；需要邮件通知/注册激活时再在 Tomcat 上下文配置 mail/Session 资源。

7.5：上传大附件被拒

原因：uploads.file.maxsize 默认 2MB、uploads.dir.maxsize 默认 20MB。 解决：管理后台调大两项；同时确认反向代理（如有）的请求体限制同步放宽。

八、参考链接

• Apache Roller 官网：https://roller.apache.org/
• Apache Roller 安装指南 PDF（发行包 docs/ 目录）：roller-install-guide.pdf
• Tomcat 9 配置参考：https://tomcat.apache.org/tomcat-9.0-doc/config.html
• MariaDB 10.6 文档：https://mariadb.org/documentation/