warning

本教程由社区贡献，不属于 Open WebUI 官方团队的支持范畴。它仅作为如何根据您的特定用例自定义 Open WebUI 的演示。想贡献代码？请查看贡献教程。

🔗 Redis Websocket 支持

概述

本教程页面概述了将 Redis 与 Open WebUI 集成以实现 websocket 支持所需的步骤。通过遵循这些步骤，您将能够在 Open WebUI 实例中启用 websocket 功能，从而允许客户端与应用程序之间进行实时通信和更新。

什么时候需要 Redis？

Redis 在 Open WebUI 中有两个截然不同的用途，了解何时需要它对于正确部署至关重要：

单实例部署

如果您将 Open WebUI 作为单个实例运行，且 UVICORN_WORKERS=1（默认值），那么 Redis 是完全可选的，并非严格需要。对于所有操作，应用程序在没有它的情况下也能正常运行。

多工作进程和多实例部署

在以下情况下，Redis 变得强制性：

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

warning

关键要求

在多工作进程或多实例方案中，如果没有 Redis，您将遇到：

不同工作进程之间的会话管理失败
实例之间的应用程序状态不一致
Websocket 连接无法正常工作
间歇性身份验证失败
实时聊天更新丢失

前提条件

一个有效的 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 有基本了解

设置 Redis

要设置 Redis 以支持 websocket，您需要创建一个具有以下内容的 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"
    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

info

注意

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

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

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

docker network create openwebui-network

配置 Open WebUI

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

基础配置（所有部署）

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

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

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

Websocket 配置

要专门启用 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 环境变量。此变量告诉服务器允许哪些来源访问其资源。

未能正确配置此项会导致 WebSocket 连接静默失败或出现模糊的浏览器错误，忘记设置此变量是 WebSocket 连接问题的常见原因。

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

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

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

info

Redis 数据库编号

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

REDIS_URL 使用数据库 0 存储常规应用程序状态
WEBSOCKET_REDIS_URL 使用数据库 1 存储 websocket 特定数据

这种分离有助于隔离不同类型的数据。如果愿意，您可以为两者使用相同的数据库编号，但为了更好的组织和潜在的性能优化，建议使用单独的数据库。

可选配置

REDIS_KEY_PREFIX="open-webui"

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

Sentinel 故障转移配置

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

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

缺少超时配置的症状：

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

必需配置：

REDIS_SOCKET_CONNECT_TIMEOUT=5

概述​

什么时候需要 Redis？​

单实例部署​

多工作进程和多实例部署​

前提条件​

设置 Redis​

配置 Open WebUI​

基础配置（所有部署）​

Websocket 配置​

可选配置​

Sentinel 故障转移配置​

概述