UniDesk
110 lines
4.6 KiB
Markdown
110 lines
4.6 KiB
Markdown
# Pipeline v2 Model Proxy Architecture
|
||
|
||
Pipeline v2 procedure runner 通过 model proxy 链路将容器内 OpenCode 的模型请求路由到外部 API 提供商。本文档记录 proxy 链路的稳定架构、各 model 组件的差异和 D601 宿主服务部署约束。
|
||
|
||
## Proxy Chain 总体架构
|
||
|
||
```text
|
||
OpenCode (container)
|
||
↓ HTTP (127.0.0.1:17655)
|
||
In-container model proxy (opencodeContainerHarness)
|
||
↓ HTTP/HTTPS
|
||
Upstream origin (per model config)
|
||
↓ (if host proxy)
|
||
External API provider (HTTPS)
|
||
```
|
||
|
||
每个 model 组件在 `config.json` 的 `proxy` 字段声明 in-container proxy 的监听端口和上游地址。OpenCode 的 provider config 中 `baseUrl` 固定指向 `http://127.0.0.1:{proxy.port}/{path}`，由 harness 在容器启动时写入。
|
||
|
||
In-container proxy 的职责：
|
||
- 注入 auth token（从容器环境变量读取，按 `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` 优先级查找）
|
||
- 429 rate limit 自动重试与 quota pause 计时（暂停时间不计入 node active timeout）
|
||
- 请求/响应透传（streaming 兼容）
|
||
|
||
## Model 组件 Proxy 配置对比
|
||
|
||
| Model | proxy.upstreamOrigin | 宿主服务 | Auth env |
|
||
|-------|---------------------|----------|----------|
|
||
| `minimax-m27` | `https://api.minimaxi.com` | 无（容器直连） | `ANTHROPIC_AUTH_TOKEN` |
|
||
| `gpt-5.5` | `http://host.docker.internal:17680` | `hyueapi-proxy.service` | `OPENAI_API_KEY` |
|
||
|
||
### minimax-m27（直连模式）
|
||
|
||
容器内 proxy 直接 HTTPS 连接 `api.minimaxi.com`，无需宿主中间层。适用于上游 API 不需要 Host header 覆盖或 TLS SNI 特殊处理的场景。
|
||
|
||
### gpt-5.5（宿主 proxy 模式）
|
||
|
||
容器内 proxy 通过 Docker `host.docker.internal` 连接宿主 port 17680 的 HTTP reverse proxy，由宿主 proxy 完成 HTTP→HTTPS 升级和 `Host: hyueapi.com` header 注入。
|
||
|
||
两跳设计原因：hyueapi.com 使用 Cloudflare，要求 TLS SNI 与 Host header 匹配；容器内 Node.js HTTP proxy 只做 HTTP 转发，TLS 终止由宿主 proxy 完成，避免容器内处理 Cloudflare 证书验证和 SNI 问题。
|
||
|
||
## D601 宿主 hyueapi-proxy 服务
|
||
|
||
部署路径：`~/pipeline/services/hyueapi-proxy/proxy.mjs`
|
||
|
||
systemd user service：`~/.config/systemd/user/hyueapi-proxy.service`
|
||
|
||
```bash
|
||
# 状态检查
|
||
systemctl --user status hyueapi-proxy.service
|
||
|
||
# 重启
|
||
systemctl --user restart hyueapi-proxy.service
|
||
|
||
# 验证（需要 auth）
|
||
KEY=$(cat ~/pipeline/.state/secrets/gpt-5.5/OPENAI_API_KEY)
|
||
curl -H "Authorization: Bearer $KEY" http://127.0.0.1:17680/v1/models
|
||
```
|
||
|
||
服务行为：
|
||
- 监听 `0.0.0.0:17680`（容器通过 `host.docker.internal` 访问）
|
||
- 上游 `hyueapi.com:443`（HTTPS）
|
||
- 覆盖 `Host` header 为 `hyueapi.com`
|
||
- 透传所有其他 header（包括 `Authorization`）
|
||
- 无认证、无缓存、无日志（生产态）
|
||
|
||
## Harness Token 注入规则
|
||
|
||
`scripts/src/opencodeContainerHarness.ts` 中 in-container proxy 的 token 查找顺序：
|
||
|
||
```
|
||
ANTHROPIC_AUTH_TOKEN → ANTHROPIC_API_KEY → OPENAI_API_KEY
|
||
```
|
||
|
||
model 组件的 `auth.envNames` 声明注入到容器的环境变量名。对于 OpenAI-compatible 提供商（如 gpt-5.5），`envNames` 必须包含 `OPENAI_API_KEY`，harness 才能在 proxy 层自动注入 Bearer token。
|
||
|
||
## Smoke Test 验证
|
||
|
||
每个 model 组件应配套一个 smoke-test pipeline 用于验证端到端连通性：
|
||
|
||
```text
|
||
components/pipeline/gpt-5.5-smoke-test/config.json
|
||
components/procedure/gpt-5.5-smoke-connectivity/config.json
|
||
```
|
||
|
||
Smoke test 验证链路：
|
||
1. 容器启动，harness 写入 OpenCode provider config 并启动 in-container proxy
|
||
2. OpenCode server 启动，harness 创建 session 并发送 prompt
|
||
3. 模型通过 proxy chain 完成请求（`POST /v1/responses`）
|
||
4. 模型执行任务并通过 OA skill 提交 `benchmark-repair-result-v1`
|
||
5. Harness 验证 OA submission 存在且 container exit code = 0
|
||
|
||
运行方式：
|
||
```bash
|
||
cd ~/pipeline
|
||
npx tsx scripts/pipeline-cli.ts procedure start \
|
||
--pipeline gpt-5.5-smoke-test \
|
||
--node smoke \
|
||
--task "Connectivity test: ..."
|
||
```
|
||
|
||
## 新增 Model 组件检查清单
|
||
|
||
1. 创建 `components/model/{id}/config.json`，声明 `opencode`、`auth`、`proxy` 和 `runtimeEnv`
|
||
2. 创建 `.state/secrets/{id}/{ENV_NAME}` 存放 API key
|
||
3. 如果上游需要 Host header 覆盖或 TLS 特殊处理，部署宿主 proxy 服务并将 `proxy.upstreamOrigin` 指向 `http://host.docker.internal:{port}`
|
||
4. 确认 `auth.envNames` 中的变量名在 harness token 查找链中（当前支持 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`）
|
||
5. 创建 smoke-test pipeline 和 procedure 组件
|
||
6. 运行 smoke test 验证端到端连通性
|
||
7. 提交到 pipeline 仓库
|