# 使用服务端数据库

LobeChat 提供了内置的客户端数据库体验。
但某些重要功能仅在服务端开发中可用。

为了使用服务端数据库功能，
需要参考 [部署服务端数据库](https://lobehub.com/docs/self-hosting/server-database) 的说明来配置所有前置条件。
本文档提供了一个更简化的配置方法，能够在本地开发时快速启动简化的服务端环境。

## 快速设置

### 环境配置

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

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

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

- **服务模式**: `NEXT_PUBLIC_SERVICE_MODE=server`
- **数据库**: 带连接字符串的 PostgreSQL
- **身份验证**: 带 Casdoor SSO 的 NextAuth
- **存储**: MinIO S3 兼容存储
- **搜索**: SearXNG 搜索引擎

### 启动 Docker 服务

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

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

这将启动以下服务：

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

### 运行数据库迁移

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

```bash
pnpm db:migrate
```

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

### 启动开发服务器

启动 LobeChat 开发服务器：

```bash
pnpm dev
```

服务器将在 `http://localhost:3010` 上启动

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

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

## 图像生成开发

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

### 图像生成配置

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

### 图像生成架构

图像生成功能需要：

- **PostgreSQL**：存储生成图像的元数据
- **MinIO/S3**：存储实际的图像文件
- **服务器模式**：文件处理所需（`NEXT_PUBLIC_SERVICE_MODE=server`）

### 存储配置

`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_PUBLIC_DOMAIN=http://localhost:${MINIO_PORT}
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/lobechat`
- **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` 的开发模式下，迁移也会在启动时自动运行。