Codex
52 lines
3.1 KiB
Markdown
52 lines
3.1 KiB
Markdown
# v0.2 Codex API Forwarder 稳定外部通道规格
|
||
|
||
`hwlab-codex-api-forwarder` 是 `hwlab-cloud-api` Pod 内的本地 sidecar，监听 `127.0.0.1:49280/responses`，为 Code Agent `codex-api` provider profile 提供到 hyueapi Responses upstream 的直连 HTTP 转发通道。它没有独立 Kubernetes Service，但属于 v02 稳定外部 provider 通道的一部分。
|
||
|
||
## 在系统中的职责划分
|
||
|
||
- 为 `hwlab-cloud-api` 中的 `codex-api` profile 提供 OpenAI Responses 兼容上游，不经过 `hwlab-deepseek-proxy`。
|
||
- 保证 `hyueapi.com` / `.hyueapi.com` 保留在 `NO_PROXY` / `no_proxy` 中，避免被 G14 proxy 或其他 egress 配置劫持。
|
||
- 只在同 Pod loopback 暴露，不向 ClusterIP、公网、浏览器或普通用户开放。
|
||
- 使用同一个 Code Agent provider SecretRef 注入鉴权材料，但自身不记录或打印 Secret 值。
|
||
|
||
## 内部架构
|
||
|
||
- `cmd/hwlab-codex-api-responses-forwarder/main.ts` 启动 HTTP proxy。
|
||
- listen host 默认 `127.0.0.1`，端口默认 `49280`。
|
||
- upstream 默认 `https://hyueapi.com`，可由 `HWLAB_CODE_AGENT_CODEX_API_UPSTREAM_BASE_URL` 覆盖。
|
||
- forwarder 会过滤 hop-by-hop headers、限制请求体大小，并按 upstream base path 规范化 `/v1/responses`、`/v1/models` 等路径。
|
||
|
||
## API 接口说明
|
||
|
||
| 接口 | 说明 |
|
||
| --- | --- |
|
||
| `GET /health`、`GET /health/live`、`GET /health/liveliness` | 本地 forwarder 存活检查，返回 upstream host 和 required NO_PROXY entries。 |
|
||
| `GET /health/readiness` | 本地 readiness，不证明 upstream provider 鉴权可用。 |
|
||
| `POST /v1/responses` | Codex API profile 的 Responses 请求代理入口。 |
|
||
| `GET /v1/models` | 按 upstream base path 代理模型列表请求。 |
|
||
|
||
## 测试规格
|
||
|
||
## T1
|
||
|
||
阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：在 `hwlab-cloud-api` Pod 内访问 `127.0.0.1:49280/health/live`，确认 `upstream.host` 为 hyueapi 域名，且 `NO_PROXY` / `no_proxy` 包含 `hyueapi.com` 和 `.hyueapi.com`。
|
||
|
||
## T2
|
||
|
||
阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/agent/chat` 指定 `codex-api` provider profile 做短连接聊天，只有 result completed 且 assistant reply 非空才算 provider 通道通过。
|
||
|
||
## T3
|
||
|
||
阅读 docs/reference/spec-v02-codex-api-forwarder.md，然后用 cli 手动测试以下内容：确认该 forwarder 没有独立 Kubernetes Service，也没有公网端口；所有调用都应来自同 Pod `hwlab-cloud-api`。
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| loopback Responses forwarder | 已实现 | `hwlab-cloud-api` Pod sidecar 监听 `127.0.0.1:49280`。 |
|
||
| hyueapi direct NO_PROXY | 已实现/持续约束 | forwarder 启动时合并 required NO_PROXY entries。 |
|
||
| health/readiness | 已实现 | health 返回 upstream 和 no_proxy 信息。 |
|
||
| provider auth 真实验收 | 已实现/持续约束 | 必须通过 `/v1/agent/chat` 短连接 result 判定。 |
|
||
| 独立 Service/公网暴露 | 不采用 | 只能由同 Pod loopback 调用。 |
|
||
|