lobehub/docs/development/basic/setup-development.zh-CN.mdx

---
title: 环境设置指南
description: 详细介绍 LobeHub 的开发环境设置，包括软件安装和项目配置。
tags:
  - LobeHub
  - 开发环境
  - Node.js
  - PNPM
  - Git
  - Docker
  - PostgreSQL
---

# 环境设置指南

欢迎阅读 LobeHub 的开发环境设置指南。

## 在线开发

如果你有 GitHub Codespaces 的使用权限，可以点击下方按钮一键进入在线开发环境：

[![][codespaces-shield]][codespaces-link]

## 本地开发

在开始开发 LobeHub 之前，你需要在本地环境中安装和配置一些必要的软件和工具。本文档将指导你完成这些步骤。

### 开发环境需求

首先，你需要安装以下软件：

- Node.js：LobeHub 是基于 Node.js 构建的，因此你需要安装 Node.js。我们建议安装最新的稳定版。
- PNPM：我们使用 PNPM 作为管理器。你可以从 [pnpm 的官方网站](https://pnpm.io/installation) 上下载并安装。
- Bun：我们使用 Bun 作为 npm scripts runner，你可以从 [Bun 的官方网站](https://bun.com/docs/installation) 上下载并安装。
- Git：我们使用 Git 进行版本控制。你可以从 Git 的官方网站上下载并安装。
- Docker：用于运行 PostgreSQL、MinIO 等服务。你可以从 [Docker 官方网站](https://www.docker.com/get-started) 下载并安装。
- IDE：你可以选择你喜欢的集成开发环境（IDE），我们推荐使用 WebStorm/VSCode。

### VSCode 用户

推荐安装 [.vscode/extensions.json](https://github.com/lobehub/lobehub/blob/main/.vscode/extensions.json) 中推荐安装的扩展获得最佳开发体验。

### 项目设置

完成上述软件的安装后，你可以开始设置 LobeHub 项目了。

#### 1. 获取代码

首先，你需要从 GitHub 上克隆 LobeHub 的代码库。在终端中运行以下命令：

```bash
git clone https://github.com/lobehub/lobehub.git
cd lobehub
```

#### 2. 安装依赖

使用 PNPM 安装项目的依赖包：

```bash
pnpm i
```

#### 3. 配置环境

复制示例环境文件来创建你的 Docker Compose 配置：

```bash
cp docker-compose/local/.env.example docker-compose/local/.env
```

根据需要编辑 `docker-compose/local/.env` 文件以适应你的开发设置。此文件包含 Docker 服务所需的所有环境变量，配置了：

- **数据库**：带连接字符串的 PostgreSQL
- **身份验证**：带 Casdoor SSO 的 Better Auth
- **存储**：MinIO S3 兼容存储
- **搜索**：SearXNG 搜索引擎

#### 4. 启动 Docker 服务

使用 Docker Compose 启动所有必需的服务：

```bash
docker-compose -f docker-compose.development.yml up -d
```

这将启动以下服务：

- PostgreSQL 数据库（端口 5432）
- MinIO 存储（端口 9000）
- Casdoor 身份验证（端口 8000）
- SearXNG 搜索（端口 8080）

可以通过运行以下命令检查所有 Docker 服务运行状态：

```bash
docker-compose -f docker-compose.development.yml ps
```

#### 5. 运行数据库迁移

执行数据库迁移脚本以创建所有必要的表：

```bash
pnpm db:migrate
```

预期输出：`✅ database migration pass.`

#### 6. 启动开发服务器

启动 LobeHub 开发服务器：

```bash
bun run dev
```

现在，你可以在浏览器中打开 `http://localhost:3010`，你应该能看到 LobeHub 的欢迎页面。这表明你已经成功地设置了开发环境。

![Chat Page](https://hub-apac-1.lobeobjects.space/docs/fc7b157a3bc016bc97719065f80c555c.png)

## 图像生成开发

在开发图像生成功能（文生图、图生图）时，Docker Compose 配置已经包含了处理生成图像和用户上传所需的所有存储服务。

### 图像生成配置

现有的 Docker Compose 配置已经包含了 MinIO 存储服务以及 `docker-compose/local/.env.example` 中的所有必要环境变量。无需额外配置。

### 图像生成架构

图像生成功能需要：

- **PostgreSQL**：存储生成图像的元数据
- **MinIO/S3**：存储实际的图像文件

### 存储配置

`docker-compose/local/.env.example` 文件包含所有必要的 S3 环境变量：

```bash
# S3 存储配置（本地开发使用 MinIO）
S3_ACCESS_KEY_ID=${MINIO_ROOT_USER}
S3_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}
S3_ENDPOINT=http://localhost:${MINIO_PORT}
S3_BUCKET=${MINIO_LOBE_BUCKET}
S3_ENABLE_PATH_STYLE=1  # MinIO 必需
S3_SET_ACL=0  # MinIO 兼容性
```

### 文件存储结构

生成的图像和用户上传在 MinIO 存储桶中按以下方式组织：

```
lobe/                # S3 存储桶 (MINIO_LOBE_BUCKET)
├── generated/       # 生成的图像
│   └── {userId}/
│       └── {sessionId}/
│           └── {imageId}.png
└── uploads/         # 用户上传的图像处理文件
    └── {userId}/
        └── {fileId}.{ext}
```

### 图像开发工作流

在开发图像生成功能时，生成的图像将：

1. 由 AI 模型创建
2. 通过预签名 URL 上传到 S3/MinIO
3. 元数据存储在 PostgreSQL 中
4. 通过公共 S3 URL 提供服务

测试图像上传的示例代码：

```typescript
// 示例：上传生成的图像
const uploadUrl = await trpc.upload.createPresignedUrl.mutate({
  filename: 'generated-image.png',
  contentType: 'image/png',
});

// 上传到 S3
await fetch(uploadUrl, {
  method: 'PUT',
  body: imageBlob,
  headers: { 'Content-Type': 'image/png' },
});
```

### 服务地址

运行 Docker Compose 开发环境时：

- **PostgreSQL**：`postgres://postgres@localhost:5432/LobeHub`
- **MinIO API**：`http://localhost:9000`
- **MinIO 控制台**：`http://localhost:9001` (admin/CHANGE\_THIS\_PASSWORD\_IN\_PRODUCTION)
- **应用程序**：`http://localhost:3010`

## 故障排除

### 重置服务

如遇到问题，可以重置整个服务堆栈：

```bash
# 停止并删除所有容器
docker-compose -f docker-compose.development.yml down

# 删除卷（这将删除所有数据）
docker-compose -f docker-compose.development.yml down -v

# 重新启动
docker-compose -f docker-compose.development.yml up -d
pnpm db:migrate
```

### 端口冲突

如果端口已被占用：

```bash
# 检查端口使用情况
lsof -i :5432  # PostgreSQL
lsof -i :9000  # MinIO API
lsof -i :9001  # MinIO 控制台
```

### 数据库迁移

配置脚本会自动运行迁移。如需手动运行：

```bash
pnpm db:migrate
```

注意：在使用 `pnpm dev:desktop` 的开发模式下，迁移也会在启动时自动运行。

---

在开发过程中，如果你在环境设置上遇到任何问题，或者有任何关于 LobeHub 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！

[codespaces-link]: https://codespaces.new/lobehub/lobehub
[codespaces-shield]: https://github.com/codespaces/badge.svg