Apache Turbine 配置参数详解

本文基于 Apache Turbine 7.0（org.apache.turbine:turbine 7.0，JDK 17 + jakarta.servlet 6.1.0）实测环境逐项解析配置文件，全部示例与回显取自真实服务器验证记录。

一、配置体系总览

Turbine 7.0 的配置由四层组成，启动时按以下关系加载：

层	文件	加载者	作用
Servlet 层	`WEB-INF/web.xml`	Servlet 引擎	注册 Turbine Servlet，指定主配置文件位置
主配置层	`WEB-INF/conf/TurbineResources.properties`	org.apache.turbine.Turbine	管道、模板、动作、服务注册表
Avalon 组件层	`WEB-INF/conf/componentConfiguration.xml` + `roleConfiguration.xml`	fulcrum-yaafi	数据库、加密、Intake、上传、安全等 Fulcrum 组件
日志层	`WEB-INF/conf/log4j2.xml`	log4j2	应用与各服务日志的落盘

主配置文件位置由 web.xml 的 properties 初始化参数指定，配置根目录由 applicationRoot 参数决定（webContext 表示以 Web 应用根目录为基准解析相对路径）。

二、TurbineResources.properties 核心参数解析

2.1 管道与页面渲染

log4j2.file = log4j2.xml
pipeline.default.descriptor = WEB-INF/conf/turbine-classic-pipeline.xml

log4j2.file：log4j2 配置文件名，Turbine 启动时在 WEB-INF 目录下定位它。
pipeline.default.descriptor：请求管道定义文件。实测工程中该文件（turbine-classic-pipeline.xml）声明了经典 Valve 链，顺序为：

DefaultSetEncodingValve → DetermineActionValve → DetermineTargetValve
→ DefaultSessionTimeoutValve → DefaultLoginValve → DefaultSessionValidationValve
→ DefaultACLCreationValve → ExecutePageValve → CleanUpValve
→ DetermineRedirectRequestedValve

自建 Valve 时在 <valves> 中插入即可，顺序即执行顺序。

2.2 服务器数据与编码

serverdata.default.serverName=
serverdata.default.serverPort=80
serverdata.default.serverScheme=http
serverdata.default.scriptName=
serverdata.default.contextPath=
input.encoding=UTF-8

这些参数为 TemplateLink 等工具生成 URL 提供默认值；留空时自动取当前请求的值。input.encoding 决定请求参数解码编码，中文环境保持 UTF-8。

2.3 模块缓存与包扫描

module.cache=false
action.cache.size=20
layout.cache.size=10
navigation.cache.size=10
page.cache.size=5
screen.cache.size=50
scheduledjob.cache.size=10
module.packages=com.example.modules,com.example.flux.modules,org.apache.turbine.modules

module.packages：Screen/Action 等 Java 模块的搜索包前缀，自建模块必须落在其中列出的包下。
module.cache 与各 *.cache.size：生产环境建议 module.cache=true 并按模块数量调整缓存上限，避免每次请求反射构造模块对象。

2.4 页面、登录与错误跳转

template.homepage=Index.vm
screen.homepage=
template.login=Login.vm
screen.login=
template.error=Error.vm
screen.error=VelocityErrorScreen
screen.invalidstate=error.InvalidState
action.login=LoginUserIntake
action.logout=LogoutUser
action.sessionvalidator=sessionvalidator.TemplateSessionValidator
action.accesscontroller=AccessController
action.eventsubmit.needsvalue = false
use.ssl=true
login.message=Thank you for your visit. Please log into the system.
login.error=Sorry your username or password is incorrect!
logout.message=Thank you for using the system. Please come back soon.

template.homepage：未指定页面时的默认模板；template.login/template.error 为登录页与错误页。
action.login/action.logout：登录/登出动作类名（不含包前缀，按 module.packages 解析）。
action.sessionvalidator 与 action.accesscontroller：会话校验与访问控制动作，是"未登录跳登录页"机制的执行者。
login.error：实测登录失败时页面返回的正是这段文案（curl 验证见第八节）。

2.5 服务注册表（services.*）

每个 Turbine 服务以 services.<简称>.classname 注册，实测工程启用的核心服务：

services.AvalonComponentService.classname=org.apache.turbine.services.avaloncomponent.TurbineYaafiComponentService
services.RunDataService.classname=org.apache.turbine.services.rundata.TurbineRunDataService
services.ServletService.classname=org.apache.turbine.services.servlet.TurbineServletService
services.AssemblerBrokerService.classname=org.apache.turbine.services.assemblerbroker.TurbineAssemblerBrokerService
services.PullService.classname=org.apache.turbine.services.pull.TurbinePullService
services.TemplateService.classname=org.apache.turbine.services.template.TurbineTemplateService
services.SecurityService.classname=org.apache.turbine.services.security.DefaultSecurityService
services.UIService.classname = org.apache.turbine.services.ui.TurbineUIService
services.VelocityService.classname=org.apache.turbine.services.velocity.TurbineVelocityService
services.JsonRpcService.classname=org.apache.turbine.services.jsonrpc.TurbineJsonRpcService
services.SchedulerService.classname=org.apache.turbine.services.schedule.QuartzSchedulerService

配套参数：

services.RunDataService.default.run.data=org.apache.turbine.services.rundata.DefaultTurbineRunData
services.RunDataService.default.parameter.parser=org.apache.fulcrum.parser.DefaultParameterParser
services.RunDataService.default.cookie.parser=org.apache.fulcrum.parser.DefaultCookieParser
services.AssemblerBrokerService.screen=org.apache.turbine.services.assemblerbroker.util.java.JavaScreenFactory
services.AssemblerBrokerService.action=org.apache.turbine.services.assemblerbroker.util.java.JavaActionFactory
services.SchedulerService.enabled=false
services.SchedulerService.earlyInit=true
services.PullService.earlyInit= true
services.SecurityService.user.manager = org.apache.turbine.services.security.DefaultUserManager
services.SecurityService.user.class=org.apache.fulcrum.security.model.turbine.entity.impl.TurbineUserImpl
services.SecurityService.wrapper.class = com.example.wrapper.TurbineUserWrapper

要点：AssemblerBrokerService.* 决定 Screen/Action 等"装配体"由 Java 类工厂加载；SchedulerService.enabled=false 表示 Quartz 定时任务关闭，开启后从数据库调度表读取任务；SecurityService.wrapper.class 把 Fulcrum 的 TurbineUser 包装成应用自定义用户对象。

2.6 TemplateService 与 VelocityService

services.TemplateService.layout.cache.size=2
services.TemplateService.navigation.cache.size=10
services.TemplateService.screen.cache.size=50
services.VelocityService.template.extension=vm
services.VelocityService.default.page = VelocityPage
services.VelocityService.default.screen = VelocityScreen
services.VelocityService.default.layout = VelocityOnlyLayout
services.VelocityService.default.navigation = VelocityNavigation
services.VelocityService.default.error.screen = VelocityErrorScreen
services.VelocityService.default.layout.template = Default.vm
services.VelocityService.catch.errors = true
services.VelocityService.default_encoding=UTF-8
services.VelocityService.velocimacro.library = macros/TurbineMacros.vm,macros/applicationMacros.vm
services.VelocityService.resource.loader = file
services.VelocityService.file.resource.loader.class = org.apache.velocity.runtime.resource.loader.FileResourceLoader
services.VelocityService.file.resource.loader.path = /templates/app,/templates/flux
services.VelocityService.file.resource.loader.cache = false
services.VelocityService.file.resource.loader.modificationCheckInterval = 2

模板查找顺序：TemplateService 按 templates/app/screens/<名字>.vm 等约定定位模板；找不到 Screen 类时回落到 VelocityService.default.screen。
file.resource.loader.path：Velocity 文件加载器的模板根目录，新增模板目录时在此追加。
开发期保持 file.resource.loader.cache=false 以便热改模板；生产改为 true 并调整 modificationCheckInterval。

2.7 Pull 工具（tool.*）

tool.request.link=org.apache.turbine.services.pull.tools.TemplateLink
tool.request.page=org.apache.turbine.util.template.HtmlPageAttributes
tool.request.content=org.apache.turbine.services.pull.tools.ContentTool
tool.request.l10n=org.apache.turbine.services.localization.LocalizationTool
tool.request.dateFormatter=org.apache.turbine.services.pull.util.DateFormatter
tool.request.intake=org.apache.turbine.services.intake.IntakeTool
tool.request.related=com.example.services.pull.RelatedTool
tool.session.sessionData=org.apache.turbine.services.pull.util.SessionData
tool.global.ui=org.apache.turbine.services.pull.tools.UITool

tool.request.* 在每次请求注入 Velocity 上下文，模板里直接用 $link、$intake 等引用；tool.session.* 作用域为会话；tool.global.* 为全局。应用自有工具类照此格式追加。

三、web.xml 配置详解

实测工程的 web.xml（Servlet 3.1 语法，Turbine 7.0 在 Tomcat 11/Jetty 12 下验证通过）核心段落：

<servlet>
    <servlet-name>Turbine</servlet-name>
    <servlet-class>org.apache.turbine.Turbine</servlet-class>
    <init-param>
        <param-name>applicationRoot</param-name>
        <param-value>webContext</param-value>
    </init-param>
    <init-param>
        <param-name>properties</param-name>
        <param-value>WEB-INF/conf/TurbineResources.properties</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Turbine</servlet-name>
    <url-pattern>/app/*</url-pattern>
</servlet-mapping>
<session-config>
    <session-timeout>60</session-timeout>
    <cookie-config><max-age>3600</max-age></cookie-config>
</session-config>
<welcome-file-list><welcome-file>app</welcome-file></welcome-file-list>

要点：所有业务请求经 /app/* 进入 Turbine；/templates/* 与 /logs/* 在 web.xml 中通过空 <auth-constraint /> 禁止直接访问，防止模板源码与日志泄露。

四、数据源与 Torque 配置

4.1 Torque.properties

torque.dsfactory.turbine.factory=org.apache.torque.dsfactory.JndiDataSourceFactory
torque.dsfactory.turbine.jndi.path=java:comp/env/jdbc/turbine
torque.dsfactory.turbine.jndi.ttl=300000
torque.database.turbine.adapter=auto
torque.database.default=turbine
torque.idbroker.cleverquantity=true
torque.idbroker.initialId = 101

Torque 不直连数据库，而是经 JNDI 取数据源，adapter=auto 由 Torque 自动探测数据库方言。

4.2 Jetty 数据源（jetty-ee10-env.xml）

<New id="Turbine" class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg><Ref refid="wac"/></Arg>
    <Arg>jdbc/turbine</Arg>
    <Arg>
        <New class="org.apache.commons.dbcp2.BasicDataSource">
            <Set name="driverClassName">com.mysql.cj.jdbc.Driver</Set>
            <Set name="url">jdbc:mysql://localhost:3306/turbine</Set>
            <Set name="username">db_user</Set>
            <Set name="password">db_password</Set>
            <Set name="connectionProperties">useSSL=false</Set>
            <Set name="validationQuery">SELECT 1</Set>
        </New>
    </Arg>
</New>

4.3 Tomcat 数据源（META-INF/context.xml）

<Resource name="jdbc/turbine" global="jdbc/turbine" type="javax.sql.DataSource"
    driverClassName="com.mysql.cj.jdbc.Driver"
    url="jdbc:mysql://localhost:3306/turbine?serverTimezone=UTC"
    username="db_user" password="db_password"
    maxTotal="100" maxIdle="20" minIdle="5" maxWaitMillis="10000"/>

生产改造点：连接串改走内网地址、账号最小权限、口令不落明文（用 Tomcat 凭据加密或环境变量注入）。

五、Fulcrum 组件配置（Intake/Upload/Security）

Fulcrum 组件在 componentConfiguration.xml 中配置，实测文件的关键节点：

<intake>
    <serialDataPath>WEB-INF/appData.ser</serialDataPath>
    <xmlPaths><xmlPath>WEB-INF/conf/intake.xml</xmlPath></xmlPaths>
</intake>
<parser>
    <parameterEncoding>utf-8</parameterEncoding>
    <automaticUpload>true</automaticUpload>
    <pool2><maxTotal>1024</maxTotal><blockWhenExhausted>true</blockWhenExhausted>
           <maxWaitMillis>500</maxWaitMillis></pool2>
</parser>
<upload repository="/tmp" sizeMax="1048576" sizeThreshold="10240"/>
<crypto>
    <algorithm>
        <unix>org.apache.fulcrum.crypto.provider.UnixCrypt</unix>
        <clear>org.apache.fulcrum.crypto.provider.ClearCrypt</clear>
        <java>org.apache.fulcrum.crypto.provider.JavaCrypt</java>
    </algorithm>
</crypto>
<securityService/>
<authenticator/>
<!-- 启用口令加密的示例：
<authenticator><algorithm>java</algorithm><cipher>SHA1</cipher></authenticator> -->
<modelManager/>
<aclFactory/>

Intake：表单校验规则定义在 WEB-INF/conf/intake.xml，例如 Login 组的 Username 字段带 required 与 minLength=4 规则；模板中经 $loginGroup.Username.Key 渲染出形如 login_0u 的输入框名。
UploadService：repository 为暂存目录，sizeMax 限制单文件字节数（此处 1MB），sizeThreshold 为落盘阈值。
Security：authenticator 缺省为明文比对；生产环境取消注释并选择 java（SHA 系）等算法，同时更新 TURBINE_USER.PASSWORD_VALUE 的存储格式。

六、日志配置（log4j2.xml）

log4j2 依赖 log4j-jakarta-web 提供的 Web Lookup，TurbineResources.properties 中 log4j2.file=log4j2.xml 指定文件名。实测 Appender 定义：

<Console name="console" target="SYSTEM_OUT">
    <PatternLayout pattern="%d [%t] %-5p | %c - %m%n"/>
</Console>
<File name="turbine" fileName="${web:rootDir}/logs/turbine.log">...</File>
<File name="application" fileName="${web:rootDir}/logs/application.log">...</File>
<File name="avalon" fileName="${web:rootDir}/logs/avalon.log">...</File>
<File name="scheduler" fileName="${web:rootDir}/logs/scheduler.log">...</File>
<File name="torque" fileName="${web:rootDir}/logs/torque.log">...</File>
<File name="sql" fileName="${web:rootDir}/logs/sql.log">...</File>
<File name="velocity" fileName="${web:rootDir}/logs/velocity.log">...</File>

${web:rootDir} 解析为 Web 应用根目录，因此日志统一落在应用目录的 logs/ 下。启动应用后实测文件清单：

application.log  avalon.log  scheduler.log  sql.log  torque.log  turbine.log  velocity.log

turbine.log 实测样例行：

2026-10-12 12:35:14,029 [http-nio-8080-exec-3] INFO  org.apache.turbine.annotation.AnnotationProcessor - No key template.invalidstate of type class java.lang.String injected into object org.apache.turbine.modules.actions.sessionvalidator.TemplateSessionValidator@dd9ec66. Field templateInvalidState is set to default null.

七、JVM 参数

内嵌 Jetty（mvn jetty:run）：通过 MAVEN_OPTS 传递，实测 MAVEN_OPTS='-Xms256m -Xmx512m'。
独立 Tomcat：写入 /opt/tomcat/bin/setenv.sh，CATALINA_OPTS="-Xms256m -Xmx512m"。
建议同时加 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/turbine 便于故障取证。

验证（实测回显）：

jps -v | grep -v Jps

7746 Launcher -Xms256m -Xmx512m -Dclassworlds.conf=/opt/maven/bin/m2.conf -Dmaven.home=/opt/maven ...

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

-Xms256m
-Xmx512m

八、实测验证方法

登录失败文案与 login.error 一致：

curl -s -d 'username=admin&password=wrongpass' http://localhost:8081/app/action/LoginUser | grep -oE 'Sorry your username[^<]*'

回显：

Sorry your username or password is incorrect!

登录成功后会话可用（返回 1 表示页面出现 Logout 链接）：

curl -s -c /tmp/ck.txt -d 'username=admin&password=q1w2e3r4' http://localhost:8081/app/action/LoginUser -o /dev/null
curl -s -b /tmp/ck.txt http://localhost:8081/app/template/Index.vm | grep -c Logout

端口与进程核对：ss -tlnp | grep 8081 显示 java 进程监听，jps -l 区分 Maven/Launcher 与 Tomcat/Bootstrap。

九、生产配置模板

# TurbineResources.properties 生产要点（在 archetype 基础上修改）
module.cache=true
screen.cache.size=100
services.SchedulerService.enabled=true
input.encoding=UTF-8
use.ssl=true
serverdata.default.serverName=www.example.com
serverdata.default.serverScheme=https
serverdata.default.serverPort=443
template.error=Error.vm
login.error=用户名或密码错误，请重新输入。

配合要点：log4j2 的 File Appender 全部改用 RollingFile（按天/按大小滚动）；componentConfiguration.xml 的 upload 仓库改到独立数据盘目录并调大 sizeMax；authenticator 启用 SHA 系算法；数据源指向内网数据库并启用 TLS。

十、常见问题

**Q1：**改了 TurbineResources.properties 不生效？该文件在 war 包内/源码目录中，内嵌 Jetty 直接改 src/main/webapp/WEB-INF/conf/ 下的文件后需重启 mvn jetty:run；Tomcat 部署则要改 webapps/<应用>/WEB-INF/conf/ 下的实际文件或重新打包。

**Q2：**访问 /app 报 404 或页面空白？检查 web.xml 的 properties 参数路径是否正确、load-on-startup 是否为 1，并查看 logs/turbine.log 与 logs/application.log 中的初始化异常。

**Q3：**数据库连接失败？按链路排查：Torque.properties 的 JNDI 路径 → web.xml 的 resource-ref → Jetty env / context.xml 的账号密码与连接串 → 数据库端授权。logs/torque.log 与 logs/sql.log 有具体报错。

**Q4：**上传文件报超限？调整 componentConfiguration.xml 中 <upload sizeMax=...>；注意部分 Servlet 引擎还有自身 multipart 上限需同步调大。

**Q5：**日志没生成？确认 pom 中包含 log4j-jakarta-web 依赖、TurbineResources.properties 的 log4j2.file 指向的文件存在于 WEB-INF 下，且应用对 logs/ 目录有写权限。

十一、参考链接

Turbine 7.0 官方文档：https://turbine.apache.org/turbine/turbine-7-0/
Turbine 7.0 服务说明：https://turbine.apache.org/turbine/turbine-7-0/services/index.html
Turbine 7.0 API 文档：https://turbine.apache.org/turbine/turbine-7-0/apidocs/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
log4j2 Web 应用手册：https://logging.apache.org/log4j/2.x/manual/webapp.html
Apache Torque 官网：https://db.apache.org/torque/