如何在带cPanel的AlmaLinux上用子域名代替端口运行服务？

一、先启用Apache代理模块 #

这是你之前配置失效的核心原因，WHM/cPanel默认未开启反向代理所需模块：

• 登录WHM，进入「软件」>「EasyApache 4」
• 选择「自定义」当前配置，找到「Apache模块」标签
• 勾选以下模块：
  • proxy
  • proxy_http
  • proxy_html（可选，用于修正页面内的静态资源路径）
• 点击「开始定制」，等待编译完成后Apache会自动重启

二、正确配置反向代理虚拟主机 #

使用WHM的「包含编辑器」添加配置，推荐选择后虚拟主机包含（针对mysubdomain.mymaindomain.com的特定包含，而非全局），添加以下代码：

# HTTP 80端口配置
<VirtualHost *:80>
    ServerName mysubdomain.mymaindomain.com

    # 保留原始请求主机头，让Keycloak识别真实域名
    ProxyPreserveHost On
    # 转发所有请求到本地8080端口
    ProxyPass / http://localhost:8080/
    # 重写响应中的URL为子域名
    ProxyPassReverse / http://localhost:8080/

    # 告诉Keycloak用户使用的协议和端口，避免生成带8080的跳转链接
    RequestHeader set X-Forwarded-Proto "http"
    RequestHeader set X-Forwarded-Port "80"
</VirtualHost>

# HTTPS 443端口配置（AutoSSL生效后添加）
<VirtualHost *:443>
    ServerName mysubdomain.mymaindomain.com

    ProxyPreserveHost On
    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/

    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Port "443"

    # AutoSSL会自动生成SSL证书配置，无需手动添加
</VirtualHost>

三、调整Keycloak配置适配反向代理 #

修改Keycloak配置文件，让它识别代理环境：

针对Keycloak 17+（Quarkus版本） #

编辑/opt/keycloak/conf/keycloak.conf，添加：

proxy=edge
hostname=mysubdomain.mymaindomain.com
hostname-strict=true

针对Keycloak 16及以下（WildFly版本） #

编辑/opt/keycloak/standalone/configuration/standalone.xml：

1. 找到<subsystem xmlns="urn:jboss:domain:undertow:*">下的<http-listener>，添加proxy-address-forwarding="true"：

<http-listener name="default" socket-binding="http" redirect-socket="https" proxy-address-forwarding="true"/>

2. 找到<subsystem xmlns="urn:jboss:domain:keycloak-server:*">，添加：

<proxy-edge>true</proxy-edge>
<hostname>mysubdomain.mymaindomain.com</hostname>

修改完成后重启Keycloak：

systemctl restart keycloak

四、故障排查步骤 #

如果配置后仍无法访问，按以下顺序排查：

• 检查Apache错误日志：查看/usr/local/apache/logs/error_log，确认是否有代理模块加载失败、配置语法错误等信息
• 验证本地访问：在服务器上执行curl http://localhost:8080，确认Keycloak服务本身正常运行
• 防火墙配置：确保8080端口仅允许本地访问（可通过iptables -A INPUT -p tcp --dport 8080 -s 127.0.0.1 -j ACCEPT配置），同时对外开放80/443端口
• AutoSSL状态：在WHM「SSL/TLS」>「Manage AutoSSL」中检查子域名的证书是否已成功颁发并生效
• 清除缓存：用浏览器无痕模式测试，避免旧重定向缓存干扰

内容的提问来源于stack exchange，提问作者Tijs Klaren