Open WebUI 扩展

Open WebUI 旨在满足您的扩展需求——从单用户到跨整个企业和机构的组织级部署。下面的步骤将指导您随着需求的增长如何配置部署。

Open WebUI 遵循无状态、容器优先的架构，这意味着扩展它非常类似于扩展任何现代 Web 应用程序。无论您是从个人兴趣配置过渡到支持一个部门，还是从数百名用户增长到数千名用户，所采用的构建块都是相同的。

本指南将从高维度指导您了解核心概念和配置。有关确切的环境变量详细信息，请参阅环境变量参考。

理解默认设置

在开箱即用状态下，Open WebUI 以单容器方式运行，包含：

存储在本地卷上的嵌入式 SQLite 数据库
用于 RAG 向量的嵌入式 ChromaDB 向量数据库（同样由 SQLite 支持）
单个 Uvicorn worker 进程
无外部依赖（无 Redis，无外部数据库）

这对于个人使用、小团队或评估非常完美。当您不再满足于这些默认设置时，扩展之旅便开始了——至关重要的一点是，在您安全地运行多个进程之前，两个 SQLite 数据库（主数据库和向量数据库）都必须被替换。

步骤 1 — 切换到 PostgreSQL

何时使用： 您计划运行多个 Open WebUI 实例，或者您希望为主数据库获得更好的并发性能和可靠性。如果您的 SQLite 文件存放在本地直接挂载的 SSD/NVMe 之外的任何其他存储介质上，您也应该切换——请参阅下方的提示。

如果您是在本地磁盘上部署的单副本实例，则不需要此步骤

保留 SQLite 适用于： 单副本部署、个人使用、评估、家庭实验室设置以及小团队——只要数据库文件存放在本地直接挂载的 SSD/NVMe 上，且您没有运行多个副本或 Worker 进程。 0.8 → 0.9 版本异步后端的影响只在 webui.db 存放在网络存储上时显现；在本地磁盘上，SQLite 快速、受支持且是一个非常合理的默认选择。无需进行迁移，您可以跳过此步骤并直接跳到您真正需要的后续步骤。

SQLite 将所有内容存储在单个文件中，无法很好地处理来自多个进程的并发写入。PostgreSQL 是生产级数据库，支持许多同时进行的并发连接。

具体操作：

设置 DATABASE_URL 环境变量以指向您的 PostgreSQL 服务器：

DATABASE_URL=postgresql://user:password@db-host:5432/openwebui

关键注意事项：

Open WebUI 不会在数据库之间迁移数据——请在 SQLite 中产生生产数据之前规划好此项。
对于高并发部署，请调节 DATABASE_POOL_SIZE 和 DATABASE_POOL_MAX_OVERFLOW 以匹配您的使用模式。有关详细指南，请参阅数据库优化。
请记住，每个 Open WebUI 实例都维护自己的连接池，因此总连接数 = 连接池大小 × 实例数量。
如果您跳过此步骤并在使用 SQLite 的情况下运行多个实例，您将遇到 database is locked 错误和数据损坏。详情请参阅数据库损坏 / “锁定（Locked）”错误。

提示

一个比较好的调优起点是 DATABASE_POOL_SIZE=15 和 DATABASE_POOL_MAX_OVERFLOW=20。请保持每个实例的合并总连接数远低于您的 PostgreSQL max_connections 限制（默认是 100）。

有关凭据处理和 SQLCipher 加密的 SQLite 选项，请参阅安全加固指南的数据库部分。

为什么在网络存储上的 SQLite 会在扩展（或升级）时立即失效

自 0.9.0 版本起，后端数据层已完全异步化（异步 SQLAlchemy + aiosqlite）。该项更改极大地提高了 Open WebUI 的并发处理能力——但作为一个副作用，它使得所有原本“SQLite 在 NFS/CephFS/Azure Files 上运行缓慢”的问题一夜之间从可以忍受变成了致命伤。许多管理员在从 0.8.x 升级后立即遇到了这个问题，而没有更改部署中的任何其他配置。

原因简述：SQLite 的持久化保证是针对每次提交（commit）执行 fsync()。在本地 SSD 上，这大约需要 ~100 μs。但在 NFS / CephFS / Azure Files / 由网络存储支持的 Kubernetes PVC 上，这需要 50–500 ms，有时甚至需要数秒。在旧的同步后端中，FastAPI 的 ~40 个线程的 Worker 池起到了天然的限流作用，因此缓慢的存储仅仅意味着“应用变慢”。但在异步后端中，不存在线程池的天花板——asyncio 事件循环并行调度数以千计的数据库协程，每一次缓慢的 fsync 都会导致连接被一直占用，而 SQLAlchemy 异步连接池（默认 pool_size=5 + max_overflow=10 = 15 个连接）几乎瞬间就会饱和。然后您就会看到：

sqlalchemy.exc.TimeoutError: QueuePool limit of size 5 overflow 10 reached,
connection timed out, timeout 30.00

增大连接池仅仅是将崩溃点往后推迟。更多连接意味着有更多并发的慢 fsync 在冲击本就缓慢的存储；文件系统依然是瓶颈。

最重要的是，SQLite 的 WAL 模式依赖内存映射的 -shm 文件来进行跨进程协作，而根据 SQLite 官方的说法，通过 NFS 进行 mmap 是极不可靠的——在高异步并发下，它会产生实际的锁定病态表现（死锁、PRAGMA journal_mode=WAL 启动但永远无法完成、简单查询遭遇数分钟的停滞）。

在 SQLite 依然保留在网络存储上的情况下，没有任何设置可以修复这个问题。 仅有以下三种选择：

最佳方案 — 切换到 PostgreSQL（本步骤）。 数据库服务器针对其自己的本地存储管理其自己的 I/O。您的应用通过网络套接字（Socket）访问它，该网络开销比 NFS 的 fsync 要低几个数量级，且 PostgreSQL 从第一天起就是为并发写入而设计的。这是多副本、多用户或 Kubernetes/Swarm 部署中唯一受支持的配置。
将 webui.db 从网络存储移至本地 SSD/NVMe 上。 仅适用于单节点、低用户的部署。您的 RAG 文件和上传的普通文件依然可以留在 NFS 上——这里专门产生问题的是 SQLite，而不是共享文件系统本身。
如果您目前两样都无法做到，可以采用临时变通方法：
```
DATABASE_POOL_SIZE=1
DATABASE_SQLITE_PRAGMA_BUSY_TIMEOUT=30000
```
将其序列化为单个异步连接，以并发性换取稳定性。这在长期内不受支持——请尽早规划真正的迁移。

简而言之：同步后端通过线程池限制了并发，因此缓慢的存储只是让一切变慢。而异步后端允许极大的并发，这意味着缓慢的 fsync 堆积，连接占用时间变长，连接池饱和，最终导致整体死锁。同样的存储在以前是可以容忍的，那是因为以前应用程序并没有要求它同时进行 20 个并发的 fsync。

步骤 2 — 添加 Redis

何时使用： 您希望运行多个 Open WebUI 实例（水平扩展）或多个 Uvicorn worker。

Redis 充当了共享状态存储，以便您的所有 Open WebUI 实例能够协调会话、WebSocket 连接和应用程序状态。如果没有它，用户会因为不同的实例处理请求而体验到不一致的行为。

具体操作：

设置以下环境变量：

REDIS_URL=redis://redis-host:6379/0
WEBSOCKET_MANAGER=redis
ENABLE_WEBSOCKET_SUPPORT=true

关键注意事项：

对于单实例部署，要实现基础功能不需要 Redis。但是，如果没有 Redis，退出登录不会撤销 Token——它们保持有效直到自然过期（默认：4 周）。如果您的部署是面向生产环境或处理敏感数据的，强烈建议即使在单实例中也配置 Redis，或者缩短 JWT_EXPIRES_IN 以限制暴露窗口。详情请参阅安全加固指南中的 Token 撤销。
如果您正在使用 Redis Sentinel 来实现高可用性，请同时设置 REDIS_SENTINEL_HOSTS 并考虑设置 REDIS_SOCKET_CONNECT_TIMEOUT=5 以防止在故障转移期间挂起。
对于 AWS Elasticache 或其他托管的 Redis Cluster 服务，请设置 REDIS_CLUSTER=true。
请确保您的 Redis 服务器配置了 timeout 1800 和足够高的 maxclients (10000+)，以防止连接随着时间的推移而耗尽。
对于绝大多数部署，即使有数千名用户，单个 Redis 实例也已足够。除非您有特定的高可用（HA）或带宽要求，否则您几乎肯定不需要 Redis Cluster。如果您认为自己需要 Redis Cluster，请先检查您的连接数和内存使用量是否是由可修复的配置问题导致的（请参阅常见的反模式）。
在多实例设置中，如果没有 Redis，您将会遇到 WebSocket 403 错误、配置同步问题以及间歇性身份验证失败。

有关完整的 Redis 逐步安装指导（Docker Compose、Sentinel、Cluster 模式、验证），请参阅 Redis WebSocket 支持教程。对于反向代理后面的 WebSocket 和 CORS 问题，请参阅连接错误。

步骤 3 — 运行多个实例

何时使用： 您需要处理更多用户或需要高可用性（容器崩溃或部署期间无停机时间）。

Open WebUI 是无状态的，因此您可以在负载均衡器后运行所需数量的多个实例。每个实例都是相同且可以互换的。

注意

在运行多个实例之前，请确保您已完成 步骤 1 和步骤 2（PostgreSQL 和 Redis）。您还需要在所有副本中共享相同的 WEBUI_SECRET_KEY——否则，用户将遇到登录循环和 401 错误。关于如何生成、存储和轮换该密钥（以及匹配的 OAUTH_SESSION_TOKEN_ENCRYPTION_KEY），请参阅安全加固指南中的密钥（Secret Key）。有关完整的上线前检查列表，请参阅核心要求检查列表。

选项 A：容器编排（推荐）

使用 Kubernetes、Docker Swarm 或类似平台来管理多个副本：

保持每个容器的 UVICORN_WORKERS=1（让编排器处理扩展，而不是应用本身）
在除一个指定的“主（primary）”Pod 之外的所有副本上设置 ENABLE_DB_MIGRATIONS=false，以防止迁移竞态条件——安全流程请参阅更新和迁移
通过调整您的副本数量来进行扩缩容

选项 B：每个容器运行多个 Worker

对于较简单的设置（例如，单台高性能服务器），可以增加 UVICORN_WORKERS：

UVICORN_WORKERS=4

这会在单个容器内部生成多个应用程序进程。在使用此方法时，您依然需要 PostgreSQL 和 Redis。

信息

通常更推荐采用容器编排，因为它可以提供自动重启、滚动更新和更细粒度的资源控制。当无法使用编排时，在单个容器内运行多个 Worker 进程是一个更简单的替代方案。

步骤 4 — 切换到外部向量数据库

何时使用： 您运行了多个 Uvicorn worker (UVICORN_WORKERS > 1) 或多个副本。这是强制性要求。

默认的 ChromaDB 会在多进程设置中崩溃

默认的向量数据库 (ChromaDB) 使用了由 SQLite 支持的本地 PersistentClient。SQLite 连接是非 fork 安全的——当 uvicorn 派生出多个 Worker 进程时，每个进程都会继承相同的数据库连接。并发写入（例如在上传文档时）会导致 Worker 进程瞬间死亡：

save_docs_to_vector_db:1619 - adding to collection file-id
INFO:     Waiting for child process [pid]
INFO:     Child process [pid] died

这是众所周知的 SQLite 局限性，并非 Bug。在多个容器访问同一个 ChromaDB 数据目录的多副本部署中，它也会产生同样的影响。

关于完整的崩溃序列分析，请参阅文档上传期间 Worker 崩溃或 RAG 故障排查：上传期间 Worker 死亡。

具体操作：

将 VECTOR_DB 环境变量设置为客户端-服务器架构的向量数据库：

VECTOR_DB=pgvector

推荐的替代方案：

向量数据库	最佳适用场景	配置方式
PGVector	已在使用 PostgreSQL 的团队——复用您现有的数据库基础设施	`VECTOR_DB=pgvector` + `PGVECTOR_DB_URL=postgresql://...`
MariaDB Vector	基于 HNSW 的向量搜索——性能与其他实现相当，在多连接工作负载下具有更强的可扩展性	`VECTOR_DB=mariadb-vector` + `MARIADB_VECTOR_DB_URL=mariadb+mariadbconnector://...`
Milvus	具有高查询吞吐量的大规模自托管部署；支持多租户以实现单用户隔离	`VECTOR_DB=milvus` + `MILVUS_URI=http://milvus-host:19530`
Qdrant	需要高效过滤和元数据搜索的自托管部署；支持多租户	`VECTOR_DB=qdrant` + `QDRANT_URI=http://qdrant-host:6333`
Pinecone	完全托管的云服务——零基础设施维护，按使用量计费	`VECTOR_DB=pinecone` + `PINECONE_API_KEY=...`
ChromaDB（HTTP 模式）	保留 ChromaDB 但通过将其作为独立服务器运行以确保多进程安全	`VECTOR_DB=chroma` + `CHROMA_HTTP_HOST=chroma-host` + `CHROMA_HTTP_PORT=8000`

备注

只有 PGVector 和 ChromaDB 会得到 Open WebUI 团队的持续维护。其他向量库主要是由社区添加的。

提示

如果您已经在使用 PostgreSQL 作为主数据库，PGVector 是最简单的选择——它在您已有的数据库基础上增加了向量搜索，无需额外的基础设施。

为了在自托管环境中获得最大程度的扩展性，Milvus 和 Qdrant 都支持 多租户模式 (ENABLE_MILVUS_MULTITENANCY_MODE=True / ENABLE_QDRANT_MULTITENANCY_MODE=True)，这可以在大规模部署时提供更好的资源共享。

何时使用： 您运行了多个实例，且这些实例需要共享上传的文件、生成的图像以及其他用户数据。

默认情况下，Open WebUI 将上传的文件存储在本地文件系统的 DATA_DIR（通常为 /app/backend/data）下。在多实例设置中，每个实例都需要能够访问相同的文件。如果没有共享存储，当请求打到不同的副本时，您将看到上传的文件和 RAG 知识变得无法访问。

我需要云存储 (S3) 吗？

不一定。 Open WebUI 存储所有上传的文件时，都采用基于 UUID 的唯一文件名。多个进程和副本只会创建新文件或读取已有文件——它们永远不会同时写入同一个文件。这意味着简单的共享文件系统挂载在正常运行时便可正确工作，且不会产生写入冲突。虽然您需要确保，在共享存储中所有的 Worker 进程/副本都可以访问相同的共享 DATA_DIR 目录。

您的选择：

方案	何时使用
共享文件系统（NFS、AWS EFS、CephFS、GlusterFS，或者简单的共享 Docker 卷）	对绝大多数部署来说最简单的选项。在所有实例上将相同的目录挂载到 `/app/backend/data` 下。适用于本地环境、Docker Swarm 以及使用 ReadWriteMany (RWX) 卷的 Kubernetes。
云对象存储（S3、GCS、Azure Blob）	适用于极大容量的云原生部署，或者当您希望使用托管持久化（11 个 9 的可靠性）且不想管理共享文件系统时。需要设置 `STORAGE_PROVIDER`。

STORAGE_PROVIDER 实际上控制什么？

STORAGE_PROVIDER 仅控制上传的文件（文档、图片等）存储在哪里。它不会影响主数据库（主数据库请使用 DATABASE_URL）或向量数据库（向量数据库请使用 VECTOR_DB）。如果不设置此变量，文件会保存在本地文件系统的 DATA_DIR 下。

选项 A：共享文件系统（最简单）

无需进行配置更改——只需确保所有实例都挂载了相同的目录即可：

Kubernetes 示例：

volumes:
  - name: data
    persistentVolumeClaim:
      claimName: openwebui-data  # 必须是 ReadWriteMany (RWX)

Docker Compose 示例：

volumes:
  - /opt/data/openwebui-data:/app/backend/data

注意

请不要将 SQLite 数据库放在网络文件系统上。SQLite 的文件锁定在 NFS 上无法可靠工作。这是在扩展至多个实例之前必须切换到 PostgreSQL（步骤 1）的另一个原因。

一旦共享了您的数据目录，请锁定可能存入其中的文件：参阅文件上传限制了解大小、数量和扩展名上限，参阅数据目录了解文件系统权限和备份指南。

选项 B：云对象存储

设置 STORAGE_PROVIDER 和对应的凭证：

支持的提供商：

提供商	将 `STORAGE_PROVIDER` 设置为
Amazon S3（或兼容 S3 的服务，如 MinIO, R2）	`s3`
Google Cloud Storage	`gcs`
Microsoft Azure Blob Storage	`azure`

STORAGE_PROVIDER=s3
S3_BUCKET_NAME=my-openwebui-bucket
S3_REGION_NAME=us-east-1

每个提供商都有自己用于凭据和 Bucket 配置的环境变量。详情请参阅环境变量参考。

步骤 6 — 优化内容提取与向量化模型（Embeddings）

何时使用： 您需要经常处理文档（RAG、知识库）且正在生产环境中运行。

这些默认设置在大规模运行时会导致内存泄漏

默认的内容提取引擎 (pypdf) 和默认的向量化模型引擎 (SentenceTransformers) 是生产环境 Open WebUI 部署中最常见的两个内存泄漏原因。修复这些问题与切换到 PostgreSQL 或添加 Redis 同样重要。

具体操作：

将内容提取引擎切换为外部服务：

CONTENT_EXTRACTION_ENGINE=tika
TIKA_SERVER_URL=http://tika:9998

将向量化模型引擎切换为外部服务商：

RAG_EMBEDDING_ENGINE=openai
# 或在自托管时使用：
RAG_EMBEDDING_ENGINE=ollama

关键注意事项：

默认的内容提取器 (pypdf) 存在无法避免的已知内存泄漏，这会导致您的 Open WebUI 进程内存不断增长。外部提取器（Tika, Docling）在其自己的进程/容器中运行，从而隔离了这些泄漏。
默认的 SentenceTransformers 向量化模型在每个 Worker 进程中大约会加载 ~500MB。如果有 8 个 Worker 进程，这意味着仅向量化模型就需要占用 4GB 的 RAM。使用外部向量化服务可以消除这项开销。
详细指南和配置选项请参阅性能指南中的内容提取引擎和向量化模型引擎。
外部 Tika、Docling 或向量化模型端点会成为 Open WebUI 的新出站访问目的地。请仅通过内部网络访问它们，并仔细阅读安全加固指南中的网络与出站请求章节了解 SSRF 默认设置（AIOHTTP_CLIENT_ALLOW_REDIRECTS=false，WEB_FETCH_FILTER_LIST），以防配置错误的提取器 URL 被重定向到内部地址。

步骤 7 — 添加可观测性

何时使用： 您希望监控性能、排查故障，并了解您的部署在大规模运行时的行为。

Open WebUI 支持通过 OpenTelemetry 将 Trace、Metric 和 Log 导出至您的可观测性平台（Grafana、Datadog、New Relic 等）：

ENABLE_OTEL=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4317

这可以为您提供关于请求延迟、数据库查询性能、错误率等指标的可见性。

完整设置指南请参阅 OpenTelemetry 监控。应用层日志配置（日志级别、调试输出）请参阅 Open WebUI 日志记录。关于面向日志收集器的结构化日志默认设置，以及用于记录身份验证事件、管理员操作和数据访问的专用审计日志，请参阅安全加固指南中的可观测性和审计日志。

整体架构

一个生产就绪的、已扩展的部署通常架构如下：

┌─────────────────────────────────────────────────────┐
│                   负载均衡器                         │
│              (Nginx, HAProxy, Cloud LB)             │
└──────────┬──────────┬──────────┬────────────────────┘
           │          │          │
     ┌─────▼──┐ ┌─────▼──┐ ┌────▼───┐
     │ WebUI  │ │ WebUI  │ │ WebUI  │   ← 无状态容器
     │ Pod 1  │ │ Pod 2  │ │ Pod N  │
     └───┬────┘ └───┬────┘ └───┬────┘
         │          │          │
    ┌────▼──────────▼──────────▼────┐
    │         PostgreSQL            │   ← 共享数据库
    │     (+ PGVector 用于 RAG)     │   ← 向量数据库 (或其它向量数据库)
    └───────────────────────────────┘
    ┌───────────────────────────────┐
    │           Redis               │   ← 共享状态与 WebSocket
    └───────────────────────────────┘
    ┌───────────────────────────────┐
    │  共享存储 (NFS 或 S3)         │   ← 共享文件存储
    └───────────────────────────────┘

运行遇到问题？ 扩展与高可用故障排查指南涵盖了常见问题（登录循环、WebSocket 失败、数据库锁、Worker 崩溃）及其解决方案。对于大规模部署下的性能调优，请参阅优化、性能与内存占用。

扩展部署的最低环境变量配置

# 数据库
DATABASE_URL=postgresql://user:password@db-host:5432/openwebui

# 向量数据库 (在多 Worker/多副本时，请勿使用默认的 ChromaDB)
VECTOR_DB=pgvector
PGVECTOR_DB_URL=postgresql://user:password@db-host:5432/openwebui

# Redis
REDIS_URL=redis://redis-host:6379/0
WEBSOCKET_MANAGER=redis
ENABLE_WEBSOCKET_SUPPORT=true

# 存储 — 择其一：
# 选项 A: 共享文件系统 (无需配置环境变量，直接挂载相同的文件卷即可)
# 选项 B: 云存储
# STORAGE_PROVIDER=s3
# S3_BUCKET_NAME=my-openwebui-bucket
# S3_REGION_NAME=us-east-1

# 内容提取 (请勿在生产环境使用默认的 pypdf)
CONTENT_EXTRACTION_ENGINE=tika
TIKA_SERVER_URL=http://tika:9998

# 向量化模型 (大规模部署下请勿使用默认的 SentenceTransformers)
RAG_EMBEDDING_ENGINE=openai
# 或：RAG_EMBEDDING_ENGINE=ollama

# Worker 数量 (让编排器处理扩缩容，保持 worker 数为 1)
UVICORN_WORKERS=1

# 数据库迁移 (在除一个实例之外的所有实例上均设置为 false)
ENABLE_DB_MIGRATIONS=false

大规模部署时需要重新审视的安全默认设置

一些在单用户评估时很合理的默认设置，一旦将部署置于 SSO 之后为真实用户提供服务，就变得不再那么合适了。完整讨论在安全加固指南中展开；以下是企业级部署中最常遗漏的项：

停用外部头像 URL 重定向 — ENABLE_PROFILE_IMAGE_URL_FORWARDING=false。默认情况下，用户/模型的头像端点会通过 302 重定向到 profile_image_url 中包含的任何外部 URL，这会导致查看该头像的每个用户的浏览器将其 IP、User-Agent 和 Referer 泄露给该外部源。对于共享部署，除非您的 IdP 仅提供 data: URI 的头像（Open WebUI 会本地持久化，不受影响）或者您有意识要保持渲染 IdP 托管的头像（例如您的 OAUTH_PICTURE_CLAIM 返回 Google/Gravatar 链接且您希望显示它们），否则请将此值设置为 false。有关对应的 OAuth 头像 Claim 设置，请参阅 SSO 配置。
将所有副本上的 WEBUI_SECRET_KEY 和 OAUTH_SESSION_TOKEN_ENCRYPTION_KEY 设置为相同值。如果不这样做，会话将在滚动重启时断开，且由一个 Pod 写入的 OAuth Token 无法被另一个 Pod 解密。
如果您的部署包含敏感数据，请调低 JWT_EXPIRES_IN 的默认值（当前为四周），尤其是在尚未部署 Redis 以便在退出登录时撤销 Token 的情况下。参阅 Token 撤销。
在所有客户端迁移到新的服务器端会话模型之后，禁用 ENABLE_OAUTH_ID_TOKEN_COOKIE (false)。旧版 Cookie 会将 IdP 的原始 id_token 传输给浏览器；新模型会将它保存在服务器端。

这些是配置默认项，而不是新功能——当一个部署拥有多个用户且前面放置了真正的身份提供商时，已有的控制开关变得愈发重要。

除了这几个简短项之外，安全加固指南按主题对相同的关注点进行了分组，以便您能够一步步进行处理：网络部署、身份验证与注册、会话与 Cookie 安全、安全响应头、访问控制、Tool、Function 与 Pipeline，以及末尾的安全至上的部署实践检查表。

快速参考：何时我需要什么？

场景	PostgreSQL	Redis	外部向量数据库	外部内容提取	外部向量化模型	共享存储
单用户 / 评估阶段	✗	✗	✗	✗	✗	✗
小团队 (< 50 用户，单实例)	推荐	推荐†	✗	推荐	✗	✗
多个 Uvicorn worker	必须	必须	必须	强烈推荐	强烈推荐	✗ (相同文件系统)
多实例 / 高可用 (HA)	必须	必须	必须	强烈推荐	强烈推荐	可选 (NFS 或 S3)
大规模 (1000+ 用户)	必须	必须	必须	强烈推荐	强烈推荐	可选 (NFS 或 S3)

†如果没有 Redis，退出登录和修改密码将无法撤销 Token——Token 将一直有效，直到 JWT_EXPIRES_IN 过期（默认：4 周）。对于处理敏感数据的生产部署，建议配置 Redis 以进行正确的 Token 撤销。参见 Token 撤销。

关于“外部向量数据库”

默认的 ChromaDB 使用本地 SQLite 后端，会在多进程并发访问下崩溃。“外部向量数据库”意味着使用客户端-服务器架构的数据库（PGVector, Milvus, Qdrant, Pinecone）或者以独立 HTTP 服务器运行的 ChromaDB。详情请参见步骤 4。

关于“共享存储”

对于多实例部署，所有副本都需要能够访问相同的上传文件。一个共享文件系统挂载（本地驱动器、NFS、EFS、CephFS）便已足够——云对象存储（S3/GCS/Azure）是一个可扩展的替代方案，但并不是必须的。文件采用基于 UUID 的唯一命名方式，因此不会有写入冲突。详情请参见步骤 5。

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.

理解默认设置​

步骤 1 — 切换到 PostgreSQL​

为什么在网络存储上的 SQLite 会在扩展（或升级）时立即失效​

步骤 2 — 添加 Redis​

步骤 3 — 运行多个实例​

选项 A：容器编排（推荐）​

选项 B：每个容器运行多个 Worker​

步骤 4 — 切换到外部向量数据库​

步骤 5 — 在实例之间共享文件存储​

我需要云存储 (S3) 吗？​

选项 A：共享文件系统（最简单）​

选项 B：云对象存储​

步骤 6 — 优化内容提取与向量化模型（Embeddings）​

步骤 7 — 添加可观测性​

整体架构​

扩展部署的最低环境变量配置​

大规模部署时需要重新审视的安全默认设置​

快速参考：何时我需要什么？​

理解默认设置

步骤 1 — 切换到 PostgreSQL

为什么在网络存储上的 SQLite 会在扩展（或升级）时立即失效

步骤 2 — 添加 Redis

步骤 3 — 运行多个实例

选项 A：容器编排（推荐）

选项 B：每个容器运行多个 Worker

步骤 4 — 切换到外部向量数据库

步骤 5 — 在实例之间共享文件存储

我需要云存储 (S3) 吗？

选项 A：共享文件系统（最简单）

选项 B：云对象存储

步骤 6 — 优化内容提取与向量化模型（Embeddings）

步骤 7 — 添加可观测性

整体架构

扩展部署的最低环境变量配置

大规模部署时需要重新审视的安全默认设置

快速参考：何时我需要什么？