pikasTech-HWLAB/docs/reference/spec-v02-hwlab-edge-proxy.md

# 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 为准。
- Pod readiness/liveness 必须使用 edge 自身 `/health`，不能使用会依赖 upstream 的 `/health/live`，避免 cloud-api 短暂不可用时把 edge-proxy 自身杀成 CrashLoop。
- `/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 承担。 |