docs: document codex-api provider diagnostics
This commit is contained in:
Codex
@@ -25,15 +25,19 @@ stdio session supervisor，并证明 `/workspace/hwlab` 可读写、`CODEX_HOME=
|
||||
可创建和复用同一个 Codex thread/session。
|
||||
|
||||
Codex token boundary 仍由授权路径把 `OPENAI_API_KEY` 注入到 DEV runtime。DEV Pod
|
||||
必须使用 `HWLAB_CODE_AGENT_OPENAI_BASE_URL` 指向受控 DEV egress/proxy 路径，不能
|
||||
直接指向 public `api.openai.com`。G14 默认 `deepseek` profile 指向
|
||||
不能直接指向 public `api.openai.com`。G14 默认 `deepseek` profile 指向
|
||||
`http://hwlab-deepseek-proxy.<namespace>.svc.cluster.local:4000/v1/responses`；该
|
||||
Service 必须先进入 `hwlab-deepseek-responses-bridge`，由 bridge 解压 Codex
|
||||
Responses 的 zstd request body、规范化 `/v1/models` 返回、丢弃非 `function` tool，
|
||||
再转发到同 Pod 内 Moon Bridge 4001。Moon Bridge 是 DeepSeek profile 的真实
|
||||
Responses 转换和 prompt cache 保留层；不要在 HWLAB 中手写完整转换器替代它。
|
||||
`codex-api` profile 仍可指向
|
||||
`http://172.26.26.227:17680/v1/responses` 作为旧 Responses 通道。
|
||||
`codex-api` profile 是独立的 Codex/OpenAI-compatible Responses 通道。G14 上
|
||||
`hwlab-cloud-api` 应把 `codex-api` base URL 指向同 Pod 的 `127.0.0.1` loopback
|
||||
forwarder；forwarder 再直连 `hyueapi.com` / `.hyueapi.com`，并把这两个域名显式保留在
|
||||
`NO_PROXY` / `no_proxy`。这不是 DeepSeek bridge，也不是公网 `api.openai.com`，不能把
|
||||
hyueapi 流量改成 HTTP/SOCKS proxy。`http://172.26.26.227:17680/v1/responses` 只能作为
|
||||
D601 legacy Code Queue runner 或历史 egress 的对照线索；迁移到 G14 后不得把它当作
|
||||
G14 默认 `codex-api` base URL，也不得用 DeepSeek bridge 伪装 `codex-api` 通过。
|
||||
|
||||
Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入，
|
||||
`provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为
|
||||
@@ -43,6 +47,103 @@ Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime
|
||||
DEV egress/base-url 合同是否声明和保留；不得读取 Secret data，也不得把 Secret 值写入
|
||||
report、issue、PR 或截图。
|
||||
|
||||
## Provider 切换排查方法论
|
||||
|
||||
Provider/profile 切换故障必须先在目标 pod/host 上打通最小真实闭环，再进入完整 CI/CD、
|
||||
GitOps render 或正式发布。`deepseek`、`codex-api` 和未来 provider 共享 cloud-api 会话与
|
||||
Workbench UI，但排查时必须把 profile overlay、认证、网络、模型、Codex CLI/app-server
|
||||
逐层拆开，避免用一个 profile 的成功掩盖另一个 profile 的退化。
|
||||
|
||||
最小闭环按以下顺序分层，任何一层失败都不能跳到正式 CI/CD 试错：
|
||||
|
||||
1. 运行面确认：在 G14 `/root/hwlab` 与 G14 k3s 目标 pod 内确认当前分支、镜像、env overlay、
|
||||
`CODEX_HOME`、Codex 版本和 workspace；D601 只能作为 legacy 对照，不作为 G14 source truth。
|
||||
2. 凭证边界：只检查 Secret 引用、`auth.json` 顶层 key 和值长度，不打印 secret。Codex CLI 的
|
||||
`auth.json` 应能暴露 `OPENAI_API_KEY` 顶层 key；形如 `auth` 的不明结构必须先按 blocker 处理。
|
||||
3. 直连边界：`hyueapi.com` / `.hyueapi.com` 必须在 `NO_PROXY` 与 `no_proxy` 内。需要同时检查
|
||||
shell env 和 Codex/Rust trace；若 trace 显示 `network_proxy: None` 且直接连接 `hyueapi.com:443`，
|
||||
不能再把问题归类为 proxy 污染。
|
||||
4. 裸 Responses API：在同一个目标 pod 内用同一份 auth、同一模型、同一 base host 发
|
||||
`/responses` 或 `/v1/responses` 流式请求，确认网络、认证和模型是否可用。裸 API 通过只证明
|
||||
upstream 可达，不等于 Workbench 或 Codex runner 通过。
|
||||
5. Codex CLI 对照：用同一模型、同一 `CODEX_HOME`、同一 prompt 运行 `codex exec --json`；同时在
|
||||
D601 Code Queue runner 上做同模型对照，记录版本、config 形态、NO_PROXY、proxy env 和 transport
|
||||
摘要。D601 对照只用于定位差异，不能把 D601 路径写回 G14 默认运行态。
|
||||
6. Loopback forwarder 对照：如果裸 Responses API 通过、Codex CLI 直连失败，并且 trace 已确认
|
||||
`network_proxy: None`，必须在同一个目标 Pod 内增加只监听 `127.0.0.1` 的临时 forwarder，使用同一份
|
||||
auth、同一模型和同一 prompt 复测 `codex exec` 与 `/v1/agent/chat`。forwarder 只能把流量转到可配置的
|
||||
hyueapi upstream，不能硬编码 D601 IP，也不能复用 DeepSeek bridge。
|
||||
7. App-server 闭环：最终证据必须来自 repo-owned Codex app-server stdio 或明确批准的等价
|
||||
long-lived runner，返回 `completed` 且 `reply.content` 非空。Node/raw HTTPS、stub、bridge、
|
||||
source-only smoke、前端状态都不能升级成 DEV-LIVE reply pass。
|
||||
|
||||
排查记录应保留稳定结论和判定方法，不写 Secret、一次性 trace 全文或日期化流水账。遇到
|
||||
“裸 API 通过但 Codex CLI/app-server 失败”时，优先抓 Codex/Rust transport 日志并与 D601 成功
|
||||
路径比对：模型、service tier、`auth.json` 结构、base URL、是否直连、实际连接 IP、请求体大小、
|
||||
SSE 是否 completed。只有这些证据归一后，才修改源码、render、SecretRef 或发布配置。
|
||||
|
||||
## Codex API 转发根因
|
||||
|
||||
`codex-api` 在 G14 上采用 pod-local loopback forwarder 是一个受控传输边界修复，不是为了规避
|
||||
hyueapi 直连要求。根因判定按以下证据链成立：
|
||||
|
||||
- 同一目标 Pod 内，使用同一份 auth、同一模型、同一 Responses payload，通过 Node HTTPS 直接请求
|
||||
`hyueapi.com` 能获得完整 SSE `response.completed`；这排除了模型、Secret、请求体、基本网络可达性和
|
||||
hyueapi 账号本身不可用。
|
||||
- 同一目标 Pod 内，Codex CLI/Rust 传输直连 `https://hyueapi.com/responses` 会在 streaming 阶段断开；
|
||||
Rust trace 显示 `network_proxy: None` 且连接目标是 `hyueapi.com:443`，这排除了全局 proxy 污染和
|
||||
`NO_PROXY` 未生效作为主因。
|
||||
- 把 Codex CLI 的 base URL 改为同 Pod `127.0.0.1`，再由 Node forwarder 使用直连 HTTPS 转发到
|
||||
hyueapi，`codex exec` 与 `/v1/agent/chat` 均能完成并返回非空 assistant 回复；这把失败边界收敛到
|
||||
Codex CLI 的 Rust HTTPS/SSE transport 与 G14->hyueapi 边缘路径组合，而不是 Workbench、DeepSeek、
|
||||
模型或 auth。
|
||||
- D601 Code Queue runner 使用同模型可成功，只能证明 D601 legacy 路径可作为对照；不能把
|
||||
`172.26.26.227:17680` 写回 G14 默认配置。
|
||||
|
||||
因此，在不修改 Codex CLI 二进制、不要求 hyueapi 改边缘行为、也不把 hyueapi 流量送进 HTTP/SOCKS
|
||||
proxy 的前提下，pod-local Node forwarder 是当前可控的最小修复。它的职责只是替换 Codex CLI 失败的
|
||||
直接 HTTPS/SSE transport；hyueapi 仍由 forwarder 进程直连，`hyueapi.com` / `.hyueapi.com` 仍必须在
|
||||
`NO_PROXY` 和 `no_proxy` 中。
|
||||
|
||||
## 转发器迁移与隔离
|
||||
|
||||
Codex API forwarder 必须是 Pod 内部能力，推荐作为 `hwlab-cloud-api` 同 Pod sidecar 或等价的同 Pod
|
||||
受控进程运行。`hwlab-cloud-api` 只连接 `http://127.0.0.1:<port>`；forwarder 通过 env 配置 upstream，
|
||||
默认 upstream host 为 `hyueapi.com`。以下约束保证它可迁移且不会污染其他运行面：
|
||||
|
||||
- 禁止硬编码 provider host IP、D601 `172.26.26.227`、G14 节点 IP、namespace 名或 NodePort。可配置项只应是
|
||||
loopback listen port、upstream base URL、模型 profile env 和 Secret 引用。
|
||||
- forwarder 不创建 Kubernetes Service、Ingress、NodePort 或 host port；它只监听 Pod network namespace 内的
|
||||
`127.0.0.1`。同一 k3s 集群内 `hwlab-dev`、`hwlab-prod` 或其他 namespace 可以同时各自运行一个
|
||||
`hwlab-cloud-api` Pod 和同端口 forwarder，因为每个 Pod 都有独立 loopback。
|
||||
- 不要给 `hwlab-cloud-api` Pod 启用 `hostNetwork` 来承载 forwarder。若某个迁移目标必须使用 hostNetwork，
|
||||
必须重新评估端口冲突和隔离边界，不能沿用“Pod 内同端口无冲突”的结论。
|
||||
- 迁移到其他 k3s 时，只需要保证目标 Pod 能直连 `hyueapi.com:443`、SecretRef 仍以 `OPENAI_API_KEY` 注入、
|
||||
`CODEX_HOME/auth.json` 形态正确、`NO_PROXY/no_proxy` 包含 `hyueapi.com` 与 `.hyueapi.com`，以及
|
||||
loopback forwarder 进程跟 `hwlab-cloud-api` 在同一 Pod network namespace。
|
||||
- DEV、PROD 和临时 smoke Pod 的证据必须分开记录。DEV forwarder 通过不能自动证明 PROD 通过；PROD
|
||||
需要在 PROD namespace 的目标 Pod 内复跑最小 `/v1/agent/chat` 闭环。
|
||||
|
||||
## 自动化兼容性
|
||||
|
||||
Forwarder 不需要人工维护长驻进程。正式固化后，它应由 Kubernetes Deployment 管理生命周期：Pod 创建时随
|
||||
`hwlab-cloud-api` 启动，Pod 删除时一起退出，异常退出由 kubelet 按 Pod/容器 restart policy 重启。人工只允许在
|
||||
临时 smoke Pod 中手动启动 forwarder 做分层诊断；运行态不应依赖手动 `kubectl exec` 后台进程。
|
||||
|
||||
自动化门禁只需要做合同级检查，不需要读取 Secret 或调用外部模型：
|
||||
|
||||
- desired state 中 `codex-api` profile base URL 指向 Pod-local loopback，不指向 D601 IP 或
|
||||
`api.openai.com`。
|
||||
- forwarder 的 upstream base URL 由 env 配置，默认 host 为 `hyueapi.com`，并且 `NO_PROXY/no_proxy`
|
||||
包含 `hyueapi.com` 与 `.hyueapi.com`。
|
||||
- `hwlab-cloud-api` Pod 模板包含 forwarder sidecar 或明确等价的同 Pod 受控进程；forwarder 不暴露
|
||||
Service、NodePort、Ingress 或 hostPort。
|
||||
- `deepseek` profile 仍指向 DeepSeek bridge/Moon Bridge；`codex-api` profile 不依赖 DeepSeek bridge。
|
||||
|
||||
完整 CI/CD、GitOps render 或发布流水线只能在目标 Pod 最小闭环已经通过、且当前 CI/CD 基础设施可用时继续。
|
||||
最小闭环没有通过时，不要通过反复推送 CI/CD 来探索 provider transport；CI/CD 只能固化已经在目标运行面证明可行的
|
||||
配置和代码。
|
||||
|
||||
## 判定标准
|
||||
|
||||
| 观测结果 | readiness |
|
||||
|
||||
Reference in New Issue
Block a user