本指南将介绍如何在 NGINX 反向代理之后安装 Keycloak，使用 Let’s Encrypt 实现 SSL 终止，并使用已有的 MariaDB 数据库。Keycloak 将以非系统用户身份运行，并配置为生产模式。
前提条件
- 一台 Ubuntu 24.04 服务器
- 一个已指向服务器的公网域名（如：
keycloak.maksonlee.com） - 已部署的 MariaDB 数据库
- 已安装的 NGINX
- 已开放的 80 和 443 端口
- 在 MariaDB 中创建 Keycloak 数据库和用户
sudo mysql -u root -p
进入 MariaDB 后执行：
CREATE DATABASE keycloak;
CREATE USER 'keycloak'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'localhost';
FLUSH PRIVILEGES;
EXIT;
- 安装 Java 21
sudo apt update
sudo apt install openjdk-21-jdk -y
java -version
- 下载并安装 Keycloak
wget https://github.com/keycloak/keycloak/releases/download/26.2.0/keycloak-26.2.0.tar.gz
tar -xvzf keycloak-26.2.0.tar.gz
sudo mv keycloak-26.2.0 /opt/keycloak
sudo useradd -m keycloak
sudo chown -R keycloak:keycloak /opt/keycloak
- 添加 MariaDB JDBC 驱动
sudo wget https://downloads.mariadb.com/Connectors/java/connector-java-3.5.3/mariadb-java-client-3.5.3.jar -O /opt/keycloak/providers/mariadb.jar
sudo chown keycloak:keycloak /opt/keycloak/providers/mariadb.jar
- 配置 Keycloak
sudo su - keycloak
编辑 /opt/keycloak/conf/keycloak.conf：
db=mariadb
db-username=keycloak
db-password=your_secure_password
db-url=jdbc:mariadb://localhost:3306/keycloak
hostname=keycloak.maksonlee.com
http-enabled=true
http-host=127.0.0.1
proxy-headers=xforwarded
- 构建 Keycloak
cd /opt/keycloak
bin/kc.sh build
exit
- 添加初始 NGINX 配置（尚未启用 SSL）
在运行 Certbot 之前，先添加一个简单配置：
server {
listen 80;
server_name keycloak.maksonlee.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
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 http;
}
}
保存为：
/etc/nginx/sites-enabled/keycloak
然后重载 NGINX：
sudo nginx -t && sudo systemctl reload nginx
- 使用 Certbot 获取 SSL 证书
sudo certbot --nginx -d keycloak.maksonlee.com
Certbot 将自动更新 NGINX 配置并启用 SSL。
- 最终 NGINX 配置（包含 SSL 与 Headers）
确认最终配置如下：
server {
server_name keycloak.maksonlee.com;
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/keycloak.maksonlee.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/keycloak.maksonlee.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
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 https;
proxy_set_header X-Forwarded-Port 443;
proxy_set_header X-Forwarded-Host $host;
proxy_http_version 1.1;
proxy_set_header Connection "";
}
}
server {
listen 80;
server_name keycloak.maksonlee.com;
return 301 https://$host$request_uri;
}
- 动 Keycloak 并设置临时管理员账号
sudo su - keycloak
export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=admin
export JAVA_OPTS="-Xms128m -Xmx128m"
cd /opt/keycloak
bin/kc.sh start
现在可以访问：
https://keycloak.maksonlee.com
使用上面的临时账户登录，系统会提示你创建永久管理员账户。
- 将 Keycloak 设为 systemd 服务
创建服务单元文件：
sudo vi /etc/systemd/system/keycloak.service
粘贴以下内容：
[Unit]
Description=Keycloak Server
After=network.target
[Service]
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --http-host=127.0.0.1
Restart=always
Environment=JAVA_OPTS=-Xms128m -Xmx128m
[Install]
WantedBy=multi-user.target
启用并启动服务：
sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak
Keycloak 现已通过 NGINX 启用 SSL 终止安全运行，后端使用 MariaDB 存储数据。