Genarrative/docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md

api-server 外部服务环境变量配置 2026-05-07

背景

server-rs/crates/api-server/src/config.rs 统一收口 api-server 启动配置。外部服务分为两类：

1. 公共服务：阿里云、腾讯云、微信等对外公开且接口域名稳定的服务。
2. 非公共服务：团队自选模型网关、图片网关、视频模型、内部兼容服务等，URL 与模型名可能随部署、供应商或账号策略变化。

本次约定：公共服务 URL 可以保留代码默认值；非公共服务的 URL 与模型名必须通过环境变量提供，不再在 config.rs 写死具体模型名称或私有网关地址。

公共服务默认值

以下默认值属于公共服务稳定接口，可继续保留在代码或示例环境中：

DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
ALIYUN_SMS_ENDPOINT=dypnsapi.aliyuncs.com
WECHAT_AUTHORIZE_ENDPOINT=https://open.weixin.qq.com/connect/qrconnect
WECHAT_ACCESS_TOKEN_ENDPOINT=https://api.weixin.qq.com/sns/oauth2/access_token
WECHAT_USER_INFO_ENDPOINT=https://api.weixin.qq.com/sns/userinfo

说明：DashScope 属于阿里云公开服务，基础 URL 可保留；具体图片模型名不属于稳定公共接口，必须由环境变量配置。

非公共服务必配项

生产环境或真实联调使用到对应能力时，应显式配置以下变量：

# 文本 LLM 网关
GENARRATIVE_LLM_PROVIDER=openai-compatible
GENARRATIVE_LLM_BASE_URL=
GENARRATIVE_LLM_API_KEY=
GENARRATIVE_LLM_MODEL=

# APIMart / OpenAI 兼容 Responses 文本网关
APIMART_BASE_URL=
APIMART_API_KEY=
APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000

# VectorEngine / Gemini 原生图片 / GPT-image-2 / Suno / Vidu 生成网关
VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn
VECTOR_ENGINE_API_KEY=
VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000

# Hyper3D Rodin Gen-2 3D 模型生成
HYPER3D_BASE_URL=https://api.hyper3d.com/api/v2
HYPER3D_API_KEY=
HYPER3D_MODEL_REQUEST_TIMEOUT_MS=180000

# 火山引擎豆包语音 ASR / TTS
VOLCENGINE_SPEECH_API_KEY=
VOLCENGINE_SPEECH_APP_ID=
VOLCENGINE_SPEECH_ACCESS_KEY=
VOLCENGINE_SPEECH_ASR_RESOURCE_ID=volc.seedasr.sauc.concurrent
VOLCENGINE_SPEECH_TTS_RESOURCE_ID=seed-tts-2.0
VOLCENGINE_SPEECH_REQUEST_TIMEOUT_MS=180000
VOLCENGINE_SPEECH_ASR_WS_URL=wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async
VOLCENGINE_SPEECH_TTS_BIDIRECTION_WS_URL=wss://openspeech.bytedance.com/api/v3/tts/bidirection
VOLCENGINE_SPEECH_TTS_SSE_URL=https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse

# DashScope 图片模型名
DASHSCOPE_SCENE_IMAGE_MODEL=
DASHSCOPE_REFERENCE_IMAGE_MODEL=
DASHSCOPE_COVER_IMAGE_MODEL=

# Ark / 角色视频模型网关
ARK_CHARACTER_VIDEO_BASE_URL=
ARK_CHARACTER_VIDEO_API_KEY=
ARK_CHARACTER_VIDEO_MODEL=
ARK_CHARACTER_VIDEO_REQUEST_TIMEOUT_MS=420000

兼容变量

为降低部署切换成本，当前代码仍兼容部分历史变量：

GENARRATIVE_LLM_BASE_URL / LLM_BASE_URL
GENARRATIVE_LLM_MODEL / LLM_MODEL / VITE_LLM_MODEL
GENARRATIVE_LLM_API_KEY / LLM_API_KEY / ARK_API_KEY
DASHSCOPE_SCENE_IMAGE_MODEL / DASHSCOPE_IMAGE_MODEL
DASHSCOPE_REFERENCE_IMAGE_MODEL / DASHSCOPE_IMAGE_EDIT_MODEL
DASHSCOPE_COVER_IMAGE_MODEL / DASHSCOPE_IMAGE_MODEL
ARK_CHARACTER_VIDEO_BASE_URL / ARK_BASE_URL / GENARRATIVE_LLM_BASE_URL / LLM_BASE_URL
ARK_CHARACTER_VIDEO_API_KEY / ARK_API_KEY / GENARRATIVE_LLM_API_KEY / LLM_API_KEY
ARK_CHARACTER_VIDEO_MODEL / DASHSCOPE_CHARACTER_VIDEO_MODEL
VOLCENGINE_SPEECH_API_KEY / VOLCENGINE_API_KEY
VOLCENGINE_SPEECH_APP_ID / VOLCENGINE_ACCESS_KEY_ID
VOLCENGINE_SPEECH_ACCESS_KEY / VOLCENGINE_SECRET_ACCESS_KEY
HYPER3D_BASE_URL / RODIN_BASE_URL
HYPER3D_API_KEY / RODIN_API_KEY
HYPER3D_MODEL_REQUEST_TIMEOUT_MS / RODIN_MODEL_REQUEST_TIMEOUT_MS

运行时行为

1. AppConfig::default() 不再包含具体非公共模型名或私有网关 URL。
2. AppConfig::from_env() 会从环境变量读取非公共模型名和 URL。
3. 文本 LLM provider 为 ark 且未配置 GENARRATIVE_LLM_BASE_URL 时，仍回退到 Ark 公开基础 URL。
4. 角色视频 provider 复用 Ark 且未配置 ARK_CHARACTER_VIDEO_BASE_URL 时，仍回退到 Ark 公开基础 URL。
5. 具体模型名缺失时不在配置层伪造默认模型，调用到对应能力时由下游配置校验返回缺配置错误。
6. VectorEngine 图片与音频生成只读取 VECTOR_ENGINE_BASE_URL / VECTOR_ENGINE_API_KEY，其中 GPT-image-2 与抓大鹅 Gemini 素材 sheet 图片生成额外读取 VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS；不复用 APIMART_*、GENARRATIVE_LLM_* 或前端变量。拼图 Agent 的生成 action 不做前端自动重试，避免一次点击在上游超时后重复触发外部生图与钱包扣退费；若 VectorEngine 请求达到该超时窗口，api-server 返回 504 Gateway Timeout，error.details.provider 为 vector-engine，并保留具体超时 message。
7. 火山引擎语音能力由 platform-speech 收口协议帧与上游鉴权，api-server 只暴露平台鉴权后的代理路由，不向前端返回任何密钥字段。
8. Hyper3D Rodin Gen-2 使用公开默认 https://api.hyper3d.com/api/v2，API Key 只读取 HYPER3D_API_KEY / RODIN_API_KEY，不复用文本 LLM、图片或音频网关密钥。
9. APIMart 当前只保留给创意 Agent 的 gpt-5 Responses 文本/多模态理解链路；抓大鹅物品素材 sheet、GPT-image-2 图片生成和音频生成都不得读取 APIMart 配置。
10. 本地 npm run api-server、npm run dev:rust、npm run dev 与 npm run dev:web 的环境文件优先级固定为非空外层 shell 变量最高，其后 .env、.env.local、.env.secrets.local 逐层覆盖；真实密钥建议放在 .env.secrets.local，防止 .env 中的空示例值覆盖私密配置。外层 shell 变量如果是空字符串或全空白，不再遮蔽本地 env 文件中的真实值。
11. OSS 客户端只在 ALIYUN_OSS_BUCKET、ALIYUN_OSS_ENDPOINT、ALIYUN_OSS_ACCESS_KEY_ID、ALIYUN_OSS_ACCESS_KEY_SECRET 四项齐全时初始化。四项全部缺失表示未启用 OSS；部分缺失时 api-server 记录 warning 并继续启动，具体上传、换签或读取 generated 私有资产的接口返回 OSS 未完成环境变量配置，并在 error.details.missingEnv 中列出缺失变量。
12. 抓大鹅 2D 草稿素材生成需要同时具备 VectorEngine 与 OSS 配置：VectorEngine Gemini gemini-3-pro-image-preview 原生 generateContent 负责生成 5x5 物品素材 sheet；封面和 9:16 背景图走 VectorEngine /v1/images/generations 的 gpt-image-2-all JSON 链路；1:1 容器 UI 图走 VectorEngine /v1/images/edits multipart 链路，并把 public/match3d-background-references/pot-fused-reference.png 作为 image part 上传，不能再用 generations image 数组弱参考。OSS 负责保存切割后的五视角图片及其它生成图。缺少 VectorEngine 或 OSS 时应通过 error.details.reason 向前端暴露具体缺项，不能只显示泛化“服务暂不可用”。素材图、封面图和背景图生成在调用外部生图前必须先预检 OSS，避免已消耗外部生图后才发现无法落库。
13. 拼图有参考图且开启 AI 重绘时使用 VectorEngine POST /v1/images/edits multipart 接口。若返回 error sending request for url，代表后端未收到 HTTP 响应；响应 details 会带 reason、source、connect、body、timeout 和 endpoint，排查时优先检查服务器网络、DNS、防火墙、代理和参考图大小。拼图图片客户端强制 HTTP/1.1，以降低上游 multipart HTTP/2 连接中断风险。
14. 本地排查 OSS 未完成环境变量配置 时必须核对键名是否精确为 ALIYUN_OSS_ACCESS_KEY_SECRET。常见误写是把 OSS 的首字母 O 写成数字 0，例如 ALIYUN_0SS_ACCESS_KEY_SECRET；该键不会被 api-server 读取。

本地配置检查

拼图真实生成同时依赖 VectorEngine 与 OSS。触发生成前可先运行：

npm run check:api-server-env

该命令只输出配置项是否存在，不打印密钥值。若显示 ALIYUN_0SS_*，说明把 OSS 的字母 O 写成了数字 0。修正 env 文件后必须重启 npm run api-server 或 npm run dev，已经运行中的 api-server 进程不会自动读取新的环境变量。

示例文件

生产示例环境变量维护在：

deploy/env/api-server.env.example

真实密钥、内部网关 URL 和具体模型名只应写入服务器 /etc/genarrative/api-server.env 或本地未提交的 .env.local / .env.secrets.local，不得提交到仓库。