creator-hub/docs/gateway-outbound-channel-plan.md

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

取代 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。