@lobehub/lobehub 2.1.10 → 2.1.12

package/.github/actions/desktop-build-setup/action.yml

@@ -24,6 +24,17 @@ runs:
       shell: bash
       run: pnpm install --node-linker=hoisted
 
+    # 移除国内 electron 镜像配置，GitHub Actions 使用官方源更快
+    - name: Remove China electron mirror from .npmrc
+      shell: bash
+      run: |
+        NPMRC_FILE="./apps/desktop/.npmrc"
+        if [ -f "$NPMRC_FILE" ]; then
+          sed -i.bak '/^electron_mirror=/d; /^electron_builder_binaries_mirror=/d' "$NPMRC_FILE"
+          rm -f "${NPMRC_FILE}.bak"
+          echo "✅ Removed electron mirror config from .npmrc"
+        fi
+
     - name: Install deps on Desktop
       shell: bash
       run: npm run install-isolated --prefix=./apps/desktop

package/.github/workflows/claude-migration-support.yml

@@ -70,12 +70,12 @@ jobs:
             ```
 
             2. Read the latest migration documentation based on the issue:
-            - If issue #11757 (NextAuth): `cat docs/self-hosting/advanced/auth/nextauth-to-betterauth.mdx`
-            - If issue #11707 (Clerk): `cat docs/self-hosting/advanced/auth/clerk-to-betterauth.mdx`
+            - If issue #11757 (NextAuth): `cat docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.mdx`
+            - If issue #11707 (Clerk): `cat docs/self-hosting/migration/v2/auth/clerk-to-betterauth.mdx`
 
             3. Read additional reference files:
-            - Main auth documentation: `cat docs/self-hosting/advanced/auth.mdx`
-            - Migration internals: `cat docs/self-hosting/advanced/auth/migration-internals.mdx`
+            - Main auth documentation: `cat docs/self-hosting/auth.mdx`
+            - Migration internals: `cat docs/self-hosting/migration/v2/auth/migration-internals.mdx`
             - Deprecated env vars checker: `cat scripts/_shared/checkDeprecatedAuth.js`
 
             4. Analyze the user's comment and determine:

package/.github/workflows/pr-build-desktop.yml

@@ -109,6 +109,17 @@ jobs:
       - name: Install dependencies
         run: pnpm install --node-linker=hoisted
 
+      # 移除国内 electron 镜像配置，GitHub Actions 使用官方源更快
+      - name: Remove China electron mirror from .npmrc
+        shell: bash
+        run: |
+          NPMRC_FILE="./apps/desktop/.npmrc"
+          if [ -f "$NPMRC_FILE" ]; then
+            sed -i.bak '/^electron_mirror=/d; /^electron_builder_binaries_mirror=/d' "$NPMRC_FILE"
+            rm -f "${NPMRC_FILE}.bak"
+            echo "✅ Removed electron mirror config from .npmrc"
+          fi
+
       - name: Install deps on Desktop
         run: npm run install-isolated --prefix=./apps/desktop
 

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 # Changelog
 
+### [Version 2.1.12](https://github.com/lobehub/lobe-chat/compare/v2.1.11...v2.1.12)
+
+<sup>Released on **2026-02-03**</sup>
+
+#### 🐛 Bug Fixes
+
+- **changelog**: Normalize versionRange to valid semver.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **changelog**: Normalize versionRange to valid semver, closes [#12049](https://github.com/lobehub/lobe-chat/issues/12049) ([74b9bd0](https://github.com/lobehub/lobe-chat/commit/74b9bd0))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.11](https://github.com/lobehub/lobe-chat/compare/v2.1.10...v2.1.11)
+
+<sup>Released on **2026-02-02**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Hide password features when AUTH_DISABLE_EMAIL_PASSWORD is set.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Hide password features when AUTH_DISABLE_EMAIL_PASSWORD is set, closes [#12023](https://github.com/lobehub/lobe-chat/issues/12023) ([e2fd28e](https://github.com/lobehub/lobe-chat/commit/e2fd28e))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 2.1.10](https://github.com/lobehub/lobe-chat/compare/v2.1.9...v2.1.10)
 
 <sup>Released on **2026-02-02**</sup>

package/changelog/v2.json

@@ -1,4 +1,18 @@
 [
+  {
+    "children": {},
+    "date": "2026-02-03",
+    "version": "2.1.12"
+  },
+  {
+    "children": {
+      "fixes": [
+        "Hide password features when AUTH_DISABLE_EMAIL_PASSWORD is set."
+      ]
+    },
+    "date": "2026-02-02",
+    "version": "2.1.11"
+  },
   {
     "children": {},
     "date": "2026-02-02",

package/docker-compose/local/zitadel/.env.example

@@ -12,7 +12,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/lobechat
 AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg
 AUTH_SSO_PROVIDERS=zitadel
 # ZiTADEL provider configuration
-# Please refer to：https://lobehub.com/zh/docs/self-hosting/advanced/auth/providers/zitadel
+# Please refer to: https://lobehub.com/docs/self-hosting/auth/providers/zitadel
 AUTH_ZITADEL_ID=285945938244075523
 AUTH_ZITADEL_SECRET=hkbtzHLaCEIeHeFThym14UcydpmQiEB5JtAX08HSqSoJxhAlVVkyovTuNUZ5TNrT
 AUTH_ZITADEL_ISSUER=http://localhost:8080

package/docker-compose/local/zitadel/.env.zh-CN.example

@@ -11,7 +11,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/lobechat
 AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg
 AUTH_SSO_PROVIDERS=zitadel
 # ZiTADEL 鉴权服务提供商部分
-# 请参考：https://lobehub.com/zh/docs/self-hosting/advanced/auth/next-auth/zitadel
+# 请参考：https://lobehub.com/zh/docs/self-hosting/auth/providers/zitadel
 AUTH_ZITADEL_ID=285945938244075523
 AUTH_ZITADEL_SECRET=hkbtzHLaCEIeHeFThym14UcydpmQiEB5JtAX08HSqSoJxhAlVVkyovTuNUZ5TNrT
 AUTH_ZITADEL_ISSUER=http://localhost:8080

package/docker-compose/production/logto/.env.example

@@ -12,7 +12,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/lobe
 
 # Authentication related environment variables
 # Supports Auth0, Azure AD, GitHub, Authentik, Zitadel, Logto, etc.
-# For supported providers, see: https://lobehub.com/docs/self-hosting/advanced/auth
+# For supported providers, see: https://lobehub.com/docs/self-hosting/auth
 # If you have ACCESS_CODE, please remove it. We use Better Auth as the sole authentication source
 # Required: Auth secret key. Generate with: openssl rand -base64 32
 AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg

package/docker-compose/production/logto/.env.zh-CN.example

@@ -11,7 +11,7 @@ DATABASE_URL=postgresql://postgres:uWNZugjBqixf8dxC@postgresql:5432/lobe
 
 # 鉴权服务必需的环境变量
 # 可以使用 Auth0、Azure AD、GitHub、Authentik、Zitadel、Logto 等，如有其他接入诉求欢迎提 PR
-# 目前支持的鉴权服务提供商请参考：https://lobehub.com/zh/docs/self-hosting/advanced/auth
+# 目前支持的鉴权服务提供商请参考：https://lobehub.com/zh/docs/self-hosting/auth
 # 如果你有 ACCESS_CODE，请务必清空，我们以 Better Auth 作为唯一鉴权来源
 # 必填，用于鉴权的密钥，可以使用 openssl rand -base64 32 生成
 AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg

package/docker-compose/production/zitadel/.env.example

@@ -17,7 +17,7 @@ AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg
 AUTH_SSO_PROVIDERS=zitadel
 
 # ZiTADEL provider configuration
-# Please refer to：https://lobehub.com/zh/docs/self-hosting/advanced/auth/providers/zitadel
+# Please refer to: https://lobehub.com/docs/self-hosting/auth/providers/zitadel
 AUTH_ZITADEL_ID=285934220675723622
 AUTH_ZITADEL_SECRET=pe7Nh3lopXkZkfqh5YEDYI2xsbIz08eZKqInOUZxssd3refRia518Apbv3DZ
 AUTH_ZITADEL_ISSUER=https://zitadel.example.com

package/docker-compose/production/zitadel/.env.zh-CN.example

@@ -16,7 +16,7 @@ AUTH_SECRET=NX2kaPE923dt6BL2U8e9oSre5RfoT7hg
 AUTH_SSO_PROVIDERS=zitadel
 
 # ZiTADEL 鉴权服务提供商部分
-# 请参考：https://lobehub.com/zh/docs/self-hosting/advanced/auth/next-auth/zitadel
+# 请参考：https://lobehub.com/zh/docs/self-hosting/auth/providers/zitadel
 AUTH_ZITADEL_ID=285934220675723622
 AUTH_ZITADEL_SECRET=pe7Nh3lopXkZkfqh5YEDYI2xsbIz08eZKqInOUZxssd3refRia518Apbv3DZ
 AUTH_ZITADEL_ISSUER=https://zitadel.example.com

package/docs/changelog/index.json

@@ -6,7 +6,7 @@
       "image": "/blog/assets7f3b38c1d76cceb91edb29d6b1eb60db.webp",
       "id": "2025-12-20-mcp",
       "date": "2025-12-20",
-      "versionRange": ["1.142.8", "1.143"]
+      "versionRange": ["1.142.8", "1.143.0"]
     },
     {
       "image": "/blog/assets3a7f0b29839603336e39e923b423409b.webp",

package/docs/development/basic/add-new-authentication-providers.mdx

@@ -114,7 +114,7 @@ AUTH_OKTA_ISSUER: process.env.AUTH_OKTA_ISSUER,
 
 ### Step 4: Update Documentation (Optional)
 
-Add provider documentation in `docs/self-hosting/advanced/auth.mdx` and `docs/self-hosting/advanced/auth.zh-CN.mdx`.
+Add provider documentation in `docs/self-hosting/auth.mdx` and `docs/self-hosting/auth.zh-CN.mdx`.
 
 ## Adding a Built-in Provider
 

package/docs/development/basic/add-new-authentication-providers.zh-CN.mdx

@@ -115,7 +115,7 @@ AUTH_OKTA_ISSUER: process.env.AUTH_OKTA_ISSUER,
 
 ### 步骤 4: 更新文档（可选）
 
-在 `docs/self-hosting/advanced/auth.mdx` 和 `docs/self-hosting/advanced/auth.zh-CN.mdx` 中添加提供商文档。
+在 `docs/self-hosting/auth.mdx` 和 `docs/self-hosting/auth.zh-CN.mdx` 中添加提供商文档。
 
 ## 添加内置提供商
 

package/docs/development/basic/setup-development.mdx

@@ -10,7 +10,8 @@ tags:
   - PNPM
   - Bun
   - Git
-  - VSCode
+  - Docker
+  - PostgreSQL
 ---
 
 # Environment Setup Guide
@@ -35,6 +36,7 @@ First, you need to install the following software:
 - PNPM: We use PNPM as the preferred package manager. You can download and install it from the [PNPM official website](https://pnpm.io/installation).
 - Bun: We use Bun as the npm scripts runner. You can download and install it from the [Bun official website](https://bun.com/docs/installation).
 - Git: We use Git for version control. You can download and install it from the Git official website.
+- Docker: Required for running PostgreSQL, MinIO, and other services. You can download and install it from the [Docker official website](https://www.docker.com/get-started).
 - IDE: You can choose your preferred integrated development environment (IDE). We recommend using WebStorm/VSCode.
 
 ### VSCode Users
@@ -45,20 +47,72 @@ We recommend installing the extensions listed in [.vscode/extensions.json](https
 
 After installing the above software, you can start setting up the LobeHub project.
 
-1. **Get the code**: First, you need to clone the LobeHub codebase from GitHub. Run the following command in the terminal:
+#### 1. Get the Code
+
+First, you need to clone the LobeHub codebase from GitHub. Run the following command in the terminal:
 
 ```bash
 git clone https://github.com/lobehub/lobehub.git
+cd lobehub
 ```
 
-2. **Install dependencies**: Then, navigate to the project directory and use PNPM to install the project's dependencies:
+#### 2. Install Dependencies
+
+Use PNPM to install the project's dependencies:
 
 ```bash
-cd lobehub
 pnpm i
 ```
 
-3. **Start the development server**: After installing the dependencies, you can start the development server:
+#### 3. Configure Environment
+
+Copy the example environment file to create your Docker Compose configuration:
+
+```bash
+cp docker-compose/local/.env.example docker-compose/local/.env
+```
+
+Edit `docker-compose/local/.env` as needed for your development setup. This file contains all necessary environment variables for the Docker services and configures:
+
+- **Database**: PostgreSQL with connection string
+- **Authentication**: Better Auth with Casdoor SSO
+- **Storage**: MinIO S3-compatible storage
+- **Search**: SearXNG search engine
+
+#### 4. Start Docker Services
+
+Start all required services using Docker Compose:
+
+```bash
+docker-compose -f docker-compose.development.yml up -d
+```
+
+This will start the following services:
+
+- PostgreSQL database (port 5432)
+- MinIO storage (port 9000)
+- Casdoor authentication (port 8000)
+- SearXNG search (port 8080)
+
+You can check all Docker services are running by running:
+
+```bash
+docker-compose -f docker-compose.development.yml ps
+```
+
+#### 5. Run Database Migrations
+
+Execute the database migration script to create all necessary tables:
+
+```bash
+pnpm db:migrate
+```
+
+You should see: `✅ database migration pass.`
+
+#### 6. Start Development Server
+
+Launch the LobeHub development server:
 
 ```bash
 bun run dev
@@ -68,17 +122,125 @@ 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
+## 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 `docker-compose/local/.env.example`. No additional setup is required.
+
+### Image Generation Architecture
 
-The basic setup above uses LobeHub's client-side database mode. If you need to work with server-side features such as:
+The image generation feature requires:
 
-- Database persistence
-- File uploads and storage
-- Image generation
-- Multi-user authentication
-- Advanced server-side integrations
+- **PostgreSQL**: Stores metadata about generated images
+- **MinIO/S3**: Stores the actual image files
 
-Please refer to the [Work with Server-Side Database](/docs/development/basic/work-with-server-side-database) guide for complete setup instructions.
+### Storage Configuration
+
+The `docker-compose/local/.env.example` 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_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/LobeHub`
+- **MinIO API**: `http://localhost:9000`
+- **MinIO Console**: `http://localhost:9001` (admin/CHANGE\_THIS\_PASSWORD\_IN\_PRODUCTION)
+- **Application**: `http://localhost:3010`
+
+## Troubleshooting
+
+### Reset Services
+
+If you encounter issues, you can reset the entire stack:
+
+```bash
+# Stop and remove all containers
+docker-compose -f docker-compose.development.yml down
+
+# Remove volumes (this will delete all data)
+docker-compose -f docker-compose.development.yml down -v
+
+# Start fresh
+docker-compose -f docker-compose.development.yml up -d
+pnpm db:migrate
+```
+
+### 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.
+
+---
 
 During the development process, if you encounter any issues with environment setup or have any questions about LobeHub development, feel free to ask us at any time. We look forward to seeing your contributions!
 

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

@@ -7,6 +7,8 @@ tags:
   - Node.js
   - PNPM
   - Git
+  - Docker
+  - PostgreSQL
 ---
 
 # 环境设置指南
@@ -29,8 +31,9 @@ tags:
 
 - 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) 上下载并安装。
+- 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 用户
@@ -41,20 +44,72 @@ tags:
 
 完成上述软件的安装后，你可以开始设置 LobeHub 项目了。
 
-1. **获取代码**：首先，你需要从 GitHub 上克隆 LobeHub 的代码库。在终端中运行以下命令：
+#### 1. 获取代码
+
+首先，你需要从 GitHub 上克隆 LobeHub 的代码库。在终端中运行以下命令：
 
 ```bash
 git clone https://github.com/lobehub/lobehub.git
+cd lobehub
 ```
 
-2. **安装依赖**：然后，进入项目目录，并使用 `pnpm` 安装项目的依赖包：
+#### 2. 安装依赖
+
+使用 PNPM 安装项目的依赖包：
 
 ```bash
-cd lobehub
 pnpm i
 ```
 
-3. **启动开发服务器**：安装完依赖后，你可以启动开发服务器：
+#### 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
@@ -64,17 +119,125 @@ bun run dev
 
 ![Chat Page](https://hub-apac-1.lobeobjects.space/docs/fc7b157a3bc016bc97719065f80c555c.png)
 
-## 使用服务端功能
+## 图像生成开发
+
+在开发图像生成功能（文生图、图生图）时，Docker Compose 配置已经包含了处理生成图像和用户上传所需的所有存储服务。
+
+### 图像生成配置
+
+现有的 Docker Compose 配置已经包含了 MinIO 存储服务以及 `docker-compose/local/.env.example` 中的所有必要环境变量。无需额外配置。
+
+### 图像生成架构
 
-上述基础设置使用 LobeHub 的客户端数据库模式。如果你需要开发服务端功能，如：
+图像生成功能需要：
 
-- 数据库持久化
-- 文件上传和存储
-- 图像生成
-- 多用户身份验证
-- 高级服务端集成
+- **PostgreSQL**：存储生成图像的元数据
+- **MinIO/S3**：存储实际的图像文件
 
-请参考[使用服务端数据库](/docs/development/basic/work-with-server-side-database)指南获得完整的设置说明。
+### 存储配置
+
+`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 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！