# RAGFlow + Keycloak 生产级 HTTPS 标准接入方案

下面给你一套**RAGFlow + Keycloak 生产级 HTTPS 标准接入方案（可落地）**。我按“正确架构 → Keycloak → Nginx → RAGFlow → 验证步骤”完整给你一步一步拆开。

---

# 一、标准企业架构（必须先搞清）

推荐结构：

```text
Browser
   ↓ HTTPS（443）
Nginx（TLS终止）
   ↓ HTTP 内网
RAGFlow (9380)
Keycloak (8081)
PostgreSQL

```

---

# 二、核心原则（避免你现在的坑）

必须统一三点：

### ✔ 1. 外部必须 HTTPS

### ✔ 2. 内部全部 HTTP

### ✔ 3. Keycloak 必须信任 X-Forwarded headers

---

# 三、第一步：准备 HTTPS（Nginx）

## 1. 生成证书（测试环境）

```bash
cd /home/shuncom/ragflow-main/docker

mkdir -p /nginx/ssl

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout ./nginx/ssl/key.pem \
  -out ./nginx/ssl/cert.pem \
  -subj "/CN=192.168.4.16"

```

---

## 2. Nginx HTTPS 配置（核心）

```nginx
server {
    listen 80;
    server_name 192.168.4.16;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name 192.168.4.16;

    ssl_certificate     /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    # =========================
    # RAGFlow 前端
    # =========================
    root /ragflow/web/dist;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # =========================
    # RAGFlow API
    # =========================
    location ^~ /api/ {
        proxy_pass http://127.0.0.1:9380;
        include proxy.conf;

        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /v1/ {
        proxy_pass http://127.0.0.1:9380;
        include proxy.conf;

        proxy_set_header X-Forwarded-Proto https;
    }

    location ^~ /api/v1/admin {
        proxy_pass http://127.0.0.1:9381;
        include proxy.conf;
    }

    # =========================
    # Keycloak 反代（重点）
    # =========================
    location /auth/ {
        proxy_pass http://127.0.0.1:8081/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-Port 443;
    }
}

```

---

# 四、第二步：Keycloak HTTPS 正确配置（关键）

你的 docker-compose：

```yaml
keycloak:
  image: quay.io/keycloak/keycloak:24.0
  command: start-dev

  environment:
    KEYCLOAK_ADMIN: admin
    KEYCLOAK_ADMIN_PASSWORD: admin123

    KC_DB: postgres
    KC_DB_URL_HOST: postgres
    KC_DB_URL_DATABASE: keycloak
    KC_DB_USERNAME: keycloak
    KC_DB_PASSWORD: keycloak123

    # =========================
    # 核心HTTPS/代理配置
    # =========================
    KC_PROXY: edge
    KC_PROXY_HEADERS: xforwarded

    KC_HTTP_ENABLED: "true"
    KC_HOSTNAME: 192.168.4.16
    KC_HOSTNAME_STRICT: "false"
    KC_HOSTNAME_STRICT_HTTPS: "false"

    KC_HOSTNAME_PORT: 443

  ports:
    - "8081:8080"

```

---

# 五、第三步：RAGFlow OIDC 配置

在 `service_conf.yaml.template`：

```yaml
oauth:
  oidc:
    display_name: "SSO Login"
    client_id: "ragflow"
    client_secret: "xxx"

    issuer: "https://192.168.4.16/auth/realms/shuncom"

    scope: "openid email profile"

    redirect_uri: "https://192.168.4.16/api/v1/auth/login/oidc"

```

---

# 六、第四步：Keycloak 客户端配置（关键）

在 Keycloak 控制台：

## Client 配置：

### ✔ Valid Redirect URIs（必须）

```text
https://192.168.4.16/api/v1/auth/login/oidc

```

或（推荐通配）：

```text
https://192.168.4.16/*

```

---

### ✔ Web Origins

```text
https://192.168.4.16

```

---

### ✔ Access Type

```
confidential

```

---

### ✔ Standard Flow

```
ON

```

---

# 七、第五步：必须避免的坑（非常重要）

## ❗ 坑1：不能混 HTTP / HTTPS

必须统一：

- ❌ [http://192.168.4.16](http://192.168.4.16/)
- ✔ [https://192.168.4.16](https://192.168.4.16/)

---

## ❗ 坑2：Keycloak 必须信任 X-Forwarded-Proto

否则 cookie 会错：

```text
Secure cookie rejected

```

---

## ❗ 坑3：redirect\_uri 必须 HTTPS

---

# 八、第六步：验证流程

## 1. 测试 HTTPS

```bash
curl -k https://192.168.4.16

```

---

## 2. 测试 Keycloak

```text
https://192.168.4.16/auth

```

---

## 3. 测试 OIDC

登录：

```
https://192.168.4.16

```

---

# 九、你当前问题本质总结

你之前的问题全部来自：

> ❌ Keycloak + Nginx 没统一 HTTPS scheme（X-Forwarded-Proto错误）

---

# 十、企业级稳定版架构（推荐最终形态）

```text
Nginx（HTTPS）
   ↓
Keycloak（HTTP 内网）
   ↓
RAGFlow（HTTP 内网）

```

---

# 十一、如果你要一步到位（强烈建议）

我可以帮你直接升级成：

## ✔ 企业级SSO完整生产架构

包含：

- HTTPS + Nginx标准配置
- Keycloak OIDC 完整修复
- RAGFlow 登录不循环
- AD/LDAP自动同步
- 角色映射
- 多域名SSO

---

只要你说一句：

> “做企业级SSO最终生产架构”

我可以直接给你一套**可以上线用的完整配置（避免你现在所有坑）**。