🔗 Redis WebSocket 支持

注意

本教程由社区贡献，不受 Open WebUI 团队支持。它仅作为如何针对特定用例自定义 Open WebUI 的演示。想要做出贡献？请查看贡献教程。

Overview

本篇文档概述了将 Redis 与 Open WebUI 集成以支持 WebSocket 的必要步骤。通过遵循这些步骤，您将能够在您的 Open WebUI 实例中启用 WebSocket 功能，从而实现客户端与应用程序之间的实时通信和更新。

When is Redis Required?

Redis 在 Open WebUI 中服务于两个不同的目的，理解何时需要它对于正确部署至关重要。有关所有扩缩容要求（PostgreSQL、Redis、向量数据库、存储）的高级概述，请参阅扩展 Open WebUI (Scaling Open WebUI) 指南。

Single Instance Deployments

如果您将 Open WebUI 作为单实例运行，且 UVICORN_WORKERS=1（默认值），那么 Redis 对于基础功能不是必需的。在没有它的情况下，应用程序的绝大多数操作仍能正常运行。

安全提示：令牌吊销需要 Redis

在没有 Redis 的情况下，退出登录并不会使用户的 JWT 令牌失效。该令牌在自然过期之前（默认：4 周）将一直有效且可用。在没有 Redis 的情况下，修改密码和管理员发起的账户停用也无法吊销现有令牌。

对于面向生产环境的部署，请配置 Redis 或缩短 JWT_EXPIRES_IN 以限制暴露窗口。有关详细信息，请参阅安全加固 (Hardening) 指南。

Multi-Worker and Multi-Instance Deployments

在以下场景中，Redis 变得必不可少：

多个 Uvicorn Workers (UVICORN_WORKERS > 1)
- 在单台主机上运行多个工作进程 (worker processes)
- 需要 Redis 在各个 worker 之间共享会话状态和应用程序配置
多节点部署 (Multi-Node Deployments)
- 拥有多个 Pod 的 Kubernetes 集群
- 拥有多个副本的 Docker Swarm
- 具有多个 Open WebUI 实例的负载均衡设置
- 需要 Redis 来协调所有实例之间的状态
高可用设置 (High Availability Setups)
- 多个 Open WebUI 进程同时运行的任何部署模式
- 需要 Redis 进行会话管理、WebSocket 协调和状态同步

注意

关键要求

在多 worker 或多实例场景中，如果没有配置 Redis，您将遇到：

跨 worker 的会话管理失败
实例之间的应用程序状态不一致
无法正常工作的 WebSocket 连接
断断续续的身份验证失败
实时聊天更新丢失

Prerequisites

一个有效的 Open WebUI 实例（运行版本为 1.0 或更高）
一个 Redis 容器（在本示例中，我们将使用 docker.io/valkey/valkey:8.0.1-alpine，它基于最新的 Redis 7.x 版本）
系统上已安装 Docker Compose（版本为 2.0 或更高）
用于 Open WebUI 与 Redis 之间通信的 Docker 网络
对 Docker、Redis 和 Open WebUI 的基本理解

Critical: Redis Server Configuration

危险

防止出现“达到最大客户端数量 (Max Number of Clients Reached)”错误

在将 Open WebUI 配置为使用 Redis 之前，您必须确保您的 Redis 服务器本身配置正确。常见的错误配置会导致连接随着时间的推移而不断累积，最终耗尽连接限制，从而导致完全的身份验证失败（所有用户都会遇到 500 内部服务器错误）。

问题所在：

Open WebUI 使用 Redis 进行：

令牌验证/吊销检查（针对每个已验证的请求）
WebSocket 管理（实时更新）
会话存储（如果启用了 ENABLE_STAR_SESSIONS_MIDDLEWARE）

在某些发行版上，使用默认的 Redis 设置（maxclients 1000, timeout 0）时，连接永远不会关闭。数天或数周后，它们会默默地累积，直到达到上限。然后，突然之间，所有人都会无法登录。

症状：

应用程序在数天/数周内运行良好
突然之间，所有用户在登录时都会收到 500 内部服务器错误
日志中的错误：redis.exceptions.ConnectionError: max number of clients reached
随着旧连接最终断开，可能会暂时“自行修复”，但随后会再次失败

解决方案：

将以下设置添加到您的 Redis 配置中：

# 允许足够的并发连接
maxclients 10000

# 关闭空闲超过 30 分钟（1800 秒）的连接
# 这并不会影响会话有效性 —— 仅关闭到 Redis 的 TCP 连接
timeout 1800

对于 Docker 部署，请在您的 Redis 启动命令中添加：

services:
  redis:
    image: docker.io/valkey/valkey:8.0.1-alpine
    command: "valkey-server --save 30 1 --maxclients 10000 --timeout 1800"
    # ... 其他配置

为什么 timeout 1800 是安全的：

该超时时间仅影响空闲的 Redis TCP 连接，不影响用户会话。当连接超时关闭时：

用户的 JWT 令牌依然有效
他们的会话不受影响
下一次请求只需重新打开一个 Redis 连接（增加约 1-5ms 延迟，完全无感）

监控：

检查当前连接数：

redis-cli INFO clients | grep connected_clients

在配置了正确的 timeout 后，这个数字应该自然波动（在活跃时间内上升，在空闲时间内下降），而不是无限攀升。

Setting up Redis

要为 WebSocket 支持设置 Redis，您需要创建一个具有以下内容的 docker-compose.yml 文件：

version: '3.9'
services:
  redis:
    image: docker.io/valkey/valkey:8.0.1-alpine
    container_name: redis-valkey
    volumes:
      - redis-data:/data
    command: "valkey-server --save 30 1 --maxclients 10000 --timeout 1800"
    healthcheck:
      test: "[ $$(valkey-cli ping) = 'PONG' ]"
      start_period: 5s
      interval: 1s
      timeout: 3s
      retries: 5
    restart: unless-stopped
    cap_drop:
      - ALL
    cap_add:
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"
    networks:
      - openwebui-network

volumes:
  redis-data:

networks:
  openwebui-network:
    external: true

信息

配置说明

在此配置中未包含 ports 指令，因为在大多数情况下这并非必需。Open WebUI 服务依然可以通过 Docker 网络内部访问 Redis 服务。但是，如果您需要从 Docker 网络外部访问 Redis 实例（例如，为了调试或监控目的），您可以添加 ports 指令来公开 Redis 端口（例如 6379:6379）。

上述配置设置了一个名为 redis-valkey 的 Redis 容器，并挂载了一个用于数据持久化的数据卷。healthcheck 指令可确保在容器无法响应 ping 命令时重启容器。--save 30 1 命令选项表示如果至少有 1 个键发生更改，则每 30 分钟将 Redis 数据库保存到磁盘一次。

重要提示： --maxclients 10000 --timeout 1800 标志可以防止连接耗尽。详情请参见上方的“关键：Redis 服务器配置”部分。

要创建用于 Open WebUI 与 Redis 之间通信的 Docker 网络，请运行以下命令：

docker network create openwebui-network

Configuring Open WebUI

要在 Open WebUI 中启用 Redis 支持，您需要根据部署类型配置不同的环境变量。

Basic Configuration (All Deployments)

对于所有使用 Redis 的部署模式（单实例或多实例），请设置以下基础环境变量：

REDIS_URL="redis://redis-valkey:6379/0"

此变量为应用程序状态管理、会话存储和实例间协调配置了主 Redis 连接。

WebSocket Configuration

要专门启用 WebSocket 支持，请添加以下附加环境变量：

ENABLE_WEBSOCKET_SUPPORT="true"
WEBSOCKET_MANAGER="redis"
WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1"

关键：为 WebSocket 连接配置 CORS

WebSocket 连接中一个非常常见且难以调试的问题是跨源资源共享 (CORS) 策略配置错误。如果您的 Open WebUI 实例是从与后端不同的域名或端口进行访问的（例如，在反向代理后面），您必须设置 CORS_ALLOW_ORIGIN 环境变量。此变量告诉服务器哪些源 (origins) 被允许访问其资源。

如果未正确配置，将导致 WebSocket 连接默默失败或抛出含糊的浏览器错误，忘记设置此变量是 WebSocket 连接问题的常见原因。

示例： 如果您通过 https://my-open-webui.com 访问您的 UI，您必须设置：

CORS_ALLOW_ORIGIN="https://my-open-webui.com"

您还可以提供以分号分隔的允许域名列表。请勿在生产环境或反向代理设置中跳过此步骤。

信息

Redis 数据库编号

注意 URL 中不同的数据库编号（/0 与 /1）：

REDIS_URL 使用数据库 0 存放通用应用程序状态
WEBSOCKET_REDIS_URL 使用数据库 1 存放 WebSocket 特定的数据

这种分离有助于隔离不同类型的数据。如果需要，您也可以在两个变量中使用相同的数据库编号，但推荐使用不同的数据库，以便更好地组织数据并实现潜在的性能优化。

Optional Configuration

REDIS_KEY_PREFIX="open-webui"

REDIS_KEY_PREFIX 允许开发人员让多个 Open WebUI 实例共享同一个 Redis 实例，而不会发生键名冲突。在 Redis 集群模式下，前缀格式化为 {prefix}:（例如，{open-webui}:config:*），以对同一哈希槽内的配置键启用多键操作。

Sentinel Failover Configuration

关键：Sentinel 部署的套接字超时

Redis Sentinel 设置需要显式配置套接字连接超时，以确保正确的故障转移行为。如果在没有超时的情况下，当 Redis 主节点 (master node) 下线时，应用程序可能会无限挂起 —— 甚至可能会阻止应用程序的重启。

缺少超时配置的症状：

在故障转移期间，应用程序变得完全没有响应
如果第一个 Sentinel 主机不可达，应用程序在启动时挂起
在主节点故障转移后，恢复需要数分钟而不是数秒

必需的配置：

REDIS_SOCKET_CONNECT_TIMEOUT=5

这为与 Redis/Sentinel 节点的套接字连接尝试设置了 5 秒的超时时间，使应用程序能够优雅地进行故障转移。

如果使用 WEBSOCKET_REDIS_OPTIONS

当您显式设置 WEBSOCKET_REDIS_OPTIONS 时，REDIS_SOCKET_CONNECT_TIMEOUT 不会自动应用于 WebSocket 连接。您必须在两个地方都包含超时设置：

REDIS_SOCKET_CONNECT_TIMEOUT=5
WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}'

Retry and Reconnect Logic

为了在 Sentinel 故障转移期间（即新主节点正在选举和提升的窗口期）增强韧性，您可以配置重试行为，以防止应用程序过快地耗尽其重连尝试次数。

REDIS_SENTINEL_MAX_RETRY_COUNT：在使用 Sentinel 时，设置 Redis 操作的最大重试次数（默认值：2）。
REDIS_RECONNECT_DELAY：在重试尝试之间添加一个可选的延迟（以毫秒为单位，例如 REDIS_RECONNECT_DELAY=500）。这可以防止过于紧密的重试循环，从而避免在新的主节点就绪之前拖垮事件循环或阻塞应用程序。

Connection Health Checks

如果您的 Redis 服务器配置了超时时间（推荐做法 —— 见上文），那么处于空闲状态的时间超过该超时时间的连接池连接将在服务器端被回收。如果没有健康检查，下一个获取这些死套接字的请求将失败，并抛出 ConnectionError: Connection reset by peer。

REDIS_HEALTH_CHECK_INTERVAL：redis-py 在重用空闲的连接池连接之前，应该每隔多久（以秒为单位）PING 一下该连接（例如 REDIS_HEALTH_CHECK_INTERVAL=60）。该值必须短于您的 Redis 服务器的 timeout，以及连接到 Redis 的路径上的任何防火墙/负载均衡器的空闲超时。设置为 0 或留空以禁用。
REDIS_SOCKET_KEEPALIVE：在所有 Redis 客户端套接字上启用 TCP SO_KEEPALIVE（例如 REDIS_SOCKET_KEEPALIVE=True）。启用后，操作系统内核会在空闲连接上发送 TCP 保活探测，检测由无声防火墙/负载均衡器重置或 TCP 层面的网络抖动引起的半开套接字。

这两种机制是互补的：

REDIS_HEALTH_CHECK_INTERVAL 工作在应用程序级别 —— redis-py 在签出连接时 PING 空闲连接，从而验证套接字并重置服务器的空闲计时器。
REDIS_SOCKET_KEEPALIVE 工作在TCP/内核级别 —— 即使没有应用层流量流动，内核也能检测到死掉的对端。

推荐配对

为了获得健壮的生产环境部署，建议将这三个层面配置在一起：

机制	层面	涵盖范围	作用说明
`timeout 1800` (redis.conf)	服务器端	回收应用程序遗忘的泄漏/孤立连接	安全网
`REDIS_HEALTH_CHECK_INTERVAL=60`	应用程序级别	在实际命令使用连接前检测死套接字；保持连接池活跃	主动防护
`REDIS_SOCKET_KEEPALIVE=True`	TCP/内核级别	检测因网络静默重置（防火墙、负载均衡器、网卡抖动）引起的半开套接字	网络级防护

Redis Cluster Mode

对于使用 Redis 集群（包括托管服务如 AWS Elasticache Serverless）的部署，请使用以下配置启用集群模式：

REDIS_URL="redis://your-cluster-endpoint:6379/0"
REDIS_CLUSTER="true"

信息

关键配置说明

REDIS_CLUSTER 启用了感知集群的连接处理
REDIS_URL 应该指向您集群的配置端点
如果定义了 REDIS_SENTINEL_HOSTS，此选项将不起作用（Sentinel 具有更高优先级）
当使用集群模式时，REDIS_KEY_PREFIX 会自动格式化为 {prefix}:，以确保多键操作指向相同的哈希槽

AWS Elasticache Serverless

对于 AWS Elasticache Serverless 部署，请使用以下配置：

REDIS_URL="rediss://your-elasticache-endpoint.serverless.use1.cache.amazonaws.com:6379/0"
REDIS_CLUSTER="true"

注意带有双“s”的 rediss:// 协议方案，它启用了 TLS，这是 Elasticache Serverless 所必需的。

OpenTelemetry Support

Redis 集群模式与 OpenTelemetry 工具完全兼容。当启用 ENABLE_OTEL 时，无论您使用的是单个 Redis 实例、Redis Sentinel 还是 Redis 集群模式，Redis 操作都会被正确追踪。

Complete Example Configuration

这里是一个完整的示例，展示了所有与 Redis 相关的环境变量：

# 多 worker/多实例部署必需
REDIS_URL="redis://redis-valkey:6379/0"

# WebSocket 支持必需
ENABLE_WEBSOCKET_SUPPORT="true"
WEBSOCKET_MANAGER="redis"
WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1"

# 推荐用于 Sentinel 部署（防止故障转移挂起）
REDIS_SOCKET_CONNECT_TIMEOUT=5
REDIS_SENTINEL_MAX_RETRY_COUNT=5
REDIS_RECONNECT_DELAY=1000

# 推荐：检测陈旧的连接池连接（必须 < Redis 服务器超时时间）
REDIS_HEALTH_CHECK_INTERVAL=60

# 推荐：启用 TCP 保活以在内核级别检测死亡对端
REDIS_SOCKET_KEEPALIVE=True

# 可选
REDIS_KEY_PREFIX="open-webui"

对于 Redis Sentinel 部署，请务必确保设置了 REDIS_SOCKET_CONNECT_TIMEOUT，以防止在主节点故障转移期间应用程序挂起。

Redis Cluster Mode Example

对于 Redis 集群部署（包括 AWS Elasticache Serverless）：

# Redis 集群必需
REDIS_URL="rediss://your-cluster-endpoint:6379/0"
REDIS_CLUSTER="true"

# WebSocket 支持必需
ENABLE_WEBSOCKET_SUPPORT="true"
WEBSOCKET_MANAGER="redis"
WEBSOCKET_REDIS_URL="rediss://your-cluster-endpoint:6379/0"
WEBSOCKET_REDIS_CLUSTER="true"

# 可选
REDIS_KEY_PREFIX="open-webui"

Docker Run Example

当使用 Docker 运行 Open WebUI 时，将其连接到相同的 Docker 网络并包含所有必要的 Redis 变量：

docker run -d \
  --name open-webui \
  --network openwebui-network \
  -v open-webui:/app/backend/data \
  -p 3000:8080 \
  -e REDIS_URL="redis://redis-valkey:6379/0" \
  -e ENABLE_WEBSOCKET_SUPPORT="true" \
  -e WEBSOCKET_MANAGER="redis" \
  -e WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1" \
  -e REDIS_KEY_PREFIX="open-webui" \
  ghcr.io/open-webui/open-webui:main

注意

关于服务名称的重要说明

在上面的示例中，我们使用 redis://redis-valkey:6379，是因为：

redis-valkey 是 docker-compose.yml 中定义的容器名称
Docker 的内部 DNS 会将此名称解析为网络内的正确 IP 地址
这是 Docker 部署推荐的方法

从一个容器连接 to 另一个容器时，请勿使用 127.0.0.1 或 localhost —— 这些指的是容器自身的本地主机，而不是 Redis 容器。

Multi-Worker Configuration

如果您在单台主机上运行多个 Uvicorn workers，请添加此变量：

UVICORN_WORKERS="4"  # 根据您的 CPU 核心数进行调整
REDIS_URL="redis://redis-valkey:6379/0"  # 当 UVICORN_WORKERS > 1 时必需

危险

关键：UVICORN_WORKERS > 1 时必需配置 Redis

如果您将 UVICORN_WORKERS 设置为大于 1 的任何值，您必须配置 REDIS_URL。否则会导致：

会话状态在不同请求之间丢失
身份验证断断续续地失败
应用程序配置不一致
WebSocket 发生故障

危险

关键：默认的 ChromaDB (SQLite) 与多 Worker 不兼容

除了 Redis 之外，您还必须解决向量数据库的问题。默认的 ChromaDB 使用本地基于 SQLite 的 PersistentClient，它并不是分支安全 (fork-safe) 的。当 Uvicorn 分支成多个 worker 时，在文档上传期间对同一个 SQLite 文件的并发写入会导致 worker 瞬间崩溃（提示 Child process died）。

您必须选择以下操作之一：

切换到客户端-服务器模式的向量数据库（如 VECTOR_DB=pgvector、mariadb-vector、milvus 或 qdrant）
将 ChromaDB 作为独立的 HTTP 服务器运行，并设置 CHROMA_HTTP_HOST / CHROMA_HTTP_PORT

有关详细信息，请参阅扩展与高可用指南 (Scaling & HA guide)。

Verification

Verify Redis Connection

首先，确认您的 Redis 实例正在运行且接受连接：

docker exec -it redis-valkey valkey-cli -p 6379 ping

如果 Redis 实例正常运行，此命令应输出 PONG。

Verify Open WebUI Configuration

在使用正确的 Redis 配置启动 Open WebUI 实例后，请检查日志以确认集成成功：

Check for General Redis Connection

寻找指出 Redis 被用于应用程序状态的日志消息：

docker logs open-webui 2>&1 | grep -i redis

Check for Websocket Redis Connection

如果您启用了 WebSocket 支持，您应该会看到以下特定的日志消息：

DEBUG:open_webui.socket.main:Using Redis to manage websockets.

要专门检查这一点：

docker logs open-webui 2>&1 | grep "Using Redis to manage websockets"

Verify Redis Keys

您还可以验证 Open WebUI 是否确实在向 Redis 写入数据：

# 列出所有 Open WebUI 的键名
docker exec -it redis-valkey valkey-cli --scan --pattern "open-webui*"

# 或者使用默认的 Redis CLI
docker exec -it redis-valkey redis-cli --scan --pattern "open-webui*"

如果 Redis 配置正确，您应该会看到带有您配置的前缀的键名（例如 open-webui:session:*、open-webui:config:*）。

Test Multi-Worker Setup

如果您在 UVICORN_WORKERS > 1 的情况下运行，请测试会话是否在不同的 worker 之间持久存在：

登录 Open WebUI
多次刷新页面
您应该始终保持登录状态

如果您被随机登出或看到身份验证错误，这通常意味着 Redis 配置不正确。

Troubleshooting

Common Issues and Solutions

Issue: "Connection to Redis failed"

症状：

日志中出现有关 Redis 连接的错误消息
应用程序无法启动或崩溃
WebSocket 无法工作

解决方案：

验证 Redis 容器正在运行：docker ps | grep redis
检查 Redis 状态是否健康：docker exec -it redis-valkey valkey-cli ping
验证网络连通性：docker network inspect openwebui-network
确保 REDIS_URL 使用的是正确的容器名称，而不是 127.0.0.1 或 localhost
检查两个容器是否处于同一个 Docker 网络中

Issue: "Session lost after page refresh" (with UVICORN_WORKERS > 1)

症状：

用户被随机登出
身份验证可以工作但无法持久保持
每次刷新页面时的行为不一致

原因： 使用多个 worker 时未配置 REDIS_URL

解决方案： 添加 REDIS_URL 环境变量：

REDIS_URL="redis://redis-valkey:6379/0"

Issue: "Websockets not working"

症状：

实时聊天更新没有出现
需要刷新页面才能看到新消息
浏览器控制台中出现连接错误

解决方案：

验证所有 WebSocket 环境变量均已设置：
- ENABLE_WEBSOCKET_SUPPORT="true"
- WEBSOCKET_MANAGER="redis"
- WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1"
检查日志中是否包含：DEBUG:open_webui.socket.main:Using Redis to manage websockets.
验证可以从 Open WebUI 容器访问 Redis

Issue: "Multiple Open WebUI instances interfering with each other"

症状：

配置更改会影响其他实例
不同部署之间的会话发生冲突
运行多个 Open WebUI 安装时出现非预期行为

解决方案： 为每个安装使用不同的 REDIS_KEY_PREFIX 值：

# 实例 1
REDIS_KEY_PREFIX="openwebui-prod"

# 实例 2
REDIS_KEY_PREFIX="openwebui-dev"

Issue: "Redis memory usage growing continuously"

症状：

Redis 内存使用量随着时间的推移而增加
容器最终耗尽内存

解决方案：

配置 Redis 的 maxmemory 淘汰策略：

   command: "valkey-server --save 30 1 --maxmemory 256mb --maxmemory-policy allkeys-lru"

监控 Redis 内存：docker exec -it redis-valkey valkey-cli info memory
如果需要，清理旧键：docker exec -it redis-valkey valkey-cli FLUSHDB

Issue: "max number of clients reached" after days/weeks of operation

症状：

应用程序在很长一段时间内运行良好，然后突然失败
所有登录尝试均返回 500 内部服务器错误
日志中的错误：redis.exceptions.ConnectionError: max number of clients reached
可能会暂时恢复，但随后会再次失败

原因： 由于连接累积达到 Redis 的 maxclients 限制。这在以下情况下发生：

timeout 被设置为 0（连接永远不关闭）
对于您的使用模式，maxclients 设置得太低

解决方案：

检查当前连接数：

redis-cli INFO clients | grep connected_clients

检查当前设置：

redis-cli CONFIG GET maxclients
redis-cli CONFIG GET timeout

修复配置：

redis-cli CONFIG SET maxclients 10000
redis-cli CONFIG SET timeout 1800

通过添加到 redis.conf 或 Docker 命令中以使其永久生效：
```
maxclients 10000
timeout 1800
```

重启 Redis 以清除已累积的连接：

# 对于 systemd
sudo systemctl restart redis

# 对于 Docker
docker restart redis-valkey

预防措施： 务必将 timeout 配置为一个合理的值（例如 1800 秒）。超时时间仅影响空闲的 TCP 连接，不影响用户会话 —— 这是安全且推荐的。将此与客户端的 REDIS_HEALTH_CHECK_INTERVAL 配对使用（见下文）。

Issue: "Connection reset by peer" errors on first request after idle period

症状：

日志中偶尔出现 redis.exceptions.ConnectionError: Connection reset by peer 报错
错误倾向于在低活动时期（夜晚、周末）过后出现
触发该错误的请求失败并返回 500 内部服务器错误，但随后的请求可以成功
当配置了 Redis 服务器的 timeout 时更为常见（本应如此配置 —— 参见上文）

原因： Redis 服务器回收了空闲连接（通过其 timeout 设置），但 redis-py 中的连接池套接字并不知道该连接已死。下一个从连接池中获取该套接字的请求向已关闭的连接发送了命令。

解决方案：

将 REDIS_HEALTH_CHECK_INTERVAL 环境变量设置为短于您的 Redis 服务器 timeout 的值：

# Redis 服务器超时时间为 1800 秒 (30 分钟)，因此每 60 秒检查一次
REDIS_HEALTH_CHECK_INTERVAL=60

这告诉 redis-py 在重用任何空闲超过 60 秒的连接池连接之前对其进行 PING 检查。如果连接已死，它将被透明地替换。PING 还会重置服务器的空闲计时器，从而使正在使用的连接保持活跃。

如何选择合适的值：

您的 Redis `timeout`	建议的 `REDIS_HEALTH_CHECK_INTERVAL`
300 (5 分钟)	30
900 (15 分钟)	60
1800 (30 分钟)	60
3600 (1 小时)	120

健康检查间隔也应该短于应用程序与 Redis 之间的任何防火墙或负载均衡器的空闲超时时间。

Additional Resources

Getting Help

如果您在遵循本指南后仍然遇到问题：

检查 Open WebUI GitHub Issues
仔细检查您的完整配置是否存在拼写错误
验证所有容器都可以在 Docker 网络上进行通信
从 Open WebUI 和 Redis 容器中收集相关日志
加入 Open WebUI Discord 获取社区支持

通过遵循这些步骤和故障排除提示，您应该能够成功为 Open WebUI 设置 Redis，以用于应用程序状态管理和 WebSocket 支持，从而实现可靠的多实例部署以及客户端与应用程序之间的实时通信。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

Overview​

When is Redis Required?​

Single Instance Deployments​

Multi-Worker and Multi-Instance Deployments​

Prerequisites​

Critical: Redis Server Configuration​

Setting up Redis​

Configuring Open WebUI​

Basic Configuration (All Deployments)​

WebSocket Configuration​

Optional Configuration​

Sentinel Failover Configuration​

Retry and Reconnect Logic​

Connection Health Checks​

Redis Cluster Mode​

AWS Elasticache Serverless​

OpenTelemetry Support​

Complete Example Configuration​

Redis Cluster Mode Example​

Docker Run Example​

Multi-Worker Configuration​

Verification​

Verify Redis Connection​

Verify Open WebUI Configuration​

Check for General Redis Connection​

Check for Websocket Redis Connection​

Verify Redis Keys​

Test Multi-Worker Setup​

Troubleshooting​

Common Issues and Solutions​

Issue: "Connection to Redis failed"​

Issue: "Session lost after page refresh" (with UVICORN_WORKERS > 1)​

Issue: "Websockets not working"​

Issue: "Multiple Open WebUI instances interfering with each other"​

Issue: "Redis memory usage growing continuously"​

Issue: "max number of clients reached" after days/weeks of operation​

Issue: "Connection reset by peer" errors on first request after idle period​

Additional Resources​

Getting Help​

Overview

When is Redis Required?

Single Instance Deployments

Multi-Worker and Multi-Instance Deployments

Prerequisites

Critical: Redis Server Configuration

Setting up Redis

Configuring Open WebUI

Basic Configuration (All Deployments)

WebSocket Configuration

Optional Configuration

Sentinel Failover Configuration

Retry and Reconnect Logic

Connection Health Checks

Redis Cluster Mode

AWS Elasticache Serverless

OpenTelemetry Support

Complete Example Configuration

Redis Cluster Mode Example

Docker Run Example

Multi-Worker Configuration

Verification

Verify Redis Connection

Verify Open WebUI Configuration

Check for General Redis Connection

Check for Websocket Redis Connection

Verify Redis Keys

Test Multi-Worker Setup

Troubleshooting

Common Issues and Solutions

Issue: "Connection to Redis failed"

Issue: "Session lost after page refresh" (with UVICORN_WORKERS > 1)

Issue: "Websockets not working"

Issue: "Multiple Open WebUI instances interfering with each other"

Issue: "Redis memory usage growing continuously"

Issue: "max number of clients reached" after days/weeks of operation

Issue: "Connection reset by peer" errors on first request after idle period

Additional Resources

Getting Help