2ba4250165
- monorepo: pnpm workspace + go.work + pyproject.toml + commitlint/husky - infra: docker-compose (minimal + full profiles) + init-sql + prometheus - arch-scan: multi-language scanner skeleton (TS/Go/Python/Proto) - shared-proto: buf v2 + classes.proto (ClassService CRUD contract) - api-gateway: Go/Gin + JWT HS256 auth + reverse proxy + request ID - classes: NestJS golden template (error system + observability + middleware + CRUD + tests) - teacher-portal: Next.js + paper-feel UI design system - CI/CD: 4 workflows (go/ts/py/proto) - docs: migration guide + project_rules + coding-standards + git-workflow + ui-design-system + 004 + 9 module READMEs + known-issues + spec/plan migration + roadmap
115 lines
3.4 KiB
Markdown
115 lines
3.4 KiB
Markdown
# 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 跨节点方案、连接数上限策略、心跳间隔选型。
|