# push-gateway 推送网关服务

> 版本：0.1（骨架）
> 日期：2026-07-07
> 状态：P5 待交付
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)

---

## 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. 架构图

```mermaid
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. 核心流程图

```mermaid
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 跨节点方案、连接数上限策略、心跳间隔选型。