Ubuntu 22.04 安装 Apache Tobago 指南
在 Ubuntu 22.04 上从零安装 Apache Tobago 5.15.2 的完整运行环境，覆盖 JDK 17 与 Tomcat 9 的 apt/官方包安装、Maven 构建 Tobago WAR、部署启动与浏览器级回显验证，命令与回显均实测通过。
Ubuntu 22.04 安装 Apache Tobago 指南
目标：在 Ubuntu 22.04 上从零搭好 Apache Tobago 5.15.2 的开发与运行环境（OpenJDK 17 + Maven 3.9 + Tomcat 9 + MyFaces 2.3），构建出第一个 Tobago WAR 并部署到 Tomcat 完成页面渲染与表单回显验证；本文全部命令与回显均已在 Ubuntu 22.04 实测通过。
Apache Tobago 是 Apache MyFaces 项目下的 JSF 组件框架，以「页面即组件树」的方式提供主题化 UI（页面、输入框、按钮、表格等），最终产物是标准的 Java Web 应用（WAR）。因此「安装 Tobago」的本质是：装好 JDK 与构建工具 → 用 Maven 把 Tobago 组件打成 WAR → 把 WAR 部署到 Servlet 应用服务器（Tomcat）→ 浏览器或 curl 验证页面渲染。本文按此链路给出完整落地步骤。
一、环境信息
本节先固定可复现的基线环境，后续所有命令均在此环境执行。
- 操作系统：Ubuntu 22.04 LTS（x86_64）
- JDK：OpenJDK 17.0.20.1（apt 包
openjdk-17-jdk-headless） - 构建工具：Apache Maven 3.9（
maven:3.9发行包，任一 ≥3.6.3 的 Maven 均可） - 应用服务器：Apache Tomcat 9.0.58（apt 包
tomcat9） - 组件版本：Apache Tobago 5.15.2（
org.apache.myfaces.tobago:tobago-core:5.15.2） - JSF 实现：Apache MyFaces 2.3.12（
org.apache.myfaces.core:myfaces-impl:2.3.12） - 实测工程目录：
/opt/tobago-demo
系统与版本确认（实时回显）：
cat /etc/os-release | head -2
PRETTY_NAME="Ubuntu 22.04 LTS"
NAME="Ubuntu"
java -version 2>&1 | head -1
openjdk version "17.0.20.1" 2026-08-18
⚠️ 重要：Tobago 5.15.2 走的是
javax.faces（JSF 2.3）技术栈而不是 Jakarta 命名空间，因此必须配 Tomcat 9（javax 技术栈），不能部署到 Tomcat 10.1。同时 Tobago 官方包内含少量 Java 17 字节码，运行时要求 JDK 17+，不要用 JDK 8 跑 5.x。若必须用 JDK 8，请选 Tobago 4.6.0（纯 Java 8 字节码），见第 2 篇《CentOS 8 安装 Apache Tobago 指南》的版本选型说明。
二、前置条件
- 具有 root 或 sudo 权限的 Ubuntu 22.04 系统。
- 可正常访问 Ubuntu 官方软件源（
apt update成功）。 - 可访问 Maven 中央仓库
repo1.maven.org（构建时拉取 Tobago 依赖）。 - 至少 2 GB 可用磁盘空间（JDK + Maven + Tomcat + 依赖合计约 600 MB）。
源与网络确认（实时回显）：
curl -sI --max-time 20 https://repo1.maven.org/maven2/ | head -1
HTTP/2 200
三、版本选型说明
本节给出 Tobago 的版本谱系与配套要求，帮助读者一次选对版本。以下结论均来自 Maven Central 元数据与字节码实测。
| Tobago 版本线 | 最新版本 | JSF 命名空间 | 运行 JDK | 配套应用服务器 | JSF 实现 |
|---|---|---|---|---|---|
| 4.x | 4.6.0 | javax.faces（JSF 2.3） | JDK 8+ | Tomcat 8.5/9 | MyFaces 2.3 |
| 5.x | 5.15.2 | javax.faces（JSF 2.3） | JDK 17+（字节码实测） | Tomcat 9 | MyFaces 2.3 |
| 6.x | 6.12.2 | jakarta.faces（Faces 4.0） | JDK 17+ | Tomcat 10.1 | MyFaces 4.0 |
💡 技术拓展：网上常见说法「Tobago 5.x 需要 Jakarta EE 9+」与实测不符。对
tobago-core-5.15.2.jar反编译统计：全部 889 个类中 777 个是 Java 8 字节码（major 52）、112 个是 Java 17 字节码（major 61），且META-INF/faces-config.xml声明的是 JSF 2.3 规范、类内引用javax/faces351 处、jakarta/faces0 处——即 5.x 是「Java EE 命名空间 + 高版本 JDK」的组合，Jakarta 迁移在 6.x 才完成。本文按实测选 Tobago 5.15.2 + Tomcat 9 + MyFaces 2.3.12。
5.15.2 的 Maven 坐标确认（实时回显）：
curl -s https://repo1.maven.org/maven2/org/apache/myfaces/tobago/tobago-core/maven-metadata.xml | grep -E "<version>5\.15\.2|<release>"
<version>5.15.2</version>
<release>6.12.2</release>
四、方案 A：Maven 构建 Tobago WAR 工程（推荐）
4.1 安装 JDK 17 与 Maven
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends openjdk-17-jdk-headless curl
回显（节选）：
Setting up openjdk-17-jdk-headless:amd64 (17.0.20.1-1ubuntu1~22.04) ...
安装 Maven 3.9（解压官方二进制包到 /opt）：
curl -sO https://repo1.maven.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.tar.gz
tar xzf apache-maven-3.9.9-bin.tar.gz -C /opt
ln -sf /opt/apache-maven-3.9.9/bin/mvn /usr/local/bin/mvn
mvn -v | head -3
Apache Maven 3.9.9 (bb087f8bfad3c4b8e83de295bd7c42e57a957860)
Maven home: /opt/apache-maven-3.9.9
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
4.2 建立最小 Tobago 工程
完整的工程结构与源码在《Apache Tobago 5.15.2 快速入门与集成示例》第三章逐步给出，这里直接复用该文工程。将工程放到 /opt/tobago-demo 后执行构建：
cd /opt/tobago-demo
mvn -B clean package 2>&1 | tail -4
[INFO] --- war:3.4.0:war (default-war) @ tobago-demo ---
[INFO] Packaging webapp
[INFO] Assembling webapp [tobago-demo] in [/opt/tobago-demo/target/tobago-demo]
[INFO] Processing war project
[INFO] Building war: /opt/tobago-demo/target/tobago-demo.war
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
产物确认：
ls -lh /opt/tobago-demo/target/tobago-demo.war | awk '{print $5, $9}'
8.8M /opt/tobago-demo/target/tobago-demo.war
💡 说明：WAR 内已打进
tobago-core、tobago-theme-scarborough、myfaces-api/impl、jaxb-api等运行时依赖，属于自包含部署物；javax.servlet-api声明为provided作用域，由 Tomcat 提供。
五、方案 B：直接部署官方示例 WAR
5.1 适用场景
不写代码、只想先看看 Tobago 页面长什么样时，可直接从 Maven Central 拉取官方示例 tobago-example-blank（与 core 同版本发布）部署。
5.2 下载与部署
curl -s -o /opt/blank.war https://repo1.maven.org/maven2/org/apache/myfaces/tobago/tobago-example-blank/5.15.2/tobago-example-blank-5.15.2.war
ls -lh /opt/blank.war | awk '{print $5, $9}'
8.4M /opt/blank.war
⚠️ 注意：官方示例 WAR 直接部署到纯 Tomcat 9 会启动失败，实测需补两处运行时依赖并改一处配置，全部为一次性操作：
- 补 JSTL：官方示例假定应用服务器提供 JSTL，纯 Tomcat 9 没有，需将
javax.servlet.jsp.jstl-api-1.2.1.jar与javax.servlet.jsp.jstl-1.2.5.jar放入WEB-INF/lib（缺失时报JspViewDeclarationLanguage相关 500）。- 补 JAXB：JDK 9 起移除了
javax.xml.bind，需将jaxb-api-2.3.1.jar放入WEB-INF/lib（缺失时页面 writeState 报NullPointerException: Cannot invoke javax.xml.bind.DatatypeConverter.encodeHexBinary）。- 安全注解：在示例的
WEB-INF/tobago-config.xml中、</theme-config>之后追加<security-annotation>ignore</security-annotation>（注意该元素在 XSD 序列中位于最后，放在 name 之后会因 schema 校验失败导致整份配置被拒）。修正后重新打包部署，页面返回 200 并正常渲染
<tobago-page>。自建工程在 pom 里显式引入jaxb-api并自带 tobago-config.xml（见第 3 篇），可从源头避开这三个坑。
六、方案对比
| 维度 | 方案 A：Maven WAR 工程 | 方案 B：官方示例 WAR |
|---|---|---|
| 适用对象 | 正式开发、长期维护 | 快速预览、教学演示 |
| 依赖管理 | pom 显式声明，可控 | 需手工补 jar |
| 组件覆盖 | 按需引入 | 固定的 blank 页面 |
| 与 CI 集成 | 原生支持 | 需二次打包 |
| 上手成本 | 中（需写最小工程） | 低 |
结论：生产与开发一律走方案 A；方案 B 仅用于一分钟内验证应用服务器就绪。
七、基础配置：安装并启动 Tomcat 9
7.1 apt 安装 tomcat9
Ubuntu 22.04 官方源内置 Tomcat 9.0.58（javax 技术栈，正好匹配 Tobago 5.x）：
DEBIAN_FRONTEND=noninteractive apt-get install -y tomcat9
dpkg -l tomcat9 | tail -1
ii tomcat9 9.0.58-1ubuntu0.2 all Apache Tomcat 9 - Servlet and JSP engine
💡 技术拓展：Tomcat 9（javax.）与 Tomcat 10.1（jakarta.）不兼容。选型对照：Tobago 4.x/5.x → Tomcat 9 + MyFaces 2.3；Tobago 6.x → Tomcat 10.1 + MyFaces 4.0。把 5.x 的 WAR 部署到 Tomcat 10.1 会在启动期抛
ClassNotFoundException: javax.servlet.ServletContextListener。
7.2 启动方式
Ubuntu 的 tomcat9 包按 systemd 服务设计（tomcat9.service + socket 激活），常规服务器直接：
systemctl enable --now tomcat9
systemctl status tomcat9 | head -3
在无 systemd 的最小环境中（如精简镜像、手工运维场景），可用包内脚本手动拉起，注意必须同时给出 CATALINA_BASE 与 CATALINA_HOME：
CATALINA_BASE=/var/lib/tomcat9 CATALINA_HOME=/usr/share/tomcat9 JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 /usr/share/tomcat9/bin/startup.sh
Tomcat started.
端口监听确认：
ss -ltn | grep 8080
LISTEN 0 100 *:8080 *:* users:(("java",pid=2713,fd=38))
7.3 部署 WAR
cp /opt/tobago-demo/target/tobago-demo.war /var/lib/tomcat9/webapps/
chown tomcat:tomcat /var/lib/tomcat9/webapps/tobago-demo.war
sleep 12
Tomcat 热部署完成即可访问，无需重启服务。
八、验证清单
以下 4 项全部通过即认为安装成功（均为实测回显）。
- 应用服务器就绪：
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/tobago-demo/
200
- Tobago 页面渲染（自定义标签已转成 HTML + Web Component）：
curl -s http://127.0.0.1:8080/tobago-demo/ | sed 's/></>\n</g' | grep -E "scarborough.*css|<title>|tobago-page" | head -3
<title>Tobago Demo</title>
<link rel='stylesheet' href='/tobago-demo/tobago/scarborough/5.15.2/css/tobago.css' type='text/css'>
<tobago-page locale='en_US' class='container-fluid' id='page' focus-on-error='true' wait-overlay-delay-full='1000' wait-overlay-delay-ajax='1000'>
-
组件树完整：页面中应能看到
tobago-in（输入框）、tobago-button（按钮）、tobago-out（输出）以及随请求生成的javax.faces.ViewState与org.apache.myfaces.tobago.webapp.Secret隐藏域。 -
表单回显交互：浏览器打开
http://<服务器IP>:8080/tobago-demo/，在姓名框输入q1w2e3r4点击「提交」，页面出现「你好, q1w2e3r4! (来自 Tobago 回显)」即完整闭环。等价的命令行验证（先 GET 取 ViewState 与 Secret，再按 JSF Ajax 协议 POST）实测结果：
POST HTTP 200
--- 回显检查 ---
你好, q1w2e3r4! (来自 Tobago 回显)
input type='text' name='page:name' id='page:name::field' value='q1w2e3r4' class='form-control' required='required'/
九、FAQ
Q1：部署后访问 500，日志出现 Cannot invoke "javax.xml.bind.DatatypeConverter.encodeHexBinary"？
JDK 9+ 移除了 JAXB，而 MyFaces 的 view-state 生成依赖它。在 pom 中加入 javax.xml.bind:jaxb-api:2.3.1 重新打包部署即可（本文工程已内置）。
Q2：页面返回 500，日志有 NullPointerException ... authorizationHelper is null？
Tobago 5 默认 security-annotation 为 disable，会走 CDI 授权检查，而 Tomcat 9 没有 CDI 实现。在应用 WEB-INF/tobago-config.xml 中配置 <security-annotation>ignore</security-annotation>（XSD 顺序上必须位于文件末尾的元素区）。
Q3：把 WAR 部署到 Tomcat 10.1 启动失败，报找不到 javax.servlet.ServletContextListener？
Tobago 5.x 是 javax 技术栈，必须用 Tomcat 9；Tomcat 10.1 请改配 Tobago 6.x + MyFaces 4.x。
Q4：apt install tomcat9 后 service tomcat9 start 提示 unrecognized service？
Ubuntu 的 tomcat9 由 systemd 管理，先 systemctl enable --now tomcat9；无 systemd 环境按 7.2 节手动拉起，并注意指定 CATALINA_BASE、CATALINA_HOME、JAVA_HOME 三个变量。
Q5：构建报 release version 17 not supported？
编译机的 JDK 低于 17。Tobago 5.15.2 含 Java 17 字节码，编译与运行都要求 JDK 17+。
十、卸载与清理
# 停服务并卸载 tomcat9（apt 安装方式）
systemctl disable --now tomcat9 2>/dev/null
DEBIAN_FRONTEND=noninteractive apt-get purge -y tomcat9 tomcat9-common
rm -rf /var/lib/tomcat9 /etc/tomcat9
# 移除工程与产物
rm -rf /opt/tobago-demo /opt/blank.war /opt/apache-maven-3.9.9 /usr/local/bin/mvn
# 移除 JDK（可选，谨慎确认无其他业务依赖）
apt-get purge -y openjdk-17-jdk-headless
执行后确认无残留监听：
ss -ltn | grep 8080 || echo "port 8080 free"
port 8080 free
十一、参考链接
- Apache Tobago 官方站点：https://tobago.apache.org/
- Tobago Getting Started：https://tobago.apache.org/getting-started.html
- Maven Central tobago-core：https://repo1.maven.org/maven2/org/apache/myfaces/tobago/tobago-core/
- MyFaces Core 2.3：https://repo1.maven.org/maven2/org/apache/myfaces/core/myfaces-impl/
- Apache Tomcat 9 文档：https://tomcat.apache.org/tomcat-9.0-doc/
- Ubuntu 软件包 tomcat9：https://packages.ubuntu.com/jammy/tomcat9