@lobehub/chat 1.100.0 → 1.100.1

package/.cursor/rules/testing-guide/testing-guide.mdc

@@ -214,6 +214,176 @@ describe('<UserProfile />', () => {
 **修复方法**: 更新了测试文件中的 mock 数据结构，使其与最新的 API 响应格式保持一致。具体修改了 `user.test.ts` 中的 `mockUserData` 对象结构。
 ```
 
+## 🎯 测试编写最佳实践
+
+### Mock 数据策略：追求"低成本的真实性" 📋
+
+**核心原则**: 测试数据应默认追求真实性，只有在引入"高昂的测试成本"时才进行简化。
+
+#### 什么是"高昂的测试成本"？
+
+"高成本"指的是测试中引入了外部依赖，使测试变慢、不稳定或复杂：
+
+- **文件 I/O 操作**：读写硬盘文件
+- **网络请求**：HTTP 调用、数据库连接
+- **系统调用**：获取系统时间、环境变量等
+
+#### ✅ 推荐做法：Mock 依赖，保留真实数据
+
+```typescript
+// ✅ 好的做法：Mock I/O 操作，但使用真实的文件内容格式
+describe('parseContentType', () => {
+  beforeEach(() => {
+    // Mock 文件读取操作（避免真实 I/O）
+    vi.spyOn(fs, 'readFileSync').mockImplementation((path) => {
+      // 但返回真实的文件内容格式
+      if (path.includes('.pdf')) return '%PDF-1.4\n%âãÏÓ'; // 真实 PDF 文件头
+      if (path.includes('.png')) return '\x89PNG\r\n\x1a\n'; // 真实 PNG 文件头
+      return '';
+    });
+  });
+
+  it('should detect PDF content type correctly', () => {
+    const result = parseContentType('/path/to/file.pdf');
+    expect(result).toBe('application/pdf');
+  });
+});
+
+// ❌ 过度简化：使用不真实的数据
+describe('parseContentType', () => {
+  it('should detect PDF content type correctly', () => {
+    // 这种简化数据没有测试价值
+    const result = parseContentType('fake-pdf-content');
+    expect(result).toBe('application/pdf');
+  });
+});
+```
+
+#### 🎯 真实标识符的价值
+
+```typescript
+// ✅ 使用真实的提供商标识符
+it('should parse OpenAI model list correctly', () => {
+  const result = parseModelString('openai', '+gpt-4,+gpt-3.5-turbo');
+  expect(result.add).toHaveLength(2);
+  expect(result.add[0].id).toBe('gpt-4');
+});
+
+// ❌ 使用占位符标识符（价值较低）
+it('should parse model list correctly', () => {
+  const result = parseModelString('test-provider', '+model1,+model2');
+  expect(result.add).toHaveLength(2);
+  // 这种测试对理解真实场景帮助不大
+});
+```
+
+### 错误处理测试：测试"行为"而非"文本" ⚠️
+
+**核心原则**: 测试应该验证程序在错误发生时的行为是可预测的，而不是验证易变的错误信息文本。
+
+#### ✅ 推荐的错误测试方式
+
+```typescript
+// ✅ 测试是否抛出错误
+it('should throw error when invalid input provided', () => {
+  expect(() => processInput(null)).toThrow();
+});
+
+// ✅ 测试错误类型（最推荐）
+it('should throw ValidationError for invalid data', () => {
+  expect(() => validateUser({})).toThrow(ValidationError);
+});
+
+// ✅ 测试错误属性而非消息文本
+it('should throw error with correct error code', () => {
+  expect(() => processPayment({})).toThrow(
+    expect.objectContaining({
+      code: 'INVALID_PAYMENT_DATA',
+      statusCode: 400,
+    }),
+  );
+});
+```
+
+#### ❌ 应避免的做法
+
+```typescript
+// ❌ 过度依赖具体错误信息文本
+it('should throw specific error message', () => {
+  expect(() => processUser({})).toThrow('用户数据不能为空，请检查输入参数');
+  // 这种测试很脆弱，错误文案稍有修改就会失败
+});
+```
+
+#### 🎯 例外情况：何时可以测试错误信息
+
+```typescript
+// ✅ 测试标准 API 错误（这是契约的一部分）
+it('should return proper HTTP error for API', () => {
+  expect(response.statusCode).toBe(400);
+  expect(response.error).toBe('Bad Request');
+});
+
+// ✅ 测试错误信息的关键部分（使用正则）
+it('should include field name in validation error', () => {
+  expect(() => validateField('email', '')).toThrow(/email/i);
+});
+```
+
+### 疑难解答：警惕模块污染 🚨
+
+**识别信号**: 当你的测试出现以下"灵异"现象时，优先怀疑模块污染：
+
+- 单独运行某个测试通过，但和其他测试一起运行就失败
+- 测试的执行顺序影响结果
+- Mock 设置看起来正确，但实际使用的是旧的 Mock 版本
+
+#### 典型场景：动态 Mock 同一模块
+
+```typescript
+// ❌ 容易出现模块污染的写法
+describe('ConfigService', () => {
+  it('should work in development mode', async () => {
+    vi.doMock('./config', () => ({ isDev: true }));
+    const { getSettings } = await import('./configService'); // 第一次加载
+    expect(getSettings().debugMode).toBe(true);
+  });
+
+  it('should work in production mode', async () => {
+    vi.doMock('./config', () => ({ isDev: false }));
+    const { getSettings } = await import('./configService'); // 可能使用缓存的旧版本！
+    expect(getSettings().debugMode).toBe(false); // ❌ 可能失败
+  });
+});
+
+// ✅ 使用 resetModules 解决模块污染
+describe('ConfigService', () => {
+  beforeEach(() => {
+    vi.resetModules(); // 清除模块缓存，确保每个测试都是干净的环境
+  });
+
+  it('should work in development mode', async () => {
+    vi.doMock('./config', () => ({ isDev: true }));
+    const { getSettings } = await import('./configService');
+    expect(getSettings().debugMode).toBe(true);
+  });
+
+  it('should work in production mode', async () => {
+    vi.doMock('./config', () => ({ isDev: false }));
+    const { getSettings } = await import('./configService');
+    expect(getSettings().debugMode).toBe(false); // ✅ 测试通过
+  });
+});
+```
+
+#### 🔧 排查和解决步骤
+
+1. **识别问题**: 测试失败时，首先问自己："是否有多个测试在 Mock 同一个模块？"
+2. **添加隔离**: 在 `beforeEach` 中添加 `vi.resetModules()`
+3. **验证修复**: 重新运行测试，确认问题解决
+
+**记住**: `vi.resetModules()` 是解决测试"灵异"失败的终极武器，当常规调试方法都无效时，它往往能一针见血地解决问题。
+
 ## 📂 测试文件组织
 
 ### 文件命名约定
@@ -320,4 +490,7 @@ git show HEAD -- path/to/component.ts | cat # 查看最新提交的修改
 - **修复原则**: 失败1-2次后寻求帮助，测试命名关注行为而非实现细节
 - **调试流程**: 复现 → 分析 → 假设 → 修复 → 验证 → 总结
 - **文件组织**: 优先在现有 `describe` 块中添加测试，避免创建冗余顶级块
+- **数据策略**: 默认追求真实性，只有高成本（I/O、网络等）时才简化
+- **错误测试**: 测试错误类型和行为，避免依赖具体的错误信息文本
+- **模块污染**: 测试"灵异"失败时，优先怀疑模块污染，使用 `vi.resetModules()` 解决
 - **安全要求**: Model 测试必须包含权限检查，并在双环境下验证通过

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 # Changelog
 
+### [Version 1.100.1](https://github.com/lobehub/lobe-chat/compare/v1.100.0...v1.100.1)
+
+<sup>Released on **2025-07-17**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: Use server env config image models.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: Use server env config image models, closes [#8478](https://github.com/lobehub/lobe-chat/issues/8478) ([768ee2b](https://github.com/lobehub/lobe-chat/commit/768ee2b))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ## [Version 1.100.0](https://github.com/lobehub/lobe-chat/compare/v1.99.6...v1.100.0)
 
 <sup>Released on **2025-07-17**</sup>

package/changelog/v1.json

@@ -1,4 +1,13 @@
 [
+  {
+    "children": {
+      "fixes": [
+        "Use server env config image models."
+      ]
+    },
+    "date": "2025-07-17",
+    "version": "1.100.1"
+  },
   {
     "children": {
       "features": [

package/docs/self-hosting/environment-variables/model-provider.mdx

@@ -625,4 +625,29 @@ If you need to use Azure OpenAI to provide model services, you can refer to the
 - Default: `-`
 - Example: `-all,+qwq-32b,+deepseek-r1`
 
+## FAL
+
+### `ENABLED_FAL`
+
+- Type: Optional
+- Description: Enables FAL as a model provider by default. Set to `0` to disable the FAL service.
+- Default: `1`
+- Example: `0`
+
+### `FAL_API_KEY`
+
+- Type: Required
+- Description: This is the API key you applied for in the FAL service.
+- Default: -
+- Example: `fal-xxxxxx...xxxxxx`
+
+### `FAL_MODEL_LIST`
+
+- Type: Optional
+- Description: Used to control the FAL model list. Use `+` to add a model, `-` to hide a model, and `model_name=display_name` to customize the display name of a model. Separate multiple entries with commas. The definition syntax follows the same rules as other providers' model lists.
+- Default: `-`
+- Example: `-all,+fal-model-1,+fal-model-2=fal-special`
+
+The above example disables all models first, then enables `fal-model-1` and `fal-model-2` (displayed as `fal-special`).
+
 [model-list]: /docs/self-hosting/advanced/model-list

package/docs/self-hosting/environment-variables/model-provider.zh-CN.mdx

@@ -624,4 +624,29 @@ LobeChat 在部署时提供了丰富的模型服务商相关的环境变量，
 - 默认值：`-`
 - 示例：`-all,+qwq-32b,+deepseek-r1`
 
+## FAL
+
+### `ENABLED_FAL`
+
+- 类型：可选
+- 描述：默认启用 FAL 作为模型供应商，当设为 0 时关闭 FAL 服务
+- 默认值：`1`
+- 示例：`0`
+
+### `FAL_API_KEY`
+
+- 类型：必选
+- 描述：这是你在 FAL 服务中申请的 API 密钥
+- 默认值：-
+- 示例：`fal-xxxxxx...xxxxxx`
+
+### `FAL_MODEL_LIST`
+
+- 类型：可选
+- 描述：用来控制 FAL 模型列表，使用 `+` 增加一个模型，使用 `-` 来隐藏一个模型，使用 `模型名=展示名` 来自定义模型的展示名，用英文逗号隔开。模型定义语法规则与其他 provider 保持一致。
+- 默认值：`-`
+- 示例：`-all,+fal-model-1,+fal-model-2=fal-special`
+
+上述示例表示先禁用所有模型，再启用 `fal-model-1` 和 `fal-model-2`（显示名为 `fal-special`）。
+
 [model-list]: /zh/docs/self-hosting/advanced/model-list

package/docs/self-hosting/faq/vercel-ai-image-timeout.mdx

@@ -0,0 +1,65 @@
+---
+title: Resolving AI Image Generation Timeout on Vercel
+description: >-
+  Learn how to resolve timeout issues when using AI image generation models like gpt-image-1 on Vercel by enabling Fluid Compute for extended execution time.
+
+tags:
+  - Vercel
+  - AI Image Generation
+  - Timeout
+  - Fluid Compute
+  - gpt-image-1
+---
+
+# Resolving AI Image Generation Timeout on Vercel
+
+## Problem Description
+
+When using AI image generation models (such as `gpt-image-1`) on Vercel, you may encounter timeout errors. This occurs because AI image generation typically requires more than 1 minute to complete, which exceeds Vercel's default function execution time limit.
+
+Common error symptoms include:
+
+- Function timeout errors during image generation
+- Failed image generation requests after approximately 60 seconds
+- "Function execution timed out" messages
+
+### Typical Log Symptoms
+
+In your Vercel function logs, you may see entries like this:
+
+```plaintext
+JUL 16 18:39:09.51 POST 504 /trpc/async/image.createImage
+Provider runtime map found for provider: openai
+```
+
+The key indicators are:
+
+- **Status Code**: `504` (Gateway Timeout)
+- **Endpoint**: `/trpc/async/image.createImage` or similar image generation endpoints
+- **Timing**: Usually occurs around 60 seconds after the request starts
+
+## Solution: Enable Fluid Compute
+
+For projects created before Vercel's dashboard update, you can resolve this issue by enabling Fluid Compute, which extends the maximum execution duration to 300 seconds.
+
+### Steps to Enable Fluid Compute (Legacy Vercel Dashboard)
+
+1. Go to your project dashboard on Vercel
+2. Navigate to the **Settings** tab
+3. Find the **Functions** section
+4. Enable **Fluid Compute** as shown in the screenshot below:
+
+![Enable Fluid Compute](https://hub-apac-1.lobeobjects.space/docs/2e2ff332c4b440b584efe1d7ba46aed5.png)
+
+5. After enabling, the maximum execution duration will be extended to 300 seconds by default
+
+### Important Notes
+
+- **For new projects**: Newer Vercel projects have Fluid Compute enabled by default, so this issue primarily affects legacy projects
+
+## Additional Resources
+
+For more information about Vercel's function limitations and Fluid Compute:
+
+- [Vercel Fluid Compute Documentation](https://vercel.com/docs/fluid-compute)
+- [Vercel Functions Limitations](https://vercel.com/docs/functions/limitations#max-duration)

package/docs/self-hosting/faq/vercel-ai-image-timeout.zh-CN.mdx

@@ -0,0 +1,63 @@
+---
+title: 解决 Vercel 上 AI 绘画生图超时问题
+description: 了解如何通过开启 Fluid Compute 来解决在 Vercel 上使用 gpt-image-1 等 AI 绘画模型时遇到的超时问题。
+tags:
+  - Vercel
+  - AI 绘画
+  - 超时问题
+  - Fluid Compute
+  - gpt-image-1
+---
+
+# 解决 Vercel 上 AI 绘画生图超时问题
+
+## 问题描述
+
+在 Vercel 上使用 AI 绘画模型（如 `gpt-image-1`）时，您可能会遇到超时错误。这是因为 AI 绘画生成通常需要超过 1 分钟的时间，超出了 Vercel 默认的函数执行时间限制。
+
+常见的错误症状包括：
+
+- 图像生成过程中出现函数超时错误
+- 图像生成请求在大约 60 秒后失败
+- 出现 "函数执行超时" 的错误消息
+
+### 典型的日志现象
+
+在您的 Vercel 函数日志中，您可能会看到类似这样的条目：
+
+```plaintext
+JUL 16 18:39:09.51 POST 504 /trpc/async/image.createImage
+Provider runtime map found for provider: openai
+```
+
+关键指标包括：
+
+- **状态码**: `504`（网关超时）
+- **端点**: `/trpc/async/image.createImage` 或类似的图像生成端点
+- **时间**: 通常在请求开始后约 60 秒出现
+
+## 解决方案：开启 Fluid Compute
+
+对于在 Vercel 控制台更新前创建的项目，您可以通过开启 Fluid Compute 来解决此问题，这将最大执行时长延长至 300 秒。
+
+### 开启 Fluid Compute 的步骤（旧版 Vercel 控制台）
+
+1. 前往您在 Vercel 上的项目控制台
+2. 进入 **Settings**（设置）选项卡
+3. 找到 **Functions**（函数）部分
+4. 按照下方截图所示开启 **Fluid Compute**：
+
+![开启 Fluid Compute](https://hub-apac-1.lobeobjects.space/docs/2e2ff332c4b440b584efe1d7ba46aed5.png)
+
+5. 开启后，最大执行时长将默认延长至 300 秒
+
+### 重要说明
+
+- **新项目**：较新的 Vercel 项目默认已启用 Fluid Compute，因此此问题主要影响旧版项目
+
+## 其他资源
+
+有关 Vercel 函数限制和 Fluid Compute 的更多信息：
+
+- [Vercel Fluid Compute 文档](https://vercel.com/docs/fluid-compute)
+- [Vercel 函数限制说明](https://vercel.com/docs/functions/limitations#max-duration)

package/docs/usage/providers/fal.mdx

@@ -13,7 +13,7 @@ tags:
 
 # Using Fal in LobeChat
 
-<Image alt={'Using Fal in LobeChat'} cover src={'https://github.com/user-attachments/assets/febb2ffb-8fe8-4f88-b8c9-8fa0985a2352'} />
+<Image alt={'Using Fal in LobeChat'} cover src={'https://hub-apac-1.lobeobjects.space/docs/f253e749baaa2ccac498014178f93091.png'} />
 
 [Fal.ai](https://fal.ai/) is a lightning-fast inference platform specialized in AI media generation, hosting state-of-the-art models for image and video creation including FLUX, Kling, HiDream, and other cutting-edge generative models. This document will guide you on how to use Fal in LobeChat:
 
@@ -28,7 +28,7 @@ tags:
     alt={'Open the creation window'}
     inStep
     src={
-'https://github.com/user-attachments/assets/a2203b3a-1657-485a-a060-b018e7b2faaa'
+'https://hub-apac-1.lobeobjects.space/docs/3f3676e7f9c04a55603bc1174b636b45.png'
 }
   />
 
@@ -36,7 +36,7 @@ tags:
     alt={'Create API Key'}
     inStep
     src={
-'https://github.com/user-attachments/assets/a216e326-6a51-4f3a-b8c1-23bb995ddac2'
+'https://hub-apac-1.lobeobjects.space/docs/214cc5019d9c0810951b33215349136e.png'
 }
   />
 
@@ -44,7 +44,7 @@ tags:
     alt={'Retrieve API Key'}
     inStep
     src={
-'https://github.com/user-attachments/assets/faee998d-4349-4c17-a5c4-07a7ff65f18e'
+'https://hub-apac-1.lobeobjects.space/docs/499a447e98dcc79407d56495d0305e2a.png'
 }
   />
 
@@ -53,12 +53,12 @@ tags:
   - Visit the `Settings` page in LobeChat.
   - Under **AI Service Provider**, locate the **Fal** configuration section.
 
-  <Image alt={'Enter API Key'} inStep src={'https://github.com/user-attachments/assets/7566f679-f935-4a5b-9c98-a8d99d9c7994'} />
+  <Image alt={'Enter API Key'} inStep src={'https://hub-apac-1.lobeobjects.space/docs/fa056feecba0133c76abe1ad12706c05.png'} />
 
   - Paste the API key you obtained.
   - Choose a Fal model (e.g. `fal-ai/flux-pro`, `fal-ai/kling-video`, `fal-ai/hidream-i1-fast`) for image or video generation.
 
-  <Image alt={'Select Fal model for media generation'} inStep src={'https://github.com/user-attachments/assets/817167ff-4723-4f84-8528-c779c5c3a118'} />
+  <Image alt={'Select Fal model for media generation'} inStep src={'https://hub-apac-1.lobeobjects.space/docs/7560502f31b8500032922103fc22e69b.png'} />
 
   <Callout type={'warning'}>
     During usage, you may incur charges according to Fal's pricing policy. Please review Fal's

package/docs/usage/providers/fal.zh-CN.mdx

@@ -13,7 +13,7 @@ tags:
 
 # 在 LobeChat 中使用 Fal
 
-<Image alt={'在 LobeChat 中使用 Fal'} cover src={'https://github.com/user-attachments/assets/febb2ffb-8fe8-4f88-b8c9-8fa0985a2352'} />
+<Image alt={'在 LobeChat 中使用 Fal'} cover src={'https://hub-apac-1.lobeobjects.space/docs/f253e749baaa2ccac498014178f93091.png'} />
 
 [Fal.ai](https://fal.ai/) 是一个专门从事 AI 媒体生成的快速推理平台，提供包括 FLUX、Kling、HiDream 等在内的最先进图像和视频生成模型。本文将指导你如何在 LobeChat 中使用 Fal：
 
@@ -28,7 +28,7 @@ tags:
     alt={'打开创建窗口'}
     inStep
     src={
-'https://github.com/user-attachments/assets/a2203b3a-1657-485a-a060-b018e7b2faaa'
+'https://hub-apac-1.lobeobjects.space/docs/3f3676e7f9c04a55603bc1174b636b45.png'
 }
   />
 
@@ -36,7 +36,7 @@ tags:
     alt={'创建 API Key'}
     inStep
     src={
-'https://github.com/user-attachments/assets/a216e326-6a51-4f3a-b8c1-23bb995ddac2'
+'https://hub-apac-1.lobeobjects.space/docs/214cc5019d9c0810951b33215349136e.png'
 }
   />
 
@@ -44,7 +44,7 @@ tags:
     alt={'获取 API Key'}
     inStep
     src={
-'https://github.com/user-attachments/assets/faee998d-4349-4c17-a5c4-07a7ff65f18e'
+'https://hub-apac-1.lobeobjects.space/docs/499a447e98dcc79407d56495d0305e2a.png'
 }
   />
 
@@ -53,12 +53,12 @@ tags:
   - 访问 LobeChat 的 `设置` 页面；
   - 在 `AI服务商` 下找到 `Fal` 的设置项；
 
-  <Image alt={'填入 API 密钥'} inStep src={'https://github.com/user-attachments/assets/7566f679-f935-4a5b-9c98-a8d99d9c7994'} />
+  <Image alt={'填入 API 密钥'} inStep src={'https://hub-apac-1.lobeobjects.space/docs/fa056feecba0133c76abe1ad12706c05.png'} />
 
   - 粘贴获取到的 API Key；
   - 选择一个 Fal 模型（如 `fal-ai/flux-pro`、`fal-ai/kling-video`、`fal-ai/hidream-i1-fast`）用于图像或视频生成。
 
-  <Image alt={'选择 Fal 模型进行媒体生成'} inStep src={'https://github.com/user-attachments/assets/817167ff-4723-4f84-8528-c779c5c3a118'} />
+  <Image alt={'选择 Fal 模型进行媒体生成'} inStep src={'https://hub-apac-1.lobeobjects.space/docs/7560502f31b8500032922103fc22e69b.png'} />
 
   <Callout type={'warning'}>
     在使用过程中，你可能需要向 Fal 支付相应费用，请在大量调用前查阅 Fal 的官方计费政策。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/chat",
-  "version": "1.100.0",
+  "version": "1.100.1",
   "description": "Lobe Chat - an open-source, high-performance chatbot framework that supports speech synthesis, multimodal, and extensible Function Call plugin system. Supports one-click free deployment of your private ChatGPT/LLM web application.",
   "keywords": [
     "framework",

package/src/libs/model-runtime/utils/openaiCompatibleFactory/index.test.ts

@@ -1392,7 +1392,7 @@ describe('LobeOpenAICompatibleFactory', () => {
         {
           id: 'gemini',
           releasedAt: '2025-01-10',
-          type: undefined,
+          type: 'chat',
         },
       ]);
     });

package/src/libs/model-runtime/utils/openaiCompatibleFactory/index.ts

@@ -7,6 +7,7 @@ import { Stream } from 'openai/streaming';
 import { LOBE_DEFAULT_MODEL_LIST } from '@/config/aiModels';
 import { RuntimeImageGenParamsValue } from '@/libs/standard-parameters/meta-schema';
 import type { ChatModelCard } from '@/types/llm';
+import { getModelPropertyWithFallback } from '@/utils/getFallbackModelProperty';
 
 import { LobeRuntimeAI } from '../../BaseAI';
 import { AgentRuntimeErrorType, ILobeAgentRuntimeErrorType } from '../../error';
@@ -462,7 +463,7 @@ export const createOpenAICompatibleRuntime = <T extends Record<string, any> = an
       return resultModels.map((model) => {
         return {
           ...model,
-          type: model.type || LOBE_DEFAULT_MODEL_LIST.find((m) => m.id === model.id)?.type,
+          type: model.type || getModelPropertyWithFallback(model.id, 'type'),
         };
       }) as ChatModelCard[];
     }