LobeHub
LobeHub

与 LobeHub 桌面端自动同步

LobeHub 桌面端为用户提供了更好的使用体验,同时也扩展了 LobeHub 的能力边界,允许用户在离线环境下使用 LobeHub。本文档将指导您如何配置 LobeHub 桌面端以及如何将其与自托管实例连接。

系统要求

LobeHub 桌面端使用 Electron 构建,支持以下操作系统:

  • Windows
  • macOS
  • Linux(部分发行版)

桌面端版本说明

LobeHub 桌面端的版本发布遵循以下逻辑:

  • Beta 版本:所有合并到 main 分支并自动发布版本,都会自动创建为 LobeHub 桌面端的 Beta 版本
  • Stable 版本:开发团队会通过手动打标来定期发布稳定版本

如果您希望获得最新功能,可以使用 Beta 版本;如果您注重稳定性,请使用 Stable 版本。

与自托管实例连接

LobeHub 桌面端可以与您自托管的 LobeHub 实例连接,以便您可以在桌面端使用您的自托管配置。

准备工作

在将桌面端与自托管实例连接前,您需要确保您的自托管实例已正确配置 OIDC 相关环境变量。

请确保您的自托管实例版本为 1.83.6 或更高,以支持桌面端连接功能。

OIDC 环境变量配置

只要在自托管实例中配置了 JWKS_KEY 环境变量,OIDC 就会自动启用,无需单独设置 ENABLE_OIDC 开关。

点击下方按钮一键生成 JWKS_KEY:

Shell
JWKS_KEY='点击按钮生成'

将生成的环境变量添加到您的部署配置中。

OIDC_JWKS_KEY 已改名为 JWKS_KEY。如果您的部署中仍配置的是 OIDC_JWKS_KEY,需要手动将其重命名为 JWKS_KEY—— 系统不会自动回退。

如果您使用一键部署方式(如 Vercel、Railway 等平台)部署 LobeHub,您需要:

  1. 将上述环境变量添加到部署平台的环境变量配置中
  2. 对于 Vercel 部署,请确保 APP_URL 环境变量设置为你的域名 URL,这对于正确处理认证回调至关重要

连接步骤

  1. 打开 LobeHub 桌面端
  2. 点击右上角 wifi 图标
  3. 输入您的自托管实例地址(例如:https://your-LobeHub-instance.com)
  4. 点击 "连接" 按钮
  5. 您将被重定向到登录页面,完成授权后即可使用您的自托管配置

连接设备网关

设备网关让助理在这台电脑上运行本地工具。

  1. 按 Docker Compose 部署说明 启动网关。通过域名访问时,反向代理到 8788 端口,并开启 HTTPS 和 WebSocket 支持。

  2. 如需让客户端自动获取地址,在 LobeHub 服务端设置以下环境变量,然后重新部署:

    *.txt
    Plaintext
    DEVICE_GATEWAY_PUBLIC_URL=https://device-gateway.example.com
  3. 在桌面端登录该实例,打开标题栏中的 设备网关 开关。CLI 用户运行:

    *.sh
    Shell
    lh login --server https://lobe.example.com
    lh connect

连接后,可在设备列表中查看这台电脑的在线状态。

已有的自定义网关地址仍会优先使用。也可通过桌面端的 DEVICE_GATEWAY_URL 环境变量或 lh connect --gateway <url> 手动指定地址,无需配置服务端环境变量。

常见问题

502 Bad Gateway

问题: 点击授权按钮后,跳转到 /oidc/consent 路径时出现 502 Bad Gateway 错误。

解决方案:

  • 确认您已经正确设置了 JWKS_KEY 环境变量
  • 确保 JWKS_KEY 是有效的 JSON 格式,没有额外的单引号
  • 检查您的服务端日志,查看具体错误信息

如果您使用 Nginx 作为反向代理,可能是请求头太大导致的问题。可以尝试在 Nginx 配置中添加以下设置:

*.txt
Plaintext
proxy_buffer_size   16k;
proxy_buffers       8 16k;
proxy_busy_buffers_size 32k;

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: 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

图片加载问题

问题: 使用 Docker 部署的服务端,桌面端连接后无法加载头像或其他图片资源。

解决方案:

  • 如果您使用 Minio 作为存储,需要在 Minio 配置中允许跨域请求
  • 在您的 Minio 服务中添加适当的 CORS 配置