LobeHub 是一个以 Agent 为工作单元的开源应用。它不只提供单轮对话界面，还把 Agent 创建、模型接入、工具调用、项目组织、定时任务、多人协作和个人记忆放在同一套工作空间中。对于需要集中管理多个模型与 Agent、避免数据散落在多个浏览器会话中的场景，自托管版本提供了更明确的数据与配置控制边界。

界面将对话内容与文档工作区放在同一视图中，便于围绕长文本持续处理。

仓库当前推荐的 Docker 路径不是手工编写单容器启动命令，而是通过官方初始化脚本生成 Docker Compose 基础设施，再由 Compose 统一启动相关服务。这种方式降低了组件漏配的概率，但也意味着部署前应审阅脚本，升级时必须同时关注镜像、数据库和生成的配置文件。

项目仓库：https://github.com/lobehub/lobehub

功能与组件关系

LobeHub 的核心对象是 Agent。一个 Agent 可以绑定模型、提示词、记忆和工具，并在项目、页面或 Agent Group 中参与任务。仓库资料列出的主要能力包括：

• Agent Builder：通过描述需求创建并配置 Agent。
• 统一模型入口：在同一界面管理不同模型和模态能力。
• 工具与插件：支持 Function Calling、插件及 MCP 兼容工具。
• Agent Groups：让多个 Agent 在共享上下文中并行处理任务。
• Pages 与 Projects：组织长文本、上下文和工作成果。
• Schedule：按计划触发 Agent 任务。
• Personal Memory：以结构化、可编辑的方式管理个人记忆。
• Workspace：提供团队协作、归属和可见性控制。

工作区集中展示 Agent、会话和任务入口。

Agent 配置视图用于调整模型、提示词和相关能力。

从部署角度看，可以把自托管环境划分为四层：

1. 浏览器负责访问 Web 界面。
2. LobeHub 应用处理会话、Agent、工具调用和服务端接口。
3. Docker Compose 管理应用及脚本生成的依赖服务。
4. 外部模型接口提供实际推理能力，API Key 不应提交到仓库或写进公开镜像。

具体服务名、镜像和依赖数量可能随版本调整，不能套用旧版 Compose 文件。部署完成后应以本机生成的 Compose 配置为准。

部署前准备

准备一台可以运行 Docker 的 Linux 主机。仓库资料没有限定发行版和最低资源规格，因此不能据此给出固定的 CPU、内存结论。磁盘空间除了容纳镜像，还要覆盖数据库、附件、日志和后续升级产生的临时数据。

开始部署前检查以下条件：

• Docker Engine 可以正常运行。
• Docker Compose 插件可用，即支持docker compose命令。
• 主机可以访问容器镜像仓库和模型接口。
• 已准备 OpenAI API Key，或已确认所接入模型服务的兼容地址。
• 域名、反向代理和 HTTPS 如有需要，应在应用启动后再接入。
• 防火墙只开放实际使用的 Web 入口以及受限来源的 SSH 端口。
• 生产环境已经规划备份目录和恢复方法。

检查 Docker 与 Compose：

dockerversiondockercompose version

如果第一条命令提示无法连接 Docker daemon，应先启动 Docker 服务，并确认当前用户有权访问 Docker socket。不要通过开放未认证的远程 Docker API 来绕过权限问题。

步骤一：创建独立部署目录

仓库 README 使用lobehub-db作为初始化目录。保留独立目录的意义在于把 Compose 文件、环境配置和持久化数据集中管理，后续备份时不必在系统中到处查找。

mkdirlobehub-dbcdlobehub-dbpwd

不要在已经存放其他应用配置的目录中直接运行初始化脚本。脚本可能创建多个文件或子目录，独立目录可以降低覆盖现有文件的风险。

步骤二：下载并审阅初始化脚本

README 给出的快捷命令是：

bash<(curl-fsSLhttps://lobe.li/setup.sh)

该写法会把网络响应直接交给 Bash 执行，适合快速初始化，但不利于检查脚本内容和保留部署证据。更稳妥的做法是先下载，再人工查看：

curl-fsSLhttps://lobe.li/setup.sh-osetup.shlesssetup.shbashsetup.sh

curl中的-f会在 HTTP 请求失败时返回错误，-sS减少普通输出但保留错误信息，-L允许跟随重定向。执行前可以额外记录脚本摘要：

sha256sum setup.sh

摘要只能证明之后使用的是同一份文件，不能证明脚本本身安全。真正需要检查的是脚本下载了哪些文件、使用了哪些镜像、创建了哪些目录，以及是否修改系统级配置。

初始化过程中的交互项应根据本机域名、认证和模型接入方案填写，不要照抄其他部署实例的密钥、URL 或数据库密码。

步骤三：核对脚本生成的配置

脚本运行结束后，先查看当前目录，不要立即启动服务：

find.-maxdepth2-typef-printdockercompose config--servicesdockercompose config--images

前一条命令用于确认脚本生成了哪些配置文件；后两条分别列出 Compose 服务和镜像。这里不硬编码服务名，是因为仓库处于活跃开发状态，基础设施组成可能改变。

还可以渲染 Compose 配置进行审查：

dockercompose config>compose.rendered.yamllesscompose.rendered.yaml

渲染结果可能包含环境变量展开后的敏感信息，compose.rendered.yaml不能上传到公开仓库。检查完成后可将其删除，或放入权限受控的运维归档中。

重点核对以下内容：

• 镜像来源和标签是否符合预期。
• 数据卷是否绑定到持久化目录。
• 数据库是否只在 Compose 内部网络提供服务。
• Web 端口是否与现有服务冲突。
• 应用 URL 是否与计划使用的域名和协议一致。
• API Key、认证密钥和数据库密码是否为真实生成值，而不是示例值。
• 是否存在不必要的宿主机目录挂载或特权模式。

步骤四：配置模型环境变量

仓库 README 明确列出以下三个 OpenAI 相关变量：

默认接口地址为：

https://api.openai.com/v1

在初始化脚本生成的环境变量文件中配置时，可参考下面的结构。尖括号内容必须替换，文件名以脚本实际生成结果为准：

OPENAI_API_KEY=<替换为真实 API Key> OPENAI_PROXY_URL=https://api.openai.com/v1 OPENAI_MODEL_LIST=qwen-7b-chat,+glm-6b,-gpt-3.5-turbo

OPENAI_MODEL_LIST的规则来自仓库资料：

• +模型名：显式增加模型。
• -模型名：隐藏模型。
• 模型名=显示名称：修改界面中的显示名称。
• 多个项目使用英文逗号分隔。

上面的模型列表只是语法示例，不代表对应模型一定能通过当前接口访问。最终可用模型取决于模型服务端实际开放的模型 ID。

API Key 不宜直接写在docker compose up命令行中，否则可能进入 Shell 历史。环境文件应限制权限：

chmod600<部署脚本生成的环境变量文件>

还应确认该文件没有被 Git 跟踪：

gitstatus--short2>/dev/null||true

会话界面提供模型选择和消息交互区域，实际模型列表由服务端能力与配置共同决定。

步骤五：启动 Compose 服务

配置核对完成后，在lobehub-db目录运行：

dockercompose pulldockercompose up-d

docker compose pull先拉取配置中引用的镜像，可以把网络或镜像标签问题与容器启动问题分开。up -d以后台方式创建并启动服务。

随后查看容器状态：

dockercomposepsdockercompose logs--tail=200

不能只依据docker compose up -d返回成功判断部署完成。容器可能在几秒后因数据库连接、密钥格式或端口冲突退出。docker compose ps中若出现反复重启或退出状态，应先检查日志，不要连续重建容器掩盖原始错误。

步骤六：确认监听端口和访问入口

仓库给出的初始化流程没有在资料中声明固定宿主机端口，因此应从生成的 Compose 配置读取，不应猜测为某个常见端口：

dockercomposepsdockercompose port<应用服务名><容器端口>

<应用服务名>和<容器端口>可从以下命令输出中确认：

dockercompose config--servicesdockercompose config

如果应用只供本机反向代理访问，端口应尽量绑定到回环地址。若确实需要直接从外部访问，则只放行 Compose 映射出的 TCP 端口，并限制来源地址。数据库、缓存等内部组件不应直接暴露到公网。

使用浏览器打开初始化配置对应的地址。若配置了域名和 HTTPS，还应检查证书、反向代理的请求头以及 WebSocket 或流式响应是否被中途缓存。

步骤七：完成应用级验收

网页能打开只证明静态资源和部分接口可访问。完整验收至少覆盖以下路径：

1. 打开首页并确认主要资源没有持续返回 4xx 或 5xx。
2. 创建一个测试 Agent，填写非敏感的测试提示词。
3. 选择已配置且服务端确实开放的模型。
4. 发送简短消息，确认能够收到完整响应。
5. 刷新页面，检查会话与 Agent 配置是否仍然存在。
6. 重启 Compose 服务，再次确认数据未丢失。
7. 查看容器日志，排除持续出现的数据库、认证和模型接口错误。

重启测试命令：

dockercompose restartdockercomposepsdockercompose logs--since=5m

多个 Agent 可在共享任务上下文中参与协作。

项目视图用于集中管理会话、页面和相关工作内容。

模型调用失败时，应把“LobeHub 页面可访问”和“模型接口可调用”作为两个独立检查项。前者正常并不能证明 API Key、接口地址和模型名称正确。

为什么不优先从源码构建

仓库支持本地开发，README 给出的命令是：

gitclone https://github.com/lobehub/lobehub.gitcdlobehubpnpminstallpnpmdev

SPA 前端开发命令为：

bun run dev:spa

该模式用于开发和调试，不等同于生产部署。仓库还说明dev:spa使用9876端口，但这不能据此推断 Docker 自托管服务也使用相同端口。

源码镜像构建涉及 Node.js、Corepack、pnpm workspace 和大量依赖。给定终端记录中的docker build -t rainpen-target .在第 25 个构建步骤下载依赖时因外部执行超时，以退出码124结束；这不是构建成功证据，也不能据此判断代码错误。

构建已进入工作区依赖安装阶段，但在完成镜像前因超时终止。

对于目标只是运行服务的环境，官方初始化脚本和预构建镜像更容易复现。只有需要修改源码、验证补丁或定制构建参数时，才有必要转向源码构建。构建环境还应预留足够内存、磁盘和网络时间；终端记录显示 Dockerfile 构建阶段设置了NODE_OPTIONS="--max-old-space-size=8192"，但这只是构建参数，不能直接当作运行服务的最低内存要求。

备份与恢复

备份不能只保存 Compose 文件。真正需要保护的是配置、密钥和持久化数据。由于初始化脚本生成的卷结构可能随版本改变，应通过 Compose 查询实际挂载关系：

dockercompose configdockervolumels

在lobehub-db的上级目录创建文件级归档时，可以先停止应用，减少数据库写入期间产生不一致快照的风险：

cd..dockercompose-flobehub-db/<实际的Compose文件名>stoptar-czflobehub-backup-$(date+%F).tar.gz lobehub-dbdockercompose-flobehub-db/<实际的Compose文件名>start

<实际的Compose文件名>必须替换为初始化脚本生成的文件名。若数据库使用 Docker 命名卷且数据不在lobehub-db目录中，仅归档该目录并不完整。此时需要按照实际数据库类型执行数据库导出，并单独备份命名卷。

恢复演练应验证：

• Compose 配置能够重新解析。
• 环境变量和认证密钥未丢失。
• 数据库可以启动且结构完整。
• Agent、会话、项目和记忆数据可以读取。
• 模型密钥仍处于有效状态。
• 恢复后的域名、回调地址和代理配置与当前环境一致。

未做恢复演练的归档，只能视为备份候选，不能确认可用于灾难恢复。

升级流程

LobeHub 处于活跃开发状态，升级前应阅读 Changelog，并确认是否包含数据库迁移、环境变量变化或不兼容调整。不要在没有备份的情况下直接拉取新镜像。

通用升级步骤如下：

cdlobehub-dbdockercomposepsdockercompose config--imagesdockercompose pulldockercompose up-ddockercomposepsdockercompose logs--tail=200

执行pull之前先记录当前镜像信息，便于出现问题时定位版本：

dockercompose imagesdockerimage inspect<当前镜像名:标签>--format'{{index .RepoDigests 0}}'

长期使用浮动标签虽然方便更新，但回滚时缺少确定性。若生成的配置允许固定版本，应结合发布记录锁定经过验证的镜像标签或摘要。回滚不仅是换回旧镜像：如果新版本已经执行不可逆数据库迁移，还必须同时恢复升级前数据库。

常见故障定位

docker compose命令不存在

系统可能只安装了 Docker Engine，没有安装 Compose 插件。先确认：

dockercompose version

不要把旧式docker-compose与新版docker compose淀粉式混用到同一套自动化脚本中，避免参数和行为差异。

容器启动后立即退出

查看状态和最近日志：

dockercomposeps-adockercompose logs--tail=300

常见边界包括环境变量缺失、数据库连接失败、密钥仍为示例值、挂载目录权限不正确以及端口已被占用。

端口占用可通过 Linux 的 socket 信息检查：

ss-lntp

页面可以打开，但模型不响应

重点核对：

• OPENAI_API_KEY是否有效，是否包含多余空格或引号。
• OPENAI_PROXY_URL是否包含接口要求的路径。
• 模型 ID 是否为服务端真实支持的名称。
• 主机和容器能否解析并访问模型接口。
• 系统时间是否准确，避免签名或 TLS 校验异常。
• 容器日志中是认证错误、限流、模型不存在，还是连接超时。

不要通过把 API Key 粘贴到公开诊断网站来验证密钥。

修改环境变量后没有生效

单纯restart通常不会根据新配置重新创建容器。修改后执行：

dockercompose up-ddockercompose logs--since=5m

必要时使用docker compose config检查变量是否被 Compose 正确读取，但输出中可能出现敏感值，不能直接贴到公开工单。

刷新或重启后数据丢失

检查数据库和应用数据是否挂载到持久卷：

dockercompose configdockervolumelsdockerinspect<容器名>

如果数据只写在容器可写层，重新创建容器后就可能丢失。修复挂载前先保留现有容器，不要贸然执行删除卷的命令。

初始化脚本下载失败

验证 URL、DNS、TLS 和系统时间：

curl-Ihttps://lobe.li/setup.shdate

若处于受限网络环境，需要同时保证脚本地址、容器镜像仓库、软件源和模型接口均可访问。只解决其中一个地址不能保证完整部署成功。

源码构建长时间停在依赖安装

给定构建记录显示工作区包含大量依赖，超时发生在pnpm i尚未完成时。可以检查磁盘、内存和网络，而不是仅依据退出码判断依赖冲突：

df-hfree-hdockersystemdf

退出码124通常表示外部超时控制终止了命令。应提高构建任务允许的执行时间，并保留完整末尾日志，再判断是否存在真正的编译错误。

安全与运维边界

自托管解决的是部署位置和数据控制问题，并不会自动完成安全加固。对外提供服务时还需要处理：

• 使用 HTTPS，避免认证信息和会话内容明文传输。
• 限制服务器管理端口的来源地址。
• 不公开数据库和缓存端口。
• 为环境文件设置严格权限。
• 定期轮换模型 API Key 和应用认证密钥。
• 升级前备份，升级后检查日志和数据库迁移。
• 对插件和 MCP 工具授予最小权限。
• 监控 CPU、内存、磁盘、网络与容器重启次数。
• 日志中如包含提示词、接口响应或密钥，应控制访问和保留周期。

插件能够扩展 Function Calling，也扩大了外部访问和工具执行范围。启用第三方插件前应检查其仓库、权限需求、网络目标和维护状态，不应把插件能力等同于可信执行环境。

参考资料

• LobeHub 项目仓库：https://github.com/lobehub/lobehub
• Docker 镜像：https://hub.docker.com/r/lobehub/lobehub
• 自托管文档：https://lobehub.com/docs/self-hosting
• 项目更新记录：https://lobehub.com/changelog
• 问题跟踪：https://github.com/lobehub/lobehub/issues
• 插件 SDK：https://github.com/lobehub/chat-plugin-sdk
• 插件模板：https://github.com/lobehub/chat-plugin-template
• Docker Compose 官方文档：https://docs.docker.com/compose/

仓库资料标注项目许可证为 Apache-2.0，但许可证可能随项目版本调整。部署、修改或再分发前，应以当前检出版本中的LICENSE文件为准，而不是只依据历史 README 或镜像页面。