CentOS 8 安装 Apache Tobago 指南

目标：在 CentOS 8 上从零搭好 Apache Tobago 5.15.2 的运行环境（OpenJDK 17 + Tomcat 9 + Tobago WAR 部署与回显验证），重点解决 CentOS 8 EOL 后官方源失效与 el8 下 JAVA_HOME 需要显式声明两大拦路虎；本文全部命令与回显均已在 CentOS 8 实测通过。

CentOS 8 于 2021 年底停止维护（EOL），官方源 mirror.centos.org 已下线，因此本文先用 vault 归档源恢复包管理能力，再完成 JDK 17、Tomcat 9 与 Tobago WAR 的部署验证。Tobago 的安装链路与第 1 篇一致：装 JDK → 备好 WAR → 部署到 Tomcat 9 → curl 验证；差别集中在 yum/dnf 换源与 el8 环境变量处理上。

一、环境信息

操作系统：CentOS Linux 8（x86_64，官方 centos:8 发行基线）
JDK：OpenJDK 17.0.1（yum 包 java-17-openjdk）
应用服务器：Apache Tomcat 9.0.123（官方 tar 包，el8 无可用 rpm）
组件版本：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）
归档源：阿里云 mirrors.aliyun.com/centos-vault/8.5.2111
实测工程目录：/opt/tobago-demo（WAR 在构建机产出后拷贝）

系统确认（实时回显）：

cat /etc/os-release | head -2

NAME="CentOS Linux"
VERSION="8"

uname -m

x86_64

⚠️ 重要：与第 1 篇结论一致，Tobago 5.15.2 是 javax.faces（JSF 2.3）技术栈且要求 JDK 17+ 运行，必须搭配 Tomcat 9，不能部署到 Tomcat 10.1。

二、前置条件

具有 root 权限的 CentOS 8 系统。
可访问阿里云镜像站 mirrors.aliyun.com（EOL 后唯一的包来源）。
可访问 Maven 中央仓库 repo1.maven.org 与 Apache 下载站 downloads.apache.org。
至少 2 GB 可用磁盘空间。

归档源连通性确认（实时回显）：

curl -sI --max-time 20 http://mirrors.aliyun.com/centos-vault/8.5.2111/BaseOS/x86_64/os/ | head -1

HTTP/1.1 200 OK

三、版本选型说明

Tobago 版本谱系与配套要求（详见第 1 篇第三章的字节码实测）：

Tobago 版本线	最新版本	JSF 命名空间	运行 JDK	配套应用服务器
4.x	4.6.0	javax.faces	JDK 8+（纯 Java 8 字节码）	Tomcat 8.5/9
5.x	5.15.2	javax.faces	JDK 17+（实测 112 个类为 major 61）	Tomcat 9
6.x	6.12.2	jakarta.faces	JDK 17+	Tomcat 10.1

本文主线选 Tobago 5.15.2 + JDK 17 + Tomcat 9；若目标机只能用 JDK 8，请选 Tobago 4.6.0，此时把工程 pom 中 tobago.version 改为 4.6.0、tobago-config.xml 的 version 属性改为 4.0（4.x 解析器不认识 5.1，实测报 SAXException: Using unknown version attribute '5.1'），其余步骤完全一致。

💡 技术拓展：JSF 实现选型。Tobago 是组件库，还需要一个 JSF 实现才能运行，主流选择是 Apache MyFaces（2.3.12，与 Tobago 同属 Apache 软件基金会）与 Eclipse Mojarra（2.3.x）。两者都实现 JSF 2.3 规范；本文选 MyFaces——与 Tobago 同门，issue 响应快，且官方示例与文档均以 MyFaces 为准。

四、修复 EOL 软件源（vault 换源）

4.1 确认官方源已失效

curl -s -o /dev/null -w '%{http_code}\n' --max-time 10 http://mirrorlist.centos.org/?release=8&arch=x86_64&repo=BaseOS
dnf makecache 2>&1 | tail -2

Failed to download metadata for repo 'appstream': Cannot prepare internal mirrorlist: Curl error (6): Couldn't resolve host name for http://mirrorlist.centos.org/?release=8&arch=x86_64&infra=container [Could not resolve host: mirrorlist.centos.org]

4.2 换用阿里云 centos-vault

el8 的 repo 文件使用 mirrorlist 动态选源，EOL 后该域名已不可解析，必须注释掉 mirrorlist、启用 baseurl 并指向 vault 归档：

sed -i -e 's|mirror.centos.org|mirrors.aliyun.com|g' \
       -e 's|$contentdir/$releasever|centos-vault/8.5.2111|g' \
       -e 's|^mirrorlist=|#mirrorlist=|' \
       /etc/yum.repos.d/CentOS-Linux-*.repo
dnf makecache 2>&1 | tail -1

Metadata cache created.

💡 说明：8.5.2111 是 CentOS 8 的最终存档版本号，vault 目录按版本快照归档；$contentdir/$releasever 变量替换后不再随系统版本变化，需写死为 8.5.2111。

五、安装 JDK 17 并显式声明 JAVA_HOME

5.1 安装

dnf install -y java-17-openjdk java-17-openjdk-devel 2>&1 | tail -1
java -version 2>&1 | head -1

Complete!
openjdk version "17.0.1" 2021-10-19 LTS

5.2 显式声明 JAVA_HOME（el8 必做）

RHEL 系的 OpenJDK 包不像 Debian 系那样提供 java_home 包装脚本，el8 上必须显式导出 JAVA_HOME，否则 Tomcat 启动脚本只能靠 which java 兜底，在多 JDK 共存或非交互 shell 下会直接启动失败。写入全局 profile：

cat >> /etc/profile.d/java17.sh <<'EOF'
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
export PATH=$JAVA_HOME/bin:$PATH
EOF
source /etc/profile.d/java17.sh
echo $JAVA_HOME

/usr/lib/jvm/java-17-openjdk

六、方案 A：Maven 构建 Tobago WAR 工程

WAR 构建在开发机完成（工程源码见《Apache Tobago 5.15.2 快速入门与集成示例》），把产物 tobago-demo.war 拷贝到目标机 /opt/tobago-demo/target/：

mkdir -p /opt/tobago-demo/target
cp tobago-demo.war /opt/tobago-demo/target/    # 从构建机拷入
ls -lh /opt/tobago-demo/target/tobago-demo.war | awk '{print $5, $9}'

8.8M /opt/tobago-demo/target/tobago-demo.war

开发机构建回显（mvn -B clean package 节选）：

[INFO] --- war:3.4.0:war (default-war) @ tobago-demo ---
[INFO] Building war: /opt/tobago-demo/target/tobago-demo.war
[INFO] BUILD SUCCESS

七、方案 B：直接部署官方示例 WAR

从 Maven Central 拉取官方空白示例 tobago-example-blank 5.15.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

⚠️ 注意：官方示例 WAR 在纯 Tomcat 9 上有三个实测坑，需先修正再部署：

WEB-INF/lib 补 JSTL 两个 jar：javax.servlet.jsp.jstl-api-1.2.1.jar、javax.servlet.jsp.jstl-1.2.5.jar（Tomcat 不自带 JSTL，缺失时页面 500）；

WEB-INF/lib 补 jaxb-api-2.3.1.jar（JDK 9+ 无 JAXB，缺失时 writeState 抛 NullPointerException）；

WEB-INF/tobago-config.xml 在 </theme-config> 之后加 <security-annotation>ignore</security-annotation>（无 CDI 环境必配；该元素按 XSD 序列必须位于文件末尾区，插在 name 后会导致 schema 校验失败、整份配置被拒）。

自建工程方案 A 已从源头规避上述问题，推荐生产环境一律走方案 A。

八、方案对比

维度	方案 A：Maven WAR 工程	方案 B：官方示例 WAR
适用对象	正式开发、长期维护	快速验证应用服务器就绪
依赖管理	pom 声明，一次到位	手工补 JSTL/JAXB jar
可维护性	高，可持续迭代	低
部署风险	低	中（补丁遗忘即 500）

结论：以方案 A 为主，方案 B 仅作冒烟测试用。

九、基础配置：安装并启动 Tomcat 9

9.1 下载官方包

el8 源里的 tomcat 已无维护，按 Tobago 5.x 的 javax 要求装 Tomcat 9 官方 tar 包：

curl -sO https://downloads.apache.org/tomcat/tomcat-9/v9.0.123/bin/apache-tomcat-9.0.123.tar.gz
sha512sum apache-tomcat-9.0.123.tar.gz | awk '{print $1}'
curl -s https://downloads.apache.org/tomcat/tomcat-9/v9.0.123/bin/apache-tomcat-9.0.123.tar.gz.sha512

64b1130e719399c0a409e6996081433b16af8d9c89266c7aaa9849af70a1815feca91e13896f5ccc41451dc5759716d1c84882682de955822c30509de102f290
64b1130e719399c0a409e6996081433b16af8d9c89266c7aaa9849af70a1815feca91e13896f5ccc41451dc5759716d1c84882682de955822c30509de102f290 *apache-tomcat-9.0.123.tar.gz

两值一致，包完整性校验通过。

9.2 解压并启动（显式 JAVA_HOME）

tar xzf apache-tomcat-9.0.123.tar.gz -C /opt
rm -rf /opt/apache-tomcat-9.0.123/webapps/*
chmod +x /opt/apache-tomcat-9.0.123/bin/*.sh
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
cd /opt/apache-tomcat-9.0.123 && ./bin/startup.sh

Tomcat started.

9.3 部署 WAR

cp /opt/tobago-demo/target/tobago-demo.war /opt/apache-tomcat-9.0.123/webapps/
sleep 12

如需随开机自启，追加 systemd 单元（/etc/systemd/system/tomcat.service）：

[Unit]
Description=Apache Tomcat 9
After=network.target

[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk
ExecStart=/opt/apache-tomcat-9.0.123/bin/startup.sh
ExecStop=/opt/apache-tomcat-9.0.123/bin/shutdown.sh
User=root

[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now tomcat

十、验证清单

应用服务器就绪：

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/tobago-demo/

Tobago 主题资源加载（scarborough 主题 CSS 随页面引用）：

curl -s http://127.0.0.1:8080/tobago-demo/ | grep -oE "href='[^']*scarborough[^']*css[^']*'" | head -1

href='/tobago-demo/tobago/scarborough/5.15.2/css/tobago.css'

组件树与状态域：页面含 tobago-page、tobago-in、tobago-button、tobago-out，并随请求输出 javax.faces.ViewState 与 org.apache.myfaces.tobago.webapp.Secret 隐藏域。
表单回显交互：浏览器输入 q1w2e3r4 提交后出现「你好, q1w2e3r4! (来自 Tobago 回显)」。命令行等价验证实测：

POST HTTP 200
--- 回显检查 ---
你好, q1w2e3r4! (来自 Tobago 回显)
input type='text' name='page:name' id='page:name::field' value='q1w2e3r4' class='form-control' required='required'/

十一、FAQ

Q1：dnf makecache 一直报 Couldn't resolve host: mirrorlist.centos.org？ EOL 后该域名已注销。按第四章注释 mirrorlist= 并改用 baseurl 指向 mirrors.aliyun.com/centos-vault/8.5.2111。

Q2：Tomcat 启动后 8080 无监听，catalina.out 报 Neither the JAVA_HOME nor the JRE_HOME environment variable is defined？ el8 不会自动设置 JAVA_HOME。按 5.2 节写入 /etc/profile.d/java17.sh 并 source，或在 systemd 单元中用 Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk 注入。

Q3：部署后页面 500，日志有 NullPointerException ... authorizationHelper？ Tobago 5 默认安全注解为 disable，在无 CDI 的 Tomcat 9 上必然触发。在 WEB-INF/tobago-config.xml 配 <security-annotation>ignore</security-annotation>（置于文件末尾元素区）。

Q4：访问 500，日志有 javax.xml.bind.DatatypeConverter 相关 NPE？ JDK 9+ 缺 JAXB，pom 加 javax.xml.bind:jaxb-api:2.3.1 重新打包，或把该 jar 放进 WEB-INF/lib。

Q5：Tobago 4.6.0 工程在 JDK 8 构建部署时报 Using unknown version attribute '5.1'？ 4.x 解析器只认 tobago-config.xml 的 version="4.0"，把工程内该属性从 5.1 改为 4.0 即可（实测改后 HTTP 200）。

十二、卸载与清理

# 停止并移除 Tomcat
/opt/apache-tomcat-9.0.123/bin/shutdown.sh
rm -rf /opt/apache-tomcat-9.0.123 /opt/apache-tomcat-9.0.123.tar.gz /etc/systemd/system/tomcat.service
systemctl daemon-reload
# 移除工程产物
rm -rf /opt/tobago-demo /opt/blank.war
# 移除 JDK（可选）
dnf remove -y java-17-openjdk java-17-openjdk-devel

确认清理结果：

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/
Apache Tomcat 9 下载：https://downloads.apache.org/tomcat/tomcat-9/
阿里云 CentOS Vault：https://mirrors.aliyun.com/centos-vault/
CentOS 8 EOL 说明：https://www.centos.org/centos-linux-eol/