1. 系統要求

在安裝 Keycloak 26.x 之前，請確保您的系統符合以下要求：

• 爪哇：JDK 17 或 21（推薦 OpenJDK 21）

• 資料庫：PostgreSQL 13-16（推薦）、MySQL 8.0+、MariaDB 10.6+

• 記憶體：至少 512MB（建議 2GB+ 用於生產）

• 中央處理器：至少 1 個核心（建議生產時使用 2 個以上核心）

• 作業系統：Linux（Ubuntu 22.04/24.04、CentOS 9、RHEL 9）、macOS、Windows

2. 在裸機上安裝 (Ubuntu)

2.1.安裝Java 21

sudo apt update
sudo apt install -y openjdk-21-jdk
java -version

2.2.安裝 PostgreSQL

sudo apt install -y postgresql postgresql-contrib
sudo systemctl enable postgresql
sudo systemctl start postgresql
Tạo database và user cho Keycloak
sudo -u postgres psql -c "CREATE USER keycloak WITH PASSWORD 'keycloak_password';"
sudo -u postgres psql -c "CREATE DATABASE keycloak OWNER keycloak;"

2.3.下載並安裝Keycloak

# Tải Keycloak 26.5.x
cd /opt
wget https://github.com/keycloak/keycloak/releases/download/26.5.6/keycloak-26.5.6.tar.gz
tar -xzf keycloak-26.5.6.tar.gz
ln -s keycloak-26.5.6 keycloak
Cấu hình database
cat > /opt/keycloak/conf/keycloak.conf << 'EOF'
Database
db=postgres
db-url-host=localhost
db-url-port=5432
db-url-database=keycloak
db-username=keycloak
db-password=keycloak_password
Hostname
hostname=keycloak.example.com
HTTP
http-enabled=true
http-port=8080
EOF
Chạy development mode
/opt/keycloak/bin/kc.sh start-dev

2.4.建立管理員用戶

# Tạo admin user khi start
KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin \
  /opt/keycloak/bin/kc.sh start-dev
Hoặc dùng lệnh bootstrap
/opt/keycloak/bin/kc.sh bootstrap-admin user 

--username admin --password admin

3. 使用 Docker 和 Docker Compose 安裝

3.1.簡單的 Docker（開發）

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.5.6 \
  start-dev

3.2. Docker Compose（生產就緒）

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5
keycloak:
image: quay.io/keycloak/keycloak:26.5.6
command: start
environment:
KC_DB: postgres
KC_DB_URL_HOST: postgres
KC_DB_URL_PORT: "5432"
KC_DB_URL_DATABASE: keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: keycloak_password
KC_HOSTNAME: keycloak.example.com
KC_PROXY_HEADERS: xforwarded
KC_HTTP_ENABLED: "true"
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: admin
ports:
- "8080:8080"
depends_on:
postgres:
condition: service_healthy
networks:
- keycloak-network
volumes:
postgres_data:
networks:
keycloak-network:

4. Kubernetes Operator部署

4.1.安裝Keycloak Operator

# Cài đặt Operator qua OperatorHub hoặc manifests
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloaks.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/keycloakrealmimports.k8s.keycloak.org-v1.yml
kubectl apply -f https://raw.githubusercontent.com/keycloak/keycloak-k8s-resources/26.5.6/kubernetes/kubernetes.yml

4.2. Keycloak 自訂資源

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: keycloak
spec:
  instances: 2
  db:
    vendor: postgres
    host: postgres-service
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  hostname:
    hostname: keycloak.example.com
  http:
    httpEnabled: true
  proxy:
    headers: xforwarded
  truststores:
    my-truststore:
      secret:
        name: my-truststore-secret

5. 開發模式與生產模式

標準	開發（啟動-開發）	生產（開始）
資料庫	H2 嵌入（預設）	PostgreSQL/MySQL（必要）
HTTPS	選修的	必需（或代理）
主機名稱	本機（自動）	必須配置主機名
快取	本機快取	分散式快取（Infinispan）
主題緩存	禁用（熱重載）	啟用
建造	無需先構建	你應該先運行 kc.sh build

6.配置HTTPS/TLS

# Tạo keystore với self-signed certificate
keytool -genkeypair -storepass password -storetype PKCS12 \
  -keyalg RSA -keysize 2048 -dname "CN=keycloak.example.com" \
  -alias server -ext "SAN:c=DNS:keycloak.example.com" \
  -keystore /opt/keycloak/conf/server.keystore
Cấu hình trong keycloak.conf
https-certificate-file=/path/to/cert.pem
https-certificate-key-file=/path/to/key.pem
Hoặc
https-key-store-file=/opt/keycloak/conf/server.keystore
https-key-store-password=password

7. 設定反向代理（Nginx）

upstream keycloak {
    server 127.0.0.1:8080;
}
server {
listen 443 ssl http2;
server_name keycloak.example.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;

location / {
    proxy_pass http://keycloak;
    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 $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_buffer_size 128k;
    proxy_buffers 4 256k;
    proxy_busy_buffers_size 256k;
}

}

8.創建Systemd服務

# /etc/systemd/system/keycloak.service
[Unit]
Description=Keycloak Server
After=network.target postgresql.service
[Service]
Type=exec
User=keycloak
Group=keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --optimized
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak