在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

lobehub/lobe-chat

菜单

部署选项

相关源文件

本文档提供了在各种平台和配置上部署 LobeChat 的全面指南。LobeChat 提供了多种部署方法，以适应不同的基础设施要求，从简单的仅客户端部署到全栈服务器数据库配置。

部署架构概述

LobeChat 提供了三种主要的部署架构，每种都针对不同的基础设施要求和用例而设计。

容器部署架构

来源

Docker 容器变体

LobeChat 提供了三种不同的 Docker 容器变体，每种都针对不同的部署场景和数据存储需求进行了优化。

标准容器 (`lobehub/lobe-chat`)

此变体基于 Dockerfile1-253 构建，使用浏览器 IndexedDB 将所有数据存储在客户端。适用于个人使用以及不需要服务器端数据持久化的环境。

主要特点

  • 通过 IndexedDB 进行客户端数据存储
  • 无需外部数据库
  • 通过环境变量支持 40 多个 AI 模型提供商
  • 图像文件作为二进制数据存储在浏览器中

数据库容器 (`lobehub/lobe-chat-database`)

此变体基于 Dockerfile.database1-297 构建，需要外部 PostgreSQL 数据库和 S3 存储。专为多用户环境和生产部署设计。

主要特点

  • 带 pgvector 扩展的服务器端 PostgreSQL 数据库
  • S3 兼容的对象存储，用于文件处理
  • NextAuth 集成，用于身份验证服务
  • 通过迁移脚本自动进行数据库迁移

PGLite 容器 (`lobehub/lobe-chat:pglite`)

此混合方法基于 Dockerfile.pglite1-251 构建，使用 PGLite 在浏览器中提供 SQL 功能，并可选择云同步功能。

主要特点

  • PGLite 在浏览器中提供 SQL 功能
  • 混合本地/云数据同步
  • 基本操作无需外部数据库
  • 基于 CRDT 的多设备同步冲突解决

容器环境变量配置

所有容器变体都支持针对 AI 模型提供商的广泛环境变量配置，这些配置在 Dockerfile 环境部分中定义

来源

Docker Compose 自托管

Docker Compose 提供了在 docker-compose/local/docker-compose.yml1-174 中定义的完整自托管解决方案。该部署支持由 setup 脚本管理的三个不同模式。

服务架构

部署模式

docker-compose/setup.sh1-1000 脚本提供了三种部署模式

本地模式 (默认)

  • 访问: http://:3210
  • 配置: 默认 localhost URL
  • 用例: 本地开发和测试
  • 网络: 仅内部容器网络

端口模式

  • 访问: http://your-server-ip:3210
  • 配置: 基于 IP 的 URL，带有暴露的端口
  • 用例: LAN 访问或无域名的公共 IP
  • 要求: 开放端口 3210, 8000, 9000, 9001

域名模式

  • 访问: https://lobe.example.com
  • 配置: 带有反向代理的完整域名设置
  • 用例: 带有 SSL 的生产部署
  • 要求: 域名和反向代理配置

自动化设置流程

快速部署

设置脚本生成

服务依赖项

docker-compose/local/docker-compose.yml94-164 定义了服务依赖关系

这确保了在 LobeChat 初始化之前正确的启动顺序和健康检查。

来源

云平台部署

LobeChat 支持在多个云平台部署，每个平台都有特定的配置要求和功能。

平台部署矩阵

Vercel 部署

Vercel 部署使用标准容器变体，需要外部服务来实现数据库功能。该平台提供内置的环境变量管理和自动 HTTPS。

要求

  • 外部 PostgreSQL 数据库 (Vercel Postgres, Neon 等)
  • S3 兼容的存储服务
  • 身份验证提供商 (Auth0, GitHub 等)

通过环境变量进行配置

  • DATABASE_URL: PostgreSQL 连接字符串
  • KEY_VAULTS_SECRET: 敏感数据的加密密钥
  • NEXT_AUTH_SECRET: NextAuth 会话加密
  • 模型提供商 API 密钥

Zeabur 模板部署

Zeabur 提供了一个全面的模板，在一个部署中包含了所有所需的服务。其市场中定义的模板包括

  • LobeChat 数据库应用
  • 带 pgvector 的 PostgreSQL
  • 用于对象存储的 MinIO
  • 用于身份验证的 Logto

模板服务

  1. LobeChat 数据库：主应用
  2. PostgreSQL：带 pgvector 扩展的向量数据库
  3. MinIO：S3 兼容的对象存储
  4. Logto：身份验证和用户管理

该模板自动配置服务连接，并为所有组件提供域名绑定。

自托管平台考量

对于 Railway、Render 或 DigitalOcean App Platform 等平台

容器选择

  • 对无服务器/无状态部署使用 lobehub/lobe-chat
  • 对全栈部署使用 lobehub/lobe-chat-database

数据库选项

  • 平台管理的带 pgvector 的 PostgreSQL
  • 外部数据库提供商 (Neon, PlanetScale 等)
  • 自管理数据库容器

存储配置

  • 平台对象存储服务
  • 外部 S3 提供商 (AWS, Cloudflare R2 等)
  • 用于自管理存储的 MinIO 容器

来源

部署基础设施要求

不同的部署方法需要特定的基础设施组件。了解这些要求有助于选择合适的部署策略。

基础设施依赖矩阵

服务器配置管理

src/server/globalConfig/index.ts1-100 管理部署特定配置

模型提供商配置系统

src/config/llm.ts1-336 和 src/config/modelProviders/index.ts1-229 定义了 AI 模型提供商系统

配置文件目的关键导出
src/config/llm.ts环境变量验证getLLMConfig(), llmEnv
src/config/modelProviders/index.ts提供商卡片和模型列表DEFAULT_MODEL_PROVIDER_LIST
src/config/aiModels/index.tsAI 模型定义LOBE_DEFAULT_MODEL_LIST

该系统支持 40 多个提供商，具有标准化的配置模式

  • API 密钥变量 (例如，OPENAI_API_KEY, ANTHROPIC_API_KEY)
  • 代理 URL 变量 (例如，OPENAI_PROXY_URL, GOOGLE_PROXY_URL)
  • 模型列表自定义 (例如，OPENAI_MODEL_LIST, AZURE_MODEL_LIST)

来源

部署安全与最佳实践

按部署类型划分的安全配置

基本安全变量

对于生产部署，这些环境变量至关重要

可变所需功能目的
ACCESS_CODE所有部署应用访问控制
KEY_VAULTS_SECRET数据库部署加密数据库中的敏感数据
NEXT_AUTH_SECRET数据库部署NextAuth 会话加密
S3_PUBLIC_DOMAIN文件上传文件的公共访问域
AUTH_CASDOOR_ISSUERDocker ComposeCasdoor OAuth2 配置

部署健康监控

Docker Compose 设置包括健康检查和监控

LobeChat 容器包含对依赖服务的内置健康检查，如 docker-compose/local/docker-compose.yml124-163 中所定义

来源

特殊部署场景

本地 AI 模型集成

LobeChat 可以使用 Ollama 与本地 AI 模型一起部署，提供完整的隐私和离线功能。

使用 Ollama 进行 Docker 部署

数据库迁移场景

对于数据库部署，容器处理自动模式迁移

迁移过程在容器启动期间由 Dockerfile.database1-297 自动处理，确保部署间的模式一致性。

多环境部署

适用于运行多个环境的组织

环境容器变体数据库身份验证监控
开发lobehub/lobe-chat本地/浏览器开发密钥基本日志记录
预发布lobehub/lobe-chat-database共享 PostgreSQL测试认证健康检查
生产lobehub/lobe-chat-database专用 PostgreSQL生产 SSO全面监控

边缘部署考量

适用于边缘部署或受限环境

  • PGLite 变体：对最小基础设施使用 Dockerfile.pglite1-251
  • 精简提供商：仅配置必要的 AI 提供商
  • 本地存储：使用 MinIO 容器而不是云 S3
  • 简化认证：使用基本访问代码而不是完整 SSO

来源

部署故障排除

常见 Docker 部署问题

身份验证服务问题

对于 Docker Compose 部署，常见的身份验证问题包括

OAuth2 配置错误

解决方案

  • 验证反向代理配置没有阻止 /.well-known/openid-configuration
  • 检查 AUTH_CASDOOR_ISSUER 是否与实际的 Casdoor 服务 URL 匹配
  • 确保 LobeChat 容器可以访问 Casdoor 服务

网络连接错误

解决方案

  • 验证 Casdoor 服务正在运行: docker logs -f lobe-casdoor
  • 测试连接: wget ${AUTH_CASDOOR_ISSUER}/.well-known/openid-configuration

数据库连接问题

对于数据库部署，监控迁移过程

预期成功日志

常见问题

  • 容器启动时数据库未就绪
  • 缺少 pgvector 扩展
  • 不正确的 DATABASE_URL 格式

存储服务问题

对于 S3 存储问题

MinIO 健康检查

CORS 配置： 验证 MinIO CORS 设置允许来自 LobeChat 域名的请求，如 docker-compose/local/docker-compose.yml42

端口和网络配置

Docker Compose 的默认端口分配

服务端口目的
LobeChat3210主应用
Casdoor8000身份验证服务
MinIO API9000对象存储 API
MinIO 控制台9001MinIO 网页界面

端口冲突解决

来源

常见问题排查

无法正常登录 (数据库版本)

检查这些常见错误

  1. OAuth 配置问题:
[auth][error] r3: "response" is not a conform Authorization Server Metadata response (unexpected HTTP status code)
  • 解决方案：确保您的反向代理配置没有拦截 Casdoor OAuth2 配置请求。
  1. 身份验证服务连接问题:
[auth][error] TypeError: fetch failed
  • 解决方案：检查您的身份验证服务是否正在运行并且可以从 LobeChat 访问。

来源

API 连接问题

如果您在连接模型提供商时遇到问题

  1. 检查 API 密钥是否正确配置
  2. 如果使用代理访问 API，请验证代理 URL
  3. 对于 Ollama，请确保 CORS 设置正确配置

来源

安全考量

在部署 LobeChat 时，特别是在面向公众的环境中

  1. 始终设置 ACCESS_CODE 以限制访问
  2. 对于数据库版本，禁用开放注册
  3. 保护您的 API 密钥和敏感环境变量
  4. 对于域名模式部署，请使用 HTTPS 和正确配置的证书

来源