mirror of
https://github.com/lobehub/lobehub
synced 2026-04-21 17:47:27 +00:00
3eaeb6c531
♻️ refactor: consolidate image generation docs with server database setup
- Merge image-generation-setup content into work-with-server-side-database docs
- Remove duplicate image-generation-setup documentation files
- Add server-side database links to setup-development guides
- Add missing .env.development copy step to setup instructions
- Add .env.development to .gitignore for security
The setup script approach has been replaced by Docker Compose configuration
with .env.example.development file, eliminating documentation duplication
and providing a unified server-side development workflow.
189 lines
4.6 KiB
Text
189 lines
4.6 KiB
Text
# 使用服务端数据库
|
||
|
||
LobeChat 提供了内置的客户端数据库体验。
|
||
但某些重要功能仅在服务端开发中可用。
|
||
|
||
为了使用服务端数据库功能，
|
||
需要参考 [部署服务端数据库](https://lobehub.com/docs/self-hosting/server-database) 的说明来配置所有前置条件。
|
||
本文档提供了一个更简化的配置方法，能够在本地开发时快速启动简化的服务端环境。
|
||
|
||
## 快速设置
|
||
|
||
### 环境配置
|
||
|
||
首先，复制示例环境文件来创建你的开发配置：
|
||
|
||
```bash
|
||
cp .env.example.development .env.development
|
||
```
|
||
|
||
此文件包含服务端数据库模式所需的所有环境变量，配置了：
|
||
|
||
- **服务模式**: `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 存储服务以及 `.env.example.development` 中的所有必要环境变量。无需额外配置。
|
||
|
||
### 图像生成架构
|
||
|
||
图像生成功能需要：
|
||
|
||
- **PostgreSQL**：存储生成图像的元数据
|
||
- **MinIO/S3**：存储实际的图像文件
|
||
- **服务器模式**：文件处理所需（`NEXT_PUBLIC_SERVICE_MODE=server`）
|
||
|
||
### 存储配置
|
||
|
||
`.env.example.development` 文件包含所有必要的 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` 的开发模式下，迁移也会在启动时自动运行。
|