如何开启Keycloak维护模式？将用户仪表板重定向至维护页

Keycloak本身没有原生的“维护模式”开关，但可以通过以下几种方案实现需求，且均支持手动切换：

方案一：自定义主题+系统属性手动切换 #

这种方式无需额外依赖，通过修改Keycloak账户主题实现重定向逻辑，配合系统属性控制开关：

1. 修改账户主题模板
   找到当前使用的账户主题目录（默认路径为themes/base/account，自定义主题则在对应目录），编辑核心模板文件（如template.ftl），添加维护模式判断与重定向逻辑：

   <#if System.getProperty("keycloak.maintenance.mode") == "true">
       <meta http-equiv="refresh" content="0;url=/maintenance.html">
   </#if>
   

2. 创建维护页面
   将你的维护页面（如maintenance.html）放到主题的静态资源目录（如themes/base/account/resources），确保Keycloak能访问到该页面。

3. 手动切换维护模式

   • 启动时开启：在Keycloak启动命令中添加系统属性

     ./kc.sh start -Dkeycloak.maintenance.mode=true
     

   • 运行时切换：通过JMX工具（如JConsole）连接Keycloak进程，找到java.lang下的SystemProperties，修改keycloak.maintenance.mode的值为true（开启）或false（关闭），无需重启服务。

方案二：反向代理（以Nginx为例）手动切换 #

通过反向代理层拦截请求，实现重定向，适合不想修改Keycloak主题的场景：

1. 配置Nginx反向代理
   在Nginx配置中添加维护模式判断与重定向规则：

   server {
       listen 443 ssl;
       server_name your-kc-domain.com;
   
       # 手动维护开关：on=开启，off=关闭
       set $maintenance_mode on;
   
       # 拦截所有客户账户仪表板请求，重定向到维护页面
       if ($maintenance_mode = on) {
           rewrite ^/realms/([^/]+)/account(/.*)?$ /maintenance.html permanent;
       }
   
       # 正常转发Keycloak请求
       location / {
           proxy_pass http://localhost:8080;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   
       # 维护页面静态资源路径
       location /maintenance.html {
           root /usr/share/nginx/html;
       }
   }
   

2. 手动切换维护模式
   修改Nginx配置中的$maintenance_mode值为on或off，然后重载配置即可：

   nginx -s reload
   

以上两种方案都能实现将用户账户仪表板等面向客户的页面重定向到维护页面，且支持手动快速切换。

内容的提问来源于stack exchange，提问作者mohamed hamada