Ubuntu 22.04 安装 Apache Turbine 指南

本文以 Ubuntu 22.04 实机环境为例，从零完成 Apache Turbine 7.0 的安装、配置、启动与验证，全部命令与回显均来自真实服务器操作记录。

一、环境信息

项目	实测值
操作系统	Ubuntu 22.04（GNU/Linux 6.8.0-138-generic x86_64）
CPU / 内存	12 核 / 32GB（最小 2 核 4GB 亦可运行）
JDK	OpenJDK 17.0.20.1（openjdk-17-jdk，17.0.20.1+1-1-22.04-Ubuntu）
构建工具	Maven 3.9.9（手动解压安装，apt 自带 3.6.3 不满足要求）
数据库	MariaDB（apt 仓库自带，兼容 MySQL 协议）
Turbine 版本	org.apache.turbine:turbine 7.0（Maven Central 最新稳定版）
运行方式	jetty-ee10-maven-plugin 12.0.22 内嵌启动，监听 8081 端口

二、前置条件

服务器可访问公网：需能访问 Maven 中央仓库 repo.maven.apache.org 与 Apache 归档站点 archive.apache.org。
具备 root 权限或 sudo 权限。
端口未被占用：Turbine 示例默认使用 8081，确认方式：

ss -tlnp | grep 8081

无输出即表示端口空闲。若启用 ufw，需放行端口：

ufw allow 8081/tcp

已安装 curl（用于验证），未安装时随步骤一一起安装。

三、版本选型

Turbine 的 Maven 坐标为 org.apache.turbine:turbine，截至撰稿时 Maven Central 的最新稳定版为 7.0（发布序列：4.0 → 4.0.1 → 5.0 → 5.1 → 6.0 → 7.0）。各版本关键差异如下：

Turbine 版本	Servlet API	最低 JDK	适配的 Servlet 引擎	说明
4.0 / 4.0.1	javax.servlet:servlet-api 2.5	JDK 8	Tomcat 7 / Jetty 8	老式 Servlet 2.5 接口，无注解扫描
5.0 / 5.1	javax.servlet-api 3.1.0	JDK 8	Tomcat 8.5/9、Jetty 9	升级到 Servlet 3.1，支持注解与异步
6.0	javax.servlet-api 3.1.0	JDK 11	Tomcat 9、Jetty 9/10(javax)	骨架工程开始引入 PipelineData 接口
7.0	jakarta.servlet-api 6.1.0	JDK 17	Tomcat 11、Jetty 12 (EE10)	切换到 jakarta 命名空间，本文实测版本

4.x 与 5.x 的核心差异：5.x 从 Servlet 2.5 升级到 Servlet 3.1（支持 @WebServlet 等注解、异步处理），API 包名仍为 javax.servlet；6.0 起代码要求 JDK 11；7.0 起包名整体迁移为 jakarta.servlet，必须搭配 Tomcat 11 或 Jetty 12 EE10 及以上版本，不能与旧版 javax.servlet 依赖混用。新项目建议直接选 7.0；如需维护历史工程，按原版本线保留。

四、部署步骤

4.1 安装 OpenJDK 17

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-17-jdk curl

验证：

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)

4.2 安装 Maven 3.9.9

Turbine 7.0 的父级 POM（turbine-parent 14）通过 maven-enforcer-plugin 强制要求 Maven ≥ 3.9.6，而 apt 源中的 Maven 仅 3.6.3，构建会直接失败（报错见常见问题 Q1），因此需手动安装官方二进制包：

cd /opt
curl -L -o maven.tgz https://archive.apache.org/dist/maven/maven-3/3.9.9/binaries/apache-maven-3.9.9-bin.tar.gz
tar xzf maven.tgz
ln -sfn apache-maven-3.9.9 maven

写入全局环境变量：

cat > /etc/profile.d/maven.sh <<'EOF'
export M2_HOME=/opt/maven
export PATH=$M2_HOME/bin:$PATH
EOF
source /etc/profile.d/maven.sh

验证：

mvn -version

实测回显：

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /opt/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: UTF-8
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

4.3 安装并初始化 MariaDB

Turbine 的安全体系（Fulcrum Security Torque 模型）与示例数据都依赖数据库。安装并启动 MariaDB：

DEBIAN_FRONTEND=noninteractive apt-get install -y mariadb-server
systemctl enable mariadb
systemctl start mariadb

创建示例库与账号（与官方 archetype 默认的 db_user/db_password 保持一致）：

mysql -u root -e "CREATE DATABASE turbine CHARACTER SET utf8mb4;"
mysql -u root -e "CREATE USER 'db_user'@'localhost' IDENTIFIED BY 'db_password';"
mysql -u root -e "CREATE USER 'db_user'@'127.0.0.1' IDENTIFIED BY 'db_password';"
mysql -u root -e "GRANT ALL PRIVILEGES ON turbine.* TO 'db_user'@'localhost';"
mysql -u root -e "GRANT ALL PRIVILEGES ON turbine.* TO 'db_user'@'127.0.0.1';"
mysql -u root -e "FLUSH PRIVILEGES;"

4.4 生成 Turbine 工程

使用官方 archetype turbine-webapp:7.0 生成骨架工程：

cd /root
mvn archetype:generate \
  -DarchetypeGroupId=org.apache.turbine \
  -DarchetypeArtifactId=turbine-webapp \
  -DarchetypeVersion=7.0 \
  -DgroupId=com.example \
  -DartifactId=turbine-demo \
  -Dversion=1.0.0 \
  -Dpackage=com.example \
  -DinteractiveMode=false

实测回显（尾部）：

[INFO] Parameter: turbine_database_name, Value: turbine
[INFO] Parameter: db, Value: mysql
[INFO] Project created from Archetype in dir: /root/turbine-demo
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:08 min
[INFO] Finished at: 2026-10-12T11:59:16Z
[INFO] ------------------------------------------------------------------------

4.5 工程结构与依赖说明

生成的工程为标准 Maven war 工程，关键路径：

/root/turbine-demo
├── pom.xml                                    # 构建定义（war 打包）
└── src/main
    ├── java/com/example/modules/...           # Screen/Action 业务模块
    ├── webapp/WEB-INF/web.xml                 # Turbine Servlet 入口定义
    ├── webapp/WEB-INF/conf/TurbineResources.properties   # Turbine 主配置
    ├── webapp/WEB-INF/conf/Torque.properties  # 数据库访问（Torque/JNDI）
    ├── webapp/WEB-INF/conf/log4j2.xml         # 日志配置
    ├── webapp/WEB-INF/jetty-ee10-env.xml      # Jetty JNDI 数据源定义
    ├── webapp/META-INF/context.xml            # Tomcat JNDI 数据源定义
    ├── webapp/templates/app/...               # Velocity 页面模板
    └── data/sample-mysql-data/                # 种子数据（含演示账号）

依赖方面无需再手工引入 turbine，pom.xml 中已经以 ${turbine.core}（即 7.0）声明了核心依赖与 Fulcrum 组件集（security、intake、parser、yaafi 等），确认片段如下：

<dependency>
    <groupId>org.apache.turbine</groupId>
    <artifactId>turbine</artifactId>
    <version>${turbine.core}</version>
</dependency>
<properties>
    <maven.compile.source>17</maven.compile.source>
    <maven.compile.target>17</maven.compile.target>
    <turbine.core>7.0</turbine.core>
    <torque.version>7.0</torque.version>
</properties>

4.6 修改演示账号密码

种子数据中的默认账号为 admin/password。按运维规范将演示账号密码统一改为 q1w2e3r4（账号 admin）：

cd /root/turbine-demo
sed -i "s/VALUES (1,'admin','password','TOBECHANGED','Admin');/VALUES (1,'admin','q1w2e3r4','TOBECHANGED','Admin');/" src/main/data/sample-mysql-data/_turbine-security-data.sql

确认修改：

grep -n "admin" src/main/data/sample-mysql-data/_turbine-security-data.sql | head -1

实测回显：

11:    VALUES (1,'admin','q1w2e3r4','TOBECHANGED','Admin');

4.7 构建并初始化数据库

integration-test 阶段会依次完成编译、Torque 代码与 SQL 生成、建表和灌入种子数据（sql-maven-plugin 绑定在 pre-integration-test 阶段）：

cd /root/turbine-demo
mvn integration-test

构建结束后验证数据库：

mysql -u root turbine -e "show tables;"
mysql -u root turbine -e "select USER_ID,LOGIN_NAME,PASSWORD_VALUE from TURBINE_USER;"

实测回显：

Tables_in_turbine
AUTHOR
BOOK
ID_TABLE
TURBINE_GROUP
TURBINE_PERMISSION
TURBINE_ROLE
TURBINE_ROLE_PERMISSION
TURBINE_USER
TURBINE_USER_GROUP_ROLE
USER_ID LOGIN_NAME      PASSWORD_VALUE
1       admin   q1w2e3r4
2       user    password
3       anon    nopw

4.8 以内嵌 Jetty 启动

通过 jetty-ee10-maven-plugin 启动（端口在 pom.xml 中配置为 8081）。启动前通过 MAVEN_OPTS 限定 JVM 堆为 256–512MB：

cd /root/turbine-demo
MAVEN_OPTS='-Xms256m -Xmx512m' nohup mvn jetty:run > /root/jetty.log 2>&1 &

等待约 30–60 秒后查看启动日志：

grep -E 'Started ServerConnector|Started oejs' /root/jetty.log

实测回显：

[INFO] Started ServerConnector@39124055{HTTP/1.1, (http/1.1)}{0.0.0.0:8081}
[INFO] Started oejs.Server@377d66f{STARTING}[12.0.22,sto=0] @56049ms

4.9 功能验证

访问 Turbine 默认页（Turbine Servlet 映射在 /app）：

curl -s http://localhost:8081/app | grep -oE '<title>[^<]*</title>'

实测回显：

<title>Sample Apache Turbine Application</title>

使用演示账号登录（LoginUser 动作）：

curl -s -i -c /tmp/ck.txt -d 'username=admin&password=q1w2e3r4' http://localhost:8081/app/action/LoginUser | head -4

实测回显（截取响应头前 4 行）：

HTTP/1.1 200 OK
Server: Jetty(12.0.22)
Date: Mon, 12 Oct 2026 12:13:46 GMT
Set-Cookie: JSESSIONID=node0y53h31o6si1tq9y9ys9bzycq1.node0; Path=/; Expires=Mon, 12 Oct 2026 13:13:46 GMT; Max-Age=3600

带会话 Cookie 访问首页，确认已进入登录态（出现 Logout 链接）：

curl -s -b /tmp/ck.txt http://localhost:8081/app/template/Index.vm | grep -c Logout

实测回显：

4.10 JVM 堆限定与验证

堆参数通过 MAVEN_OPTS 传入（内嵌 Jetty 与 Maven 同进程），如上节所示 -Xms256m -Xmx512m。验证方式一，使用 JDK 自带 jps：

jps -v | grep -v Jps

实测回显：

7746 Launcher -Xms256m -Xmx512m -Dclassworlds.conf=/opt/maven/bin/m2.conf -Dmaven.home=/opt/maven -Dlibrary.jansi.path=/opt/maven/lib/jansi-native -Dmaven.multiModuleProjectDirectory=/root/turbine-demo

验证方式二，使用 ps：

ps -ef | grep '[j]ava' | grep -oE '\-Xm[sx][0-9a-z]+'

实测回显：

-Xms256m
-Xmx512m

4.11 部署到独立 Tomcat 11（可选）

Turbine 7.0 基于 jakarta.servlet 6.1，可部署到 Tomcat 11。下载并解压：

cd /opt
curl -L -o tomcat.tgz https://archive.apache.org/dist/tomcat/tomcat-11/v11.0.10/bin/apache-tomcat-11.0.10.tar.gz
tar xzf tomcat.tgz
ln -sfn apache-tomcat-11.0.10 tomcat

先用 mvn package -DskipTests 生成 WAR（实测产物 target/turbine-demo-1.0.0.war，约 32MB），再部署并限定堆：

cp /root/turbine-demo/target/turbine-demo-1.0.0.war /opt/tomcat/webapps/turbine-demo.war
echo 'CATALINA_OPTS="-Xms256m -Xmx512m"' > /opt/tomcat/bin/setenv.sh
/opt/tomcat/bin/startup.sh

实测回显：

Tomcat started.

验证。根路径由 welcome-file app 接引到 Turbine Servlet（实测返回 200），应用页标题正常，登录后 grep -c Logout 返回 1，与内嵌 Jetty 行为一致：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8080/turbine-demo/app
curl -s http://localhost:8080/turbine-demo/app | grep -oE '<title>[^<]*</title>'

实测回显：

HTTP 200
<title>Sample Apache Turbine Application</title>

五、配置说明

配置文件	作用	关键项
pom.xml	构建与插件	jetty-ee10-maven-plugin 的 `<port>8081</port>` 可改监听端口；`<turbine.core>` 指定 Turbine 版本
src/main/webapp/WEB-INF/web.xml	Servlet 入口	Turbine Servlet 映射 `/app/*`；`properties` 参数指向 `WEB-INF/conf/TurbineResources.properties`；welcome-file 为 `app`
WEB-INF/conf/TurbineResources.properties	Turbine 主配置	`template.homepage=Index.vm`、`action.login=LoginUserIntake`、`services.*` 服务注册等
WEB-INF/conf/Torque.properties	数据访问	`torque.dsfactory.turbine.jndi.path=java:comp/env/jdbc/turbine`，经 JNDI 取连接
WEB-INF/jetty-ee10-env.xml	Jetty 数据源	commons-dbcp2 BasicDataSource：`jdbc:mysql://localhost:3306/turbine`，账号 `db_user/db_password`
webapp/META-INF/context.xml	Tomcat 数据源	部署到 Tomcat 时生效，数据源定义与上者等价
WEB-INF/conf/log4j2.xml	日志	输出目录为应用根目录下 `logs/`，详见《Apache Turbine 配置参数详解》

六、升级与多版本

小版本升级（7.0 → 后续 7.x）：编辑 pom.xml 中 <turbine.core> 属性值，执行 mvn clean package 后回归测试即可。
大版本升级（4.x/5.x → 7.0）：属于跨线迁移。javax.servlet 依赖需替换为 jakarta.servlet-api；JDK 需升到 17；自定义 Screen/Action 中 RunData 入参在 6.0+ 的部分回调中改为 PipelineData（可用 data.getRunData() 取回 RunData）；建议按官方 changes-report 逐项核对。
多版本并存：不同版本工程用各自的 archetype 版本号生成（如 -DarchetypeVersion=6.0 生成 6.0 工程），构建时通过 -Dmaven.compiler.source 与对应 JDK 匹配；服务器上多个 Maven/JDK 可分别解压在 /opt 下的不同目录并用环境变量切换。

七、注意事项

Maven 版本必须 ≥ 3.9.6，否则 enforcer 直接拦截（见常见问题 Q1）。
Turbine 7.0 不能部署到 Tomcat 9 及以下或 Jetty 11 及以下，javax/jakarta 命名空间不兼容。
示例种子数据以明文保存 TURBINE_USER.PASSWORD_VALUE，生产环境应在组件配置中启用 Fulcrum Security 的密码加密（fulcrum-crypto 提供 JavaCrypt/UnixCrypt 等算法），并同步更新存量口令。
应用以 root 运行仅适用于实验，生产建议创建专用系统用户并保证应用目录 logs/ 可写。
logs/ 目录会持续写入 turbine.log、velocity.log 等，建议纳入 logrotate。
访问根路径 / 在 Jetty 下默认返回目录列表而非应用页，业务入口统一走 /app（见常见问题 Q3）。

八、常见问题

**Q1：**构建报 enforcer 错误，提示 Maven 版本不满足？实测现象（apt 自带 Maven 3.6.3）：

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.5.0:enforce (enforce-maven) on project turbine-demo:
[ERROR] Rule 0: org.apache.maven.enforcer.rules.version.RequireMavenVersion failed with message:
[ERROR] Detected Maven Version: 3.6.3 is not in the allowed range [3.9.6,)

定位：turbine-parent 14 的 enforcer 规则要求 Maven ≥ 3.9.6。解决：按 4.2 节手动安装 Maven 3.9.9 并重开终端使 PATH 生效，mvn -version 确认后再构建。

**Q2：**访问 http://IP:8081/ 看到的是文件目录列表？内嵌 Jetty 下根路径由默认 Servlet 处理，应用入口是 /app（web.xml 中 Turbine Servlet 的 url-pattern）。访问 http://IP:8081/app 即可看到 "Sample Apache Turbine Application" 页面。

**Q3：**登录提示 "Sorry your username or password is incorrect!"？按顺序排查：数据库未执行 4.7 节初始化；种子账号密码仍为默认 password 未改成 q1w2e3r4；MariaDB 中 db_user 授权与 jetty-ee10-env.xml 中的连接串不一致。可用 mysql -u root turbine -e "select LOGIN_NAME,PASSWORD_VALUE from TURBINE_USER;" 核对。

**Q4：**启动时 8081 端口被占用？ ss -tlnp | grep 8081 找到占用进程并停止，或修改 pom.xml 中 jetty-ee10-maven-plugin 的 <httpConnector><port> 后重新 mvn jetty:run。

**Q5：**部署到 Tomcat 后如何确认堆参数已生效？ jps -v 查看 Bootstrap 进程参数，实测回显节选：

7998 Bootstrap ... -Xms256m -Xmx512m -Dcatalina.base=/opt/tomcat ...

若未生效，检查 /opt/tomcat/bin/setenv.sh 是否存在且用 shutdown.sh/startup.sh 完整重启。

九、卸载方式

停止应用：ps -ef | grep '[j]ava' 找到进程号后 kill <PID>（Tomcat 方式部署则执行 /opt/tomcat/bin/shutdown.sh）。
删除构建产物：cd /root/turbine-demo && mvn clean。
删除工程目录：rm -rf /root/turbine-demo。
卸载数据库（先备份 /var/lib/mysql）：

systemctl stop mariadb
apt-get purge -y mariadb-server
rm -rf /var/lib/mysql

卸载 JDK 与 Maven（确认无其他应用依赖后执行）：

apt-get purge -y openjdk-17-jdk
rm -rf /opt/maven /opt/apache-maven-3.9.9 /etc/profile.d/maven.sh

清理本地 Maven 仓库缓存（可选）：rm -rf ~/.m2/repository。

十、参考链接

Apache Turbine 官网：https://turbine.apache.org/
Turbine 7.0 官方文档：https://turbine.apache.org/turbine/turbine-7-0/
Turbine 7.0 快速上手：https://turbine.apache.org/turbine/turbine-7-0/getting-started.html
Turbine 7.0 服务说明：https://turbine.apache.org/turbine/turbine-7-0/services/index.html
Maven Central 上的 turbine 7.0：https://central.sonatype.com/artifact/org.apache.turbine/turbine/7.0
官方代码仓库（turbine-core）：https://github.com/apache/turbine-core
官方 archetype 仓库：https://github.com/apache/turbine-archetypes
Maven 3.9.9 二进制包：https://archive.apache.org/dist/maven/maven-3/3.9.9/binaries/
Apache Tomcat 11 下载：https://archive.apache.org/dist/tomcat/tomcat-11/