.env.example

# 可选：如果不想在网页右上角“API 设置”里填写，可以在这里配置默认值。
# 使用时复制本文件为 .env.local，再填写真实内容。

# OpenAI 或 OpenAI 兼容接口 Key
OPENAI_API_KEY=

# 可选：OpenAI 兼容接口根地址，通常以 /v1 结尾。
# 默认要求 https；本机 loopback HTTP 可直接用于本地 fixture。
# 远程 HTTP 必须加入 OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS。
# 示例：https://api.openai.com/v1
OPENAI_API_BASE_URL=

# 可选：服务端到图片上游的全局 HTTP(S) 代理。仅影响服务端出站请求，不影响浏览器访问本服务。
# 仅支持无认证、无路径、无查询参数和无片段的 http:// 或 https:// 根代理地址；不支持 SOCKS。
# OPENAI_UPSTREAM_PROXY_URL=http://proxy.internal:8080

# 可选：服务端多渠道多 key 配置。配置任意 OPENAI_CHANNEL_N_* 后，会优先于 OPENAI_API_KEY。
# 页面右上角“API 设置”里手动填写的 API Key/API URL 仍然拥有最高优先级。
#
# 路由策略：
# - sticky：默认值。按请求来源稳定映射到同一个渠道 key，适合减少同一用户跳渠道。
# - round_robin：按请求顺序轮询所有渠道 key，适合简单均摊流量。
# - random：每次随机选择一个渠道 key，适合轻量分散请求。
# OPENAI_ROUTING_STRATEGY=sticky
# OPENAI_UPSTREAM_REQUEST_MODES=images-non-stream,images-sse,responses-non-stream,responses-sse
# OPENAI_UPSTREAM_REQUEST_MODE_PRIORITY=images-non-stream,images-sse,responses-non-stream,responses-sse
#
# 渠道配置规则：
# - N 从 1 开始递增，例如 OPENAI_CHANNEL_1_*、OPENAI_CHANNEL_2_*。
# - ID 只用于日志排查，不会暴露 API Key。
# - BASE_URL 是 OpenAI 兼容接口根地址，通常以 /v1 结尾。
# - BASE_URL 默认要求 https；本机 loopback HTTP 可直接用于本地 fixture。
# - 远程 HTTP 必须加入 OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS。
# - API_KEYS 支持一个或多个 key，多个 key 用英文逗号分隔。
# - REQUEST_MODES 可选，用于声明该渠道经真实 smoke 验证可用的服务端请求方式。
#   单 key 旧配置可用 OPENAI_UPSTREAM_REQUEST_MODES 声明全局可用方式。
#   该白名单只供服务端路由和诊断使用；Agent 客户端仍只提交业务意图。
#   这些变量在服务启动时读取；修改后需要重启 Next.js、Docker 或 Space 服务才会生效。
#   stream_mode=auto 默认由服务端按白名单和优先级选择；未配置优先级时按低费用非流式优先。
#   stream_mode=stream 或显式页面 SSE 不会静默降级。
#   可选值：images-non-stream、images-sse、responses-non-stream、responses-sse。
#   旧后端名别名仅用于兼容输入，建议新配置始终使用上面四个规范值。
#   未配置时默认只允许 images-non-stream；配置后服务端只会把匹配方式的请求路由到该渠道。
# - REQUEST_MODE_PRIORITY 可选，用于声明该渠道在已允许请求方式内的服务端排序。
#   单渠道配置优先于 OPENAI_UPSTREAM_REQUEST_MODE_PRIORITY，且不会扩大 REQUEST_MODES 白名单。
#   未配置时默认顺序：images-non-stream、images-sse、responses-non-stream、responses-sse。
# - FAILURE_COOLDOWN_MS 可选，覆盖该渠道失败后的冷却时间。
# - PROXY_URL 可选，覆盖 OPENAI_UPSTREAM_PROXY_URL，仅用于该渠道的服务端上游请求。
# - API Key 本身不要包含逗号。
#
# 示例：
# OPENAI_CHANNEL_1_ID=official
# OPENAI_CHANNEL_1_BASE_URL=https://api.openai.com/v1
# OPENAI_CHANNEL_1_API_KEYS=sk-key-1,sk-key-2
# OPENAI_CHANNEL_1_REQUEST_MODES=images-non-stream,images-sse
# OPENAI_CHANNEL_1_REQUEST_MODE_PRIORITY=images-non-stream,images-sse
# OPENAI_CHANNEL_1_FAILURE_COOLDOWN_MS=30000
# OPENAI_CHANNEL_1_PROXY_URL=http://channel-proxy.internal:8080
# OPENAI_CHANNEL_1_USER_AGENT=visual-journal/customer
# OPENAI_CHANNEL_1_UPSTREAM_HEADERS_JSON={"X-Custom-Client":"customer"}
#
# OPENAI_CHANNEL_2_ID=backup
# OPENAI_CHANNEL_2_BASE_URL=https://your-compatible-api.example.com/v1
# OPENAI_CHANNEL_2_API_KEYS=sk-backup-1
#
# OPENAI_CHANNEL_3_ID=matsca
# OPENAI_CHANNEL_3_BASE_URL=https://img.matsca.com/v1
# OPENAI_CHANNEL_3_API_KEYS=sk-matsca-1
# OPENAI_CHANNEL_3_UPSTREAM_PROFILE=matsca
# 可选：Matsca App 模式需要同时配置 App ID 和 App Secret；直连模式不要设置。
# OPENAI_CHANNEL_3_MATSCA_APP_ID=
# OPENAI_CHANNEL_3_MATSCA_APP_SECRET=
#
# 可选：远程明文 HTTP 兼容接口 allowlist。默认只允许 HTTPS 和本机 loopback HTTP。
# 多个完整 base URL 用英文逗号分隔，仅在确认网络边界安全时启用。
# OPENAI_ALLOWED_PLAIN_HTTP_API_BASE_URLS=http://your-internal-compatible-api.example.com/v1

# 可选：统一上游请求头。默认 User-Agent 为 visual-journal/<package-version>。
# 全局 UA 可用 OPENAI_UPSTREAM_USER_AGENT 或 UPSTREAM_USER_AGENT 覆盖；
# 单渠道 UA 用 OPENAI_CHANNEL_N_USER_AGENT 覆盖，安全 extra header 用
# OPENAI_CHANNEL_N_UPSTREAM_HEADERS_JSON 配置。
# Authorization、Accept、Content-Type、Content-Length、Host 等协议头不能由 extra headers 覆盖。
# OPENAI_UPSTREAM_USER_AGENT=visual-journal/customer

# 可选：并发流式批处理容量。
# 页面提供显式“并发批量”开关；开启后，流式模式下 n>1 会拆成多个 n=1 的独立流式任务，并按服务端 key 容量并发执行。
# 默认 sticky 路由按单个 credential 容量推荐并发；round_robin/random 才会使用完整 credential 池。
# 渠道失败冷却默认关闭。显式启用后，key 出现鉴权、额度或限流类错误会短暂冷却；
# 渠道出现 5xx、CDN 超时或连接错误后会冷却整个渠道。
# 如果失败能关联到本次服务端 request mode，只冷却对应 request mode，不误伤同渠道其他可用方式。
# OPENAI_MAX_STREAMS_PER_CREDENTIAL=1
# OPENAI_CHANNEL_QUEUE_ENABLED=true
# OPENAI_CHANNEL_QUEUE_MAX_WAIT_MS=420000
# OPENAI_CHANNEL_QUEUE_MAX_SIZE=50
# 设为 true 可启用渠道/凭证失败冷却；默认 false，失败仍会记录但不会临时移出路由池。
# OPENAI_CHANNEL_FAILURE_COOLDOWN_ENABLED=false
# OPENAI_CHANNEL_FAILURE_COOLDOWN_MS=30000
#
# 可选：服务端渠道恢复探测。存在服务端凭证时默认开启，并要求冷却到期的
# credential/channel/request mode 先通过后台 GET /models 探测，成功后才重新进入用户生图流量。
# 探测不调用 /images/generations，不触发生图费用；它只确认 host、鉴权和 models 端点恢复，
# 不能替代 Images/Responses/SSE 的真实 smoke；MAX_PER_TICK 用于限制探测流量。
# OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED=true
# 如果设为 true，OPENAI_CHANNEL_RECOVERY_PROBE_ENABLED 也必须启用。
# OPENAI_CHANNEL_REQUIRE_PROBE_FOR_RECOVERY=true
# OPENAI_CHANNEL_RECOVERY_PROBE_INTERVAL_MS=60000
# OPENAI_CHANNEL_RECOVERY_PROBE_TIMEOUT_MS=5000
# OPENAI_CHANNEL_RECOVERY_PROBE_MAX_PER_TICK=1

# 可选：多上游图片兼容层默认策略。默认保持 Images API JSON 基线。
# IMAGE_GENERATION_BACKEND=images-api
# IMAGE_STREAMING_STRATEGY=auto
#
# 可选：图片上游传输策略。默认给长耗时生图保留 900 秒，并关闭 OpenAI SDK 自动重试，避免超时后重复触发计费请求。
# IMAGE_UPSTREAM_TIMEOUT_MS 必须是正整数；IMAGE_STREAM_DATA_INTERVAL_TIMEOUT_MS 可设为 0 以禁用已建立流的空闲计时器。
# IMAGE_UPSTREAM_TIMEOUT_MS=900000
# IMAGE_STREAM_DATA_INTERVAL_TIMEOUT_MS=900000
# IMAGE_UPSTREAM_MAX_RETRIES=0

# 可选：实验 Responses API 图片后端。默认关闭，且默认请求仍走 Images API。
# 要使用 Responses 后端，需要请求显式传入 image_backend=responses-image-generation，
# 或把 IMAGE_GENERATION_BACKEND 设为 responses-image-generation / responses；
# 两种方式都需要单独配置 /responses 顶层模型。
# OPENAI_RESPONSES_API_MODEL 是服务端默认顶层模型，页面请求可用 responsesModel、
# responses_model、gptModel 或 gpt_model 覆盖单次请求。
# 该配置只影响本项目的 responses-image-generation 路径，不改变兼容上游自身
# /v1/images/generations 桥接层内部选择的模型。
# 表单 model 只作为 image_generation 工具模型，不会复用为 /responses 顶层模型。
# ENABLE_RESPONSES_IMAGE_BACKEND=true
# OPENAI_RESPONSES_API_MODEL=gpt-5.4

# 可选：独立真实上游 smoke 目标。默认不触发计费请求，必须显式运行 --allow-billable。
# 每组至少提供 BASE_URL 和 API_KEY；MODEL、SIZE、QUALITY、RESPONSES_MODEL 可按上游覆盖。
# IMAGE_REAL_SMOKE_ORIGINAL_BASE_URL=https://original-new-api.example.com/v1
# IMAGE_REAL_SMOKE_ORIGINAL_API_KEY=
# IMAGE_REAL_SMOKE_GAOREN_BASE_URL=https://gaoren-new-api.example.com/v1
# IMAGE_REAL_SMOKE_GAOREN_API_KEY=
# IMAGE_REAL_SMOKE_SUB2API_BASE_URL=https://sub2api.example.com/v1
# IMAGE_REAL_SMOKE_SUB2API_API_KEY=
# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_BASE_URL=https://sub2api.example.com/v1
# IMAGE_REAL_SMOKE_SUB2API_RESPONSES_API_KEY=
# IMAGE_REAL_SMOKE_GPT2IMAGE_BASE_URL=https://gpt2image.superapi.buzz/v1
# IMAGE_REAL_SMOKE_GPT2IMAGE_API_KEY=
# IMAGE_REAL_SMOKE_GPT2IMAGE_RESPONSES_MODEL=gpt-5.4
# IMAGE_REAL_SMOKE_MATSCA_BASE_URL=https://img.matsca.com/v1
# IMAGE_REAL_SMOKE_MATSCA_API_KEY=
# 独立真实 smoke 目标使用页面外部凭证路径，只验证 Matsca direct 模式。
# App 模式请通过 OPENAI_CHANNEL_N_UPSTREAM_PROFILE=matsca 和 OPENAI_CHANNEL_N_MATSCA_APP_* 配置后运行 server-channel smoke。
# IMAGE_REAL_SMOKE_TIMEOUT_MS=240000

# 可选：给网页加一个访问码。公网部署时建议一定要设置。
APP_PASSWORD=

# Compose 默认只发布到 127.0.0.1:4783。需要局域网或公网访问时，在 shell 或 Compose 的 .env
# 文件显式设置非回环地址，并同时在 .env.local 设置上面的 APP_PASSWORD；未设置访问码时容器会拒绝启动。
# GIP_BIND_HOST=0.0.0.0
# GIP_PORT=4783

# 可选：给 /api/agent/* 使用的 Bearer token。公网或内网共享部署时建议设置。
# AGENT_API_TOKEN=

# 可选：Agent 状态后端。memory 适合临时演示，sqlite 适合单实例本地部署，postgres 适合状态并发；多实例还需共享 generated-images。
# AGENT_STATE_BACKEND=sqlite
# AGENT_SQLITE_PATH=generated-images/.agent-state/agent.sqlite
# AGENT_DATABASE_URL=postgres://gpt_image:<database-password>@localhost:5432/gpt_image_playground
# docker-compose.postgres.yml 从 shell 或 Compose 的 .env 读取此 Secret，不要把真实值写进 .env.local 或仓库文件。
# GPT_IMAGE_POSTGRES_PASSWORD=
# AGENT_REQUEST_LEASE_MS=600000
# AGENT_REQUEST_TTL_SECONDS=86400

# 可选：自动清理 WebUI 文件系统图片。默认关闭；启用后默认保留 30 天。
# 启用且使用 fs 存储时，可在“最近生成”中批量标记图片永久排除自动清理；无需额外环境变量，手动删除仍会删除图片和标记。
# WEBUI_IMAGE_AUTO_CLEANUP_ENABLED=false
# WEBUI_IMAGE_RETENTION_DAYS=30

# 可选：服务端日志等级。可选 debug、info、warn、error。生产环境默认 warn，其他环境默认 info。
# APP_LOG_LEVEL=warn
# 可选：服务端本地应用日志保留条数，默认 300。扩大后可提升 Agent 诊断可回溯窗口。
# APP_LOG_MAX_ENTRIES=300

# 本地运行一般不用设置；部署到 Vercel 时建议使用 indexeddb。
# NEXT_PUBLIC_IMAGE_STORAGE_MODE=indexeddb