Edu/docs/modules/push-gateway/README.md

push-gateway 推送网关服务

版本：0.1（骨架） 日期：2026-07-07 状态：P5 待交付 关联文档：架构影响地图

---

1. 模块职责

push-gateway 是实时推送基础设施服务（Go 实现），管理 WebSocket/SSE 长连接。 接收 msg 服务的推送请求，维护用户在线连接池，将消息实时投递到浏览器/移动端。 支持连接鉴权、心跳保活、断线重连、多设备同步、连接数监控。

---

2. 技术栈

类别	技术	版本	用途
语言	Go	1.22+	高并发长连接
Web 框架	Gin	1.10+	HTTP 升级 WebSocket
WebSocket	gorilla/websocket	1.5+	WebSocket 协议
缓存	Redis	7.x	在线连接表、pub/sub
配置	viper	1.18+	配置注入
日志	zap	1.27+	结构化日志
追踪	OpenTelemetry	1.24+	分布式追踪
编排	Kubernetes	1.28+	生产部署

---

3. 架构图

graph TB
    MSG[msg 服务] -->|gRPC Push| PG[push-gateway]
    PG --> HUB[ConnectionHub<br/>连接池管理]
    HUB --> C1[用户 1 连接]
    HUB --> C2[用户 2 连接]
    HUB --> CN[用户 N 连接]
    PG -->[(Redis<br/>在线连接表 + pub/sub)]
    MFE[微前端] -.WebSocket.-> PG
    PG --> HEART[心跳保活<br/>30s ping/pong]

待 P5 交付时补充完整的分层架构图与多副本连接同步图。

---

4. 核心流程图

sequenceDiagram
    participant U as 用户
    participant PG as push-gateway
    participant R as Redis
    participant MSG as msg 服务

    U->>PG: WebSocket 连接 + JWT 鉴权
    PG->>R: 注册在线连接（userId → nodeId）
    PG-->>U: 连接建立
    Note over PG: 心跳保活 30s ping/pong

    MSG->>PG: gRPC Push(userId, payload)
    PG->>R: 查询 userId 在线 nodeId
    alt 本节点在线
        PG->>U: WebSocket 推送消息
    else 跨节点在线
        PG->>R: pub/sub 转发到目标节点
        R->>PG: 目标节点订阅收到
        PG->>U: 推送消息
    end

待 P5 交付时补充：断线重连流程、多设备同步流程、连接数监控流程。

---

5. 对外契约

• gRPC 服务：PushService（Push、Broadcast、GetOnlineStatus）（待 P5 定义 protobuf）
• HTTP 端点：/ws（WebSocket 升级）、/healthz、/readyz、/metrics
• 事件：不发布也不消费 Kafka 事件，仅接收 msg 的 gRPC 推送调用
• Redis 协议：在线连接表（HASH）、跨节点推送（pub/sub channel push:{nodeId}）

待 P5 交付时补充完整 protobuf 定义与 WebSocket 消息协议。

---

6. 依赖关系

• 上游：msg 服务（gRPC Push 调用）
• 下游：Redis（在线连接表、pub/sub 跨节点同步）
• 客户端：teacher-portal、student-portal、parent-portal（WebSocket 连接）
• 共享包：shared-proto、shared-go

---

7. 架构约束

1. 无业务逻辑，仅做连接管理与消息转发
2. 多副本部署下，通过 Redis pub/sub 同步跨节点推送
3. 连接鉴权必须校验 JWT，禁止未认证连接
4. 心跳超时 60s 无响应则断开连接
5. 单节点最大连接数 50k，超出时拒绝新连接

待 P5 交付时补充完整约束清单。

---

8. 架构决策

待 P5 交付时补充 ADR 记录，预计包括：Go+gorilla/websocket 选型、Redis pub/sub 跨节点方案、连接数上限策略、心跳间隔选型。