# LobeChat AI 助手

## 概览

[LobeChat](https://github.com/lobehub/lobe-chat) 是一个现代的开源 AI 聊天框架，GitHub 星标超过 55K，以其精致的界面和丰富的功能著称。它支持几乎所有主要的 LLM 提供商——OpenAI、Anthropic Claude、Google Gemini、Mistral，以及通过 Ollama 的本地模型——并且都可以通过单一的自托管界面访问。

**为什么要在 Clore.ai 上运行 LobeChat？**

* **无需 GPU** — LobeChat 本身是一个轻量的 Web 应用。Clore.ai 的仅 CPU 或低 GPU 实例已完全足够用于界面。
* **与本地 LLM 配合** — 在同一台 Clore.ai 服务器上启动 Ollama 或 vLLM，并将 LobeChat 指向它以实现完全本地的私有推理。
* **经济实惠的托管** — 基本的 Clore.ai 实例费用只是传统 VPS 提供商的一小部分，而且在不使用时可以将其关闭。
* **完整的数据所有权** — 数据库模式将所有对话、文件和嵌入存储在服务器上的 PostgreSQL 实例中，由你自行掌控。

LobeChat 有两种不同的运行模式：

| 模式        | 4s                                | 最适合          |
| --------- | --------------------------------- | ------------ |
| **独立模式**  | 单个 Docker 容器，设置存储在浏览器中            | 快速测试、个人使用    |
| **数据库模式** | 完整栈（PostgreSQL + MinIO + 认证 + 应用） | 团队、多用户历史、知识库 |

***

## 要求

### 服务器规格

| 组件      | 最低     | 推荐                   | 注意事项                   |
| ------- | ------ | -------------------- | ---------------------- |
| **GPU** | 不需要    | RTX 3090（如果运行本地 LLM） | 仅在使用 Ollama/vLLM 后端时需要 |
| **显存**  | —      | 24 GB（RTX 3090）      | 用于本地模型推理               |
| **CPU** | 2 vCPU | 4+ vCPU              | LobeChat 本身很轻量         |
| **内存**  | 2 GB   | 8 GB                 | 如果使用数据库模式，需 4+ GB      |
| **存储**  | 10 GB  | 50+ GB               | 如果存储上传的文件或模型则需更多空间     |

### Clore.ai 价格参考

| 服务器类型              | 大致费用            | 模型变体                      |
| ------------------ | --------------- | ------------------------- |
| 仅 CPU 实例           | 约 $0.05–0.10/小时 | 仅独立部署的 LobeChat           |
| RTX 3090（24 GB 显存） | \~$0.20/小时      | LobeChat + Ollama 本地 LLMs |
| RTX 4090（24 GB 显存） | \~$0.35/小时      | LobeChat + 更快的本地推理        |
| A100 80 GB         | \~$1.10/小时      | LobeChat + 大型模型（70B+）     |

> 💡 **提示：** 对于仅使用 API（连接到 OpenAI、Anthropic 等），任何小型实例都可用。只有在你也想运行本地 LLM 时，GPU 服务器才有意义。参见 [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) 了解详情。

### 先决条件

* 已在 Clore.ai 部署服务器的账户
* 对服务器的 SSH 访问
* Docker 和 Docker Compose（Clore.ai 服务器上预装）
* NVIDIA 驱动（预装；仅在使用本地 LLM 后端时相关）
* 至少一个 API 密钥（OpenAI、Anthropic 等） **或** 一个本地 Ollama 实例

***

## 快速开始

### 选项 A：独立模式（推荐用于入门）

独立模式将 LobeChat 作为单个容器运行。设置和对话历史存储在浏览器的本地存储中——无需数据库。

**步骤 1：连接到你的 Clore.ai 服务器**

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

**步骤 2：拉取并运行 LobeChat**

```bash
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-openai-key-here \
  -e OPENAI_PROXY_URL=https://api.openai.com/v1 \
  lobehub/lobe-chat
```

**步骤 3：确认正在运行**

```bash
docker ps
docker logs lobechat --tail 20
```

**步骤 4：访问界面**

在浏览器中打开并访问：

```
http://<your-clore-server-ip>:3210
```

> ⚠️ **安全提示：** Clore.ai 服务器是公开可访问的。请考虑设置 `ACCESS_CODE` 以对你的实例进行密码保护（参见下文的配置部分）。

***

### 选项 B：支持多个提供商的独立模式

传入多个 API 密钥以同时支持不同提供商：

```bash
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-openai-key \
  -e ANTHROPIC_API_KEY=sk-ant-your-anthropic-key \
  -e GOOGLE_API_KEY=your-google-gemini-key \
  -e MISTRAL_API_KEY=your-mistral-key \
  -e ACCESS_CODE=your-secret-password \
  lobehub/lobe-chat
```

***

### 选项 C：使用本地 Ollama 后端

如果你在同一台 Clore.ai 服务器上运行 Ollama（参见 [Ollama 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama)):

```bash
# 首先，启动 Ollama
docker run -d \
  --name ollama \
  --restart unless-stopped \
  --gpus all \
  -p 11434:11434 \
  -v ollama:/root/.ollama \
  ollama/ollama

# 拉取模型
docker exec ollama ollama pull llama3.2

# 启动 LobeChat 并指向 Ollama
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OLLAMA_PROXY_URL=http://host-gateway:11434 \
  --add-host=host-gateway:host-gateway \
  lobehub/lobe-chat
```

> 在 Linux 上，替换 `host-gateway` 为实际的 Docker 网桥 IP，通常是 `172.17.0.1`:
>
> ```bash
> -e OLLAMA_PROXY_URL=http://172.17.0.1:11434
> ```

***

### 选项 D：数据库模式（Docker Compose）

数据库模式启用持久的对话历史、多用户支持、文件上传到兼容 S3 的存储，以及完整的知识库。

**步骤 1：创建项目目录**

```bash
mkdir -p ~/lobechat && cd ~/lobechat
```

**步骤 2：创建 `docker-compose.yml`**

```bash
cat > docker-compose.yml << 'EOF'
version: '3.8'

services:
  postgresql:
    image: pgvector/pgvector:pg16
    container_name: lobe-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: lobechat
      POSTGRES_USER: lobechat
      POSTGRES_PASSWORD: changeme_strong_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U lobechat -d lobechat"]
      interval: 10s
      timeout: 5s
      retries: 5

  minio:
    image: minio/minio
    container_name: lobe-minio
    restart: unless-stopped
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: changeme_minio_password
    command: server /data --console-address ":9001"
    volumes:
      - minio_data:/data
    ports:
      - "9000:9000"
      - "9001:9001"

  lobechat:
    image: lobehub/lobe-chat-database
    container_name: lobe-chat
    restart: unless-stopped
    depends_on:
      postgresql:
        condition: service_healthy
    ports:
      - "3210:3210"
    environment:
      # 数据库
      DATABASE_URL: postgresql://lobechat:changeme_strong_password@postgresql:5432/lobechat
      # S3 存储（MinIO）
      S3_ENDPOINT: http://minio:9000
      S3_BUCKET: lobechat
      S3_ACCESS_KEY_ID: minioadmin
      S3_SECRET_ACCESS_KEY: changeme_minio_password
      S3_PUBLIC_DOMAIN: http://<your-server-ip>:9000
      # 认证（NextAuth）
      NEXTAUTH_SECRET: your-random-32-char-secret-here
      NEXTAUTH_URL: http://<your-server-ip>:3210
      # LLM 提供商
      OPENAI_API_KEY: sk-your-openai-key
      ANTHROPIC_API_KEY: sk-ant-your-key
      # 应用
      APP_URL: http://<your-server-ip>:3210

volumes:
  postgres_data:
  minio_data:
EOF
```

**步骤 3：启动服务栈**

```bash
docker compose up -d
docker compose logs -f lobechat
```

**步骤 4：创建 MinIO 存储桶**

```bash
# 安装 MinIO 客户端
docker exec lobe-minio mc alias set local http://localhost:9000 minioadmin changeme_minio_password
docker exec lobe-minio mc mb local/lobechat
docker exec lobe-minio mc anonymous set download local/lobechat
```

***

## 配置

### 环境变量参考

| 变量                     | 4s                      | 默认值                         |
| ---------------------- | ----------------------- | --------------------------- |
| `OPENAI_API_KEY`       | OpenAI API 密钥           | —                           |
| `OPENAI_PROXY_URL`     | 自定义兼容 OpenAI 的端点        | `https://api.openai.com/v1` |
| `ANTHROPIC_API_KEY`    | Anthropic Claude API 密钥 | —                           |
| `GOOGLE_API_KEY`       | Google Gemini API 密钥    | —                           |
| `MISTRAL_API_KEY`      | Mistral AI API 密钥       | —                           |
| `OLLAMA_PROXY_URL`     | 本地 Ollama 实例的 URL       | —                           |
| `ACCESS_CODE`          | 用于保护界面的密码               | —                           |
| `DEFAULT_AGENT_CONFIG` | 默认助手行为的 JSON 配置         | —                           |
| `FEATURE_FLAGS`        | 启用/禁用特定功能的开关            | —                           |

### 启用特定功能

**启用网页搜索插件：**

```bash
-e BING_API_KEY=your-bing-search-key
```

**启用文本转语音：**

```bash
-e AZURE_TTS_API_KEY=your-azure-key \
-e AZURE_TTS_REGION=eastus
```

**为默认代理设置自定义系统提示：**

```bash
-e DEFAULT_AGENT_CONFIG='{"systemRole":"You are a helpful assistant."}'
```

### 更新 LobeChat

```bash
# 拉取最新镜像
docker pull lobehub/lobe-chat

# 停止并移除旧容器
docker stop lobechat && docker rm lobechat

# 使用相同参数启动新容器
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=sk-your-key \
  lobehub/lobe-chat
```

对于 Docker Compose：

```bash
docker compose pull
docker compose up -d
```

***

## GPU 加速

LobeChat 本身并不 **工作方式：/api/generate** 要求 GPU。然而，当在 Clore.ai 上与加速 GPU 后端配合时，你可以获得本地的、私有的 LLM 推理：

### 与 vLLM 配合（高性能推理）

参见 [vLLM 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) 以获取完整设置。快速集成：

```bash
# 启动 vLLM 服务器（在同一主机）
docker run -d \
  --name vllm \
  --gpus all \
  --restart unless-stopped \
  -p 8000:8000 \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --served-model-name llama3.1-8b

# 启动 LobeChat 并指向 vLLM（兼容 OpenAI 的 API）
docker run -d \
  --name lobechat \
  --restart unless-stopped \
  -p 3210:3210 \
  -e OPENAI_API_KEY=not-needed \
  -e OPENAI_PROXY_URL=http://172.17.0.1:8000/v1 \
  lobehub/lobe-chat
```

### 资源使用情况

| 后端                   | GPU 显存使用 | 大致吞吐量                           |
| -------------------- | -------- | ------------------------------- |
| Ollama（Llama 3.2 3B） | 约 2 GB   | 在 3090 上约 50–80 tokens/sec      |
| Ollama（Llama 3.1 8B） | \~6 GB   | 在 3090 上约 40–60 tokens/sec      |
| vLLM（Llama 3.1 8B）   | \~16 GB  | 在 3090 上约 80–150 tokens/sec     |
| vLLM（Llama 3.1 70B）  | 约 80 GB  | 在 A100 80GB 上约 20–40 tokens/sec |

***

## 提示与最佳实践

### 成本优化

* **闲置时请停止你的服务器。** Clore.ai 按小时收费——使用仪表板暂停你未主动使用的实例。
* **个人使用请用独立模式。** 除非你需要多用户支持或持久的服务器端历史记录，否则独立模式可以避免 PostgreSQL 和 MinIO 的开销。
* **对于大型模型使用 API 提供商。** 通过外部 API 路由 Claude 或 GPT-4 请求比偶尔租用 H100 更便宜。

### 安全性

```bash
# 在公共 Clore.ai IP 上始终设置访问码
-e ACCESS_CODE=your-strong-password-here

# 限制到特定来源（可选）
-e NEXT_PUBLIC_SERVICE_MODE=server
```

* 切勿在公共 IP 上暴露 LobeChat 而不设置 `ACCESS_CODE` 。
* 如果长期运行，考虑使用带 HTTPS 的 Nginx 反向代理。
* 如果怀疑密钥泄露，请更换 API 密钥。

### background = Image.open("studio\_bg.jpg")

```bash
# 如果在数据库模式下有大量用户，请增加 Node.js 堆内存
-e NODE_OPTIONS="--max-old-space-size=4096"
```

* 对于有 10+ 并发用户的数据库模式，请确保主机至少有 8 GB 内存。
* MinIO 在使用 SSD 支持的存储（Clore.ai NVMe 实例）时表现更佳。

### Clore.ai 会话之间的持久性

由于 Clore.ai 服务器可能被终止：

```bash
# 为独立模式的对话导出创建 Docker 卷
docker run -d \
  --name lobechat \
  -p 3210:3210 \
  -v lobechat_data:/app/data \
  lobehub/lobe-chat
```

定期从界面中的 设置 → 数据导出 导出对话。

***

## # 使用固定种子以获得一致结果

### 容器无法启动

```bash
# 检查日志
docker logs lobechat --tail 50

# 验证端口未被占用
ss -tlnp | grep 3210

# 检查 Docker 守护进程是否在运行
systemctl status docker
```

### 无法从 LobeChat 连接到 Ollama

```bash
# 从 LobeChat 容器测试连通性
docker exec lobechat curl -s http://172.17.0.1:11434/api/tags

# 如果失败，检查 Ollama 是否监听所有接口
docker exec ollama ollama serve --host 0.0.0.0
```

### 数据库连接错误（数据库模式）

```bash
# 检查 PostgreSQL 健康状态
docker exec lobe-postgres pg_isready -U lobechat

# 验证 DATABASE_URL 格式
# postgresql://user:password@host:port/dbname

# 如有需要，手动运行迁移
docker exec lobe-chat npx prisma migrate deploy
```

### 图片/文件无法上传（数据库模式）

```bash
# 检查 MinIO 是否可访问
curl -s http://localhost:9000/minio/health/live

# 验证存储桶是否存在
docker exec lobe-minio mc ls local/

# 检查 S3_PUBLIC_DOMAIN 是否设置为正确的服务器 IP
```

### 内存不足错误

```bash
# 检查当前内存使用情况
docker stats lobechat

# 增加容器内存限制
docker run -d \
  --name lobechat \
  --memory=2g \
  -p 3210:3210 \
  lobehub/lobe-chat
```

***

## 延伸阅读

* [LobeChat 文档](https://lobehub.com/docs) — 官方文档、插件开发、部署指南
* [LobeChat GitHub](https://github.com/lobehub/lobe-chat) — 源代码、问题、讨论
* [在 Clore.ai 上运行 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) — LobeChat 的本地 LLM 后端
* [在 Clore.ai 上运行 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) — 高性能的兼容 OpenAI 的推理
* [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) — 选择合适的 Clore.ai GPU
* [LobeChat Docker Hub](https://hub.docker.com/r/lobehub/lobe-chat) — 镜像标签和版本
* [LobeChat 环境变量](https://lobehub.com/docs/self-hosting/environment-variables) — 完整的变量参考