# 网关出站通道规划（反转连接方向）

取代 `realtime-event-push-plan.md` 的通道方向设计。该文档的事件采集、订阅管理、确认语义继续有效；传输层按本文反转。

## 前提修正

平台部署在公网，网关部署在用户内网（NAT 后，公网入站不可达）。"后台拨号连网关"（HTTP 直连与 `/v1/channel` WS）在真实部署形态下不可行。只有网关能出站连接平台。

## 目标形态

- 平台为每个网关签发 `access_key`（网关管理页生成、明文回显供配置）。
- 网关进程通过环境变量/启动参数配置平台地址与 key，主动出站建立 WS 连接（`/v1/agent`），断线自动重连（退避）。
- 平台与网关的全部业务通信复用这一条网关发起的连接；旧 HTTP 直连、定时探活整体删除，不留回退。
- 局域网部署同样成立（网关连平台的内网地址），一套模型覆盖所有形态。

## 通道消息

平台 ⇄ 网关帧（JSON，单条连接按网关隔离）：

| 方向 | 类型 | 说明 |
| --- | --- | --- |
| 网关→平台 | `hello` | 认证（连接层 Bearer key）后首帧：网关版本、能力 |
| 网关→平台 | `heartbeat` | 周期健康上报：版本、运行中浏览器数；平台据此维护 online/last_seen_at |
| 平台→网关 | `task` | `{id, method, path, payload}`，method/path 复用原 HTTP 语义 |
| 网关→平台 | `result` | `{id, status, body, error}`；网关对重复 task id 幂等拒绝 |
| 网关→平台 | `event` | 事件投递批次（原 deliveries 语义，含 subscription/alias） |
| 平台→网关 | `event_ack` | 平台事务保存成功后确认；未确认批次网关保留、重连后重推 |

## 统一任务模型

所有后台→网关通信都是持久化任务（`gateway_task` 表）：

- 同步操作（前端按钮触发）：创建任务 → 网关在线则下发并等待 result（超时明确失败）→ 返回调用方。**网关离线时同步操作立即失败并提示，不入队等待**。
- 异步任务（采集、事件类）：创建任务 → 积压；下发器按网关分组、按 id 序补发，网关上线后执行。
- 下发后连接中断的任务标记 `failed`（连接中断，结果未确认），不自动重发有副作用的操作；仍为 `pending` 的任务继续等待。
- 全量任务即执行记录：方法/路径、状态、错误、响应码、耗时；响应体不落库（结果语义在业务表中）。保留策略后续再定（TODO）。

## 数据库（迁移 1058）

- `gateway`：删除 `endpoint`/`health_status`/`last_check_reason`/`last_checked_at`；新增 `access_key`、`online`、`last_seen_at`、`version`。
- 新表 `gateway_task`：`gateway_id`、`method`、`path`、`payload jsonb`、`status(pending|dispatched|succeeded|failed)`、`response_status`、`error`、`response_bytes`、`timeout_seconds`、创建/下发/完成时间。
- `browser_env.gateway_id` 等关联不变；账号与网关的绑定关系不变。

## 平台侧

- fiber `/v1/agent` WS 升级（fasthttp/websocket），连接层 key 认证，单网关单连接会话注册表。
- `gatewayCall`/`gatewayCallWithLimit` 实现替换为「创建任务 + 等待 result」，签名不变，全部业务调用点代码不动。
- 事件流：session 收 `event` 帧按 alias 路由到监听 worker，worker 事务保存后回 `event_ack`；原 `/v1/channel` 拨号代码删除。
- 健康状态由会话维护（在线/离线/从未连接），定时探活代码删除。

## 网关侧

- 新增出站 agent：连接、认证、重连退避、心跳线程、任务分发线程池、事件推送线程（复用 SubscriptionManager 变更通知与未确认重推）。
- `_route` 业务分发逻辑抽为纯函数供任务分发调用；HTTP 监听（含 `/healthz`、`/v1/channel`）整体删除；`proxy.py` 数据面保留。
- 配置：`CREATOR_PLATFORM_URL`、`CREATOR_GATEWAY_KEY` 环境变量（启动参数等价）。

## 前端（网关管理）

- 创建/编辑：名称 + 生成/重置 key（回显平台地址与 key 的配置指引）。
- 列表：在线状态（在线/离线/从未连接）、版本、任务队列 pending 计数。
- 执行记录：每网关任务列表分页（时间、方法+路径、状态 Tag、耗时、错误）。

## 测试与完成标准

- Go：认证/会话/心跳、任务下发等待超时、离线失败、断线中断、pending 补发、result 落库、event 路由与 ack；race 检查。
- Python：出站连接、认证失败、重连、task 分发（含重复 id 幂等）、result 回传、event 推送与未确认重推、心跳。
- Web：网关管理改造、执行记录分页；antd lint 清零、build 通过。
- 迁移 1058：新库、旧库升级、重复启动三态验证。
- 单元覆盖率 ≥ 65%；不编写/运行 E2E。