Codex
48 lines
2.2 KiB
Markdown
48 lines
2.2 KiB
Markdown
# v0.2 hwlab-edge-proxy 服务规格
|
||
|
||
`hwlab-edge-proxy` 是 v02 API 公网入口的内部 edge proxy，运行在 `hwlab-v02` namespace，内部端口 `6667`。FRP `19667` 转发到该服务。
|
||
|
||
## 在系统中的职责划分
|
||
|
||
- 接收 FRP 转入的 API/health 请求，并代理到 `hwlab-cloud-api:6667`。
|
||
- `/health/live` 必须透传 cloud-api live health，因此公网 API readiness 以 cloud-api 为准。
|
||
- `/v1/internal/*` 是集群内部服务路由，必须在 public edge 上 fail-closed，不透传到 cloud-api。
|
||
- 不实现业务 API，不读取 Secret，不替代 cloud-api 权限和 runtime readiness。
|
||
|
||
## 内部架构
|
||
|
||
- `cmd/hwlab-edge-proxy/main.ts` 启动 HTTP server。
|
||
- `internal/dev-entrypoint/http.mjs` 的 `proxyHttpRequest` 负责 streaming proxy、timeout 和错误 payload。
|
||
- `HWLAB_EDGE_UPSTREAM` 指向 v02 `hwlab-cloud-api` ClusterIP；`HWLAB_EDGE_PROXY_TIMEOUT_MS` 控制长 Code Agent 请求代理窗口。
|
||
|
||
## API 接口说明
|
||
|
||
| 接口 | 说明 |
|
||
| --- | --- |
|
||
| `GET /health/live` | 代理到 upstream `/health/live`，代表公网 API live readiness。 |
|
||
| `GET /health`、`GET /edge/health` | 返回 edge-proxy 自身 health 和 upstream 配置。 |
|
||
| `GET /status`、`GET /routes` | 返回代理路由表。 |
|
||
| `/v1/internal/*` | 公网 edge 返回 `404`，不代理内部服务路由。 |
|
||
| 其他路径 | 透明代理到 `hwlab-cloud-api`。 |
|
||
|
||
## 测试规格
|
||
|
||
## T1
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-edge-proxy.md，然后用 cli 手动测试以下内容：访问 `http://74.48.78.17:19667/health/live`，确认响应是 cloud-api payload 且 `environment=v02`。
|
||
|
||
## T2
|
||
|
||
阅读 docs/reference/spec-v02-hwlab-edge-proxy.md，然后用 cli 手动测试以下内容：访问 edge-proxy `/status` 或 `/routes`，确认 upstream 指向 `hwlab-cloud-api.hwlab-v02.svc.cluster.local:6667`。
|
||
|
||
## 规格的实现情况
|
||
|
||
| 规格项 | 状态 | 说明 |
|
||
| --- | --- | --- |
|
||
| API edge proxy | 已实现 | 用户态路径透明代理 cloud-api。 |
|
||
| live health 透传 | 已实现 | `/health/live` 代理 upstream。 |
|
||
| internal route 阻断 | 已实现 | `/v1/internal/*` 不经 public edge 暴露。 |
|
||
| 长请求 timeout | 已实现 | 默认支持 Code Agent 长窗口。 |
|
||
| 业务权限/鉴权 | 不在本服务 | 由 cloud-api 承担。 |
|
||
|