Isolate cloud model access before enabling product RAG workflows

The API and ingestion tools now use a fixed internal model gateway while
governed profiles, embedding cache assignments, traceable citations, and
stable API errors establish the boundaries required by later workflows.

Constraint: The current Alibaba Cloud workspace rejects all three live model calls with authentication failures
Rejected: Give the API or seed tools the Bailian key and direct egress | combines database access, cloud credentials, and public network access
Rejected: Mix offline and Bailian vectors in one demo namespace | makes profile activation and retrieval ambiguous
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep Bailian credentials and egress exclusive to model-gateway and create a new immutable profile hash for any embedding identity change
Tested: make verify; 121 backend tests; 14 frontend tests; fresh and populated Alembic upgrade-downgrade-upgrade; two idempotent offline seeds; Docker health and HTTP retrieval; isolated provider smoke
Not-tested: Successful live Bailian responses because the supplied workspace credential currently fails authentication

docs/adr/0005-isolate-model-egress.md

@@ -0,0 +1,68 @@
+# ADR-0005：使用独立 Model Gateway 隔离百炼出口
+
+- **状态：** accepted
+- **日期：** 2026-07-13
+
+## 背景
+
+在线 RAG 必须同步完成 Query Embedding、Rerank 和 Chat SSE，但 ADR-0004 又要求数据库感知 API 不持有百炼 Key、没有公网默认出口。让 API 或 Worker 直接调用百炼，会把业务数据、数据库凭据、模型凭据和公网出口集中到同一信任边界；只保留一次性 smoke/seed 工具则无法支持在线问答。
+
+## 决策
+
+新增与 API 共用 backend 镜像的长期 `model-gateway` 服务：
+
+```text
+browser
+  -> web (edge + ingress)
+  -> gateway (ingress + data)
+  -> api (data + model)
+       -> PostgreSQL/pgvector (data)
+       -> model-gateway (model + egress)
+            -> Alibaba Cloud Model Studio
+
+worker (data + model)
+  -> PostgreSQL/pgvector
+  -> model-gateway
+```
+
+- 只有 `model-gateway` 挂载 `bailian_api_key` 并连接 `egress`；它不连接 `data`、不挂数据库 Secret、上传卷或宿主端口。
+- API 与 Worker 不挂百炼 Key、不连接 `egress`，只通过 internal `model` 网络访问固定的 `http://model-gateway:8000`。
+- API 与 Worker 使用不同的内部令牌。调用必须同时携带 `Authorization: Bearer ...` 与 `X-RAG-Caller`；Gateway 用常量时间比较把令牌映射到调用者，不能只信任 header 或 Docker 来源地址。
+- API 允许 Query Embedding、Rerank、Chat 和受控 provider health；Worker 额外允许 Document Embedding。任意越权调用失败关闭。
+- Model Gateway 只接受固定 profile、固定模型和固定端点的 vendor-neutral DTO，不接受客户端提供 URL、模型名、维度或任意转发目标。
+- Embedding、Rerank 和 Chat 继续复用现有 provider ports 与百炼 adapter，不引入 SDK、Redis、消息队列、服务网格或第二套实现。
+- 日志只允许 trace、调用者、操作、profile、输入数量、usage、耗时、request ID 和脱敏错误码；禁止记录 Key、Authorization、URL、query、messages、候选正文或响应正文。
+- 容器 readiness 只验证本地配置、Secret 和客户端初始化，不产生模型费用；真实探测使用受控内部端点和显式命令。
+
+## 内部接口
+
+- `POST /internal/v1/embeddings`：接收 `texts` 和 `input_type=query|document`；Query 恰好一条，Document 为 1–10 条；返回 1024 维向量、resolved model、usage、request ID 和耗时。
+- `POST /internal/v1/rerank`：接收 query、候选正文和 Top N；返回原始下标、score、受校验正文与 provider 元数据。
+- `POST /internal/v1/chat/completions`：非流式内部调用，用于需要先完成引用校验的场景。
+- `POST /internal/v1/chat/stream`：vendor-neutral SSE；流开始后的 provider 错误转换为终态 `error` 事件，取消必须关闭上游流。
+- `GET /health/live` 与 `GET /health/ready`：不调用百炼。
+
+公共 API 不把 Model Gateway 的内部 401/403 原样返回浏览器；这类错误统一映射为可观测的 503 配置故障。429、timeout、5xx 和非法响应分别映射为稳定、脱敏的错误码。首个输出之后不得自动重试 Chat，避免重复文本。
+
+## 被否决方案
+
+1. **API 直接挂 Key 与 egress：** 数据库感知进程同时拥有数据、模型凭据和公网出口。
+2. **Worker 直接调用百炼：** 会形成两个供应商调用实现和两个 Key 边界。
+3. **Model Gateway 连接数据库验证审批：** 重新形成“数据 + Key + egress”的高风险组合。
+4. **只依赖 Docker DNS 或来源 IP：** 网络成员不是应用层身份，不能替代内部令牌。
+5. **引入通用 API Gateway、Redis、Celery 或服务网格：** 当前单机毕设规模没有足够收益，并增加部署与恢复面。
+
+## 后续约束
+
+- `provider-smoke` 与真实 seed 必须使用 Model Gateway 客户端，不允许恢复直连百炼旁路。
+- 普通在线查询只能使用知识库已激活的 embedding profile；Fake 与 Bailian profile 永不混查。
+- Docker bridge 不是域名白名单。生产环境仍需主机防火墙或出口代理只放行获批的百炼域名。
+- 改变模型调用者、内部鉴权、网络成员、Key 边界或 SSE 协议时，必须更新本 ADR 并重跑容器网络、Secret、取消和错误脱敏验收。
+
+## 验证要求
+
+- Compose 合同证明百炼 Key 与 `egress` 只存在于 `model-gateway`。
+- Model Gateway 无数据库 Secret、`data` 网络、上传卷和宿主端口；API/Worker 无百炼 Key和 `egress`。
+- 缺失/错误令牌、调用者冒充、scope 越权、URL/模型/维度注入均有失败测试。
+- Embedding、Rerank、Chat 的成功、401、429、timeout、5xx、非法响应、SSE 取消均由 hermetic contract test 覆盖。
+- `make verify`、镜像 Secret 扫描、Docker 健康检查、网络隔离与真实三模型 smoke 全部通过后，才能宣称在线百炼模型边界可用。

docs/adr/README.md

@@ -8,3 +8,4 @@ ADR 用于记录会长期影响系统的技术决策。状态使用 `proposed`
 - [0002-separate-bailian-protocols.md](0002-separate-bailian-protocols.md)：分离百炼 Chat/Embedding 与 Rerank 协议适配器。
 - [0003-text-first-scope.md](0003-text-first-scope.md)：第一版采用文本优先边界，不宣称地质图空间理解。
 - [0004-secretless-web-ingress.md](0004-secretless-web-ingress.md)：用无 Secret 的 Nginx Web 与固定上游 gateway 隔离浏览器、API 和数据库网络。
+- [0005-isolate-model-egress.md](0005-isolate-model-egress.md)：用独立 Model Gateway 隔离百炼 Key、模型出口与数据库感知服务。