第八章：生产实践¶

本章总结 OAuth2/OIDC 在生产环境中的最佳实践。

架构设计¶

高可用架构¶

┌─────────────────────────────────────────────────────────────┐
│               生产环境认证架构                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   Load Balancer                     │   │
│  └──────────────────────────┬──────────────────────────┘   │
│                             │                               │
│         ┌───────────────────┼───────────────────┐          │
│         │                   │                   │          │
│         ▼                   ▼                   ▼          │
│  ┌──────────┐        ┌──────────┐        ┌──────────┐     │
│  │ Keycloak │        │ Keycloak │        │ Keycloak │     │
│  │  Node 1  │        │  Node 2  │        │  Node 3  │     │
│  └──────────┘        └──────────┘        └──────────┘     │
│         │                   │                   │          │
│         └───────────────────┼───────────────────┘          │
│                             │                               │
│                             ▼                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              PostgreSQL Cluster                     │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │   │
│  │  │ Primary  │  │ Replica  │  │ Replica  │          │   │
│  │  └──────────┘  └──────────┘  └──────────┘          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

部署配置¶

Keycloak 生产配置¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
  namespace: auth
spec:
  replicas: 3
  selector:
    matchLabels:
      app: keycloak
  template:
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
          - labelSelector:
              matchLabels:
                app: keycloak
            topologyKey: kubernetes.io/hostname
      containers:
      - name: keycloak
        image: quay.io/keycloak/keycloak:23.0
        args: ["start"]
        env:
        - name: KC_DB
          value: postgres
        - name: KC_DB_URL
          value: jdbc:postgresql://postgres:5432/keycloak
        - name: KC_DB_USERNAME
          valueFrom:
            secretKeyRef:
              name: keycloak-db
              key: username
        - name: KC_DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: keycloak-db
              key: password
        - name: KC_HOSTNAME
          value: auth.example.com
        - name: KC_HOSTNAME_STRICT
          value: "false"
        - name: KC_PROXY
          value: edge
        - name: KC_HTTP_ENABLED
          value: "true"
        - name: KC_HEALTH_ENABLED
          value: "true"
        - name: KC_METRICS_ENABLED
          value: "true"
        ports:
        - containerPort: 8080
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 2000m
            memory: 2Gi

监控告警¶

Prometheus 配置¶

scrape_configs:
  - job_name: 'keycloak'
    static_configs:
      - targets: ['keycloak:8080']
    metrics_path: /metrics

关键指标¶

指标	说明	告警阈值
keycloak_logins	登录次数	异常增长
keycloak_logins_failed	登录失败	> 10/min
keycloak_response_time	响应时间	P99 > 500ms
jvm_memory_used	内存使用	> 80%

告警规则¶

groups:
- name: keycloak-alerts
  rules:
  - alert: KeycloakHighLoginFailures
    expr: rate(keycloak_logins_failed[5m]) > 10
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "High login failure rate"

  - alert: KeycloakHighResponseTime
    expr: histogram_quantile(0.99, rate(keycloak_response_time_bucket[5m])) > 0.5
    for: 5m
    labels:
      severity: warning
    annotations:
      summary: "High response time"

备份恢复¶

数据库备份¶

#!/bin/bash
# PostgreSQL 备份
pg_dump -h postgres -U keycloak keycloak > /backup/keycloak_$(date +%Y%m%d).sql

# 上传到 S3
aws s3 cp /backup/keycloak_$(date +%Y%m%d).sql s3://backup-bucket/keycloak/

配置导出¶

# 导出 Realm 配置
/opt/keycloak/bin/kcadm.sh export \
  --realm my-app \
  --file /backup/realm-export.json \
  --server http://localhost:8080 \
  --user admin \
  --password admin

运维手册¶

日常检查¶

# 检查服务状态
curl http://keycloak:8080/health

# 检查数据库连接
curl http://keycloak:8080/health/ready

# 检查指标
curl http://keycloak:8080/metrics

故障处理¶

登录失败：

# 检查日志
kubectl logs -n auth -l app=keycloak --tail=100

# 检查数据库连接
kubectl exec -n auth keycloak-pod -- curl localhost:8080/health/ready

Token 验证失败：

# 检查 JWKS 端点
curl http://keycloak:8080/realms/my-app/.well-known/jwks.json

# 检查客户端配置
/opt/keycloak/bin/kcadm.sh get clients/my-client \
  -r my-app \
  --server http://localhost:8080

最佳实践总结¶

1. 架构设计¶

多实例高可用
数据库主从复制
负载均衡

2. 安全配置¶

强制 HTTPS
短期令牌
PKCE 保护

3. 性能优化¶

连接池配置
缓存优化
数据库索引

4. 监控告警¶

健康检查
指标收集
异常告警

5. 运维保障¶

自动备份
故障预案
文档完善

小结¶

OAuth2/OIDC 生产实践要点：

架构设计：高可用、可扩展
部署配置：Kubernetes、资源规划
监控告警：健康检查、指标监控
备份恢复：数据库备份、配置导出
运维保障：日常检查、故障处理

完成本教程后，你应该能够在生产环境中部署和管理 OAuth2/OIDC 认证系统。