与 LobeHub 桌面端自动同步
LobeHub 桌面端为用户提供了更好的使用体验,同时也扩展了 LobeHub 的能力边界,允许用户在离线环境下使用 LobeHub。本文档将指导您如何配置 LobeHub 桌面端以及如何将其与自托管实例连接。
系统要求
LobeHub 桌面端使用 Electron 构建,支持以下操作系统:
- Windows
- macOS
- Linux(部分发行版)
桌面端版本说明
LobeHub 桌面端的版本发布遵循以下逻辑:
- Beta 版本:所有合并到 main 分支并自动发布版本,都会自动创建为 LobeHub 桌面端的 Beta 版本
- Stable 版本:开发团队会通过手动打标来定期发布稳定版本
如果您希望获得最新功能,可以使用 Beta 版本;如果您注重稳定性,请使用 Stable 版本。
与自托管实例连接
LobeHub 桌面端可以与您自托管的 LobeHub 实例连接,以便您可以在桌面端使用您的自托管配置。
准备工作
在将桌面端与自托管实例连接前,您需要确保您的自托管实例已正确配置 OIDC 相关环境变量。
OIDC 环境变量配置
只要在自托管实例中配置了 JWKS_KEY 环境变量,OIDC 就会自动启用,无需单独设置 ENABLE_OIDC 开关。
点击下方按钮一键生成 JWKS_KEY:
JWKS_KEY='点击按钮生成'将生成的环境变量添加到您的部署配置中。
OIDC_JWKS_KEY 已改名为 JWKS_KEY。如果您的部署中仍配置的是 OIDC_JWKS_KEY,需要手动将其重命名为 JWKS_KEY—— 系统不会自动回退。如果您使用一键部署方式(如 Vercel、Railway 等平台)部署 LobeHub,您需要:
- 将上述环境变量添加到部署平台的环境变量配置中
- 对于 Vercel 部署,请确保
APP_URL环境变量设置为你的域名 URL,这对于正确处理认证回调至关重要
连接步骤
- 打开 LobeHub 桌面端
- 点击右上角 wifi 图标
- 输入您的自托管实例地址(例如:
https://your-LobeHub-instance.com) - 点击 "连接" 按钮
- 您将被重定向到登录页面,完成授权后即可使用您的自托管配置
连接设备网关
设备网关让助理在这台电脑上运行本地工具。
-
按 Docker Compose 部署说明 启动网关。通过域名访问时,反向代理到
8788端口,并开启 HTTPS 和 WebSocket 支持。 -
如需让客户端自动获取地址,在 LobeHub 服务端设置以下环境变量,然后重新部署:
Plaintext -
在桌面端登录该实例,打开标题栏中的 设备网关 开关。CLI 用户运行:
Shell
连接后,可在设备列表中查看这台电脑的在线状态。
DEVICE_GATEWAY_URL 环境变量或 lh connect --gateway <url> 手动指定地址,无需配置服务端环境变量。常见问题
502 Bad Gateway
问题: 点击授权按钮后,跳转到 /oidc/consent 路径时出现 502 Bad Gateway 错误。
解决方案:
- 确认您已经正确设置了
JWKS_KEY环境变量 - 确保
JWKS_KEY是有效的 JSON 格式,没有额外的单引号 - 检查您的服务端日志,查看具体错误信息
如果您使用 Nginx 作为反向代理,可能是请求头太大导致的问题。可以尝试在 Nginx 配置中添加以下设置:
invalid_redirect_uri 错误
问题: 授权过程中遇到 "redirect_uri did not match any of the client's registered redirect_uris" 错误。
解决方案:
检查 APP_URL 环境变量是否与您访问的 URL 一致
设备网关无法连接
- 打开后立即断开:确认网关地址属于当前登录的实例,并检查客户端已有的自定义地址。
- 连接超时:在客户端电脑运行
curl https://device-gateway.example.com/health,应返回OK;否则检查网关地址、网络和反向代理设置。
macOS 启动卡住或闪退
问题: 在 macOS 上,应用启动后长时间卡住或闪退。
解决方案:
- 检查您是否下载了正确的 macOS 架构版本:
- 对于 Apple Silicon (M3/M4 等) Mac,应使用
arm64版本 - 对于 Intel Mac,应使用
x64版本
- 对于 Apple Silicon (M3/M4 等) Mac,应使用
- 文件名示例:
- Apple Silicon:
LobeHub-Beta-1.83.6-arm64.dmg或LobeHub-Beta-1.83.6-arm64-mac.zip - Intel:
LobeHub-Beta-1.83.6-x64.dmg或LobeHub-Beta-1.83.6-mac.zip
- Apple Silicon:
图片加载问题
问题: 使用 Docker 部署的服务端,桌面端连接后无法加载头像或其他图片资源。
解决方案:
- 如果您使用 Minio 作为存储,需要在 Minio 配置中允许跨域请求
- 在您的 Minio 服务中添加适当的 CORS 配置