LobeChat：以 Agent 为工作单元、支持多模型与协作编排的现代开源 AI 聊天框架｜部署与使用全指南
项目仓库： https://github.com/lobehub/lobehub
开源协议：LobeHub Community License（基于 Apache
2.0，附加商用派生作品条款，见第 11 节） · 技术栈：Next.js 全栈 + Vite
SPA 前端、PostgreSQL（pg_search /
ParadeDB）、Redis、RustFS（S3）、SearXNG、可选 Elasticsearch ·
交付形态：Docker Compose 自托管栈、Vercel / Zeabur / Sealos /
阿里云一键部署、源码本地开发 · 默认应用端口 3210 ·
官方文档：lobehub.com/docs
非官方声明：LobeChat（现品牌 LobeHub）是开源社区项目，与 OpenAI、Anthropic、Google、Microsoft、Claude Code、Codex、Discord、Telegram、Slack、微信、QQ、LINE 等模型与平台厂商不存在隶属、授权或合作关系；文中出现的模型、渠道与服务名称仅用于说明兼容目标。API Key、订阅账号与模型服务条款由对应厂商约束，使用者须自行确认合规边界。
1 项目简介
LobeChat 是 LobeHub 团队维护的现代开源 AI 聊天框架（仓库由
lobehub/lobe-chat 更名为
lobehub/lobehub，产品现以 LobeHub
品牌发布）。项目把 Agent
视为工作单元：不再只是单轮对话框，而是一个发现、构建并与 Agent
队友共同成长的工作空间，覆盖 Agent 招募与排程、Agent Builder
搭建助手、Skills 与 MCP 工具接入、Pages / Schedule / Project / Workspace
协作形态，以及可编辑的个人记忆。部署形态以 Docker Compose
自托管为核心，同时提供
Vercel、Zeabur、Sealos、阿里云等一键部署入口。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | LobeChat（现品牌 LobeHub；仓库
lobehub/lobehub，历史仓库名
lobehub/lobe-chat） |
| 仓库地址 | github.com/lobehub/lobehub |
| 项目定位 | 以 Agent 为工作单元、支持多模型与协作编排的现代开源 AI 聊天 / Agent 框架 |
| 开源协议 | LobeHub Community License（Apache 2.0 基础 + 派生作品商用限制） |
| 技术栈 | Next.js 全栈、Vite SPA 前端、PostgreSQL（ParadeDB / pg_search）、Redis、RustFS S3、SearXNG、可选 Elasticsearch |
| 部署方式 | Docker Compose 一键栈；setup.sh 初始化脚本；Vercel / Zeabur / Sealos
/ 阿里云一键部署；pnpm dev 本地开发 |
| 应用端口 | 3210（LOBE_PORT）；RustFS
9000 / 管理台 9001；Agent 网关
8787；设备网关 8788 |
| 模型接入 | OpenAI 及任意 OpenAI
兼容端点（OPENAI_PROXY_URL）、Azure
OpenAI、Ollama、Google、Anthropic、Bedrock、Gemini
等，具体以端点配置与官方文档为准 |
| 官方文档 | lobehub.com/docs · Docker Compose 部署 · 环境变量 |
1.2 适用场景
- 个人需要一个自托管、可长期使用的 AI 聊天空间，统一接入多家云端模型与本地 / 兼容端点，而不是在多个网页之间切换。
- 团队需要把多个 Agent 组织成协作小组，按 Pages 共撰、Schedule 定时运行、Project 归集、Workspace 共享开展工作。
- 开发者希望基于 Agent Builder 无代码搭建专属助手，挂载 MCP 服务器、技能插件与定时任务，形成可分享的 Agent 团队。
- 需要把 Agent 接到日常 IM 渠道（Discord、Telegram、Slack、WhatsApp、微信、QQ、LINE 等），在已有聊天工具中接收任务与结果。
- 重视记忆可控：使用结构化、可查看可编辑的白盒个人记忆沉淀长期偏好与上下文。
- 二次开发：基于仓库 Next.js 全栈与 SPA 工作区定制界面、模型路由与 Agent 工具。
1.3 能力边界（官方口径）
- 官方 README 自述 “LobeHub organizes your agents into 7×24 operation; it hires, schedules, reports on your entire AI team”；Agent 的推理质量与工具能力取决于所配置的模型、端点与第三方 MCP 服务器，平台本身不提供模型权重。
- 项目处于活跃开发阶段，部分 Agent 编排、IM 网关与设备网关能力随版本迭代；插件体系仍在持续演进，具体可用能力以当前版本界面与官方文档为准。
- 定时任务、网关模式、MCP 工具与代码类操作具备服务器执行权限；部署者须自行约束注册范围、网络暴露面与工具白名单，平台不提供绕过平台风控或保证 Agent 行为安全的承诺。
2 功能特性
2.1 Operator：排程并汇报整个 AI 团队
- 把所有 Agent 集中在一个平台管理；系统负责招募、排程与汇报 AI 团队的工作进度，用户专注制定策略。
- 以任务为单位分派给专项 Agent，子任务并行执行后汇总为报告；支持定时运行（Schedule），在用户离线时按时间窗完成任务。
2.2 IM 网关：Agent 出现在已有聊天工具中
- 通过 IM 网关把 Agent 连接到日常使用的聊天渠道，在同一个群聊或会话中调用不同 Agent；README 展示的渠道包括 Discord、WhatsApp、Slack、Notion、Telegram、微信、LINE、QQ 等，各渠道支持状态以官方文档与插件市场为准。
2.3 Agent Builder：描述需求即生成助手
- 只需描述一次需求，Agent 配置自动完成并可立即使用；可选择模型、配置系统提示词、挂载 MCP 服务器、添加技能、设定定时任务，并选择开始对话、发布到社区或创建定时任务。
- 助手可绑定能力描述、工具集与行为约束，形成可复用的专项角色。
2.4 统一智能、Skills 与 MCP 市场
- 无缝接入任意模型与任意模态，全部由部署者掌控；模型列表可通过
OPENAI_MODEL_LIST增删与改名。 - 提供 Skills 市场与 MCP 兼容插件接入：把 Agent 连接到日常使用的工具与服务；技能、MCP 服务器数量随市场更新，README 以万级规模描述能力范围。
2.5 协作网络：Pages / Schedule / Project / Workspace
- Pages：在同一位置与多个 Agent 共同撰写、润色内容，共享上下文。
- Schedule：安排任务运行时间，让 Agent 在指定时段自动完成工作。
- Project：按项目归集会话、文件与产物，保持结构清晰、便于跟踪。
- Workspace：团队与 Agent 协作的共享空间，明确所有权与组织内可见性。
- Agent Groups 会为任务组装合适的 Agent 组合，支持并行协作与迭代改进。
2.6 个人记忆：持续学习与白盒记忆
- 持续学习：Agent 从用户的工作方式中学习，在恰当时刻调整行为。
- 白盒记忆：记忆以结构化、可编辑的形式保存，用户可查看、修改或删除 Agent 记住的内容，不接受黑盒不可见记忆。
2.7 插件体系与生态组件
- 插件用于扩展 Function Calling 能力，可引入新的函数调用与结果渲染方式；官方提供插件索引仓库、插件模板与插件 SDK、插件网关。
- 生态包含
@lobehub/ui（AIGC Web UI 组件库）、@lobehub/icons（模型品牌图标集）、@lobehub/tts（语音 React Hooks）、@lobehub/lint（工程规范配置）等独立 npm 包。
3 官方界面预览
3.1 Operator 定时任务视图
下图为官方 Operator 界面：一条每周 GitHub Issues 定时分诊任务，选择模型与优先级，列出 Backlog 子任务、活动记录与子任务完成进度，Agent 按计划自动汇总分诊报告。
3.2 IM 网关
下图左右两个面板：左侧为多个 Agent 在同一空间协作讨论的群聊形态，右侧为 IM 网关把 Agent 分发到各日常聊天渠道的渠道图标矩阵。
3.3 Agent Builder
下图为 Agent Builder 界面：以 “Recruitment Assistant” 为例，配置模型、Gmail 与 LinkedIn MCP、系统提示词、能力描述与定时任务入口；右侧为可安装的 LinkedIn 类 MCP 服务器列表。
3.4 Skills 市场与统一智能
下图左侧为 Skills 市场入口与海量技能、MCP 服务器规模展示，右侧为 “Unified intelligence”：任意模型、任意模态在受控环境中统一使用。
3.5 协作工作流
下图展示多模态工作流下的四类协作形态：Pages 共撰、Schedule 定时、Project 项目归集与 Workspace 团队共享，配套资产、文档、代码脚本目录与项目笔记面板。
3.6 个人记忆
下图为记忆面板四象限：个人记忆画像标签、持续学习的使用记录与观察模式、自适应行为的记忆检索摘要，以及可编辑、可删除的白盒 Profile 记忆。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 仓库主页 | github.com/lobehub/lobehub | 全栈前端、后端与部署源码 |
| 官方站点 | lobehub.com | 产品官网与在线演示 |
| 使用文档 | lobehub.com/docs/usage/start | 上手与界面使用说明 |
| Docker Compose 文档 | lobehub.com/docs/self-hosting/server-database/docker-compose | 自托管 Compose 部署指南 |
| 环境变量文档 | lobehub.com/docs/self-hosting/environment-variables | 全量环境变量参考 |
| 本地开发指南 | lobehub.com/docs/development/start | 仓库开发与构建说明 |
| Docker 镜像 | hub.docker.com/r/lobehub/lobehub | 官方应用镜像 |
| Releases | github.com/lobehub/lobehub/releases | 版本归档与更新说明 |
| Changelog | lobehub.com/changelog | 版本变更记录 |
| Issues 反馈 | github.com/lobehub/lobehub/issues | Bug 跟踪与功能反馈 |
| Discord 社区 | discord.gg/AYFPHvv2jT | 开发者与用户交流 |
| 插件索引 | github.com/lobehub/lobe-chat-plugins | 官方插件市场索引 |
| Agent 提交 | github.com/lobehub/lobe-chat-agents | 社区 Agent 提交仓库 |
| 插件 SDK | github.com/lobehub/chat-plugin-sdk | 插件开发 SDK |
| Vercel 一键部署 | vercel.com/new/clone | 官方模板入口 |
| Zeabur 部署 | zeabur.com/templates/VZGGTI | 官方模板入口 |
| Sealos 部署 | template.usw.sealos.io/deploy?templateName=lobehub-db | 官方模板入口 |
5 前置要求与环境配置
5.1 软件前提
- Docker 部署：Docker 与 Docker Compose 插件；栈内自带 PostgreSQL、Redis、RustFS、SearXNG 与网关服务，宿主机无需单独安装数据库。
- 本地开发：Node.js 运行环境、pnpm（仓库脚本使用 pnpm
安装与启动）；可选 Bun 运行 SPA 开发模式；具体版本要求以仓库
package.json与开发文档为准。 - 模型凭据：至少准备一个模型提供者的 API Key（如
OPENAI_API_KEY）；使用兼容端点时配置OPENAI_PROXY_URL与模型列表。 - 反向代理（公网域名部署）：需要 Nginx / Caddy 等反代并开启 WebSocket 升级，分别映射应用、RustFS 与 Agent 网关。
5.2 硬件与系统建议
| 项目 | 说明 |
|---|---|
| 服务器 | 个人 / 小团队使用 2 核 4GB 以上云主机起步；可选 Elasticsearch 节点单独预留至少 2GB 内存 |
| 操作系统 | Docker 方式支持主流 Linux 发行版；本地开发支持 macOS / Windows / Linux |
| 磁盘 | PostgreSQL 数据、Redis 持久化、RustFS 对象存储与上传文件需持久化目录，按会话与图片规模预留空间 |
| 模型推理 | 云端模型对本机硬件要求低；本地模型由独立后端提供，资源需求以后端与模型为准 |
5.3 端口分配
| 服务 | 默认端口 | 说明 |
|---|---|---|
lobe 应用 |
3210 |
主应用 HTTP 端口，宿主 ${LOBE_PORT}:3210 |
rustfs 对象存储 |
9000 |
S3 API，浏览器上传图片需通过此端点的预签名 URL 访问 |
rustfs 管理台 |
9001 |
RustFS 控制台 |
gateway Agent 网关 |
8787 |
网关模式 Agent 运行经 WebSocket 推送到浏览器，宿主
${AGENT_GATEWAY_PORT:-8787} |
gateway 设备网关 |
8788 |
把工具调用路由到已加入网关的设备，宿主
${DEVICE_GATEWAY_PORT:-8788} |
postgresql |
5432（内部） |
ParadeDB / pg_search 数据库，默认不对外暴露 |
redis |
6379（内部） |
缓存与会话状态，默认不对外暴露 |
searxng |
8080（内部） |
在线搜索聚合，配置见 searxng-settings.yml |
setup.sh 提示需确保服务器以下端口未被占用且可访问：
3210、9000、9001、8787、8788。
5.4 持久化目录与卷
| 项 | 说明 |
|---|---|
./data |
PostgreSQL 数据目录（bind mount 到
/var/lib/postgresql/data） |
redis_data 命名卷 |
Redis AOF 与快照持久化 |
rustfs-data 命名卷 |
RustFS 对象存储数据 |
fts-search-reindex-state 命名卷 |
可选 Elasticsearch 重建检查点状态 |
elasticsearch-data 命名卷 |
可选 ES 节点数据（仅启用 ES profile 时创建） |
6 方式一：setup.sh 一键初始化 + Docker Compose 部署（推荐）
6.1 创建部署目录并运行初始化脚本
# 1. 创建独立部署目录
mkdir lobehub-db && cd lobehub-db
# 2. 运行官方初始化脚本（下载 Compose、配置文件与 .env，引导生成密钥与部署模式）
bash <(curl -fsSL https://lobe.li/setup.sh)脚本依次完成：
- 选择语言（English / 简体中文）。
- 选择部署模式：
0域名模式：反向代理分别映射 LobeHub、RustFS、Agent 网关域名，访问无需端口；1端口模式：使用 IP 或域名 + 端口访问，需放开指定端口；2本地模式：仅供本机测试（localhost:3210）。
- 选择是否重新生成安全密钥；脚本自动生成
KEY_VAULTS_SECRET、AUTH_SECRET（base64 32 字节）与RUSTFS_SECRET_KEY。 - 自动生成网关
GATEWAY_SERVICE_TOKEN与 RS256 的JWKS_KEY/JWKS_PUBLIC_KEY。 - 选择是否初始化数据库：脚本执行
docker compose pull、后台启动postgresql、等待约 15 秒后停止，完成首次数据库初始化。
目录下已存在
data或s3_data文件夹时，脚本只完成初始化配置、不重复安装；如需重装，先备份并删除这两个目录。
6.2 启动服务栈
# 前台启动（默认不附加 SearXNG 日志）
docker compose up --no-attach searxng
# 确认运行正常后，后台常驻启动
docker compose up -d --no-attach searxng启动完成后按所选模式访问：本地模式
http://localhost:3210；端口模式
http://服务器IP:3210；域名模式经反向代理访问绑定域名。
6.3 手动方式（不使用 setup.sh）
# 1. 准备目录
mkdir lobehub-db && cd lobehub-db
# 2. 从仓库 docker-compose/deploy 目录下载 Compose、搜索配置、桶配置与环境变量模板
# docker-compose.yml、searxng-settings.yml、bucket.config.json、.env.example
# 仓库路径：https://github.com/lobehub/lobehub/tree/main/docker-compose/deploy
# 3. 复制环境变量模板并填写密钥、主机地址与模型 Key
cp .env.example .env
# 4. 拉取镜像并初始化数据库
docker compose pull
docker compose up -d postgresql
# 等待数据库就绪后再启动全栈
# 5. 启动全部服务
docker compose up -d6.4 部署模式与反向代理要点
- 域名模式：在反向代理中完成域名到端口的映射——主应用域名
→
127.0.0.1:3210；RustFS 域名 →127.0.0.1:9000；Agent 网关域名 →127.0.0.1:8787（WebSocket）。 - Agent 网关 WebSocket：网关模式把 Agent 运行结果经
WebSocket 推送到浏览器；反向代理需开启 WebSocket
升级头（
Upgrade/Connection），AGENT_GATEWAY_URL必须是浏览器可访问的网关地址。 - RustFS 浏览器访问：对话内上传图片使用浏览器可达的
S3_ENDPOINT预签名地址；服务端到 RustFS 的请求走 Compose 内网S3_INTERNAL_ENDPOINT=http://rustfs:9000。 - 所有服务须使用同一协议；域名模式选择 HTTPS
时，按脚本提示把对外地址统一切换为
https。
7 方式二：源码本地运行（开发 / 二次开发）
7.1 环境准备
- 安装 Node.js 与 pnpm；需要 SPA 独立开发模式时可安装 Bun。
- 本地完整运行通常仍需 PostgreSQL、Redis 等后端服务；开发联调可参考官方 开发指南 与仓库内开发脚本说明。
7.2 克隆与启动
git clone https://github.com/lobehub/lobehub.git
cd lobehub
# 安装依赖
pnpm install
# 全栈开发：Next.js + Vite SPA
pnpm dev
# 仅 SPA 前端（端口 9876）
bun run dev:spa7.3 开发说明
dev:spa启动后终端会打印调试代理 URL（指向生产后端的_dangerous_local_dev_proxy），用于带热更新地对接生产后端联调；这是开发便利入口，不作为变更验证依据。- 服务端环境变量、模型端点与密钥配置方式与 Docker 部署保持一致，详见官方 环境变量文档。
8 配置项说明
8.1 基础部署项（取自
deploy.env.example）
| 变量 | 默认值 | 说明 |
|---|---|---|
LOBE_PORT |
3210 |
主应用宿主端口，容器内固定 3210 |
RUSTFS_PORT |
9000 |
RustFS S3 API 宿主端口 |
RUSTFS_ADMIN_PORT |
9001 |
RustFS 管理台宿主端口 |
APP_URL |
http://localhost:3210 |
浏览器访问的主应用对外地址 |
INTERNAL_APP_URL |
http://localhost:3210 |
服务端内部通信地址；Docker Compose 部署必填，主机 / 局域网 IP 作为
APP_URL 时，AI 图像生成等功能依赖此项正确 |
LOBE_DB_NAME |
lobechat |
PostgreSQL 数据库名 |
POSTGRES_PASSWORD |
模板内置示例值 | 数据库密码，生产环境务必改为强随机值 |
S3_ENDPOINT |
http://localhost:9000 |
浏览器访问的 RustFS S3 端点 |
RUSTFS_ACCESS_KEY |
admin |
RustFS 访问账号 |
RUSTFS_SECRET_KEY |
YOUR_RUSTFS_PASSWORD |
RustFS 访问密钥，setup.sh 自动生成 |
RUSTFS_LOBE_BUCKET |
lobe |
对话图片等对象存储桶名 |
8.2 安全密钥
| 变量 | 说明 |
|---|---|
KEY_VAULTS_SECRET |
凭据保险库密钥（base64 32 字节），setup.sh 用
openssl rand -base64 32 生成 |
AUTH_SECRET |
会话认证密钥（base64 32 字节），setup.sh 自动生成 |
GATEWAY_SERVICE_TOKEN |
LobeHub 与网关之间的共享令牌（hex 32），setup.sh 自动生成 |
JWKS_KEY |
签发内部 JWT 的 RS256 私钥集；每次部署必须唯一 |
JWKS_PUBLIC_KEY |
不含私钥字段的公钥集，传给网关用于校验浏览器会话 JWT |
生产部署前必须替换全部默认占位密钥；
JWKS_KEY跨部署复用会导致网关信任非法会话，更换密钥后需重启应用与网关并重新登录。
8.3 注册与登录策略
| 变量 | 说明 |
|---|---|
AUTH_ALLOWED_EMAILS |
允许登录的邮箱列表，逗号分隔；设置后仅列表内邮箱可登录，留空允许所有用户注册 |
AUTH_DISABLE_EMAIL_PASSWORD |
设为 1 后禁用邮箱密码注册 / 登录，仅允许 SSO 登录 |
HTTP_PROXY / HTTPS_PROXY |
容器访问外部模型服务所需代理（可选） |
8.4 Agent / 设备网关
| 变量 | 默认值 | 说明 |
|---|---|---|
AGENT_GATEWAY_PORT |
8787 |
Agent 网关宿主端口 |
DEVICE_GATEWAY_PORT |
8788 |
设备网关宿主端口 |
AGENT_GATEWAY_URL |
http://localhost:8787 |
浏览器可见的 Agent 网关地址；反向代理时开启 WebSocket 升级 |
DEVICE_GATEWAY_URL |
http://gateway:8788 |
Compose 网络内设备网关地址 |
DEVICE_GATEWAY_PUBLIC_URL |
空 | 可选；桌面 / CLI 客户端发现设备网关的公网地址，留空时由各客户端通过
lh connect --gateway <url> 自行配置 |
8.5 模型提供者配置
| 变量 | 说明 |
|---|---|
OPENAI_API_KEY |
OpenAI 接口密钥（README 部署示例中为必填项） |
OPENAI_PROXY_URL |
覆盖 OpenAI 请求基础地址；默认
https://api.openai.com/v1，可填第三方兼容代理或自建端点 |
OPENAI_MODEL_LIST |
模型列表控制：+ 增加模型、-
隐藏模型、模型名=展示名 自定义显示名，逗号分隔；示例
qwen-7b-chat,+glm-6b,-gpt-3.5-turbo |
Azure OpenAI、Ollama、Google、Anthropic 等其他端点的接入方式与环境变量，以官方 环境变量文档 与 自定义端点指南 为准。
8.6 可选检索与搜索组件
| 项 | 说明 |
|---|---|
| SearXNG | Compose 内置 searxng/searxng，配置文件
searxng-settings.yml，内部端口 8080 |
| Redis 缓存 | redis:7-alpine，REDIS_URL=redis://redis:6379，REDIS_PREFIX=lobechat，REDIS_TLS=0 |
| Elasticsearch | 默认禁用；通过 COMPOSE_PROFILES=elasticsearch 等
profile 启用，需先阅读官方全文搜索文档；JVM
堆内存不超过容器可用内存一半，Linux 主机需设置
vm.max_map_count=262144，不要对外发布 9200
端口 |
9 常用运维命令
9.1 Compose 日常操作
# 查看服务状态
docker compose ps
# 后台启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart lobe
# 跟踪应用与网关日志
docker compose logs -f lobe
docker compose logs -f gateway
docker compose logs -f searxng
# 进入应用容器排查
docker compose exec lobe sh9.2 镜像更新
# 拉取最新镜像后滚动重建
docker compose pull
docker compose up -d通过 Vercel / Fork 方式部署时，按官方 上游自动同步文档 保留并启用同步 Action；自建 Compose 部署升级前先阅读 Changelog 的破坏性更改说明，并备份
./data、redis_data、rustfs-data与.env。
9.3 备份与恢复
- 数据库：备份 PostgreSQL
./data目录，或进入postgresql容器执行pg_dump导出。 - 对象存储：备份
rustfs-data命名卷；对话图片与头像按桶lobe归集。 - 配置与状态：备份
.env、searxng-settings.yml、bucket.config.json；Redis 缓存丢失不影响业务主数据，重启后自动重建。
9.4 密钥与状态维护
# 重新生成本地部署密钥（参照 setup.sh 逻辑，更换后重启全栈并重新登录）
# KEY_VAULTS_SECRET / AUTH_SECRET：openssl rand -base64 32
# GATEWAY_SERVICE_TOKEN：openssl rand -hex 32- 网关会话状态保留在内存中，容器重启后进行中的运行会丢失；定时任务与已完成记录以数据库为准。
9.5 本地开发命令
pnpm install # 安装依赖
pnpm dev # 全栈开发
bun run dev:spa # 仅 SPA 前端（9876）10 常见故障排查
10.1 端口被占用
- 应用
3210、RustFS9000/9001、网关8787/8788任一被占用都会导致容器启动失败；用docker compose ps与lsof -i:端口核对，修改.env中对应端口变量后重启。 - 内部
5432、6379、8080默认不对外发布；无需外部访问时不要暴露这些端口。
10.2 启动后页面无法访问
- 先
docker compose logs -f lobe查看启动报错；数据库未就绪时应用会反复重连，确认postgresql健康检查通过后再查看应用日志。 - 核对
APP_URL与INTERNAL_APP_URL：浏览器访问地址与服务端内部地址区分正确；反向代理域名模式下不要把内部地址暴露给浏览器。
10.3 对话内图片上传失败
- 浏览器必须能访问
S3_ENDPOINT（预签名 URL 上传）；域名模式下为 RustFS 单独配置域名与反代，CORS 规则由rustfs-init初始化桶时写入。 - 确认
RUSTFS_ACCESS_KEY、RUSTFS_SECRET_KEY与 Compose 环境一致；S3_INTERNAL_ENDPOINT=http://rustfs:9000仅用于内网服务端请求，不要改成宿主机地址。 - 头像上传不依赖对话图片存储；两类上传报错时分别核对 RustFS 桶配置与应用日志。
10.4 网关模式 / 定时任务无响应
- 确认
ENABLE_AGENT_GATEWAY=1已生效，AGENT_GATEWAY_URL是浏览器可达的网关地址，反向代理已放行 WebSocket 升级。 GATEWAY_SERVICE_TOKEN在应用与网关两侧一致；JWKS_PUBLIC_KEY与应用JWKS_KEY配对；网关容器日志可通过docker compose logs gateway查看握手与校验错误。- 网关内存态不保留进行中运行，重启容器后未完成任务需重新触发。
10.5 模型请求失败或模型列表为空
- 核对
OPENAI_API_KEY、OPENAI_PROXY_URL是否正确；公司网络代理下配置HTTP_PROXY/HTTPS_PROXY，并把内网地址加入NO_PROXY。 - 模型列表被
OPENAI_MODEL_LIST的-规则隐藏时，在变量中移除对应隐藏规则；其他端点接入方式以官方环境变量文档为准。 - 第三方代理 Key 的有效性与安全由对应服务商负责，出现证书校验错误时先核对系统时间与代理 TLS 配置。
10.6 注册与登录受限
- 公网部署建议设置
AUTH_ALLOWED_EMAILS白名单，或AUTH_DISABLE_EMAIL_PASSWORD=1仅开放 SSO；默认配置允许注册，关闭前确认已创建管理员账号。 - 更换
AUTH_SECRET或JWKS_KEY后旧会话失效，需要重新登录；忘记访问入口时先检查反向代理与APP_URL配置。
10.7 可选 Elasticsearch 启动失败
- 启用 ES profile 前确认主机
vm.max_map_count=262144；JVM 堆内存（ES_JAVA_OPTS）不超过容器可用内存的一半，ES 节点至少预留 2GB 内存。 - 不要对外发布
9200端口；启用后按文档先执行一次性回填docker compose run --rm fts-search-reindex --apply --fresh-run --yes，状态就绪后再启动增量同步 worker。
10.8 本地开发启动异常
- 确认 Node.js 与 pnpm
版本符合仓库要求；依赖安装失败时切换镜像源后重新
pnpm install。 dev:spa仅启动前端，后端能力需按开发文档连接对应服务；调试代理 URL 仅用于本地联调，不作为功能验收环境。
11 风险与合规说明
以下条款整理自官方 README、
LICENSE（LobeHub Community License）、.env.example与官方文档口径；如与官方原文不一致，以仓库LICENSE、README 与 lobehub.com/docs 最新说明为准。
11.1 开源协议与商用边界
- 项目自 1.0 起采用 LobeHub Community License，基于
Apache License 2.0 并附加以下条件：
- 允许商用：未修改源码的前提下，可作为前端与后端服务直接商用；
- 派生作品需授权：如果基于 LobeChat
开发并分发派生作品，须向出品方申请商业许可，联系邮箱
hello@lobehub.com。
- 贡献代码视为同意出品方可调整开源协议松紧、贡献代码可用于包括云版本在内的商业用途；除上述附加条件外，其余权利与限制遵循 Apache License 2.0。PostgreSQL、Redis、RustFS、SearXNG、Elasticsearch 等第三方组件各自遵循其对应许可证。
11.2 模型与 API 条款
- 平台不提供模型与 API Key；OpenAI、Azure、Google、Anthropic、Bedrock、Ollama 及其他兼容端点归对应厂商或后端项目所有，受其服务条款、隐私政策与计费规则约束。
- 第三方代理 Key 的有效性、稳定性与数据安全由代理服务商负责；选择第三方代理前评估隐私与合规风险。
11.3 数据隐私与访问控制
- 对话、记忆、文件与对象存储保存在自托管数据库与 RustFS 中；公网部署应关闭开放注册、配置邮箱白名单或 SSO、启用 HTTPS，并定期备份。
- 个人记忆内容对用户可见、可编辑、可删除；管理员与运维方应遵守对应地区的数据保护要求，不要把敏感文档与商业机密发送到不受信任的云端模型。
11.4 Agent、工具与网关风险
- Agent Builder、MCP 服务器、Skills、定时任务与 IM 网关具备调用工具、读取文件、发起网络请求与执行命令的能力；第三方 Agent、插件与 MCP 服务器应审核来源、权限与凭据范围后再启用。
- 网关模式把 Agent 运行暴露到 WebSocket 通道，设备网关可把工具调用路由到已加入设备；上线前完成令牌、会话校验与网络隔离配置。
- 项目处于活跃开发阶段，部分编排与网关能力为迭代中的功能；项目按现状（AS-IS）提供，不保证模型输出正确、不保证所有渠道与端点持续兼容。使用者自行承担模型选择、数据泄露、服务中断与业务损失风险。如认为仓库内特定文件侵犯合法权益，请通过 GitHub Issues 提交说明，不要在公开 Issue 中贴出 API Key、密码、会话 Cookie 或内部地址。