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 配置视图用于调整模型、提示词和相关能力。
从部署角度看，可以把自托管环境划分为四层：
- 浏览器负责访问 Web 界面。
- LobeHub 应用处理会话、Agent、工具调用和服务端接口。
- Docker Compose 管理应用及脚本生成的依赖服务。
- 外部模型接口提供实际推理能力，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.shcurl中的-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 相关变量：
| 变量 | 是否必需 | 用途 |
|---|---|---|
OPENAI_API_KEY | 是 | 模型接口认证密钥 |
OPENAI_PROXY_URL | 否 | 覆盖默认的 OpenAI API 基础地址 |
OPENAI_MODEL_LIST | 否 | 增加、隐藏模型或修改显示名称 |
默认接口地址为：
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-turboOPENAI_MODEL_LIST的规则来自仓库资料：
+模型名：显式增加模型。-模型名：隐藏模型。模型名=显示名称：修改界面中的显示名称。- 多个项目使用英文逗号分隔。
上面的模型列表只是语法示例，不代表对应模型一定能通过当前接口访问。最终可用模型取决于模型服务端实际开放的模型 ID。
API Key 不宜直接写在docker compose up命令行中，否则可能进入 Shell 历史。环境文件应限制权限：
chmod600<部署脚本生成的环境变量文件>还应确认该文件没有被 Git 跟踪：
gitstatus--short2>/dev/null||true会话界面提供模型选择和消息交互区域，实际模型列表由服务端能力与配置共同决定。
步骤五：启动 Compose 服务
配置核对完成后，在lobehub-db目录运行：
dockercompose pulldockercompose up-ddocker 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 或流式响应是否被中途缓存。
步骤七：完成应用级验收
网页能打开只证明静态资源和部分接口可访问。完整验收至少覆盖以下路径：
- 打开首页并确认主要资源没有持续返回 4xx 或 5xx。
- 创建一个测试 Agent，填写非敏感的测试提示词。
- 选择已配置且服务端确实开放的模型。
- 发送简短消息，确认能够收到完整响应。
- 刷新页面，检查会话与 Agent 配置是否仍然存在。
- 重启 Compose 服务，再次确认数据未丢失。
- 查看容器日志，排除持续出现的数据库、认证和模型接口错误。
重启测试命令：
dockercompose restartdockercomposepsdockercompose logs--since=5m多个 Agent 可在共享任务上下文中参与协作。
项目视图用于集中管理会话、页面和相关工作内容。
模型调用失败时，应把“LobeHub 页面可访问”和“模型接口可调用”作为两个独立检查项。前者正常并不能证明 API Key、接口地址和模型名称正确。
为什么不优先从源码构建
仓库支持本地开发，README 给出的命令是：
gitclone https://github.com/lobehub/lobehub.gitcdlobehubpnpminstallpnpmdevSPA 前端开发命令为：
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 或镜像页面。
)
