LobeHub 并非只在大模型接口外增加一层聊天界面。它以 Agent 为工作单元将 Agent 创建、模型调用、技能扩展、任务组织、定时执行和记忆管理集中到同一个工作区。对于需要持续在线、多设备访问或希望自行管理模型密钥与工作数据的场景自托管版本更便于控制网络入口、数据存储和更新节奏。仓库提供的桌面端截图展示了工作区导航、对话区域和功能入口的整体布局。从聊天界面到 Agent 工作区普通聊天工具主要围绕单次会话组织内容。任务增多后提示词、上下文和模型配置容易分散在不同会话中。LobeHub 的组织方式更接近可扩展的 Agent 工作台Operator 用于集中管理、调度和查看 Agent 的执行情况。Agent Builder 用于创建 Agent 并维护相关配置。模型入口集中管理可按部署环境接入不同模型服务。技能与插件扩展 Function Calling并支持接入 MCP 兼容工具。Agent Groups 允许多个 Agent 围绕同一任务协作。Pages、Project 和 Workspace 分别承载内容、项目与工作区。Schedule 用于按计划执行任务不依赖浏览器持续打开。Personal Memory 以可查看、可编辑的方式管理 Agent 记忆。功能页面延续统一的导航结构Agent、会话和内容区域集中在同一界面内。Agent 操作界面展示了主要内容区域及其相关控制入口。这套结构适合持续性任务例如由不同 Agent 分别处理资料检索、内容整理和结果复核再将产出归入同一项目。若需求只是偶尔调用一次模型部署完整服务会额外引入数据库、更新和备份工作需要衡量维护成本。工作区截图表明项目并非只有单一聊天窗口而是包含多种任务视图。不同功能页面沿用相近的布局便于在会话、Agent 和项目内容之间切换。除常规聊天外项目还提供面向文档内容的工作模式。这种模式更适合长内容整理和多轮修改避免将全部材料堆叠在持续增长的聊天记录中。深色主题下的文档模式具有独立编辑区域交互重点不同于普通对话气泡。部署路线与组件关系LobeHub 官方提供多种部署方式。在通用 Linux 服务器上Docker Compose 路线更容易复现应用及其依赖由容器编排管理部署文件、环境变量和持久化数据也能按目录统一维护。从运维角度看自托管环境主要包含以下部分LobeHub 应用容器提供 Web 界面和服务端功能。安装脚本生成的 Compose 配置及相关依赖服务。持久化目录用于保存配置和需要保留的数据。外部模型 APILobeHub 通过密钥和接口地址调用模型。宿主机端口、防火墙或反向代理负责提供网络入口。服务器应满足这些基础条件运行支持 Docker 的 64 位 Linux 系统。可以访问安装脚本地址、容器镜像仓库和计划使用的模型 API。磁盘能够容纳镜像、数据库及后续用户数据。已准备可用的模型服务 API Key。可以通过 SSH 登录并且 SSH 端口未被网络防火墙阻断。Debian、Ubuntu 等常见 Linux 发行版都可以作为容器宿主环境。若需要重装系统操作前必须备份已有数据因为重装通常会覆盖系统盘。系统重装页面提供多种发行版镜像部署容器版 LobeHub 时应选择支持 Docker 的 Linux 系统。用 Docker Compose 部署 LobeHub下面使用正式版资料中记录的官方初始化脚本与 Docker Compose 流程。安装脚本可能随项目版本变化在服务器上执行远程脚本前应先下载并检查内容。步骤一连接服务器并确认环境将尖括号中的内容替换为实际 SSH 用户名和服务器地址ssh远程用户名服务器公网IP登录后检查 CPU 架构、系统版本和磁盘空间uname-mcat/etc/os-releasedf-h部署目标应是支持 Docker 的 64 位 Linux 环境。磁盘剩余空间过少时不宜直接开始拉取镜像否则可能在解压镜像或初始化数据库时失败。服务器密码、SSH 私钥、完整公网地址和模型 API Key 不应出现在公开截图、工单或命令历史分享中。步骤二安装 Docker Engine 和 Compose 插件Docker 安装方式取决于具体 Linux 发行版应优先参考 Docker Engine 官方安装文档。对于没有旧版 Docker 环境的新系统可以使用官方安装脚本curl-fsSLhttps://get.docker.com-oget-docker.shsudoshget-docker.shsudosystemctlenable--nowdockersudodockerversionsudodockercompose version这里同时检查docker version和docker compose version因为只安装 Docker 客户端并不代表 Compose 插件已经可用。后续命令默认当前用户拥有 Docker 操作权限。若执行时出现权限错误可以保留sudo或者按照 Docker 官方文档配置非 root 用户权限。将用户加入docker组会赋予接近 root 的容器管理能力不应把不可信账户加入该组。步骤三建立部署目录正式版资料中的 LobeHub README 流程使用lobehub-db作为部署目录mkdirlobehub-dbcdlobehub-dbpwd安装脚本生成的配置和持久化内容应集中保留在该目录中。服务投入使用后不要把这个目录当作普通临时文件夹清理。若目录需要放在单独的数据盘应先挂载数据盘再在相应路径创建目录。例如/srv/lobehub-db可以作为自定义位置但该路径属于部署者自行选择的变量不是项目固定要求。步骤四下载并检查初始化脚本资料中记录的快捷执行方式是bash(curl-fsSLhttps://lobe.li/setup.sh)直接通过管道执行不便于确认脚本内容。服务器部署更适合先下载再检查并执行curl-fsSLhttps://lobe.li/setup.sh-osetup.shlesssetup.shbashsetup.sh脚本运行期间应根据终端实际提示填写域名、密钥或其他参数不要套用旧教程中的 Compose 文件。脚本执行后检查生成的文件和 Compose 服务find.-maxdepth2-typef-printdockercompose config--servicesdocker compose config --services用于确认 Compose 文件能够解析并列出定义的服务。完整执行docker compose config可能展开环境变量其中可能包含敏感值因此输出不应直接发布。步骤五核对模型接口变量正式版资料记录了三个与 OpenAI 兼容接口相关的环境变量OPENAI_API_KEY替换为实际API密钥 OPENAI_PROXY_URL可选的OpenAI兼容接口地址 OPENAI_MODEL_LIST可选的模型列表规则OPENAI_API_KEY是该部署资料中的必填示例。OPENAI_PROXY_URL默认对应https://api.openai.com/v1只有接入其他兼容接口时才需要覆盖。OPENAI_MODEL_LIST可使用增加模型、使用-隐藏模型并通过模型名显示名调整界面名称。不同版本的初始化脚本可能把变量写入不同文件。可以只检索包含变量名的文件避免主动输出密钥值grep-R-l-EOPENAI_API_KEY|OPENAI_PROXY_URL|OPENAI_MODEL_LIST.使用实际检索到的文件路径进行编辑vi包含模型变量的实际配置文件chmod600包含模型变量的实际配置文件权限600表示仅文件所有者可读写。它能减少同一宿主机上其他普通用户读取密钥的风险但不能替代主机权限管理和密钥轮换。使用兼容接口时需要同时确认接口路径、模型名称、认证方式和服务端证书。接口声称兼容并不代表所有模型列表、流式响应和工具调用行为都完全一致。步骤六启动 Compose 服务在包含 Compose 文件的lobehub-db目录执行dockercompose up-ddockercomposepsup -d在后台创建并启动服务ps用于查看容器状态与端口映射。不要预设应用固定使用某个宿主机端口应以docker compose ps的PORTS列为准。修改环境变量后可以重建容器使新配置生效dockercompose up-d--force-recreatedockercomposeps--force-recreate会重新创建容器但不应在尚未确认数据挂载和备份状态时随意删除卷。步骤七按实际映射放行端口在服务器网络防火墙中新增 TCP 规则端口填写docker compose ps显示的实际宿主机端口。来源地址能够限定为自己的固定公网出口时应避免直接允许任意来源访问。防火墙表单包含协议、端口、来源地址和动作截图中的1145仅为演示值不能作为 LobeHub 的固定端口使用。如果后续通过 Nginx、Caddy 或其他反向代理绑定域名并配置 HTTPS通常只向公网开放 Web 入口应用端口可限制为本机监听或可信网络访问。反向代理的具体配置取决于所选软件不应与 LobeHub 的 Compose 配置混为一谈。验收不应停在容器状态容器显示Up只能说明进程没有立即退出不能证明页面、数据库、模型接口和持久化均可用。先查看容器状态及最近日志dockercomposepsdockercompose logs--tail200根据docker compose ps查到的宿主机端口在服务器本机发起 HTTP 请求curl-Ihttp://127.0.0.1:实际宿主机端口再通过浏览器访问http://服务器公网IP:实际宿主机端口完整验收至少覆盖以下环节页面能够加载静态资源没有持续请求失败。配置的模型出现在模型列表中。发送测试消息后可以获得模型响应。刷新页面或重新登录后需要保留的数据仍然存在。docker compose logs --tail200中没有持续重启、数据库连接失败或鉴权错误。宿主机 CPU、内存、网络和磁盘 I/O 没有持续出现异常占用。重启 Compose 服务后再次确认页面、模型调用和数据状态。重启验证可执行dockercompose restartdockercomposepsdockercompose logs--tail100监控页面可观察 CPU、内存、网络和磁盘 I/O截图数值只代表采集时刻容量判断应结合实际负载和服务器规格。源码构建为何不是默认部署路线仓库源码可以通过 Dockerfile 构建但现有终端证据并未完成整个构建。记录中的命令为dockerbuild-trainpen-target.构建过程执行到第25/60步在pnpm i下载依赖期间因外部执行超时以退出码124中止。因此这份记录只能证明构建进入依赖安装阶段不能证明镜像已经生成。终端记录显示基础镜像和部分依赖已下载但构建任务最终以退出码124结束。该次 Dockerfile 记录使用NODEJS_VERSION24构建阶段设置了NODE_OPTIONS--max-old-space-size8192这个参数表示 Node.js 构建进程允许使用的堆内存上限不等同于运行容器必然占用 8 GB 内存。不过60 步构建流程、工作区依赖安装和较高的构建内存上限表明源码构建比拉取已发布镜像需要更多时间、磁盘和内存余量。仅以运行服务为目标时使用官方初始化脚本和发布镜像更合适。只有需要修改源码、验证补丁或制作自定义镜像时才有必要准备独立构建环境并为依赖下载设置足够的任务超时时间。终端取证对应canary分支提交197ba354。项目持续开发文章中的变量和脚本行为应在实际部署时与当前官方文档再次核对。常见故障与排查边界docker compose命令不存在检查 Docker Engine 和 Compose 插件是否都已安装dockerversiondockercompose version如果只有docker命令而没有docker compose子命令应按照 Docker Compose 安装文档为当前发行版安装插件。容器启动后反复重启保留第一次有效报错避免连续执行up -d覆盖排查线索dockercomposeps-adockercompose logs--tail300日志中应重点检查数据库连接、必填环境变量、配置文件权限和端口占用。某个依赖服务尚未就绪也可能导致应用容器启动失败需要结合各服务日志判断而不是只查看应用容器。本机可访问公网无法打开按网络路径逐层检查dockercomposepsss-lntpcurl-Ihttp://127.0.0.1:实际宿主机端口curl成功但公网失败通常应继续检查端口监听地址、服务器系统防火墙和外层网络防火墙。若 Compose 只绑定到127.0.0.1该端口本来就不应被公网直接访问应通过同机反向代理提供入口。页面可打开但模型调用失败检查OPENAI_API_KEY是否有效兼容接口是否需要设置OPENAI_PROXY_URL以及服务器能否连接目标 API。日志中的状态码代表不同问题401通常指向认证信息无效或缺失。403通常表示接口拒绝当前请求或权限不足。429可能与速率限制或账户配额有关。连接超时通常需要检查 DNS、路由、代理和目标服务可达性。应以docker compose logs中的原始错误为依据避免在没有状态码时盲目更换密钥或重建容器。初始化脚本或镜像下载缓慢检查服务器 DNS、脚本地址和镜像仓库的网络连通性。源码构建出现退出码124更可能表示任务达到外部超时限制不能直接推断为项目代码错误。如果目标只是部署服务应回到官方发布镜像路线。确实需要源码构建时再单独处理网络、代理、磁盘空间和构建超时。修改变量后配置没有生效先确认修改的是 Compose 实际读取的文件dockercompose config--servicesdockercompose config检查时不要公开包含密钥的完整输出。确认配置来源后重建容器dockercompose up-d--force-recreatedockercompose logs--tail200若变量属于构建期配置仅重启现有容器可能不会生效需要以当前版本文档说明为准。更新、备份与回滚准备更新前应确认 Compose 挂载关系和持久化目录cdlobehub-dbdockercompose configdockercomposepsdocker compose config的输出可能包含敏感信息只用于本机核对。备份应覆盖安装脚本生成的配置、数据库数据和其他持久化目录而不仅是 Compose 文件。完成备份后再更新镜像dockercompose pulldockercompose up-ddockercomposepsdockercompose logs--tail200更新后重新执行页面加载、模型调用和数据持久化测试。若新版本涉及数据库迁移直接换回旧镜像未必能恢复旧数据结构因此备份应在拉取和启动新版本之前完成。备份页面可用于在更新镜像、调整存储配置或重装系统前创建恢复点。仅创建备份还不够。可恢复性取决于备份是否覆盖正确目录、数据库是否处于一致状态以及恢复流程是否经过验证。关键工作区投入使用后应安排定期备份并在隔离环境中验证恢复步骤。面向持续运行的安全配置直接通过公网 IP 和应用端口访问适合部署验收不适合作为长期入口。正式使用前还应完成这些配置绑定域名并启用 HTTPS。按当前版本文档配置登录与鉴权避免工作区匿名公开。限制 SSH 和管理端口的来源地址。应用端口位于反向代理之后时只绑定本机或可信网络。不将模型密钥提交到 Git 仓库也不在截图和公开日志中展示。为密钥设置轮换机制发现泄露后立即撤销旧密钥。定期备份持久化数据并实际验证恢复流程。更新前查阅 LobeHub Changelog核对数据库迁移和环境变量变化。插件与 MCP 服务按最小权限接入不向不可信工具提供敏感上下文。参考资料LobeHub GitHub 仓库LobeHub 中文 READMELobeHub Docker 部署说明LobeHub Docker Hub 镜像LobeHub 官方文档LobeHub 环境变量说明入口LobeHub ChangelogLobeHub IssuesLobeHub Apache-2.0 许可证Docker Engine 安装文档Docker Compose 文档OpenAI API Keys部署要点回顾LobeHub 自托管的关键工作不只是一条docker compose up -d。模型密钥是否正确、持久化目录是否明确、网络端口是否按实际映射开放以及更新前是否具备可恢复备份都会直接影响服务能否持续使用。官方初始化脚本减少了手工组织依赖服务的工作量但远程脚本内容、生成的 Compose 配置和环境变量仍需在执行时核对。容器启动后还应通过本机 HTTP 请求、浏览器访问、真实模型调用、数据持久化测试和容器日志完成闭环验收从而区分“容器进程存在”和“LobeHub 功能可用”这两种状态。