docs: document upstream model config failure

docs/deployment.md

@@ -161,6 +161,71 @@ python3.12 manage.py import_ai_models /secure/cmhub/ai_models.json --create-defa
 - `AiModel.timeout_seconds` 不能继续依赖默认 `0` 口径上线；图片模型必须按真实耗时设置读取超时。
 - 运营后台需配置 `PricingRule` 和 `ExchangeRate`，否则生成和充值会因缺规则被拒绝。
 
+### AI 上游配置故障处理
+
+已知线上故障形态：
+
+1. `GET /api/v1/balance` 成功，说明 API Key 与 base URL 可用。
+2. `GET /api/v1/models` 中 `title-standard` 存在，`operation_type="title"`，`pricing_status="priced"`。
+3. `POST /api/v1/generate/title` 返回：
+
+```json
+{"error":{"code":"upstream_error","message":"上游模型配置不可用"}}
+```
+
+该形态优先判定为**服务端上游模型运行配置不可用**，不是桌面端 payload 问题；生成失败后应确认余额未减少。
+
+修复步骤：
+
+1. 确认线上 `.env` 中 `AI_KEY_ENCRYPTION_KEY` 存在且是有效 Fernet key；不要更换已用于加密入库的 key。
+2. 在 django-admin 检查 `/admin/ai/modelalias/`：`title-standard` 必须 `is_active=True`、`operation_type=title`，且指向 active 的 `AiModel`。
+3. 在 `/admin/ai/aimodel/` 检查该模型：`url`、`model`、`api_type`、`capabilities`、API Key 均已配置；标题模型至少包含 `text` 能力，如需看图标题还应包含 `vision`。
+4. 若怀疑解密失败，在后台重新保存该 `AiModel` 的 API Key，或使用当前 `AI_KEY_ENCRYPTION_KEY` 重新执行 `import_ai_models` 导入模型配置。
+5. 环境变量改动后重启 `cmhub-web.service` 与 `cmhub-generate.service`；数据库模型配置改动通常热生效，但生产排障时可统一重启减少不确定性。
+
+命令行诊断时不要打印真实 API Key，可只打印是否存在和密文前缀：
+
+```bash
+python3.12 manage.py shell
+```
+
+```python
+from apps.ai.aliases import resolve_model_alias
+
+alias = resolve_model_alias("title", "title-standard")
+model = alias.ai_model
+print({
+    "alias": alias.alias,
+    "alias_active": alias.is_active,
+    "operation_type": alias.operation_type,
+    "model_name": model.name,
+    "model_active": model.is_active,
+    "api_type": model.api_type,
+    "url_set": bool(model.url),
+    "model_set": bool(model.model),
+    "capabilities": sorted(model.capabilities_set()),
+    "has_api_key": model.has_api_key,
+    "encrypted_prefix": model.api_key_encrypted[:7] if model.api_key_encrypted else "",
+})
+
+resolved = model.to_resolved_model()
+print({
+    "resolved_api_type": resolved.api_type,
+    "resolved_url_set": bool(resolved.url),
+    "resolved_model_set": bool(resolved.model),
+    "resolved_has_api_key": bool(resolved.api_key),
+})
+```
+
+修复后验收：
+
+```bash
+python3.12 manage.py check
+python3.12 manage.py smoke_ai_generation title
+```
+
+再用真实 API Key 调 `GET /api/v1/balance`、`GET /api/v1/models`、`POST /api/v1/generate/title`。期望标题接口返回 `titles`、`points_cost`、`points_balance`、`call_id`；若上游失败，确认错误不再是「上游模型配置不可用」。
+
 ## 七、Gunicorn 运行
 
 建议把同步图片生成分流到独立 Gunicorn 池，避免长请求占满普通页面和 admin 的 worker。