references/lobe-chat
1
0
Fork 0
mirror of https://github.com/lobehub/lobe-chat.git synced 2026-06-13 19:20:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 docs: consolidate image generation docs with server database setup (#9096)

Browse Source 
♻️ 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.
This commit is contained in:
Maple Gao
2025-09-10 18:16:58 +01:00
committed by GitHub
parent aa841a3879
commit 3eaeb6c531
8 changed files with 251 additions and 463 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -38,6 +38,7 @@ tmp/
.env
.env.local
.env*.local
.env.development
venv/
.venv/
docs/development/basic/image-generation-setup.mdx
-190
View File
@@ -1,190 +0,0 @@
---
title: Image Generation Development Setup
description: Configure local environment for developing text-to-image and image-to-image features
---
# Image Generation Development Setup
This guide helps developers set up the local environment for developing image generation features (text-to-image, image-to-image) with file storage capabilities.
## Prerequisites
- Docker installed and running
- Node.js and pnpm installed
- PostgreSQL client tools (optional, for debugging)
<Callout type="warning">
**Security Notice**: This setup is designed for local development only. It uses default credentials and open permissions that are NOT suitable for production environments.
</Callout>
## Quick Setup
Run the provided script to automatically set up all required services:
```bash
# Set up PostgreSQL and MinIO for image storage
./scripts/setup-image-generation-dev.sh
# Start the development server
pnpm dev:desktop
```
This script will:
1. Start PostgreSQL (no authentication for local development)
2. Run database migrations to initialize schema
3. Start MinIO (S3-compatible storage)
4. Create and configure the storage bucket
5. Add necessary S3 environment variables to `.env.desktop`
## Architecture Overview
The image generation feature requires:
- **PostgreSQL**: Stores metadata about generated images
- **MinIO/S3**: Stores the actual image files
- **Server Mode**: Required for file handling (`NEXT_PUBLIC_SERVICE_MODE=server`)
## Environment Configuration
The following environment variables are automatically configured by the setup script:
```bash
# S3 Storage Configuration (MinIO for local development)
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=lobe-chat
S3_REGION=us-east-1
S3_PUBLIC_DOMAIN=http://localhost:9000/lobe-chat
S3_ENABLE_PATH_STYLE=1 # Required for MinIO
```
## Development Workflow
### 1. Image Generation API
When developing image generation features, generated images will be:
1. Created by the AI model
2. Uploaded to S3/MinIO via presigned URLs
3. Metadata stored in PostgreSQL
4. Served via the public S3 URL
### 2. File Storage Structure
```
lobe-chat/ # S3 Bucket
├── generated/ # Generated images
│ └── {userId}/
│ └── {sessionId}/
│ └── {imageId}.png
└── uploads/ # User uploads for image-to-image
└── {userId}/
└── {fileId}.{ext}
```
### 3. Testing Your Implementation
After setting up the environment, you can test:
```typescript
// Example: Upload generated image
const uploadUrl = await trpc.upload.createPresignedUrl.mutate({
filename: 'generated-image.png',
contentType: 'image/png',
});
// Upload to S3
await fetch(uploadUrl, {
method: 'PUT',
body: imageBlob,
headers: { 'Content-Type': 'image/png' },
});
```
## Manual Setup
If you prefer to set up services manually:
### PostgreSQL
```bash
docker run -d --name lobe-postgres \
-p 5432:5432 \
-e POSTGRES_HOST_AUTH_METHOD=trust \
-e POSTGRES_DB=postgres \
postgres:15
```
### MinIO
```bash
# Start MinIO
docker run -d --name lobe-minio \
-p 9000:9000 -p 9001:9001 \
-e MINIO_ROOT_USER=minioadmin \
-e MINIO_ROOT_PASSWORD=minioadmin \
quay.io/minio/minio:RELEASE.2025-04-22T22-12-26Z \
server /data --console-address ":9001"
# Create bucket
docker run --rm \
--link lobe-minio:minio \
--entrypoint bash \
quay.io/minio/mc:RELEASE.2025-04-18T16-45-00Z \
-c "
mc config host add minio http://minio:9000 minioadmin minioadmin &&
mc mb minio/lobe-chat &&
mc anonymous set public minio/lobe-chat
"
```
## Service URLs
- **PostgreSQL**: `postgres://postgres@localhost:5432/postgres`
- **MinIO API**: `http://localhost:9000`
- **MinIO Console**: `http://localhost:9001` (minioadmin/minioadmin)
- **Application**: `http://localhost:3015`
## Troubleshooting
### Port Conflicts
If ports are already in use:
```bash
# Check what's using the ports
lsof -i :5432 # PostgreSQL
lsof -i :9000 # MinIO API
lsof -i :9001 # MinIO Console
```
### Reset Environment
To completely reset your development environment:
```bash
# Stop and remove containers
docker stop lobe-postgres lobe-minio
docker rm lobe-postgres lobe-minio
# Re-run setup
./scripts/setup-image-generation-dev.sh
```
### Database Migrations
The setup script runs migrations automatically. If you need to run them manually:
```bash
pnpm db:migrate
```
Note: In development mode with `pnpm dev:desktop`, migrations also run automatically on startup.
## Related Documentation
- [Server Database Setup](/docs/self-hosting/server-database)
- [S3 Storage Configuration](/docs/self-hosting/advanced/s3)
- [Environment Variables](/docs/self-hosting/environment-variables)
docs/development/basic/image-generation-setup.zh-CN.mdx
-190
View File
@@ -1,190 +0,0 @@
---
title: 图像生成开发环境配置
description: 配置本地环境以开发文本生图和图像处理功能
---
# 图像生成开发环境配置
本指南帮助开发者配置本地环境，用于开发图像生成功能（文生图、图生图）等和文件存储能力。
## 前置条件
- 已安装并运行 Docker
- 已安装 Node.js 和 pnpm
- PostgreSQL 客户端工具（可选，用于调试）
<Callout type="warning">
**安全提醒**：此配置仅适用于本地开发。使用的默认凭据和开放权限不适合生产环境。
</Callout>
## 快速配置
运行提供的脚本来自动配置所有必需的服务：
```bash
# 配置 PostgreSQL 和 MinIO 用于图像存储
./scripts/setup-image-generation-dev.sh
# 启动开发服务器
pnpm dev:desktop
```
此脚本将执行：
1. 启动 PostgreSQL（本地开发无需身份验证）
2. 运行数据库迁移以初始化模式
3. 启动 MinIO（S3 兼容存储）
4. 创建并配置存储桶
5. 在 `.env.desktop` 中添加必要的 S3 环境变量
## 架构概览
图像生成功能需要：
- **PostgreSQL**：存储生成图像的元数据
- **MinIO/S3**：存储实际的图像文件
- **服务器模式**：文件处理所需（`NEXT_PUBLIC_SERVICE_MODE=server`）
## 环境配置
以下环境变量会被配置脚本自动设置：
```bash
# S3 存储配置（本地开发使用 MinIO）
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
S3_ENDPOINT=http://localhost:9000
S3_BUCKET=lobe-chat
S3_REGION=us-east-1
S3_PUBLIC_DOMAIN=http://localhost:9000/lobe-chat
S3_ENABLE_PATH_STYLE=1 # MinIO 必需
```
## 开发工作流
### 1. 图像生成 API
在开发图像生成功能时，生成的图像将：
1. 由 AI 模型创建
2. 通过预签名 URL 上传到 S3/MinIO
3. 元数据存储在 PostgreSQL 中
4. 通过公共 S3 URL 提供服务
### 2. 文件存储结构
```
lobe-chat/ # S3 存储桶
├── generated/ # 生成的图像
│ └── {userId}/
│ └── {sessionId}/
│ └── {imageId}.png
└── uploads/ # 用户上传的图像处理文件
└── {userId}/
└── {fileId}.{ext}
```
### 3. 测试您的实现
配置环境后，您可以测试：
```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' },
});
```
## 手动配置
如果您希望手动配置服务：
### PostgreSQL
```bash
docker run -d --name lobe-postgres \
-p 5432:5432 \
-e POSTGRES_HOST_AUTH_METHOD=trust \
-e POSTGRES_DB=postgres \
postgres:15
```
### MinIO
```bash
# 启动 MinIO
docker run -d --name lobe-minio \
-p 9000:9000 -p 9001:9001 \
-e MINIO_ROOT_USER=minioadmin \
-e MINIO_ROOT_PASSWORD=minioadmin \
quay.io/minio/minio:RELEASE.2025-04-22T22-12-26Z \
server /data --console-address ":9001"
# 创建存储桶
docker run --rm \
--link lobe-minio:minio \
--entrypoint bash \
quay.io/minio/mc:RELEASE.2025-04-18T16-45-00Z \
-c "
mc config host add minio http://minio:9000 minioadmin minioadmin &&
mc mb minio/lobe-chat &&
mc anonymous set public minio/lobe-chat
"
```
## 服务地址
- **PostgreSQL**：`postgres://postgres@localhost:5432/postgres`
- **MinIO API**：`http://localhost:9000`
- **MinIO 控制台**：`http://localhost:9001` (minioadmin/minioadmin)
- **应用程序**：`http://localhost:3015`
## 故障排除
### 端口冲突
如果端口已被占用：
```bash
# 检查端口使用情况
lsof -i :5432 # PostgreSQL
lsof -i :9000 # MinIO API
lsof -i :9001 # MinIO 控制台
```
### 重置环境
要完全重置开发环境：
```bash
# 停止并删除容器
docker stop lobe-postgres lobe-minio
docker rm lobe-postgres lobe-minio
# 重新运行配置
./scripts/setup-image-generation-dev.sh
```
### 数据库迁移
配置脚本会自动运行迁移。如需手动运行：
```bash
pnpm db:migrate
```
注意：在使用 `pnpm dev:desktop` 的开发模式下，迁移也会在启动时自动运行。
## 相关文档
- [服务器数据库配置](/docs/self-hosting/server-database)
- [S3 存储配置](/docs/self-hosting/advanced/s3)
- [环境变量](/docs/self-hosting/environment-variables)
docs/development/basic/setup-development.mdx
+12
View File
@@ -53,6 +53,18 @@ Now, you can open `http://localhost:3010` in your browser, and you should see th
![](https://github-production-user-asset-6210df.s3.amazonaws.com/28616219/274655364-414bc31e-8511-47a3-af17-209b530effc7.png)
## Working with Server-Side Features
The basic setup above uses LobeChat's client-side database mode. If you need to work with server-side features such as:
- Database persistence
- File uploads and storage
- Image generation
- Multi-user authentication
- Advanced server-side integrations
Please refer to the [Work with Server-Side Database](/docs/development/basic/work-with-server-side-database) guide for complete setup instructions.
During the development process, if you encounter any issues with environment setup or have any questions about LobeChat development, feel free to ask us at any time. We look forward to seeing your contributions!
[codespaces-link]: https://codespaces.new/lobehub/lobe-chat
docs/development/basic/setup-development.zh-CN.mdx
+12
View File
@@ -53,6 +53,18 @@ bun run dev
![Chat Page](https://hub-apac-1.lobeobjects.space/docs/fc7b157a3bc016bc97719065f80c555c.png)
## 使用服务端功能
上述基础设置使用 LobeChat 的客户端数据库模式。如果你需要开发服务端功能，如：
- 数据库持久化
- 文件上传和存储
- 图像生成
- 多用户身份验证
- 高级服务端集成
请参考[使用服务端数据库](/docs/development/basic/work-with-server-side-database)指南获得完整的设置说明。
在开发过程中，如果你在环境设置上遇到任何问题，或者有任何关于 LobeChat 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！
[codespaces-link]: https://codespaces.new/lobehub/lobe-chat
docs/development/basic/work-with-server-side-database.mdx
+113 -1
View File
@@ -11,7 +11,13 @@ But here is the easier approach that can reduce your pain.
### Environment Configuration
The project already includes a `.env.development` file with all necessary environment variables for server-side database mode. This file configures:
First, copy the example environment file to create your development configuration:
```bash
cp .env.example.development .env.development
```
This file contains all necessary environment variables for server-side database mode and configures:
- **Service Mode**: `NEXT_PUBLIC_SERVICE_MODE=server`
- **Database**: PostgreSQL with connection string
@@ -60,6 +66,88 @@ And you can check all Docker services are running by running:
docker-compose -f docker-compose.development.yml ps
```
## Image Generation Development
When working with image generation features (text-to-image, image-to-image), the Docker Compose setup already includes all necessary storage services for handling generated images and user uploads.
### Image Generation Configuration
The existing Docker Compose configuration already includes MinIO storage service and all necessary environment variables in `.env.example.development`. No additional setup is required.
### Image Generation Architecture
The image generation feature requires:
- **PostgreSQL**: Stores metadata about generated images
- **MinIO/S3**: Stores the actual image files
- **Server Mode**: Required for file handling (`NEXT_PUBLIC_SERVICE_MODE=server`)
### Storage Configuration
The `.env.example.development` file includes all necessary S3 environment variables:
```bash
# S3 Storage Configuration (MinIO for local development)
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 # Required for MinIO
S3_SET_ACL=0 # MinIO compatibility
```
### File Storage Structure
Generated images and user uploads are organized in the MinIO bucket:
```
lobe/ # S3 Bucket (MINIO_LOBE_BUCKET)
├── generated/ # Generated images
│ └── {userId}/
│ └── {sessionId}/
│ └── {imageId}.png
└── uploads/ # User uploads for image-to-image
└── {userId}/
└── {fileId}.{ext}
```
### Development Workflow for Images
When developing image generation features, generated images will be:
1. Created by the AI model
2. Uploaded to S3/MinIO via presigned URLs
3. Metadata stored in PostgreSQL
4. Served via the public S3 URL
Example code for testing image upload:
```typescript
// Example: Upload generated image
const uploadUrl = await trpc.upload.createPresignedUrl.mutate({
filename: 'generated-image.png',
contentType: 'image/png',
});
// Upload to S3
await fetch(uploadUrl, {
method: 'PUT',
body: imageBlob,
headers: { 'Content-Type': 'image/png' },
});
```
### Service URLs
When running with Docker Compose development setup:
- **PostgreSQL**: `postgres://postgres@localhost:5432/lobechat`
- **MinIO API**: `http://localhost:9000`
- **MinIO Console**: `http://localhost:9001` (admin/CHANGE_THIS_PASSWORD_IN_PRODUCTION)
- **Application**: `http://localhost:3010`
### Reset Services
If you encounter issues, you can reset the entire stack:
@@ -75,3 +163,27 @@ docker-compose -f docker-compose.development.yml down -v
docker-compose -f docker-compose.development.yml up -d
pnpm db:migrate
```
### Troubleshooting
#### Port Conflicts
If ports are already in use:
```bash
# Check what's using the ports
lsof -i :5432 # PostgreSQL
lsof -i :9000 # MinIO API
lsof -i :9001 # MinIO Console
```
#### Database Migrations
The setup script runs migrations automatically. If you need to run them manually:
```bash
pnpm db:migrate
```
Note: In development mode with `pnpm dev:desktop`, migrations also run automatically on startup.
docs/development/basic/work-with-server-side-database.zh-CN.mdx
+113 -1
View File
@@ -11,7 +11,13 @@ LobeChat 提供了内置的客户端数据库体验。
### 环境配置
项目已经包含了一个 `.env.development` 文件，其中包含服务端数据库模式所需的所有环境变量。此文件配置了：
首先，复制示例环境文件来创建你的开发配置：
```bash
cp .env.example.development .env.development
```
此文件包含服务端数据库模式所需的所有环境变量，配置了：
- **服务模式**: `NEXT_PUBLIC_SERVICE_MODE=server`
- **数据库**: 带连接字符串的 PostgreSQL
@@ -60,6 +66,88 @@ pnpm dev
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`
### 重置服务
如遇到问题，可以重置整个服务堆栈：
@@ -75,3 +163,27 @@ 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` 的开发模式下，迁移也会在启动时自动运行。
scripts/setup-image-generation-dev.sh
-81
View File
@@ -1,81 +0,0 @@
#!/bin/bash
echo "🚀 Setting up image upload development environment..."
# 1. 设置 PostgreSQL (无密码本地开发)
echo "Step 1: Setting up PostgreSQL..."
docker stop lobe-postgres 2>/dev/null && docker rm lobe-postgres 2>/dev/null
docker run -d --name lobe-postgres \
-p 5432:5432 \
-e POSTGRES_HOST_AUTH_METHOD=trust \
-e POSTGRES_DB=postgres \
postgres:15
echo "Waiting for PostgreSQL to start..."
sleep 10
# 运行数据库迁移
echo "Running database migrations..."
pnpm db:migrate
# 2. 启动 MinIO
echo ""
echo "Step 2: Starting MinIO..."
docker stop lobe-minio 2>/dev/null && docker rm lobe-minio 2>/dev/null
docker run -d --name lobe-minio \
-p 9000:9000 -p 9001:9001 \
-e MINIO_ROOT_USER=minioadmin \
-e MINIO_ROOT_PASSWORD=minioadmin \
quay.io/minio/minio:RELEASE.2025-04-22T22-12-26Z server /data --console-address ":9001"
# 3. 等待 MinIO 启动
echo "Waiting for MinIO to start..."
sleep 10
# 4. 创建 bucket 并设置权限
echo "Creating bucket and setting permissions..."
docker run --rm \
--link lobe-minio:minio \
--entrypoint bash \
quay.io/minio/mc:RELEASE.2025-04-18T16-45-00Z \
-c "
mc config host add minio http://minio:9000 minioadmin minioadmin
mb_output=\$(mc mb minio/lobe-chat 2>&1)
mb_exit=\$?
if [ \$mb_exit -ne 0 ]; then
echo \"\$mb_output\" | grep -q 'Bucket already exists' || { echo \"Failed to create bucket: \$mb_output\"; exit \$mb_exit; }
fi
mc anonymous set public minio/lobe-chat
"
# 5. 检查并添加 S3 配置
if [ ! -f .env.desktop ]; then
echo "Creating .env.desktop from .env.example..."
cp .env.example .env.desktop
fi
if ! grep -q "S3_ACCESS_KEY_ID" .env.desktop 2>/dev/null; then
echo ""
echo "Adding S3 configuration to .env.desktop..."
echo "" >> .env.desktop
echo "# Image Upload Configuration (added by setup-image-dev.sh)" >> .env.desktop
echo "S3_ACCESS_KEY_ID=minioadmin" >> .env.desktop
echo "S3_SECRET_ACCESS_KEY=minioadmin" >> .env.desktop
echo "S3_ENDPOINT=http://localhost:9000" >> .env.desktop
echo "S3_BUCKET=lobe-chat" >> .env.desktop
echo "S3_REGION=us-east-1" >> .env.desktop
echo "S3_PUBLIC_DOMAIN=http://localhost:9000/lobe-chat" >> .env.desktop
echo "S3_ENABLE_PATH_STYLE=1" >> .env.desktop
else
echo "S3 configuration already exists in .env.desktop"
fi
echo ""
echo "✅ Image development environment ready!"
echo ""
echo "Services running:"
echo " - PostgreSQL: postgres://postgres@localhost:5432/postgres (no password)"
echo " - MinIO S3: http://localhost:9000"
echo " - MinIO Console: http://localhost:9001 (minioadmin/minioadmin)"
echo ""
echo "Next step: pnpm dev:desktop"