Apache Roller 安装指南
在 Ubuntu 22.04 服务器上从零安装 Apache Roller 6.1.3 开源博客系统,涵盖 Tomcat 9 与 MariaDB 前置、官方 zip 下载校验、MariaDB 建库建表、JDBC 配置、JVM 堆 512MB、systemd 数据目录放行、初始化向导建站与登录验证,命令与回显均实测
Apache Roller 安装指南
目标:在真实 Ubuntu 22.04 服务器上从零安装 Apache Roller 6.1.3(基于 Java 的开源多用户博客服务器,以 WAR 形式运行于 Tomcat),覆盖前置依赖、官方下载校验、MariaDB 建库建表、JDBC 配置、systemd 托管、初始化向导与常见失败排障。以下命令与回显均在 Ubuntu 22.04.5 真实环境逐步实测。
一、环境信息
- 操作系统:Ubuntu 22.04.5 LTS(x86_64)
- Java:OpenJDK 11.0.32.1(
openjdk-11-jre-headless) - Servlet 服务器:Apache Tomcat 9.0.58(
tomcat9,Ubuntu 仓库版) - 数据库:MariaDB 10.6.23
- Apache Roller:6.1.3(
apache-roller-6.1.3-binary.zip,58,373,169 字节) - Roller 部署路径:
/var/lib/tomcat9/webapps/roller.war(访问前缀/roller) - Roller 数据目录:
/var/lib/tomcat/roller_data/(搜索索引与媒体文件) - 端口:8080(Tomcat HTTP)、3306(MariaDB)
- 运行用户:root 安装,服务以
tomcat用户运行 - 站长账号:admin / q1w2e3r4
💡 说明:Roller 官方发行包只提供 WAR 与文档(PDF),不含独立启动脚本,必须依托 Servlet 服务器(Tomcat/Jetty)运行;本文采用 Ubuntu 仓库的 Tomcat 9 + MariaDB 组合。
二、前置条件
- 一台 Ubuntu 22.04 服务器,root 权限。
- 需安装
tomcat9、mariadb-server、openjdk-11-jre-headless、wget、unzip、curl、net-tools(含netstat)。 - 服务器能访问
archive.apache.org(下载 Roller 发行包)与 Maven 中央仓库(下载 JDBC 驱动、JavaMail 包)。 - ⚠️ 不要同时安装
mysql-client与mariadb-server:两者冲突,会报mariadb-server-10.6 : Breaks: mysql-client-core-8.0依赖错误;MariaDB 自带mariadb命令行客户端,无需 mysql-client。
三、版本选型说明
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| Apache Roller | 6.1.3 | 6.1 系列最新稳定版,发行包 apache-roller-6.1.3-binary.zip / .tar.gz |
| OpenJDK | 11 | Roller 6.1 要求 Java 8/11,Ubuntu 22.04 仓库直接提供 11 |
| Tomcat | 9.0.58(Ubuntu 仓库 tomcat9) | 官方推荐 Servlet 4.0 服务器;Ubuntu 22.04 仓库即有 tomcat9 |
| MariaDB | 10.6.x | 与 MySQL 5.7 协议兼容,Roller 的 mysql 方言建表脚本可直接使用 |
| MySQL Connector/J | 8.0.33 | JDBC 驱动类 com.mysql.cj.jdbc.Driver |
⚠️ Roller 6.1 不再支持 JDK 7 与 Servlet 2.5 服务器;Tomcat 7 及更早版本不可用,建议 Tomcat 9。
四、部署步骤
4.1 更新软件源并安装基础软件
apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
tomcat9 mariadb-server openjdk-11-jre-headless wget unzip curl net-tools
验证版本回显:
# java -version
openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)
# mariadb -V
mariadb Ver 15.1 Distrib 10.6.23-MariaDB, for debian-linux-gnu (x86_64) using EditLine wrapper
启动两个系统服务:
systemctl start mariadb
systemctl start tomcat9
systemctl is-active mariadb
systemctl is-active tomcat9
回显:
active
active
4.2 下载并校验 Roller 发行包
cd /opt
wget https://archive.apache.org/dist/roller/roller-6.1/v6.1.3/apache-roller-6.1.3-binary.zip
下载完成末行回显:
apache-roller-6.1.3-binary.zip 100% [==========================>] 55.67M 4.66MB/s 时长 24s
官方提供 .sha256 校验文件(内容为 64 位十六进制摘要,按 8 位分组书写),拼接后校验:
echo "239a89809253262816ba684d23dbf2319246ae916ee9658c34663c29fd330846 apache-roller-6.1.3-binary.zip" | sha256sum -c -
回显:
apache-roller-6.1.3-binary.zip: OK
解压:
unzip -q apache-roller-6.1.3-binary.zip
ls apache-roller-6.1.3
回显:
docs webapp
发行包结构说明:
/opt/apache-roller-6.1.3/
├── LICENSE.txt、NOTICE.txt、README.md
├── docs/ # roller-install-guide.pdf、roller-user-guide.pdf、roller-template-guide.pdf
└── webapp/
└── roller.war # Web 应用本体(55,026,775 字节)
💡 数据库建表脚本不在发行包目录中,而是打包在
roller.war内的WEB-INF/classes/dbscripts/mysql/createdb.sql,下一步先解出再用。
4.3 解出 MySQL 建表脚本
mkdir -p /opt/roller-dbscripts
cd /opt/roller-dbscripts
unzip -o -q /opt/apache-roller-6.1.3/webapp/roller.war "WEB-INF/classes/dbscripts/mysql/*"
ls WEB-INF/classes/dbscripts/mysql/
回显:
310-to-400-migration.sql
400-to-500-migration.sql
500-to-510-migration.sql
510-to-520-migration.sql
520-to-610-migration.sql
createdb.sql
4.4 MariaDB 建库、授权并导入建表脚本
创建数据库 rollerdb 与专用账号 roller(密码 q1w2e3r4),字符集用 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;"
导入建表脚本:
mariadb rollerdb < /opt/roller-dbscripts/WEB-INF/classes/dbscripts/mysql/createdb.sql
验证表数量与部分表名:
mariadb rollerdb -e "SHOW TABLES;" | wc -l
mariadb rollerdb -e "SHOW TABLES;" | head -20
回显:
34
Tables_in_rollerdb
autoping
bookmark
bookmark_folder
custom_template_rendition
entryattribute
newsfeed
pingqueueentry
pingtarget
rag_entry
rag_group
rag_group_subscription
rag_planet
rag_properties
rag_subscription
roller_audit_log
roller_comment
roller_hitcounts
roller_mediafile
roller_mediafiledir
4.5 放置 JDBC 驱动与 JavaMail 包
Roller WAR 未捆绑 JDBC 驱动与 JavaMail,需要把 3 个 jar 放进 Tomcat 共享类路径 /var/lib/tomcat9/lib/(该目录本身在 Tomcat common 类加载器上,.properties 与 .jar 均会被加载):
wget -O /var/lib/tomcat9/lib/mysql-connector-j-8.0.33.jar \
https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.0.33/mysql-connector-j-8.0.33.jar
wget -O /var/lib/tomcat9/lib/javax.mail-1.6.2.jar \
https://repo1.maven.org/maven2/com/sun/mail/javax.mail/1.6.2/javax.mail-1.6.2.jar
wget -O /var/lib/tomcat9/lib/javax.activation-1.2.0.jar \
https://repo1.maven.org/maven2/com/sun/activation/javax.activation/1.2.0/javax.activation-1.2.0.jar
确认放置结果:
# ls -la /var/lib/tomcat9/lib/ | grep -E "mysql|mail|activation"
-rw-r--r-- 1 root root 2481560 Apr 16 2023 mysql-connector-j-8.0.33.jar
-rw-r--r-- 1 root root 78030 Sep 6 2017 javax.activation-1.2.0.jar
-rw-r--r-- 1 root root 659031 Aug 29 2018 javax.mail-1.6.2.jar
4.6 编写 roller-custom.properties
在 /var/lib/tomcat9/lib/ 下创建 roller-custom.properties(Tomcat common 类路径),声明 JDBC 连接方式:
cat > /var/lib/tomcat9/lib/roller-custom.properties <<'EOF'
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
EOF
参数说明见《Apache Roller 配置参数详解》篇;其中 search.index.dir 与 mediafile.storage.dir 显式指定 Roller 数据目录,避免依赖运行用户家目录默认值。
4.7 预创建 Roller 数据目录
Tomcat 服务运行用户为 tomcat,其家目录是 /var/lib/tomcat。预先创建数据目录并赋权:
mkdir -p /var/lib/tomcat/roller_data/search-index /var/lib/tomcat/roller_data/mediafiles
chown -R tomcat:tomcat /var/lib/tomcat/roller_data
4.8 放行 systemd 沙箱可写目录(Ubuntu tomcat9 必做)
Ubuntu 的 tomcat9.service 通过 systemd ReadWritePaths 限制可写路径,仅放行 /etc/tomcat9/Catalina/、/var/lib/tomcat9/webapps/、/var/log/tomcat9/;Roller 数据目录 /var/lib/tomcat/roller_data 不在其中,启动会因索引目录创建失败而报空指针(见 7.1)。用 drop-in 配置放行:
mkdir -p /etc/systemd/system/tomcat9.service.d
cat > /etc/systemd/system/tomcat9.service.d/override.conf <<'EOF'
[Service]
ReadWritePaths=/var/lib/tomcat/
EOF
systemctl daemon-reload
4.9 部署 WAR 并设置 JVM 堆内存
复制 WAR 到 Tomcat 应用目录:
cp /opt/apache-roller-6.1.3/webapp/roller.war /var/lib/tomcat9/webapps/roller.war
ls -la /var/lib/tomcat9/webapps/
回显:
drwxrwxr-x 3 tomcat tomcat 4096 Oct 12 00:47 .
drwxr-xr-x 5 root root 4096 Oct 12 00:45 ..
drwxr-xr-x 3 root root 4096 Oct 12 00:44 ROOT
-rw-r--r-- 1 root root 55026775 Oct 12 00:47 roller.war
编辑 /etc/default/tomcat9,将堆内存限定为 256-512MB。原始行:
JAVA_OPTS="-Djava.awt.headless=true"
改为:
JAVA_OPTS="-Djava.awt.headless=true -Xms256m -Xmx512m"
重启 Tomcat 并验证堆参数生效:
systemctl restart tomcat9
ps -ef | grep "[j]ava" | grep -oE "\-Xms[0-9]+m \-Xmx[0-9]+m"
回显:
-Xms256m -Xmx512m
4.10 验证服务并完成初始化向导
等待 WAR 解包部署(约 10-20 秒)后验证:
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/roller/
curl -s http://localhost:8080/roller/ | grep -oE "<title>[^<]+</title>"
回显:
200
<title>Front Page: Welcome to Roller!</title>
⚠️ 若此时返回 404,说明 Context 启动失败,按「常见问题」一节排查
/var/log/tomcat9/roller.log与/var/log/tomcat9/localhost.*.log。
首次访问时 Roller 处于未初始化状态,初始化向导分三步,全部可用 curl 完成:
第一步:创建站长账号。 向导页把注册页链接为 /roller/roller-ui/register.rol。先 GET 取表单(含会话绑定的 CSRF salt)再 POST:
curl -s -c /tmp/roller-cj.txt http://localhost:8080/roller/roller-ui/register.rol -o /tmp/reg.html
grep -E "<form" /tmp/reg.html
回显:
<form id="register" name="register" action="/roller/roller-ui/register!save.rol" method="post" class="form-horizontal">
提交注册(salt 值从 /tmp/reg.html 的 name="salt" value="..." 中取,示例取实测值):
curl -s -b /tmp/roller-cj.txt -c /tmp/roller-cj.txt -X POST "http://localhost:8080/roller/roller-ui/register!save.rol" \
--data-urlencode "salt=TVVgYb5SRTkqVcHSmv8J" --data-urlencode "bean.id=" \
--data-urlencode "bean.userName=admin" --data-urlencode "bean.screenName=admin" \
--data-urlencode "bean.fullName=Site Admin" --data-urlencode "bean.emailAddress=admin@example.com" \
--data-urlencode "bean.passwordText=q1w2e3r4" --data-urlencode "bean.passwordConfirm=q1w2e3r4" \
--data-urlencode "bean.locale=en_US" --data-urlencode "bean.timeZone=America/New_York" \
--data-urlencode "userRegister.button.save=Sign Up" -w "%{http_code}\n"
回显:
200
数据库验证(第一个注册用户自动获得 admin 角色,即全局管理员):
mariadb rollerdb -e "SELECT username,fullname FROM roller_user;"
mariadb rollerdb -e "SELECT rolename,username FROM userrole;"
回显:
username fullname
admin Site Admin
rolename username
editor admin
admin admin
第二步:登录验证。 登录表单的提交地址是 /roller/roller_j_security_check:
curl -s -c /tmp/roller-cj.txt -b /tmp/roller-cj.txt -X POST "http://localhost:8080/roller/roller_j_security_check" \
-d "j_username=admin&j_password=q1w2e3r4" -o /dev/null -w "%{http_code} %{redirect_url}\n"
curl -s -b /tmp/roller-cj.txt -L http://localhost:8080/roller/roller-ui/menu.rol | grep -oE "<title>[^<]+</title>"
回显:
302 http://localhost:8080/roller/roller-ui/menu.rol
<title>Front Page: Your Weblogs</title>
第三步:创建博客并设为前台首页。 登录会话下先取建博表单再提交:
curl -s -b /tmp/roller-cj.txt http://localhost:8080/roller/roller-ui/createWeblog.rol -o /tmp/cw.html
grep -E "<form" /tmp/cw.html
回显:
<form id="createWeblog" name="createWeblog" action="/roller/roller-ui/createWeblog!save.rol" method="post" class="form-horizontal validate-form">
提交(salt 从 /tmp/cw.html 取,示例取实测值;bean.theme 可选 basic/gaurav/fauxcoly/basicmobile/frontpage):
curl -s -b /tmp/roller-cj.txt -X POST "http://localhost:8080/roller/roller-ui/createWeblog!save.rol" \
--data-urlencode "salt=4CXeeiSssrOnLjChjLJL" --data-urlencode "bean.name=Admin Blog" \
--data-urlencode "bean.handle=adminblog" --data-urlencode "bean.emailAddress=admin@example.com" \
--data-urlencode "bean.locale=en_US" --data-urlencode "bean.timeZone=America/New_York" \
--data-urlencode "bean.theme=basic" --data-urlencode "button.save=Create Weblog" -w "%{http_code}\n"
回显:
200
再次访问向导页会出现前台博客表单,提交指定前台博客:
curl -s -b /tmp/roller-cj.txt http://localhost:8080/roller/roller-ui/setup.rol -o /tmp/setup2.html
grep -A2 'name="frontpageBlog"' /tmp/setup2.html
回显:
<select name="frontpageBlog" id="setup_frontpageBlog" class="form-control">
<option value="adminblog">Admin Blog</option>
curl -s -b /tmp/roller-cj.txt -X POST "http://localhost:8080/roller/roller-ui/setup!save.rol" \
--data-urlencode "salt=t1ngT8UvqbT1tN3iq58F" --data-urlencode "frontpageBlog=adminblog" \
--data-urlencode "aggregated=true" --data-urlencode "__checkbox_aggregated=true" -w "%{http_code}\n"
回显:
302
最终验证:站点首页已切换为新建博客,博客页与 RSS 均可访问:
curl -s http://localhost:8080/roller/ | grep -oE "<title>[^<]+</title>"
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/roller/adminblog/
curl -s http://localhost:8080/roller/adminblog/feed/entries/rss | head -1
回显:
<title>Admin Blog</title>
200
<?xml version="1.0" encoding="utf-8"?>
启动成功后 /var/log/tomcat9/roller.log 关键回显:
INFO 2026-10-12 00:53:31 [main] WebloggerFactory - Version: 6.1.3
INFO 2026-10-12 00:53:31 [main] WebloggerFactory - Revision: r2faff60f88a631d4a313e4b7511269943ba31b20
INFO 2026-10-12 00:53:32 [main] ThemeManagerImpl - Successfully loaded 5 themes from disk.
INFO 2026-10-12 00:53:32 [main] WebloggerImpl - Roller Weblogger business tier successfully initialized
五、配置说明
5.1 roller-custom.properties 位置
该文件必须位于 Tomcat common 类路径上,Ubuntu Tomcat 9 即 /var/lib/tomcat9/lib/。Roller 按「类路径根下的 roller-custom.properties」查找,放错位置(如 webapps/roller/)不会被读取。
5.2 JVM 堆内存(256-512MB)
修改位置为 /etc/default/tomcat9 的 JAVA_OPTS(见 4.9 节)。Roller 是常驻 Web 应用,堆设 512MB 即可支撑单机博客站点;核验生效值用:
ps -ef | grep "[j]ava" | grep -oE "\-Xms[0-9]+m \-Xmx[0-9]+m"
5.3 数据目录
- 搜索索引:
search.index.dir,默认位于运行用户家目录下的roller_data/search-index(tomcat 用户即/var/lib/tomcat/roller_data/search-index); - 媒体文件:
mediafile.storage.dir,默认同上 mediafiles 子目录。 - 两目录需对
tomcat用户可写,且在 systemdReadWritePaths放行范围内(见 4.7、4.8 节)。
六、注意事项
- Ubuntu 仓库 Tomcat 9 受 systemd 沙箱限制,凡 Roller 需要写入的目录(数据目录、日志目录)都必须在
ReadWritePaths放行,否则启动失败。 roller-custom.properties里的数据库密码为示例演示口令 q1w2e3r4,生产环境应换为强密码并限制roller账号来源主机。- MariaDB 与 mysql-client 系列包互斥,安装时二选一。
- Roller 默认关闭用户自注册(
users.registration.enabled=false),站长在管理后台按需开启。 - 修改
roller-custom.properties后必须systemctl restart tomcat9才生效。
七、常见问题
7.1:首页 404,日志报 NullPointerException(Lucene indexExists)
错误回显(/var/log/tomcat9/localhost.2026-10-12.log):
SEVERE [main] org.apache.catalina.core.StandardContext.listenerStart Exception sending context initialized event to listener instance of class [org.apache.roller.weblogger.ui.core.RollerContext]
java.lang.NullPointerException
at org.apache.lucene.index.DirectoryReader.indexExists(DirectoryReader.java:327)
at org.apache.roller.weblogger.business.search.lucene.LuceneIndexManager.indexExists(LuceneIndexManager.java:348)
同时 /var/log/tomcat9/roller.log 出现:
INFO 2026-10-12 00:47:31 [main] LuceneIndexManager - index dir: /var/lib/tomcat/roller_data/search-index
ERROR 2026-10-12 00:47:32 [main] LuceneIndexManager - java.io.IOException: No such file or directory
ERROR 2026-10-12 00:47:32 [main] LuceneIndexManager - Problem accessing index directory
java.nio.file.FileSystemException: /var/lib/tomcat: Read-only file system
定位:Roller 默认把索引建在 tomcat 用户家目录 /var/lib/tomcat/roller_data,但 Ubuntu tomcat9.service 的 ReadWritePaths 未放行该路径,目录建不出来,随后 indexExists 空指针导致 Context 启动失败。
解决:按 4.7 节建目录赋权、4.8 节 drop-in 放行 ReadWritePaths=/var/lib/tomcat/,重启 tomcat9 后首页恢复 200。
7.2:首页正常,但登录后 Main Menu 报 Unexpected Exception(ClassNotFoundException: javax.mail)
错误回显(/var/log/tomcat9/localhost.2026-10-12.log):
SEVERE [http-nio-8080-exec-10] org.apache.catalina.core.StandardWrapperValve.invoke Servlet.service() for servlet [default] in context with path [/roller] threw exception [Filter execution threw an exception] with root cause
java.lang.ClassNotFoundException: javax.mail.internet.AddressException
at org.apache.roller.weblogger.pojos.RollerPermission.setActionsAsList(RollerPermission.java:48)
定位:Roller WAR 编译期依赖 JavaMail 但不打进 WAR,纯 Servlet 服务器没有该类,菜单页加载权限对象时抛类未找到。
解决:把 javax.mail-1.6.2.jar 与 javax.activation-1.2.0.jar 放入 /var/lib/tomcat9/lib/(见 4.5 节)后重启。
7.3:roller.log 出现 Failed to setup mail provider 警告
回显:
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
说明:未配置 JNDI 邮件会话时的预期警告,Roller 继续启动、不影响博客功能;需要邮件通知时再在 Tomcat 配置 mail/Session JNDI 资源。
7.4:安装 mysql-client 与 mariadb-server 报依赖错误
回显:
mariadb-server-10.6 : Depends: mariadb-client-10.6 (>= 1:10.6.23-0ubuntu0.22.04.1) but it is not installable
Breaks: mysql-client-core-8.0 but 8.0.46-0ubuntu0.22.04.4 is to be installed
E: Unable to correct problems, you have held broken packages.
解决:去掉 mysql-client,只装 mariadb-server(自带 mariadb 客户端命令)。
7.5:大包下载慢
解决:archive.apache.org 带宽波动明显(实测约 5MB/s,低峰可能仅几十 KB/s),可改用 downloads.apache.org 当前版本目录或国内镜像站加速;下载后务必做 sha256 校验。
八、卸载方式
systemctl stop tomcat9 # 停止应用
rm -f /var/lib/tomcat9/webapps/roller.war # 移除 WAR
rm -rf /var/lib/tomcat9/webapps/roller # 移除解包目录
rm -f /var/lib/tomcat9/lib/roller-custom.properties /var/lib/tomcat9/lib/mysql-connector-j-8.0.33.jar
rm -f /var/lib/tomcat9/lib/javax.mail-1.6.2.jar /var/lib/tomcat9/lib/javax.activation-1.2.0.jar
rm -rf /var/lib/tomcat/roller_data # 移除数据目录
rm -rf /etc/systemd/system/tomcat9.service.d /opt/apache-roller-6.1.3 /opt/apache-roller-6.1.3-binary.zip /opt/roller-dbscripts
systemctl daemon-reload && systemctl restart tomcat9
mariadb -e "DROP DATABASE rollerdb; DROP USER 'roller'@'localhost';" # 可选:删除数据库与账号
apt-get remove -y tomcat9 mariadb-server openjdk-11-jre-headless # 可选:卸载基础软件
九、参考链接
- Apache Roller 存档下载:https://archive.apache.org/dist/roller/roller-6.1/
- Apache Roller 官网:https://roller.apache.org/
- Apache Roller 安装指南(PDF,随发行包 docs/ 目录附带):roller-install-guide.pdf
- MySQL Connector/J(Maven Central):https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/
- JavaMail 1.6.2(Maven Central):https://repo1.maven.org/maven2/com/sun/mail/javax.mail/1.6.2/