chore(api-server): 外部模型与网关配置改为环境变量

docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md

@@ -0,0 +1,86 @@
+# api-server 外部服务环境变量配置 2026-05-07
+
+## 背景
+
+`server-rs/crates/api-server/src/config.rs` 统一收口 api-server 启动配置。外部服务分为两类：
+
+1. 公共服务：阿里云、腾讯云、微信等对外公开且接口域名稳定的服务。
+2. 非公共服务：团队自选模型网关、图片网关、视频模型、内部兼容服务等，URL 与模型名可能随部署、供应商或账号策略变化。
+
+本次约定：公共服务 URL 可以保留代码默认值；非公共服务的 URL 与模型名必须通过环境变量提供，不再在 `config.rs` 写死具体模型名称或私有网关地址。
+
+## 公共服务默认值
+
+以下默认值属于公共服务稳定接口，可继续保留在代码或示例环境中：
+
+```text
+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 可保留；具体图片模型名不属于稳定公共接口，必须由环境变量配置。
+
+## 非公共服务必配项
+
+生产环境或真实联调使用到对应能力时，应显式配置以下变量：
+
+```text
+# 文本 LLM 网关
+GENARRATIVE_LLM_PROVIDER=openai-compatible
+GENARRATIVE_LLM_BASE_URL=
+GENARRATIVE_LLM_API_KEY=
+GENARRATIVE_LLM_MODEL=
+
+# APIMart / OpenAI 兼容图片网关
+APIMART_BASE_URL=
+APIMART_API_KEY=
+APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
+
+# 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
+```
+
+## 兼容变量
+
+为降低部署切换成本，当前代码仍兼容部分历史变量：
+
+```text
+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
+```
+
+## 运行时行为
+
+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. 具体模型名缺失时不在配置层伪造默认模型，调用到对应能力时由下游配置校验返回缺配置错误。
+
+## 示例文件
+
+生产示例环境变量维护在：
+
+```text
+deploy/env/api-server.env.example
+```
+
+真实密钥、内部网关 URL 和具体模型名只应写入服务器 `/etc/genarrative/api-server.env` 或本地未提交的 `.env.local` / `.env.secrets.local`，不得提交到仓库。

docs/technical/README.md

@@ -4,6 +4,7 @@
 
 ## 文档列表
 
+- [API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md](./API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md)：冻结 api-server 外部服务配置边界，公共服务 URL 可保留代码默认值，非公共模型名和私有网关 URL 统一通过环境变量注入。
 - [PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md](./PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md)：冻结个人任务与埋点系统首版方案，明确 `tracking_event`、`tracking_daily_stat`、`profile_task_config`、任务进度、领奖记录和光点钱包流水的边界。
 - [SQUARE_HOLE_IMAGE_SLOT_AND_RUNTIME_INTERACTION_FIX_2026-05-06.md](./SQUARE_HOLE_IMAGE_SLOT_AND_RUNTIME_INTERACTION_FIX_2026-05-06.md)：记录方洞挑战结果页图片槽位局部生成、洞口图历史素材、运行态拖拽与点击投放交互的修正口径。
 - [MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md](./MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md)：冻结 Maincloud 历史残留引用禁用策略，明确后续不得新增、运行或引用 `api-server:maincloud`、`GENARRATIVE_SPACETIME_MAINCLOUD_*` 和相关测试/文档口径。