支持多种部署与开发 - 数字先锋API文档

### GPT Image Playground支持多种部署与开发方式

开源地址：https://github.com/CookSleep/gpt_image_playground

官方镜像已发布至 GitHub Container Registry。Docker 部署支持在运行时注入默认配置。

------------

### Docker 部署
环境变量说明：

DEFAULT_API_URL：设置页面上默认显示的 API 地址（如 https://api.example.com/v1）。也支持填写 .json 配置 URL 或带 settings 参数的分享 URL 来导入自定义服务商配置（详见下方说明）。
API_PROXY_URL：配置内置代理实际转发到的完整 API 基础地址（仅开启代理时有效）。代理不会自动补 /v1，OpenAI 兼容接口通常必须填写到版本前缀，如 https://api.example.com/v1。
ENABLE_API_PROXY：设为 true 开启容器内置 Nginx 同源代理，用于解决浏览器跨域（CORS）限制。开启后，前端 API 代理 开关默认开启，浏览器会请求同源的 /api-proxy/{接口相对路径}，再由 Nginx 拼接到 API_PROXY_URL 后转发；用户仍可在设置中手动关闭。
LOCK_API_PROXY：设为 true 时，在 ENABLE_API_PROXY=true 的前提下将前端 API 代理 开关强制锁定为开启，用户无法关闭。
SHOW_DEFAULT_CONFIG_ONLY：设为 true 后，如果已配置默认 API URL 或默认代理，前端会禁用“当前配置”和“服务商类型”的下拉切换，只允许使用默认配置和默认服务商类型。通过页面 URL 参数传入的配置只会覆盖当前配置字段，不会新建配置、切换服务商类型或导入自定义服务商；DEFAULT_API_URL 本身仍可使用配置 URL 来定义部署端默认服务商。
HOST / PORT：指定容器内 Nginx 监听的地址和端口（默认 0.0.0.0:80）。
⚠️ 安全警告：开启 API 代理后，任何人都能将你的服务器作为代理来请求目标 API。建议仅在有访问控制（如 IP 白名单）或本地网络中开启。

💡 导入自定义服务商配置：DEFAULT_API_URL 除了填写普通 API 地址外，也支持直接填写 .json 配置 URL 或带 settings 参数的分享 URL。设为配置 URL 时，页面启动后会自动导入其中的自定义服务商和 API 配置，设置页显示的是配置 JSON 中 profile 定义的 baseUrl（而非配置 URL 本身）。

💡 隐藏真实 API 地址：如果不希望用户在前端看到真实的 API 上游地址，可以配合 ENABLE_API_PROXY=true 和 LOCK_API_PROXY=true 强制所有请求走服务器代理，再将 API_PROXY_URL 设为真实的 API 上游地址。根据使用的服务商类型，DEFAULT_API_URL 的填法不同：

OpenAI 兼容接口：将 DEFAULT_API_URL 留空或填写一个占位地址（如 https://proxy）。
自定义服务商配置：将 DEFAULT_API_URL 设为配置 URL（.json 或带 settings 参数的分享 URL），配置 JSON 中 profile 的 baseUrl 留空或填占位地址，并设置 apiProxy:true。
这样前端设置页只会显示空值或占位地址，真实 API 地址仅存在于服务器侧的 API_PROXY_URL，不会暴露给用户。

自定义服务商开启代理仅支持同步返回图片的配置；包含 taskIdPath 或 poll 的异步任务自定义服务商暂不支持 API 代理。

💡 兼容迁移：旧版本中的 API_URL 已拆分为 DEFAULT_API_URL 和 API_PROXY_URL。容器启动时会自动将遗留的 API_URL 作为两个新变量的兜底值，实现无缝兼容。建议更新配置文件，逐步迁移至新变量。

1. Docker CLI 示例

docker run -d -p 8080:80 \
  -e DEFAULT_API_URL=https://api.example.com/v1 \
  -e ENABLE_API_PROXY=true \
  -e LOCK_API_PROXY=true \
  -e API_PROXY_URL=https://api.example.com/v1 \
  ghcr.io/cooksleep/gpt_image_playground:latest
隐藏真实 API 地址示例（OpenAI 兼容接口）：

docker run -d -p 8080:80 \
  -e DEFAULT_API_URL= \
  -e API_PROXY_URL=https://real-api.example.com/v1 \
  -e ENABLE_API_PROXY=true \
  -e LOCK_API_PROXY=true \
  ghcr.io/cooksleep/gpt_image_playground:latest
上例中设置页的 API URL 为空，实际请求通过代理转发到 API_PROXY_URL。

隐藏真实 API 地址示例（同步自定义服务商配置）：

docker run -d -p 8080:80 \
  -e DEFAULT_API_URL='https://example.com/?settings={"customProviders":[...],"profiles":[{"baseUrl":"","apiProxy":true,...}]}' \
  -e API_PROXY_URL=https://real-api.example.com/v1 \
  -e ENABLE_API_PROXY=true \
  -e LOCK_API_PROXY=true \
  ghcr.io/cooksleep/gpt_image_playground:latest
上例中 DEFAULT_API_URL 为同步自定义服务商配置分享 URL，profile 的 baseUrl 留空且 apiProxy:true；真实 API 地址仅在 API_PROXY_URL 中配置，前端不可见。异步任务自定义服务商暂不支持开启代理。

(注：使用 host 网络时加 --network host，修改容器监听端口使用 -e PORT=28080)

2. Docker Compose 示例

services:
  gpt-image-playground:
    image: ghcr.io/cooksleep/gpt_image_playground:latest
    environment:
      - DEFAULT_API_URL=https://api.openai.com/v1
    ports:
      - "8080:80"
    restart: unless-stopped
更新说明：

使用 latest 标签时，重新拉取镜像并重启即可更新（如 docker compose pull && docker compose up -d）。若需固定版本可使用官方提供的版本号标签（如 0.2.x）。

------------
### 本地开发与静态构建
1. 环境准备与启动

你可以在项目根目录新建 .env.local 文件配置默认 API URL（如 VITE_DEFAULT_API_URL=https://api.example.com/v1）。然后安装依赖并启动：

导入自定义服务商配置：VITE_DEFAULT_API_URL 除了填写普通 API 地址外，也支持直接填写 .json 配置 URL 或带 settings 参数的分享 URL。设为配置 URL 时，页面启动后会自动导入其中的自定义服务商和 API 配置，设置页显示的是配置 JSON 中 profile 定义的 baseUrl（而非配置 URL 本身）。

仅展示默认配置：在 .env.local 中加入 VITE_SHOW_DEFAULT_CONFIG_ONLY=true 后，如果已配置默认 API URL 或默认代理，前端会禁用“当前配置”和“服务商类型”的下拉切换。通过页面 URL 参数传入的配置只会覆盖当前配置字段，不会新建配置、切换服务商类型或导入自定义服务商；VITE_DEFAULT_API_URL 本身仍可使用配置 URL 来定义部署端默认服务商。

npm install
npm run dev
2. 本地开发跨域代理 (可选)

如果在本地开发时遇到浏览器的 CORS 限制，可开启本地代理转发：

cp dev-proxy.config.example.json dev-proxy.config.json
修改 dev-proxy.config.json，将 target 设置为真实的完整 API 基础地址。代理不会自动补 /v1，OpenAI 兼容接口通常必须填写到版本前缀，如 https://api.example.com/v1。重启开发服务器后，在页面设置中开启 API 代理 即可（请求将被转发如 http://localhost:5173/api-proxy/... -> target/...）。此功能仅在 npm run dev 阶段生效，不会影响打包产物。

3. 本地故障模拟 API (可选)

如果需要复现图片 URL 跨域、接口返回结构异常、原始响应查看等问题，可启动内置模拟服务：

npm run mock:api
使用方式见 本地故障模拟 API。

4. 构建静态产物

npm run build
构建输出的文件位于 dist/ 目录下，可将其部署至任何静态文件服务器（如普通 Nginx、GitHub Pages、Netlify 等）。

🛠️ URL 传参快速填充
应用支持通过 URL 查询参数快速填入配置，非常适合创建书签或集成分享。根据你的服务商类型，选择对应的方式：

方式一：标准 OpenAI 兼容服务商 直接使用简短的查询参数配置：

?apiUrl=https://你的代理地址.com
?apiKey=sk-xxxx
?apiMode=images 或 ?apiMode=responses（未传时默认为 images）
?model=gpt-image-2（未传时按 apiMode 使用默认模型）
?profileName=我的配置（设置配置名称，未传时默认为 URL 参数配置）
?codexCli=true（开启 Codex CLI 兼容模式）
?streamImages=true（开启流式传输）
?streamPartialImages=2（请求中间步骤图像数，需配合 streamImages=true 使用）
例如，集成到 New API 的聊天系统：

https://gpt-image-playground.cooksleep.dev?apiUrl={address}&apiKey={key}&model={model}
https://cooksleep.github.io/gpt_image_playground?apiUrl={address}&apiKey={key}&model={model}
方式二：自定义格式服务商 如果需要导入自定义格式的 API 配置，请使用 settings 参数并传入 URL 编码后的完整 JSON：

?settings={URL编码后的JSON}（只读取 customProviders 和 profiles 列表）
推荐先在项目内完成配置生成与导入：

设置 - API 配置 - 服务商类型 - 创建自定义服务商 - AI 一键生成与导入

完成后可在 API 配置 - 当前配置 使用右侧快捷按钮：

链接按钮：复制可导入配置的 URL。复制时可选择不包含 API Key，并使用 {address}、{key}、{model} 等变量，便于在 New API 等平台中集成分享。
复制按钮：将当前配置复制一份到配置列表底部，新配置名称会追加“（复制）”。
JSON 结构示例：

{
  "customProviders": [
    {
      "id": "custom-example-task",
      "name": "示例异步任务服务商",
      "submit": {
        "path": "images/generations",
        "method": "POST",
        "contentType": "json",
        "body": {
          "model": "$profile.model",
          "prompt": "$prompt",
          "size": "$params.size",
          "quality": "$params.quality",
          "output_format": "$params.output_format",
          "output_compression": "$params.output_compression",
          "n": "$params.n",
          "image_urls": "$inputImages.dataUrls"
        },
        "taskIdPath": "data.0.task_id"
      },
      "poll": {
        "path": "tasks/{task_id}",
        "method": "GET",
        "intervalSeconds": 5,
        "statusPath": "data.status",
        "successValues": ["completed"],
        "failureValues": ["failed", "cancelled"],
        "errorPath": "data.error.message",
        "result": {
          "imageUrlPaths": ["data.result.images.*.url.*"],
          "b64JsonPaths": []
        }
      }
    }
  ],
  "profiles": [
    {
      "name": "示例异步任务服务商",
      "provider": "custom-example-task",
      "baseUrl": "https://api.example.com/v1",
      "model": "example-image-model",
      "apiMode": "images"
    }
  ]
}
第三方服务商可以参考 自定义服务商 LLM 提示词，让 LLM 根据自己的 API 文档生成可导入的完整配置。导入后只需要在设置里补充 API Key。

上一篇：GPT Image图片生成下一篇：没有了