在 Docker 中使用 Nginx 反向代理配置 Keycloak v26：解决各个领域的控制台问题

在 Docker 中将 Nginx 设置为 Keycloak 的反向代理

Keycloak 代理的 Nginx 配置后端解决方案

upstream sso-mydomain-com {
    server 10.10.0.89:8080;
}
server {
    listen 443 ssl;
    server_name sso.mydomain.com;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}
server {
    listen 8443 ssl;
    server_name sso.mydomain.com;
    error_log /usr/local/nginx/logs/sso_err.log debug;
    location / {
        proxy_pass http://sso-mydomain-com/;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

Keycloak Docker 使用环境变量撰写配置

用于使用环境变量设置 Keycloak 的 Docker Compose 文件

version: '3.9'
services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - "8080:8080"
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

Keycloak API 端点验证的单元测试

基于 Python 的单元测试来验证 Keycloak /whoami 端点响应

import requests
def test_whoami_endpoint():
    url = "https://sso.mydomain.com:8443/auth/admin/master/console/whoami?currentRealm=master"
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.get(url, headers=headers, verify=True)
        assert response.status_code == 200, "Expected 200 OK, got {}".format(response.status_code)
        print("Test passed: whoami endpoint accessible")
    except requests.ConnectionError:
        print("Connection error: Check Nginx reverse proxy and Keycloak availability")
    except AssertionError as e:
        print("Assertion error:", e)
# Run the test
test_whoami_endpoint()

替代方法：使用 Nginx 故障转移进行 Keycloak 健康检查

Bash 脚本对 Keycloak 执行健康检查并在需要时重新启动 Nginx

#!/bin/bash
# Check if Keycloak is reachable via the /whoami endpoint
URL="http://10.10.0.89:8080/auth/admin/master/console/whoami"
STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL)
if [ "$STATUS_CODE" -ne 200 ]; then
    echo "Keycloak endpoint unavailable, restarting Nginx..."
    docker restart nginx
else
    echo "Keycloak endpoint is healthy."
fi

有关使用 Nginx 和 Docker 的 Keycloak 的常见问题

1. 在 Nginx 中使用 Keycloak 时如何解决 502 Bad Gateway 错误？
2. 要排查 502 错误，请检查 Nginx 配置并确保 proxy_pass URL与Keycloak的容器地址和端口相匹配。另外，验证 Keycloak 正在运行并且可以通过内部网络访问。
3. 我可以将 SSL 终止与 Nginx 用于 Keycloak 一起使用吗？
4. 是的，Nginx 的 SSL 终止很常见。配置 ssl_certificate 和 ssl_certificate_key 在 Nginx 上处理传入请求的 HTTPS。然后 Keycloak 可以通过 HTTP 进行通信。
5. 如何对多个 Keycloak 实例进行负载平衡？
6. 定义一个 upstream Nginx 中的每个 Keycloak 实例都被阻止。放 proxy_pass 到上游服务器，Nginx 将在所有实例之间分发请求。
7. 在 Docker 中保护 Keycloak 环境变量的最佳实践是什么？
8. 使用 env_file 在 Docker Compose 中存储敏感数据，避免硬编码值。此外，对环境文件设置适当的权限以限制访问。
9. 如何在 Nginx 中自动更新 SSL 证书？
10. Let’s Encrypt 等工具可自动更新证书。更新后，使用脚本重新加载Nginx，使新证书生效，而无需重新启动容器。
11. Keycloak可以通过Nginx监控其健康状况吗？
12. 是的，用一个简单的脚本， curl 可以检查Keycloak的端点状态。发生故障时，重新启动 Nginx 或容器，以保持可用性和响应能力。
13. 是否可以通过 Nginx 日志解决 Keycloak 登录问题？
14. 放 error_log 在 Nginx 中 debug 临时级别以捕获详细日志，帮助诊断身份验证和访问问题。
15. 如何确保跨多个 Keycloak 实例的会话持久性？
16. 在 Nginx 中配置粘性会话，使用户保持连接到同一个 Keycloak 实例，从而减少由于会话更改而导致的登录问题。
17. 我可以通过自定义域访问 Keycloak 的管理控制台吗？
18. 是的，设置 KC_HOSTNAME 将 Keycloak 的环境变量添加到自定义域中。确保域在 Nginx 中正确路由。
19. 如何验证 Nginx 是否正确配置了 Keycloak？
20. 配置完成后，使用 curl 检查端点是否正确响应，或访问管理控制台并检查是否有错误。另外，监视日志中是否有任何连接问题。

总结：配置 Keycloak 和 Nginx 的要点

在 Nginx 反向代理后面配置 Keycloak 对于保护和管理访问非常有效。但是，由于配置错误，经常会出现“502 Bad Gateway”等错误和与领域相关的控制台问题。通过仔细分析日志、检查 SSL 和代理设置以及验证网络路径，您可以排除故障并优化您的设置。

通过这个过程，我们展示了容器化、代理设置和环境变量如何协同工作来稳定 Keycloak 的管理控制台。无论是负载平衡、SSL 卸载还是无缝身份验证，配置良好的设置都可以提供适合各种生产环境的弹性身份验证解决方案。 🔧