mirror of
https://github.com/lobehub/lobehub.git
synced 2026-04-02 14:29:23 +07:00
eb708e04fe
- Update environment file setup instructions to use docker-compose/local/.env.example instead of .env.example.development - Fix references to environment file locations in both English and Chinese documentation - Align documentation with actual Docker Compose configuration that uses env_file: .env in docker-compose/local/ directory Fixes #9525 🤖 Generated with [Claude Code](https://claude.ai/code) Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> Co-authored-by: Arvin Xu <arvinxx@users.noreply.github.com>
190 lines
4.7 KiB
Plaintext
190 lines
4.7 KiB
Plaintext
# 使用服务端数据库
|
||
|
||
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` 的开发模式下，迁移也会在启动时自动运行。
|