Image-Chat Gateway (img2chat-proxy) 架构设计与全流程部署使用指南

# Image-Chat Gateway (img2chat-proxy) 架构设计与全流程部署使用指南

> **项目仓库**：[https://github.com/cfwasd/image-proxy](https://github.com/cfwasd/image-proxy)  
> **核心定位**：专为 OpenAI 标准生态打造的轻量级 **Image ↔ Chat** 协议互转与云存储/图床转存网关，内置现代化 Web 运维控制台（`/admin`）、细粒度模型路由分流策略以及自动化 CI/CD 多平台编译发布流，无需安装外部运行时依赖。

---

## 目录
- [一、项目背景与核心价值](#一项目背景与核心价值)
- [二、系统架构与技术栈](#二系统架构与技术栈)
- [三、核心亮点：智能模型路由与分流策略](#三核心亮点智能模型路由与分流策略)
  - [3.1 混合模型调度痛点与设计思路](#31-混合模型调度痛点与设计思路)
  - [3.2 三大路由策略模式 (All / Whitelist / Blacklist)](#32-三大路由策略模式-all--whitelist--blacklist)
  - [3.3 通配符模式匹配算法](#33-通配符模式匹配算法)
  - [3.4 原生直通代理与 Base64 自动拦截转存云存储](#34-原生直通代理与-base64-自动拦截转存云存储)
- [四、核心功能与处理管道](#四核心功能与处理管道)
  - [4.1 文生图管道 (POST /v1/images/generations)](#41-文生图管道-post-v1imagesgenerations)
  - [4.2 图生图/改图管道 (POST /v1/images/edits)](#42-图生图改图管道-post-v1imagesedits)
  - [4.3 通用 API 透明代理透传 (ANY /*)](#43-通用-api-透明代理透传-any-)
  - [4.4 多驱动云存储与图床引擎](#44-多驱动云存储与图床引擎)
- [五、生产环境部署与 CI/CD 自动化](#五生产环境部署与-cicd-自动化)
  - [5.1 极简一键部署 (推荐)](#51-极简一键部署-推荐)
  - [5.2 常用 Systemd 运维管理](#52-常用-systemd-运维管理)
  - [5.3 源码构建与多平台编译](#53-源码构建与多平台编译)
  - [5.4 GitHub Actions 自动化 CI/CD 与多平台 Release 发布](#54-github-actions-自动化-cicd-与多平台-release-发布)
- [六、Nginx 生产反向代理与长超时配置](#六nginx-生产反向代理与长超时配置)
- [七、Web 管理控制台指南 (/admin)](#七web-管理控制台指南-admin)
  - [7.1 登录与权限管理](#71-登录与权限管理)
  - [7.2 在线配置热重载（含模型策略）](#72-在线配置热重载含模型策略)
  - [7.3 存储驱动切换与即时联调测试](#73-存储驱动切换与即时联调测试)
  - [7.4 运行日志实时监控面板](#74-运行日志实时监控面板)
- [八、完整配置字典 (config.json & 环境变量)](#八完整配置字典-configjson--环境变量)
- [九、API 接口对接规范与示例](#九api-接口对接规范与示例)
  - [9.1 文生图 (Text-to-Image)](#91-文生图-text-to-image)
  - [9.2 图生图 / 编辑原图 (Image-to-Image / Edits)](#92-图生图--编辑原图-image-to-image--edits)
  - [9.3 健康检查探针](#93-健康检查探针)
- [十、常见问题排查 (FAQ)](#十常见问题排查-faq)

---

## 一、项目背景与核心价值

在当前的大模型与 AI 绘图生态中，多数前端客户端（如 **LobeChat**、**NextChat**、**ChatGPT-Next-Web** 以及各类业务系统）均严格遵循 **OpenAI 标准生图协议**（即 `POST /v1/images/generations` 与 `POST /v1/images/edits`）。

然而在模型供给端存在诸多割裂与异构：
1. **协议异构不统一**：部分顶级生图模型（如 Google 的 `gemini-3.1-flash-image`、`gemini-2.5-flash-image`，以及各类基于多模态大模型生图能力的对话接口）仅提供 `/v1/chat/completions` 对话协议，直接在对话回复中输出图片 Base64 或 `message.images` 数组，无法直接接入标准生图客户端。
2. **混合模型调度困境**：用户的上游聚合渠道（如 One API、New API、CPA 或自建反代）通常同时挂载了原生生图模型（如 `dall-e-3`、`flux-*`、`midjourney`）与需要 Chat 转译的模型。传统网关往往“一刀切”，要么全走转译导致原生模型失败，要么全走透传无法支持 Chat 模型。
3. **传输体积臃肿**：模型生成的图片 Base64 数据量巨大（单图常见几百 KB 至数 MB），反复在对话上下文或网络流中流动会严重消耗带宽并容易引发前端 OOM 崩溃。
4. **公网直链强依赖**：现代客户端普遍要求响应中提供标准的公网直链 `url`，便于 CDN 加速与长期归档，而非庞大的 `b64_json` 字符串。

**Image-Chat Gateway (`img2chat-proxy`)** 正是为彻底打通这一生态断层而设计：
- **无缝转译**：对外暴露完全标准的 OpenAI `/v1/images/*` 接口，底层根据请求模型自动转译为上游大模型 Chat 流。
- **智能分流**：原生支持细粒度模型转发策略（全转译 / 白名单 / 黑名单），支持通配符规则，原生模型直接透明直通上游。
- **原生 Base64 自动拦截转存**：即使上游原生接口返回体积巨大的 `b64_json`，网关亦能自动拦截并上传至图床，自动替换为直链 `url`。
- **自动转存图床**：支持 S3、RustFS、阿里云 OSS、腾讯云 COS、MinIO、通用 HTTP Multipart 图床，自动生成永久公网直链。
- **透明全量透传**：除生图/改图路由外，其余所有 OpenAI 接口（如 `/v1/models`、`/v1/chat/completions` 等）无损原样反代，客户端只需配置一个统一网关 Base URL。
- **零外部依赖**：单二进制独立运行，跨平台静态编译，内存占用低（通常 < 50MB）。

---

## 二、系统架构与技术栈

### 2.1 整体架构拓扑

```
[ 各类 OpenAI 客户端 / 业务前端 ]
 (LobeChat, NextChat, Python SDK 等)
                │
                ▼
      [ Nginx 反向代理层 ] (可选，提供 HTTPS / 域名绑定 / 缓冲优化)
                │
                ▼
┌─────────────────────────────────────────────────────────────┐
│             Image-Chat Gateway (img2chat-proxy)              │
│                                                             │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   /v1/images/* 路由器   │    │  通用路由 ANY /* 透传   │  │
│  └───────────┬────────────┘    └────────────┬────────────┘  │
│              │                              │               │
│              ▼                              │               │
│   ┌───────────────────────┐                 │               │
│   │ 智能模型分流决策引擎   │                 │               │
│   │ (shouldTranslateModel)│                 │               │
│   └───┬───────────────┬───┘                 │               │
│       │ 命中转译      │ 命中直通             │               │
│       ▼               ▼                     │               │
│  ┌─────────┐   ┌────────────────┐           │               │
│  │ Chat    │   │ 上游原生       │           │               │
│  │ 提示词  │   │ /v1/images/*   │           │               │
│  │ 翻译转译│   └──────┬─────────┘           │               │
│  └────┬────┘          │                     │               │
│       │               ▼                     │               │
│       │        (检测到 b64_json)            │               │
│       │               │                     │               │
│       ▼               ▼                     │               │
│  ┌────────────────────────────────┐         │               │
│  │  通用图片 Base64 提取与清洗     │         │               │
│  └────────────────┬───────────────┘         │               │
│                   │                         │               │
│                   ▼                         │               │
│  ┌────────────────────────────────┐         │               │
│  │     统一多存储驱动抽象引擎     │         │               │
│  │  (S3 / RustFS / OSS / 图床)    │         │               │
│  └────────────────┬───────────────┘         │               │
│                   │                         │               │
└───────────────────┼─────────────────────────┼───────────────┘
                    │                         │
                    ▼                         ▼
         [ 云存储 / 对象存储桶 ]     [ 上游 API 服务端 / CPA / LLM ]
         (生成永久公网访问 URL)     (/v1/chat/completions 或 原生生图)
```

### 2.2 关键技术选型
- **运行底座**：基于 **Bun** 构建，原生高性能 TypeScript 运行时，零外部 Node.js 环境依赖，启动速度达毫秒级。
- **存储 SDK**：深度集成 `@aws-sdk/client-s3`，全面兼容标准 AWS S3、RustFS、阿里云 OSS、腾讯云 COS、MinIO、Cloudflare R2 等。
- **控制台架构**：轻量级单页 Web 控制台（`/admin`），原生 HTML5/Tailwind/ES6 构建，无需构建打包步骤，直接内嵌静态交付。

---

## 三、核心亮点：智能模型路由与分流策略

### 3.1 混合模型调度痛点与设计思路
在复杂的 AI 服务链路中，用户的同一上游渠道可能既聚合了原生生图大模型，又挂载了对话式多模态大模型。
如果所有请求都强制转译为 `/v1/chat/completions`，原生模型（如 `dall-e-3`）将因无法理解自定义 Chat 系统提示词而报错；若不转译，则 `gemini-3.1-flash-image` 等模型完全无法使用。

网关在最新版本中引入了**细粒度模型路由分流策略**（`ModelPolicyConfig`），在请求入口处实时拦截并解析模型标识，执行智能决策：

```typescript
export interface ModelPolicyConfig {
  mode: "all" | "whitelist" | "blacklist";
  models: string[];
  autoUploadNativeB64: boolean;
}
```

### 3.2 三大路由策略模式 (All / Whitelist / Blacklist)

| 策略模式 (`mode`) | 工作原理 | 适用典型场景 |
| :--- | :--- | :--- |
| **`all` (全转译模式)** | **默认模式**。所有进入 `/v1/images/*` 的请求无条件执行 Chat 提示词转译与 Base64 提取转存。 | 上游仅作为纯 Chat 大模型中转，全部生图需求均由对话多模态大模型承载。 |
| **`whitelist` (白名单转译模式)** | **推荐模式**。仅名单内的模型（如 `gemini-3.1-flash-image`）转译为 Chat 请求；**名单外的所有模型全部直通透传**给上游原生 `/v1/images/*` 接口。 | 上游主要是原生生图模型（如 DALL-E、Midjourney），仅引入个别多模态对话模型生图。 |
| **`blacklist` (黑名单直通模式)** | 名单内的模型（如 `dall-e-3`, `midjourney*`）直接直通上游原生生图接口；**名单外的其余模型均执行 Chat 转译**。 | 默认希望尽可能多的多模态模型走 Chat 转译，仅将已知必须原生的生图模型加入直通名单。 |

### 3.3 通配符模式匹配算法
网关的模型名称匹配算法具备极高宽容度与灵活性：
- **大小写无关**：输入 `Gemini-3.1-Flash-Image` 或 `gemini-3.1-flash-image` 均能精确命中。
- **前后空格自动修剪**：容忍前端或配置中误输入的空格符。
- **支持通配符 `*` 动态匹配**：
  - `flux-*`：自动匹配 `flux-schnell`、`flux-dev`、`flux-pro` 等全系衍生模型。
  - `midjourney*`：自动匹配 `midjourney-v6`、`midjourney-relax` 等。
  - `gemini-*-image`：自动匹配任意符合命名规则的 Gemini 生图模型。

匹配核心逻辑实现规范：
```typescript
export function shouldTranslateModel(model: string, policy?: ModelPolicyConfig): boolean {
  if (!policy || policy.mode === "all") return true;

const targetModel = (model || "").trim().toLowerCase();
  if (!targetModel) return true;

const list = (policy.models || []).map(m => m.trim().toLowerCase()).filter(Boolean);

const matched = list.some(pattern => {
    if (pattern === targetModel) return true;
    if (pattern.includes("*")) {
      const regex = new RegExp("^" + pattern.replace(/\*/g, ".*") + "$", "i");
      return regex.test(targetModel);
    }
    return false;
  });

if (policy.mode === "whitelist") return matched;
  if (policy.mode === "blacklist") return !matched;
  return true;
}
```

### 3.4 原生直通代理与 Base64 自动拦截转存云存储
当模型判定走原生直通时，网关并不仅仅做简单透传，而是提供了**增强型原生反代能力**：
1. **请求体无损流转发**：精准转发客户端的 `application/json` 或 `multipart/form-data` 请求体及鉴权头（`Authorization`），剥离 `host` 与 `connection` 干扰头。
2. **`autoUploadNativeB64` 智能转存**：
   - 当上游原生生图接口在响应 `data` 数组中返回 `b64_json` 且未提供公网 `url` 时；
   - 网关自动拦截该 Base64 图片，提取二进制流并上传至当前网关配置的存储驱动（S3 / OSS / 图床）；
   - 在返回 JSON 中为每个数据项注入永久直链 `item.url`；
   - 彻底解决客户端因接收超大 Base64 数据而导致网络卡死、内存泄露或解析失败的顽疾。

---

## 四、核心功能与处理管道

### 4.1 文生图管道 (POST /v1/images/generations)
- **请求格式兼容**：同时兼容 `application/json` 与原始文本载荷。
- **动态模型与鉴权透传**：支持客户端自选生图模型（缺省 fallback 为 `gpt-5.4`），完全透传客户端携带的 `Authorization: Bearer sk-...`，网关自身无状态。
- **全模态 Base64 提取矩阵**：
  1. `data:image/(png|jpeg|webp|gif);base64,...` 标准 URI 提取；
  2. `message.images` 结构提取（专为 `gemini-3.1-flash-image` 等现代多模态生图设计）；
  3. Markdown 代码围栏（` ```base64 `）提取；
  4. 裸流超长连续 Base64 自动扫描；
  5. 响应体全量 JSON 兜底扫描。
- **响应严格符合标准规范**：若客户端指定或默认请求 `url` 格式，网关严格仅返回包含公网直链的 `data: [{ "url": "..." }]`，彻底剔除冗余字段。

### 4.2 图生图/改图管道 (POST /v1/images/edits)
- **输入支持**：同时支持标准 `multipart/form-data`（通过 Blob 解析）与 `application/json`（携带 Base64 原图）。
- **多模态 Vision 提示词重塑**：
  - 自动构建符合 OpenAI Vision 规范的多模态用户消息：包含用户改图指令文本，以及原图的 `image_url`（Base64 Data URI）。
  - 注入预置的 Vision 改图系统提示词（`visionSystemPrompt`），约束上游大模型忠实保持原图主体并输出新图 Base64。
- **转存与直链回填**：将大模型产出的编辑后图片自动上传至云存储并返回。

### 4.3 通用 API 透明代理透传 (ANY /*)
除上述生图与管理端点外，其余一切 OpenAI 路由均由通用反代捕获：
- `/v1/models`、`/v1/chat/completions`、`/v1/embeddings` 等均透明反代至上游 `UPSTREAM_BASE_URL`。
- 请求头、请求方法、Query 参数、Request Body 均原样流式反代。
- 客户端（如 LobeChat）仅需在配置中统一将 Base URL 指向本网关，即可同时享用生图、改图、对话、模型发现全套能力，无需在不同节点间切换。

### 4.4 多驱动云存储与图床引擎
网关采用面向对象的驱动策略模式（`StorageDriver`），支持运行时无缝热切换：

---

## 五、生产环境部署与 CI/CD 自动化

### 5.1 极简一键部署 (推荐)
适用于 Ubuntu / Debian / CentOS / RHEL / AlmaLinux 等各类 Linux x86_64 生产服务器。

执行官方预置的一键自动化脚本（位于项目 `deploy/install.sh`）：
```bash
curl -fsSL https://raw.githubusercontent.com/cfwasd/image-proxy/main/deploy/install.sh | sudo bash
```

**脚本自动完成的任务**：
1. 自动检测系统环境并创建专用运行用户与组（`imgproxy:imgproxy`）；
2. 规范化创建标准服务目录 `/opt/img2chat-proxy` 与持久化数据目录 `/opt/img2chat-proxy/data`；
3. 从 GitHub Release 自动下载最新已编译好的 Linux x64 单文件二进制；
4. 初始化标准配置文件模板 `/opt/img2chat-proxy/data/config.json`；
5. 注册 Systemd 系统服务 `/etc/systemd/system/img2chat-proxy.service`；
6. 自动设置开机自启并即时启动服务，监听 `0.0.0.0:8080`。

### 5.2 常用 Systemd 运维管理
```bash
# 查看服务实时运行状态
sudo systemctl status img2chat-proxy

# 重启 / 停止 / 启动服务
sudo systemctl restart img2chat-proxy
sudo systemctl stop img2chat-proxy
sudo systemctl start img2chat-proxy

# 查看实时滚动日志 (带色彩输出)
sudo journalctl -u img2chat-proxy -f -o cat
```

### 5.3 源码构建与多平台编译
若需要在开发机或自有流水线上从源码构建：
```bash
# 1. 克隆代码仓库
git clone https://github.com/cfwasd/image-proxy.git
cd image-proxy

# 2. 安装 Bun 依赖
bun install --frozen-lockfile

# 3. 运行本地自动化测试集
bun src/test.ts
bun src/test-url.ts
bun src/test-admin-routes.ts
bun src/test-model-policy.ts

# 4. 开发调试模式 (热重载)
bun run dev

# 5. 跨平台静态二进制单文件编译
# Linux x64
bun run build:linux
# Linux ARM64 (aarch64 架构，如树莓派、鲲鹏服务器)
bun run build:linux-arm64
# Windows x64 (生成 img2chat-proxy-windows-x64.exe)
bun run build:windows
# macOS ARM64 (Apple Silicon M 系列)
bun build --compile --target=bun-darwin-arm64 ./src/index.ts --outfile dist/img2chat-proxy-darwin-arm64
```

### 5.4 GitHub Actions 自动化 CI/CD 与多平台 Release 发布
项目仓库在 `.github/workflows/release.yml` 中建立了全自动化的云端交叉编译发布机制：
1. **触发条件**：当向仓库推送符合语义化版本标签的代码（如 `git tag v1.1.0 && git push origin v1.1.0`）或在 Actions 控制台中手动触发 (`workflow_dispatch`) 时自动执行。
2. **全流程自动化**：
   - 自动拉取代码并安装 Bun 运行时；
   - 严格执行全部自动化单元测试（涵盖 URL 辅助函数、Admin 路由、模型策略分流等），测试不通过则立即阻断发布；
   - 自动交叉编译生成 **Linux x64**、**Linux ARM64**、**Windows x64**、**macOS ARM64** 四大平台免依赖独立二进制文件；
   - 自动提取 `deploy/` 下的部署脚本打包为 `img2chat-proxy-linux-x64.tar.gz` 生产整合包；
   - 自动计算所有发布资产的 SHA256 校验和并写入 `SHA256SUMS.txt`；
   - 自动调用 GitHub Release API 发布正式版本并上传全量附件包。

---

## 六、Nginx 生产反向代理与长超时配置

由于文生图与改图模型在大模型侧运算耗时较长（通常在 15 秒到 120 秒之间），生产环境反代必须**关闭代理缓冲**并**延长读取超时**，防止出现 `504 Gateway Time-out`。

建议将以下配置部署于 `/etc/nginx/conf.d/img2chat-proxy.conf`：

```nginx
server {
    listen 80;
    server_name image-api.yourdomain.com; # 替换为你自己的公网域名

# 允许上传大体积图片（图生图/改图需求，建议 >= 50M）
    client_max_body_size 64M;

location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

# 核心参数 1：关闭代理缓冲，保证流式即时下发
        proxy_buffering off;
        proxy_request_buffering off;

# 核心参数 2：延长超时时间至 600 秒，避免生图超时断开
        proxy_connect_timeout 600s;
        proxy_send_timeout 600s;
        proxy_read_timeout 600s;

# 核心参数 3：开启 HTTP/1.1 支持与长连接
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}
```

配置检查与热重载：
```bash
sudo nginx -t && sudo nginx -s reload
```

---

## 七、Web 管理控制台指南 (/admin)

网关自带现代化嵌入式管理运维面板，浏览器访问：
👉 `http://<服务器IP或域名>:8080/admin`

### 7.1 登录与权限管理
- **默认管理员密码**：`admin123`。
- **修改方式**：首次登录后可在后台直接修改，或在 `data/config.json` 及环境变量 `ADMIN_PASSWORD` 中进行重置。
- **安全机制**：采用基于 HTTPOnly Cookie 与 `Authorization: Bearer` 双重校验机制，未授权访问自动拦截。

### 7.2 在线配置热重载（含模型策略）
在管理面板中可实时调整并一键保存以下配置，**即刻生效，无需重启进程**：
1. **上游中转配置**：修改 CPA / One API 的 Base URL，修改请求超时时长。
2. **提示词策略微调**：自定义文生图与图生图的 System Prompt。
3. **模型转发策略管理**：
   - 可视化切换模式：`all` (全转译) / `whitelist` (白名单) / `blacklist` (黑名单)；
   - 自由增删匹配模型列表（支持多行输入与通配符，如 `flux-*`, `midjourney*`）；
   - 一键启闭“原生直通返回 Base64 自动转存 OSS”特性。

### 7.3 存储驱动切换与即时联调测试
- 支持在线配置并热切换 S3 / RustFS / OSS / 通用图床参数。
- **存储实时上传测试**：控制台内置标准测试原图，点击【测试存储连通性】，网关会立即执行真实的二进制上传并返回公网 URL，管理员可直接在新标签页中点击预览，验证存储桶读写权限与外链是否正常。

### 7.4 运行日志实时监控面板
- 内置环形缓冲区内存日志记录器（`logger.ts`），保留最近 200 条系统日志。
- 控制台提供实时日志抽屉面板，可直接查看每次请求分流日志、上游调用耗时、图片提取结果及具体错误堆栈，无需登录服务器命令行排查问题。

---

## 八、完整配置字典 (config.json & 环境变量)

配置文件存储在应用同级目录或工作区下的 `data/config.json` 中，系统启动时将合并默认值与持久化配置：

```json
{
  "server": {
    "port": 8080,
    "adminPassword": "admin123"
  },
  "upstream": {
    "baseUrl": "http://127.0.0.1:8317",
    "timeoutSeconds": 300,
    "systemPrompt": "You are a professional image generation assistant...",
    "visionSystemPrompt": "You are an expert image editing and transformation engine..."
  },
  "storage": {
    "type": "s3_rustfs",
    "s3": {
      "endpoint": "http://127.0.0.1:9000",
      "bucket": "images",
      "region": "us-east-1",
      "accessKey": "your-access-key",
      "secretKey": "your-secret-key",
      "publicBaseUrl": "https://oss.yourdomain.com",
      "forcePathStyle": true
    },
    "httpMultipart": {
      "uploadUrl": "https://imgbed.yourdomain.com/api/v1/upload",
      "fileField": "file",
      "headers": {
        "Token": "your-imgbed-token"
      },
      "responseUrlJsonPath": "data.url"
    }
  },
  "modelPolicy": {
    "mode": "whitelist",
    "models": [
      "gemini-3.1-flash-image",
      "gemini-2.5-flash-image",
      "gpt-4o",
      "gpt-5.4",
      "flux-*"
    ],
    "autoUploadNativeB64": true
  }
}
```

---

## 九、API 接口对接规范与示例

### 9.1 文生图 (Text-to-Image)

#### cURL 示例
```bash
curl -X POST "http://127.0.0.1:8080/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-upstream-key" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "Cyberpunk cityscape with neon lights reflecting in rain, cinematic lighting, 8k",
    "response_format": "url",
    "n": 1
  }'
```

#### 响应格式 (标准 OpenAI 结构)
```json
{
  "created": 1725849600,
  "data": [
    {
      "url": "https://oss.yourdomain.com/2026/09/b81d4e2e-bcf2-4296-86ad-f5f51661f50c.png"
    }
  ]
}
```

### 9.2 图生图 / 编辑原图 (Image-to-Image / Edits)

#### cURL 示例 (Multipart 形式)
```bash
curl -X POST "http://127.0.0.1:8080/v1/images/edits" \
  -H "Authorization: Bearer sk-your-upstream-key" \
  -F "image=@/path/to/original.png" \
  -F "prompt=将背景中的晴天换成科幻风格的极光与星空，保持前景人物不变" \
  -F "model=gpt-4o" \
  -F "response_format=url"
```

### 9.3 健康检查探针
- **端点**：`GET /health` 或 `GET /api/health`
- **响应**：
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "storageDriver": "S3 / RustFS / OSS"
}
```

---

## 十、常见问题排查 (FAQ)

### Q1: 客户端报错 `504 Gateway Time-out`
- **原因**：Nginx 默认代理读取超时为 60 秒，生图模型经常需要 60~120 秒完成绘制。
- **解决**：在 Nginx 反代配置的 `location` 块中加入 `proxy_read_timeout 600s;` 并确认 `proxy_buffering off;`。

### Q2: 为什么调用 `dall-e-3` 失败？
- **原因**：网关若处于 `all` 全转译模式下，会将请求发给上游 `/v1/chat/completions`。如果上游该模型仅支持生图协议不支持对话协议，上游会报错。
- **解决**：进入管理后台 `/admin`，将**模型转发策略模式**调整为 `whitelist`（白名单转译）或 `blacklist`（黑名单直通），将 `dall-e-3` 设为原生直通即可。

### Q3: 为什么图片生成成功但在前端显示裂图？
- **原因**：S3 / OSS 存储桶未配置公网读权限，或者网关中的 `publicBaseUrl` 没有填写真实可访问的 CDN 域名。
- **解决**：
  1. 确保存储桶具备公开只读权限（ACL 设置为 `public-read`）；
  2. 在控制台 `/admin` 的存储配置中，正确填写 `publicBaseUrl`（例如 `https://images.yourdomain.com`，不要包含末尾斜杠）。

### Q4: 如何在客户端中配置该网关？
- 以 **LobeChat** 为例：
  1. 进入【设置】 -> 【语言模型】 -> 【OpenAI】（或【自定义提供商】）；
  2. 端点地址（Base URL）：填入 `http://<网关IP或域名>:8080/v1`；
  3. API Key：填入你的上游聚合站 API 密钥；
  4. 自定义模型：添加 `gemini-3.1-flash-image` 并勾选 Vision / 生图能力。

---
*文档版本：v1.1.0 ｜ 维护者：王子恒 ｜ 项目状态：稳定投入生产使用*