lobehub/docs/self-hosting/platform/docker-compose.zh-CN.mdx

---
title: 通过 Docker Compose 部署 LobeHub
description: 学习如何使用 Docker Compose 部署 LobeHub 服务，包括各种服务的配置教程。
tags:
  - Docker Compose
  - LobeHub
  - Docker 容器
  - 部署指引
---

# 使用 Docker Compose 部署 LobeHub

<div style={{display:"flex", gap: 4}}>
  [![][docker-release-shield]][docker-release-link]

  [![][docker-size-shield]][docker-size-link]

  [![][docker-pulls-shield]][docker-pulls-link]
</div>

## 快速启动

<Callout type="info">
  **系统兼容性说明**

  - 支持 Unix 环境（Linux/macOS）的一键部署

  - Windows 用户需通过 [WSL 2](https://aka.ms/wsl) 运行

  - 一键启动脚本为首次部署专用，非首次部署请参考 [自定义部署](#自定义部署) 章节

  - 端口占用检查：确保 `3210`、`9000`、`9001` 端口可用
</Callout>

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

```sh
mkdir lobehub && cd lobehub
```

获取并执行部署脚本：

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

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

- [本地模式（默认）](#本地模式)：仅能在本地访问，不支持局域网 / 公网访问，适用于初次体验；
- [端口模式](#端口模式)：支持局域网 / 公网的 `http` 访问，适用于无域名或内部办公场景使用；
- [域名模式](#域名模式)：支持局域网 / 公网在使用反向代理下的 `http/https` 访问，适用于个人或团队日常使用；

<Callout type="info">
  在脚本的选项提示 `(选项1/选项2)[选项1]` 中：`(选项1 / 选项2)`
  代表可以选择的选项，`[选项1]`代表默认选项，直接回车即可选择默认选项。
</Callout>

### 本地模式

<Steps>
  ### 在交互式脚本中完成剩余配置

  持续回车采用默认配置。

  ### 查看配置生成报告

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

  ```log
  安全密钥生成结果如下：
  LobeHub:
    - URL: http://localhost:3210
  RustFS:
    - URL: http://localhost:9000
    - Username: admin
    - Password: 8c82ea41
  ```

  ### 启动 Docker

  ```sh
  docker compose up -d
  ```

  ### 检查日志

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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](http://localhost:3210) 访问你的 LobeHub 服务。
</Steps>

### 端口模式

<Steps>
  ### 在交互式脚本中完成剩余配置

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

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

  ### 查看配置生成报告

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

  ```log
  安全密钥生成结果如下：
  LobeHub:
    - URL: http://your_server_ip:3210
  RustFS:
    - URL: http://your_server_ip:9000
    - Username: admin
    - Password: dbac8440
  ```

  ### 启动 Docker

  ```sh
  docker compose up -d
  ```

  ### 检查日志

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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 服务。
</Steps>

### 域名模式

<Steps>
  ### 完成反向代理配置

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

  | 域名                  | 反代端口   | 是否必选 |
  | ------------------- | ------ | ---- |
  | `lobe.example.com`  | `3210` | 必选   |
  | `s3.example.com`    | `9000` | 必选   |
  | `s3-ui.example.com` | `9001` |      |

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

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

  - LobeHub 服务的域名设置：`lobe.example.com`
  - S3 服务的域名设置：`s3.example.com`
  - 选择访问协议：`http` 或 `https`
  - 安全密钥重新生成：我们强烈建议你重新生成安全密钥，如果你缺少脚本所需的密钥生成库，我们建议你参考 [自定义部署](#自定义部署) 章节对密钥进行修改。

  <Callout type="tip">
    **单域名部署方案**
    如果只有一个域名，可以通过不同端口区分服务：

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

  <Callout type="warning">
    以下问题可能导致你的服务无法正常访问：

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

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

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

  ### 查看配置生成报告

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

  ```log
  安全密钥生成结果如下：
  LobeHub:
    - URL: https://lobe.example.com
  RustFS:
    - URL: https://s3.example.com
    - Username: admin
    - Password: dbac8440
  ```

  ### 启动 Docker

  ```sh
  docker compose up -d
  ```

  ### 检查日志

  ```sh
  docker logs -f lobehub
  ```

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

  ```log
  [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 服务。
</Steps>

## 自定义部署

该章节主要为你介绍在不同的网络环境下自定义部署 LobeHub 服务必须要修改的配置。在开始前，你可以先下载 [Docker Compose 配置文件](https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/docker-compose.yml) 以及 [环境变量配置文件](https://raw.githubusercontent.com/lobehub/lobehub/HEAD/docker-compose/deploy/.env.zh-CN.example)。

```sh
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](https://github.com/rustfs/rustfs) 作为本地 S3 对象存储服务。如需配置 SSO 登录鉴权服务，请参考 [身份验证服务](/zh/docs/self-hosting/auth) 文档。

<Callout type="warning">
  如果你的网络拓扑较为复杂，请先确保在你的网络环境中这些服务能够正常通讯。
</Callout>

### 必要配置

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

1. S3 对象存储

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

<Callout type="warning">
  直接使用 `S3_ENDPOINT=http://rustfs:9000` 会导致对话内上传图片不可用（浏览器无法直接访问容器内网），但是头像上传不受影响
</Callout>

```env
S3_ENDPOINT=https://s3.example.com
```

2. PostgreSQL

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

```yaml
services:
  lobe:
    environment:
      - 'DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@postgresql:5432/${LOBE_DB_NAME}'
```

## 常见问题

#### 数据库迁移问题

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

```sh
docker logs -f lobehub
```

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

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

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

#### 使用 `INTERNAL_APP_URL` 配置内部服务器通信

<Callout type="info">
  如果你在 CDN（如 Cloudflare）或反向代理后部署 LobeHub，你可以配置内部服务器到服务器通信以绕过 CDN / 代理层，以获得更好的性能。
</Callout>

你可以配置 `INTERNAL_APP_URL` 环境变量：

```yaml
environment:
  - 'APP_URL=https://lobe.example.com'  # 浏览器访问的公开 URL
  - 'INTERNAL_APP_URL=http://localhost:3210'  # 服务器到服务器调用的内部 URL
```

**工作原理：**

- `APP_URL`：用于浏览器 / 客户端访问、OAuth 回调、webhook 等（通过 CDN / 代理）
- `INTERNAL_APP_URL`：用于内部服务器到服务器通信（绕过 CDN / 代理）

如果未设置 `INTERNAL_APP_URL`，它将默认为 `APP_URL`。

**配置选项：**

- `http://localhost:3210` - 如果使用 Docker 主机网络模式
- `http://lobe:3210` - 如果使用 Docker 网络与服务名称
- `http://127.0.0.1:3210` - 备用本地主机地址

<Callout type="tip">
  对于 Docker Compose 部署，推荐使用 `http://lobe:3210` 作为 `INTERNAL_APP_URL`（使用服务名称进行容器间通信）。
</Callout>

## 反向代理配置

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

**Nginx：**

```nginx
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）：

```caddyfile
lobehub.example.com {
    reverse_proxy localhost:3210
}
```

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

```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
# 查看所有服务日志
docker compose logs -f

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

# 重启所有服务
docker compose restart

# 重启指定服务
docker compose restart lobehub

# 停止所有服务
docker compose stop

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

## 备份与恢复

**数据库备份：**

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

从备份恢复：

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

**文件存储（RustFS）备份：**

```sh
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
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
docker compose ps
docker compose logs [service-name]
```

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

**数据库连接错误**

检查 PostgreSQL 是否健康：

```sh
docker compose exec postgresql pg_isready -U postgres
```

如果不健康，查看日志：`docker compose logs postgresql`

**文件上传失败**

检查 RustFS 服务：

```sh
docker compose logs rustfs
docker compose logs rustfs-init
```

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

**磁盘空间不足**

检查使用情况：`docker system df`

清理未使用的资源（请先做好备份）：

```sh
docker system prune -a --volumes
```

## 配置身份验证

如需配置 SSO 登录鉴权服务（如 Casdoor、Logto 等），请参考 [身份验证服务](/zh/docs/self-hosting/auth) 文档。

[docker-pulls-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-pulls-shield]: https://img.shields.io/docker/pulls/lobehub/lobehub?color=45cc11&labelColor=black&style=flat-square
[docker-release-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-release-shield]: https://img.shields.io/docker/v/lobehub/lobehub?color=369eff&label=docker&labelColor=black&logo=docker&logoColor=white&style=flat-square&sort=semver
[docker-size-link]: https://hub.docker.com/r/lobehub/lobehub
[docker-size-shield]: https://img.shields.io/docker/image-size/lobehub/lobehub?color=369eff&labelColor=black&style=flat-square&sort=semver