Ubuntu 22.04 安装 Apache MyFaces 4.1.3 指南

Ubuntu 22.04 安装 Apache MyFaces Core 4.1.3（Jakarta Faces 4.1 参考实现）指南：JDK 17 + Maven + Tomcat 10.1.60 环境准备、4.0.x/4.1.x 版本选型、Maven 依赖与手动 jar 两种安装方案、JVM 堆限制与 systemd 托管、验证与卸载，全程实测。

Apache MyFacesApache MyFaces2026/10/12

Ubuntu 22.04 安装 Apache MyFaces 4.1.3 指南

目标：在 Ubuntu 22.04 服务器上完成 Apache MyFaces Core 4.1.3（Jakarta Faces 4.1 规范的 Apache 参考实现，Java jar 库形态）的安装与验证。本文给出 JDK 17 + Maven + Tomcat 10.1.60 环境准备、4.0.x/4.1.x 版本选型对照、Maven 依赖引入与手动下载 jar 两种安装方案、JVM 堆限制与 systemd 托管，以及验证与卸载方式。所有命令与回显均在 Ubuntu 22.04.5 + JDK 17 + Tomcat 10.1.60 环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（VERSION_CODENAME=jammy）
  • 架构：x86_64
  • Java：OpenJDK 17.0.20.1（openjdk-17-jdk-headless，Ubuntu 官方源）
  • 构建工具：Apache Maven 3.6.3（Ubuntu 官方源）
  • Web 服务器：Apache Tomcat 10.1.60（官方二进制包，安装于 /opt/tomcat，端口 8080）
  • MyFaces 版本：Apache MyFaces Core 4.1.3（myfaces-api-4.1.3.jar / myfaces-impl-4.1.3.jar，来源 Maven Central）
  • 管理账号：admin，密码 q1w2e3r4（Tomcat Manager 管理页面）
  • jar 安装目录：/opt/myfaces/jars/；Maven 本地仓库：/root/.m2/repository/

💡 说明：Apache MyFaces 是 Jakarta Faces（JSF）规范的开源实现，以 Java jar 库形态发布（org.apache.myfaces.core 组的 myfaces-api 与 myfaces-impl），本身没有可执行守护进程或独立服务端口。所谓「安装」指两件事：① 准备好 JDK / 构建环境与 Web 服务器（本环境为 Tomcat 10.1.60）；② 把 myfaces-api / myfaces-impl 两个 jar 以 Maven 依赖或 classpath 方式引入你的 Web 工程。JSF 应用的对外入口是 Web 服务器端口（本环境 8080）。

二、前置条件

2.1 更新软件源

sudo apt-get update

2.2 安装 JDK 17、Maven 与基础工具

MyFaces Core 4.x 的 class 文件版本为 61.0，对应 JDK 17，因此必须安装 JDK 17（Ubuntu 22.04 官方源已内置）：

sudo apt-get install -y openjdk-17-jdk-headless maven wget unzip curl

验证 JDK 与 Maven：

java -version
mvn -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)

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

⚠️ 注意：mvn -version 中的 Java version 必须为 17 才表示 Maven 正在使用 JDK 17。若显示其他版本，请先执行 export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 与 export PATH=$JAVA_HOME/bin:$PATH 再重试。

2.3 安装 Web 服务器 Tomcat 10.1.60

MyFaces 4.x 需要 Servlet 6.0（对应 Tomcat 10.1.x）。从 Apache 官方 CDN 下载当前最新稳定版并校验：

cd /tmp
wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.60/bin/apache-tomcat-10.1.60.tar.gz
wget https://dlcdn.apache.org/tomcat/tomcat-10/v10.1.60/bin/apache-tomcat-10.1.60.tar.gz.sha512
sha512sum -c apache-tomcat-10.1.60.tar.gz.sha512

实测回显：

apache-tomcat-10.1.60.tar.gz: OK

解压安装到 /opt/tomcat 并确认版本：

mkdir -p /opt/tomcat
tar -xzf apache-tomcat-10.1.60.tar.gz -C /opt/tomcat --strip-components=1
/opt/tomcat/bin/version.sh

实测回显（节选）：

Server version: Apache Tomcat/10.1.60
JVM Version:    17.0.20.1+1-1-22.04-Ubuntu
JVM Vendor:     Ubuntu

💡 说明：Tomcat 10.1 自带 Servlet 6.0 / JSP / EL / WebSocket 实现，但不内置 Jakarta Faces 与 CDI。MyFaces 4.x 的托管 Bean 需要 CDI 运行环境，因此应用工程里还要引入 Weld（weld-servlet-shaded），见下一节与《构建并运行示例应用指南》。

2.4 限制 JVM 堆内存（256–512MB）

创建 /opt/tomcat/bin/setenv.sh 固定堆内存区间：

cat > /opt/tomcat/bin/setenv.sh <<'EOF'
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export CATALINA_OPTS="-Xms256m -Xmx512m -Xmn128m -Djava.security.egd=file:/dev/urandom"
export CATALINA_PID=/opt/tomcat/temp/catalina.pid
EOF
chmod +x /opt/tomcat/bin/setenv.sh

启动后确认堆参数真实生效：

/opt/tomcat/bin/startup.sh
/usr/lib/jvm/java-17-openjdk-amd64/bin/jps -v | grep Bootstrap

实测回显（节选，注意 -Xms256m -Xmx512m -Xmn128m）：

5629 Bootstrap -Djava.util.logging.config.file=/opt/tomcat/conf/logging.properties ... -Xms256m -Xmx512m -Xmn128m -Djava.security.egd=file:/dev/urandom -Dcatalina.base=/opt/tomcat -Dcatalina.home=/opt/tomcat -Djava.io.tmpdir=/opt/tomcat/temp

2.5 配置 Tomcat 管理账号

编辑 /opt/tomcat/conf/tomcat-users.xml，在 </tomcat-users> 前加入管理用户：

  <role rolename="manager-gui"/>
  <role rolename="admin-gui"/>
  <user username="admin" password="q1w2e3r4" roles="manager-gui,admin-gui"/>

重启 Tomcat 后验证管理页登录（未授权 401，正确账号 200，错误密码 401）：

curl -s -o /dev/null -w "manager_anon=%{http_code}\n" http://127.0.0.1:8080/manager/html
curl -s -o /dev/null -w "manager_auth=%{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:8080/manager/html
curl -s -o /dev/null -w "manager_bad=%{http_code}\n" -u admin:wrongpass http://127.0.0.1:8080/manager/html

实测回显：

manager_anon=401
manager_auth=200
manager_bad=401

2.6 systemd 托管 Tomcat

创建 /etc/systemd/system/tomcat.service 实现开机自启与统一管理：

[Unit]
Description=Apache Tomcat 10.1.60 Web Application Container
After=network.target

[Service]
Type=forking
Environment=JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
Environment=CATALINA_PID=/opt/tomcat/temp/catalina.pid
Environment=CATALINA_OPTS=-Xms256m -Xmx512m -Xmn128m -Djava.security.egd=file:/dev/urandom
ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh
User=root
Group=root

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable tomcat
systemctl start tomcat
systemctl is-active tomcat
systemctl status tomcat --no-pager -l

实测回显：

active

● tomcat.service - Apache Tomcat 10.1.60 Web Application Container
     Loaded: loaded (/etc/systemd/system/tomcat.service; disabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-11 19:40:50 UTC; 10s ago
    Process: 5621 ExecStart=/opt/tomcat/bin/startup.sh (code=exited, status=0/SUCCESS)
   Main PID: 5629 (java)
      Tasks: 59 (limit: 5753)

停止 / 重启循环验证：

systemctl stop tomcat; sleep 3; systemctl is-active tomcat
systemctl start tomcat; sleep 8; systemctl is-active tomcat

实测回显（依次为停止后 inactive、重启后 active）：

inactive
active

三、版本选型说明

3.1 MyFaces Core 版本对照

用 Maven Central 搜索接口探测 org.apache.myfaces.core:myfaces-api 的全部发布版本：

curl -s "https://search.maven.org/solrsearch/select?q=g:org.apache.myfaces.core+AND+a:myfaces-api&core=gav&rows=40&wt=json"

实测当前最新稳定版为 4.1.3，主要版本对照如下：

版本线对应规范class 版本所需 JDK说明
4.1.x（4.1.3）Jakarta Faces 4.161.0JDK 17当前最新稳定主线，包名 jakarta.faces.*
4.0.x（4.0.3）Jakarta Faces 4.061.0JDK 17上一代主线，包名 jakarta.faces.*
2.x / 3.xJavaServer Faces 2.352.0/55.0JDK 8/11旧命名空间 javax.faces.*，仅维护

💡 版本选择建议：新项目一律选 4.1.x 最新稳定版（4.1.3）+ JDK 17 + Tomcat 10.1。只有遗留系统依赖 javax.faces.* 命名空间时才考虑 2.x/3.x 旧线。

3.2 与 Web 服务器的搭配

  • MyFaces Core 4.x 依赖 Servlet 6.0 与 EL 3.0+，需 Tomcat 10.1.x（或 Jetty 12 / WildFly 27+）。
  • 4.x 的托管 Bean 基于 CDI（@Named + @RequestScoped 等），Tomcat 不自带 CDI，需引入 weld-servlet-shaded（实测 5.1.2.Final）。
  • 4.x 已移除 javax.faces.* 旧包名与 org.apache.myfaces.DETECT_JAVASCRIPT、org.apache.myfaces.PRETTY_HTML 等旧参数，配置时统一用 jakarta.faces.* 前缀。

四、安装方案 A：Maven 依赖引入（在线，推荐）

4.1 方案说明

在任意 Maven Web 工程（<packaging>war</packaging>）的 pom.xml 中声明 myfaces-api 与 myfaces-impl 两个依赖，Maven 会自动从中央仓库（或配置的镜像）拉取到本地仓库并打包进 WAR 的 WEB-INF/lib：

  <dependencies>
    <dependency>
      <groupId>org.apache.myfaces.core</groupId>
      <artifactId>myfaces-api</artifactId>
      <version>4.1.3</version>
    </dependency>
    <dependency>
      <groupId>org.apache.myfaces.core</groupId>
      <artifactId>myfaces-impl</artifactId>
      <version>4.1.3</version>
    </dependency>
    <dependency>
      <groupId>jakarta.servlet</groupId>
      <artifactId>jakarta.servlet-api</artifactId>
      <version>6.0.0</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

4.2 不建工程时单独拉取依赖

若只想把 jar 落到本地仓库，可用 dependency:get：

mvn dependency:get -Dartifact=org.apache.myfaces.core:myfaces-api:4.1.3
mvn dependency:get -Dartifact=org.apache.myfaces.core:myfaces-impl:4.1.3

实测返回码均为 0（构建成功）。

4.3 验证 jar 就位

find /root/.m2/repository/org/apache/myfaces/core -name "*.jar" | sort

实测回显：

/root/.m2/repository/org/apache/myfaces/core/myfaces-api/4.1.3/myfaces-api-4.1.3.jar
/root/.m2/repository/org/apache/myfaces/core/myfaces-impl/4.1.3/myfaces-impl-4.1.3.jar

⚠️ 注意：国内服务器建议在 /root/.m2/settings.xml 配置阿里云镜像（https://maven.aliyun.com/repository/public，mirrorOf 为 central）加速依赖下载。

五、安装方案 B：手动下载 jar 放置（离线 / 内网）

5.1 方案说明

内网隔离环境无法访问 Maven 中央仓库时，在可联网机器上下载两个 jar，随工程拷贝部署。

5.2 官方下载

jar 的官方分发地址是 Maven Central（repo.maven.apache.org）：

mkdir -p /opt/myfaces/jars && cd /opt/myfaces/jars
wget https://repo.maven.apache.org/maven2/org/apache/myfaces/core/myfaces-api/4.1.3/myfaces-api-4.1.3.jar
wget https://repo.maven.apache.org/maven2/org/apache/myfaces/core/myfaces-impl/4.1.3/myfaces-impl-4.1.3.jar
ls -l

实测回显：

-rw-r--r-- 1 root root 1231852 myfaces-api-4.1.3.jar
-rw-r--r-- 1 root root 2367961 myfaces-impl-4.1.3.jar

5.3 校验 jar 真实版本

jar 的 META-INF/MANIFEST.MF 内含规格名与版本号：

unzip -p myfaces-api-4.1.3.jar META-INF/MANIFEST.MF | grep -E "Specification-Title|Specification-Version"
unzip -p myfaces-impl-4.1.3.jar META-INF/MANIFEST.MF | grep -E "Specification-Title|Specification-Version"

实测回显：

Specification-Title: Apache MyFaces Core 4.1 - API
Specification-Version: 4.1
Specification-Title: Apache MyFaces Core 4.1 - Impl
Specification-Version: 4.1

确认 class 文件版本与所需 JDK 一致：

javap -verbose -cp myfaces-api-4.1.3.jar jakarta.faces.context.FacesContext | grep "major version"

实测回显：

  major version: 61

💡 major 61 = Java 17。若服务器是 JDK 17，可直接使用；否则需先按 2.2 节升级 JDK。

5.4 集成方式

离线环境二选一：

  • 直接把两个 jar 拷入工程最终 WAR 的 WEB-INF/lib/（如 unzip -j myfaces-api-4.1.3.jar -d /path/to/webapp/WEB-INF/lib/ 或直接用 cp）；
  • 或先注册进 Maven 本地仓库，再按方案 A 的方式声明依赖：
mvn install:install-file -Dfile=/opt/myfaces/jars/myfaces-api-4.1.3.jar \
  -DgroupId=org.apache.myfaces.core -DartifactId=myfaces-api -Dversion=4.1.3 -Dpackaging=jar
mvn install:install-file -Dfile=/opt/myfaces/jars/myfaces-impl-4.1.3.jar \
  -DgroupId=org.apache.myfaces.core -DartifactId=myfaces-impl -Dversion=4.1.3 -Dpackaging=jar

实测返回码均为 0，安装后本地仓库出现对应 jar：

/root/.m2/repository/org/apache/myfaces/core/myfaces-api/4.1.3/myfaces-api-4.1.3.jar

六、多方案对比与选择建议

维度方案 A：Maven 依赖引入方案 B：手动下载 jar
是否需联网需（可配国内镜像加速）下载一次后内网可用
安装方式pom 声明依赖，mvn package 自动打包wget 下载 + 校验 + 拷入 WEB-INF/lib 或 install-file
jar 版本管理随 pom 管理，升级改版本号即可手动替换 jar
适用场景可联网的日常开发/构建机内网隔离、发布机
推荐度推荐（主流）内网环境必备

💡 选择建议：可联网环境用方案 A；离线/内网环境用方案 B（在联网机下载 jar 后随包携带）。

七、配置说明

7.1 web.xml 注册 FacesServlet

MyFaces 通过前端控制器 jakarta.faces.webapp.FacesServlet 接管请求。在 Web 工程的 WEB-INF/web.xml 中注册并映射到 *.xhtml：

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
         version="6.0">
  <display-name>myfaces-demo</display-name>

  <servlet>
    <servlet-name>FacesServlet</servlet-name>
    <servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
  <servlet-mapping>
    <servlet-name>FacesServlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
  </servlet-mapping>

  <welcome-file-list>
    <welcome-file>index.xhtml</welcome-file>
  </welcome-file-list>
</web-app>

💡 MyFaces 的启动顺序：Tomcat 启动时由 org.apache.myfaces.webapp.MyFacesContainerInitializer 自动初始化 Faces 运行环境（无需手动加载 Servlet），首个请求到达时完成 EL 解析器链组装。更完整的应用构建与运行验证见《Apache MyFaces 4.1.3 构建并运行示例应用指南》。

7.2 配置参数入口

MyFaces 的全部配置通过 web.xml 的 <context-param> 注入，两类前缀：

  • 规范级参数：jakarta.faces.*（如 jakarta.faces.PROJECT_STAGE、jakarta.faces.STATE_SAVING_METHOD）；
  • MyFaces 专有参数：org.apache.myfaces.*（如 org.apache.myfaces.CACHE_EL_EXPRESSIONS、org.apache.myfaces.NUMBER_OF_VIEWS_IN_SESSION）。

参数名、默认值与取值详见《Apache MyFaces 4.1.3 配置参数详解》。

八、验证运行

8.1 验证 jar 就位与关键类存在

unzip -l /opt/myfaces/jars/myfaces-api-4.1.3.jar | grep -E "FacesServlet|FacesContext.class" | head -3

实测回显：

     7066  2026-04-30 12:37   jakarta/faces/context/FacesContext.class
     6308  2026-04-30 12:37   jakarta/faces/webapp/FacesServlet.class

8.2 验证 MyFaces 启动日志

部署任意包含 MyFaces 的 WAR（构建方法见《构建并运行示例应用指南》）后，在 /opt/tomcat/logs/catalina.out 中可见 MyFaces 启动关键日志：

org.apache.myfaces.webapp.MyFacesContainerInitializer.onStartup Using org.apache.myfaces.webapp.MyFacesContainerInitializer
org.apache.myfaces.application.ApplicationImpl.getProjectStage Couldn't discover the current project stage, using Production
org.apache.myfaces.webapp.FacesInitializerImpl.initFaces MyFaces Core has started, it took [654] ms.

💡 MyFaces Core has started 即代表 MyFaces 4.1.3 安装并在 Web 服务器中正常初始化完成。

8.3 验证 Tomcat 管理页

curl -s -o /dev/null -w "%{http_code}\n" -u admin:q1w2e3r4 http://127.0.0.1:8080/manager/html

实测回显：

200

九、常见问题

Q1：MyFaces 4.x 报 ClassNotFoundException: javax.faces.context.FacesContext？

原因是 4.x 已把包名迁移到 jakarta.faces.*。请确认：① pom 中的 myfaces-api/impl 是 4.x 版本；② 代码与页面（Facelets 命名空间 xmlns:h="jakarta.faces.html"）全部使用 jakarta.*；③ WAR 里没有混入 2.x 时代的 javax.faces 依赖。

Q2：启动报 class 文件版本错误（UnsupportedClassVersionError，major 61）？

MyFaces 4.x 的 class 版本为 61.0，需要 JDK 17。按 2.2 节安装 openjdk-17-jdk-headless 并确认 mvn -version 的 Java version 为 17。

Q3：日志出现 Both MyFaces and the RI are on your classpath？

MyFaces（Apache RI）与 Oracle Mojarra（RI）同时存在于 classpath 会导致冲突。只保留其一：删除 Mojarra 的 javax.faces-api / com.sun.faces 相关依赖，保留 myfaces-api 与 myfaces-impl。

Q4：部署后访问应用 404？

依次排查：① WAR 是否拷贝到 /opt/tomcat/webapps/（文件名即上下文路径，如 myfaces-demo.war → /myfaces-demo/）；② web.xml 的 FacesServlet 是否映射 *.xhtml 且 index.xhtml 是否存在于 WAR 根目录；③ Tomcat 是否已 systemctl is-active tomcat 为 active。

Q5：Tomcat Manager 页面返回 401？

tomcat-users.xml 中必须配置 manager-gui 角色且账号角色匹配（参考 2.5 节）。注意 Tomcat 10.1 已移除 manager 角色名，改用 manager-gui / manager-script / manager-jmx。

十、卸载方式

10.1 移除 Maven 依赖与本地仓库

rm -rf /root/.m2/repository/org/apache/myfaces

10.2 移除手动放置的 jar

rm -rf /opt/myfaces

10.3 移除 Tomcat 及托管

systemctl stop tomcat
systemctl disable tomcat
rm -f /etc/systemd/system/tomcat.service
systemctl daemon-reload
rm -rf /opt/tomcat

💡 若同时不再需要 JDK/Maven，可执行 sudo apt-get remove -y openjdk-17-jdk-headless maven。

十一、参考链接