LobeHub
LobeHub

使用 Docker Compose 部署 LobeHub

正在升级已有的 Docker Compose 部署? 最新的 docker-compose.yml 新增了 Gateway 模式所需的网关服务。启动前请先按 升级已有部署 更新 .env,否则网关容器会反复重启、智能体退回浏览器中运行,docker logs lobehub 也会打印 ACTION REQUIRED 告警。

快速启动

系统兼容性说明

  • 支持 Unix 环境(Linux/macOS)的一键部署

  • Windows 用户需通过 WSL 2 运行

  • 一键启动脚本为首次部署专用,非首次部署请参考 自定义部署 章节

  • 端口占用检查:确保 3210、9000、9001、8787、8788 端口可用

执行以下命令初始化部署环境,目录 lobehub 将用于存放你的配置文件和后续的数据库文件。

mkdir lobehub && cd lobehub

获取并执行部署脚本:

*.sh
Shell
bash <(curl -fsSL https://lobe.li/setup.sh) -l zh_CN

脚本支持以下部署模式,请根据你的需求选择相应的模式,并继续阅读文档的剩余部分。

  • 本地模式(默认):仅能在本地访问,不支持局域网 / 公网访问,适用于初次体验;
  • 端口模式:支持局域网 / 公网的 http 访问,适用于无域名或内部办公场景使用;
  • 域名模式:支持局域网 / 公网在使用反向代理下的 http/https 访问,适用于个人或团队日常使用;

在脚本的选项提示 (选项1/选项2)[选项1] 中:(选项1 / 选项2) 代表可以选择的选项,[选项1]代表默认选项,直接回车即可选择默认选项。

本地模式

在交互式脚本中完成剩余配置

持续回车采用默认配置。

查看配置生成报告

你需要在脚本运行结束后查看配置生成报告,包括各服务的访问地址和密码。

*.txt
Plaintext
安全密钥生成结果如下:
LobeHub:
  - URL: http://localhost:3210
RustFS:
  - URL: http://localhost:9000
  - Username: admin
  - Password: 8c82ea41
Agent Gateway:
  - URL: http://localhost:8787

启动 Docker

docker compose up -d

检查日志

docker logs -f lobehub

如果你在容器中看到了以下日志,则说明已经启动成功:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://localhost:3210
  - Network:      http://0.0.0.0:3210

 ✓ Starting...
 ✓ Ready in 95ms

访问应用

通过 http://localhost:3210 访问你的 LobeHub 服务。

端口模式

在交互式脚本中完成剩余配置

在端口模式中,你需要根据脚本提示完成:

  • 服务器 IP 地址设置:以便局域网 / 公网访问。
  • 安全密钥重新生成:我们强烈建议你重新生成安全密钥,如果你缺少脚本所需的密钥生成库,我们建议你参考 自定义部署 章节对密钥进行修改。

查看配置生成报告

你需要在脚本运行结束后查看配置生成报告,包括各服务的访问地址和密码。

*.txt
Plaintext
安全密钥生成结果如下:
LobeHub:
  - URL: http://your_server_ip:3210
RustFS:
  - URL: http://your_server_ip:9000
  - Username: admin
  - Password: dbac8440
Agent Gateway:
  - URL: http://your_server_ip:8787

启动 Docker

docker compose up -d

检查日志

docker logs -f lobehub

如果你在容器中看到了以下日志,则说明已经启动成功:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        http://your_server_ip:3210
  - Network:      http://0.0.0.0:3210
 ✓ Starting...
 ✓ Ready in 95ms

访问应用

你可以通过 http://your_server_ip:3210 访问你的 LobeHub 服务。

域名模式

完成反向代理配置

在域名模式中,你需要完成反向代理配置,并确保局域网 / 公网能访问到以下服务。请使用反向代理将以下服务端口映射到域名:

域名反代端口是否必选
lobe.example.com3210必选
s3.example.com9000必选
gateway.example.com8787必选
s3-ui.example.com9001

在交互式脚本中完成剩余配置

在域名模式中,你需要根据脚本提示完成:

  • LobeHub 服务的域名设置:lobe.example.com
  • S3 服务的域名设置:s3.example.com
  • Agent 网关的域名设置:gateway.example.com(反向代理需要允许 WebSocket 升级)
  • 选择访问协议:http 或 https
  • 安全密钥重新生成:我们强烈建议你重新生成安全密钥,如果你缺少脚本所需的密钥生成库,我们建议你参考 自定义部署 章节对密钥进行修改。

单域名部署方案 如果只有一个域名,可以通过不同端口区分服务:

  • LobeHub 服务的域名设置:lobe.example.com:${PORT1}
  • S3 服务的域名设置:lobe.example.com:${PORT2} 需在反向代理中配置对应端口的转发规则。 端口模式 vs 域名模式:
  • 端口模式:一键安装脚本自动使用默认端口(3210/9000/9001/8787/8788)
  • 域名模式:可自定义端口(通过反向代理配置)

以下问题可能导致你的服务无法正常访问:

  • 此处的域名配置需要与步骤1中的反向代理配置保持一致。

  • 如果你使用 Cloudflare 的域名解析服务并开启了 全程代理,请使用 https 协议。

  • 如果你使用了 HTTPS 协议,请确保你的域名证书已经正确配置,一键部署默认不支持自签发证书。

查看配置生成报告

你需要在脚本运行结束后查看配置生成报告,包括各服务的访问地址和密码。

*.txt
Plaintext
安全密钥生成结果如下:
LobeHub:
  - URL: https://lobe.example.com
RustFS:
  - URL: https://s3.example.com
  - Username: admin
  - Password: dbac8440
Agent Gateway:
  - URL: https://gateway.example.com

启动 Docker

docker compose up -d

检查日志

docker logs -f lobehub

如果你在容器中看到了以下日志,则说明已经启动成功:

*.txt
Plaintext
[Database] Start to migration...
✅ database migration pass.
-------------------------------------
  ▲ Next.js 16.x.x
  - Local:        https://localhost:3210
  - Network:      http://0.0.0.0:3210
  ✓ Starting...
  ✓ Ready in 95ms

访问应用

你可以通过 https://lobe.example.com 访问你的 LobeHub 服务。

自定义部署

该章节主要为你介绍在不同的网络环境下自定义部署 LobeHub 服务必须要修改的配置。在开始前,你可以先下载 Docker Compose 配置文件 以及 环境变量配置文件。

*.sh
Shell
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/docker-compose.yml
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/.env.zh-CN.example
mv .env.zh-CN.example .env

预备知识

一般来讲,想要完整的运行 LobeHub,你需要至少拥有如下三个服务:

  • LobeHub 自身
  • 带有 PGVector 插件的 PostgreSQL 数据库
  • 支持 S3 协议的对象存储服务

这些服务可以通过自建或者在线云服务组合搭配,以满足不同层次的部署需求。本文中,我们提供了完全基于开源自建服务的 Docker Compose 配置,你可以直接使用这份配置文件来启动 LobeHub,也可以对之进行修改以适应你的需求。

我们默认使用 RustFS 作为本地 S3 对象存储服务。如需配置 SSO 登录鉴权服务,请参考 身份验证服务 文档。

如果你的网络拓扑较为复杂,请先确保在你的网络环境中这些服务能够正常通讯。

必要配置

以下我们将介绍运行这些服务的必要配置:

  1. S3 对象存储

LobeHub 需要为 LLM 服务提供商提供文件对象的公网访问地址,因此你需要配置 S3 的 Endpoint:

直接使用 S3_ENDPOINT=http://rustfs:9000 会导致对话内上传图片不可用(浏览器无法直接访问容器内网),但是头像上传不受影响

*.txt
Plaintext
S3_ENDPOINT=https://s3.example.com

S3_ENDPOINT 只需要能被浏览器访问:docker-compose.yml 设置了 S3_INTERNAL_ENDPOINT=http://rustfs:9000,LobeHub 服务端自身会在 Compose 网络内访问 RustFS。

  1. PostgreSQL

该配置位于 docker-compose.yml 文件中,你需要配置数据库的名称和密码:

*.yml
YAML
services:
  lobe:
    environment:
      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
  1. 内部通信地址 (INTERNAL_APP_URL)

Docker Compose 部署时必须配置 INTERNAL_APP_URL。LobeHub 的异步功能(如 AI 生图)需要容器内部发起 HTTP 请求调用自身。如果未设置 INTERNAL_APP_URL,系统将使用 APP_URL 作为回退。当 APP_URL 是宿主机 IP(如 http://10.1.7.146:8080)时,容器内部无法访问该地址,导致生图等异步功能静默失败。

*.txt
Plaintext
INTERNAL_APP_URL=http://localhost:3210
  • APP_URL:用于浏览器 / 客户端访问、OAuth 回调、webhook 等
  • INTERNAL_APP_URL:用于容器内部服务间通信(绕过 CDN / 代理 / 宿主机网络)

对于 Docker Compose 部署,推荐使用 http://localhost:3210(容器调用自身)或 http://lobe:3210(使用服务名称进行容器间通信)。

  1. Agent 网关(Gateway 模式)

gateway 服务让智能体在 LobeHub 服务端运行,而不是在浏览器中运行。它需要在 .env 中配置以下变量,setup.sh 会自动填写:

  • AGENT_GATEWAY_URL:浏览器访问网关的地址,例如 https://gateway.example.com 或 http://your_server_ip:8787。浏览器会向该地址建立 WebSocket 连接,因此其前面的反向代理需要允许 WebSocket 升级并设置较长的读取超时。LobeHub 服务端则在 Compose 网络内通过 http://gateway:8787 访问网关。
  • GATEWAY_SERVICE_TOKEN:LobeHub 与网关共享的随机 Token。
  • JWKS_KEY:LobeHub 签发内部 JWT 使用的 RS256 密钥。每个部署都必须使用自己的密钥,且只保留在 lobe 容器中。
  • JWKS_PUBLIC_KEY:同一密钥去掉私钥字段后的公钥。只有它会传给网关,用于校验浏览器会话。
*.sh
Shell
# GATEWAY_SERVICE_TOKEN
openssl rand -hex 32
# JWKS_KEY 与 JWKS_PUBLIC_KEY(把输出的两行都填入 .env)
docker run --rm --entrypoint /bin/node lobehub/lobehub -e 'const c=require("crypto");const {privateKey,publicKey}=c.generateKeyPairSync("rsa",{modulusLength:2048});const meta={alg:"RS256",kid:c.randomBytes(8).toString("hex"),use:"sig"};console.log("JWKS_KEY="+JSON.stringify({keys:[{...privateKey.export({format:"jwk"}),...meta}]}));console.log("JWKS_PUBLIC_KEY="+JSON.stringify({keys:[{...publicKey.export({format:"jwk"}),...meta}]}))'

正在升级已有部署?请先完成 升级已有部署 中的步骤。网关的状态保存在内存中,重启时正在进行的运行会被中断。

通过 lh connect --gateway http://your_server_ip:8788 接入的设备,可以经由 8788 端口的设备网关为该部署执行本地工具。

可选:在 .env 中设置 DEVICE_GATEWAY_PUBLIC_URL 为客户端可访问的网关地址,例如 http://your_server_ip:8788,不要使用容器内部地址 http://gateway:8788。不配置时可继续使用上面的 --gateway;域名配置参见 连接设备网关。

升级已有部署

请在启动新的 docker-compose.yml 之前完成以下步骤。完成之前,lobe-gateway 容器会反复重启、智能体退回浏览器中运行,docker logs lobehub 启动时会打印 ACTION REQUIRED 告警。

备份 .env 并下载新的 Compose 文件

*.sh
Shell
cp .env .env.bak
curl -O https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/docker-compose.yml

在 .env 中补充网关变量

*.txt
Plaintext
AGENT_GATEWAY_PORT=8787
DEVICE_GATEWAY_PORT=8788
# 浏览器访问网关的地址,例如 https://gateway.example.com
AGENT_GATEWAY_URL=http://your_server_ip:8787
DEVICE_GATEWAY_URL=http://gateway:8788
# 填入 openssl rand -hex 32 的输出
GATEWAY_SERVICE_TOKEN=

然后在 .env 所在目录运行下面的命令,从现有 JWKS_KEY 导出公钥,并把输出的 JWKS_PUBLIC_KEY 填入 .env:

*.sh
Shell
docker run --rm -e JWKS_KEY="$(grep '^JWKS_KEY=' .env | cut -d= -f2-)" --entrypoint /bin/node lobehub/lobehub -e 'const {d,p,q,dp,dq,qi,...pub}=JSON.parse(process.env.JWKS_KEY).keys[0];console.log("JWKS_PUBLIC_KEY="+JSON.stringify({keys:[pub]}))'

域名模式下,还需要为网关域名配置反向代理到 8787 端口,并开启 WebSocket 升级。

替换示例 JWKS_KEY

如果 .env 中的 JWKS_KEY 仍是旧版 .env.example 自带的值(其 kid 为 6823046760c5d460),任何人都能伪造你的部署会接受的令牌。请使用 必要配置 中的命令生成新的密钥对,同时替换 JWKS_KEY 与 JWKS_PUBLIC_KEY,替换后桌面端和 CLI 可能需要重新登录。

重建服务

*.sh
Shell
docker compose up -d --force-recreate

常见问题

数据库迁移问题

你可以使用下述指令检查日志:

docker logs -f lobehub

在我们官方的 Docker 镜像中,会在启动镜像前自动执行数据库 schema 的 migration,我们的官方镜像承诺「空数据库 -> 完整表」这一段自动建表的稳定性。因此我们建议你的数据库实例使用一个空表实例,进而省去手动维护表结构或者 migration 的麻烦。

如果你在建表的时候出现了问题,你可以尝试使用如下命令强制移除数据库容器并重新启动:

*.sh
Shell
docker compose down  # 停止服务
sudo rm -rf ./data   # 移除挂载的数据库数据
docker compose up -d # 重新启动

反向代理配置

在生产环境中,如需使用自定义域名和 HTTPS,需在 LobeHub 前面配置反向代理。

Nginx:

*.txt
Plaintext
server {
    listen 443 ssl http2;
    server_name lobehub.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3210;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy(自动通过 Let's Encrypt 处理 HTTPS):

*.txt
Plaintext
lobehub.example.com {
    reverse_proxy localhost:3210
}

Traefik — 在 docker-compose.yml 的 lobe 服务中添加标签:

*.yml
YAML
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.lobehub.rule=Host(`lobehub.example.com`)"
  - "traefik.http.routers.lobehub.entrypoints=websecure"
  - "traefik.http.routers.lobehub.tls.certresolver=letsencrypt"

管理命令

*.sh
Shell
# 查看所有服务日志
docker compose logs -f

# 查看指定服务日志
docker compose logs -f lobe

# 重启所有服务
docker compose restart

# 重启指定服务
docker compose restart lobe

# 停止所有服务
docker compose stop

# 更新到最新版本
docker compose pull && docker compose up -d

备份与恢复

数据库备份:

*.sh
Shell
docker compose exec postgresql pg_dump -U postgres lobechat > backup.sql

从备份恢复:

*.sh
Shell
docker compose exec -T postgresql psql -U postgres lobechat < backup.sql

文件存储(RustFS)备份:

*.sh
Shell
docker compose exec rustfs tar czf /tmp/backup.tar.gz /data
docker cp lobe-rustfs:/tmp/backup.tar.gz ./rustfs-backup.tar.gz

Redis — Redis 通过 AOF 自动持久化数据。手动保存:

*.sh
Shell
docker compose exec redis redis-cli BGSAVE

资源要求

最低配置(轻量使用):

  • CPU:2 核
  • 内存:4 GB
  • 存储:20 GB

推荐配置(生产环境):

  • CPU:4 核 +
  • 内存:8 GB+
  • 存储:50 GB+(取决于文件上传量)

对于高流量部署,建议使用托管数据库(Neon、Supabase、RDS)、Redis 集群以及 CDN 加速静态资源。

故障排查

服务无法启动

检查服务状态和日志:

*.sh
Shell
docker compose ps
docker compose logs [service-name]

常见原因:端口被占用(在 .env 中修改 LOBE_PORT)、磁盘空间不足、数据库连接失败。

数据库连接错误

检查 PostgreSQL 是否健康:

*.sh
Shell
docker compose exec postgresql pg_isready -U postgres

如果不健康,查看日志:docker compose logs postgresql

文件上传失败

检查 RustFS 服务:

*.sh
Shell
docker compose logs rustfs
docker compose logs rustfs-init

rustfs-init 同时会为存储桶配置浏览器直传所需的 CORS 规则。如果浏览器上传时报网络错误,可以执行 docker compose up -d --force-recreate rustfs-init 重新配置。

确认 bucket 是否已创建:docker compose exec rustfs ls /data/lobe

磁盘空间不足

检查使用情况:docker system df

清理未使用的资源(请先做好备份):

*.sh
Shell
docker system prune -a --volumes

配置身份验证

如需配置 SSO 登录鉴权服务(如 Casdoor、Logto 等),请参考 身份验证服务 文档。