本指南將說明如何在 NGINX 反向代理後安裝 Keycloak，透過 Let’s Encrypt 進行 SSL 終止，並使用現有的 MariaDB 資料庫。Keycloak 將以非系統使用者身份執行並配置為生產環境使用。
先決條件
- Ubuntu 24.04 伺服器一台
- 公網網域名稱已指向伺服器（例如：
keycloak.maksonlee.com） - 已安裝並設定好的 MariaDB
- 已安裝的 NGINX
- 開啟 TCP 80 與 443 連接埠
- 在 MariaDB 中建立 Keycloak 資料庫與使用者
sudo mysql -u root -p
進入 MariaDB shell 後輸入：
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 Driver
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）
建立 /etc/nginx/sites-enabled/keycloak 檔案並填入：
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 與標頭）
請確認 /etc/nginx/sites-enabled/keycloak 最終設定如下：
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 作為後端儲存。