xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(push-gateway): config 扩展 + kafka consumer + ws handler + nextstep 文档

Browse Source
This commit is contained in:
SpecialX
2026-07-14 16:03:17 +08:00
parent 5a88c8b45d
commit 9fd7c018c2
8 changed files with 630 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

352
services/push-gateway/docs/nextstep-v2.md Normal file
View File

@@ -0,0 +1,352 @@
# push-gateway 模块上下游依赖与工作清单（Next Steps v2）
> 版本：v2
> 日期：2026-07-14
> 负责人：ai09
> 关联：
>
> - [push-gateway nextstep.md (v1)](./nextstep.md)
> - [msg nextstep.md](../../msg/docs/nextstep.md) §2.4 / §4
> - [student-bff nextstep-v2.md](../../student-bff/docs/nextstep-v2.md) §4.7/§4.8
> - [teacher-portal nextstep-v2.md](../../../apps/teacher-portal/docs/nextstep-v2.md) §3.2.3
> - ARB-013 Kafka topic 命名规范
---
## 1. 概述
push-gateway 是 Edu 平台的实时 WebSocket 推送基础设施（L3 网关层，端口 8081），负责维护用户在线连接、接收 msg 服务通过 HTTP `/internal/*` 和 Kafka 推送的消息、并通过 WebSocket 实时投递给在线客户端。
**v2 核心目标**：对齐 ARB-013 Kafka topic 命名规范和 msg 服务的 API 契约，消除 v1 中存在的 4 个不一致点。
---
## 2. v2 完成的工作（API 契约对齐）
### 2.1 Kafka topic 对齐（ARB-013）
| 项 | v1 | v2 | 状态 |
| ---------- | -------------------------------- | ---------------------------------------------- | ---- |
| 消费 topic | `edu.notification.requested` | `edu.notify.notification.sent` | ✅ |
| 命名规范 | 旧命名（违反 ARB-013） | `edu.<domain>.<aggregate>.<action>` | ✅ |
| DLQ topic | `edu.notification.requested.dlq` | `edu.notify.notification.sent.dlq`（自动派生） | ✅ |
**修改文件**：
- `internal/config/config.go`：`KAFKA_NOTIFICATION_TOPIC` 默认值改为 `edu.notify.notification.sent`
- `internal/kafkaconsumer/consumer.go`：包注释更新，metric label 使用 `event.EventType`（而非硬编码 "notification.requested"）
- `internal/config/config_test.go`：断言更新为新 topic 名
### 2.2 鉴权头对齐
| 项 | v1 | v2 | 状态 |
| -------- | -------------------- | -------------------------------------------------------------------- | ---- |
| 规范头名 | `X-Internal-Token` | `X-Internal-Key`（ARB-013 对齐 msg） | ✅ |
| 向后兼容 | — | 同时接受 `X-Internal-Token`（legacy alias） | ✅ |
| 环境变量 | `INTERNAL_API_TOKEN` | `PUSH_INTERNAL_TOKEN`（canonical）+ `INTERNAL_API_TOKEN`（fallback） | ✅ |
**修改文件**：
- `internal/ws/handler.go`：
- `internalTokenHeader` 常量改为 `X-Internal-Key`
- 新增 `legacyInternalTokenHeader = "X-Internal-Token"` 兼容别名
- `checkInternalToken()` 依次尝试两个头
- `internal/config/config.go`：优先读取 `PUSH_INTERNAL_TOKEN`，为空时回退到 `INTERNAL_API_TOKEN`
### 2.3 请求体字段命名对齐
| 项 | v1 | v2 | 状态 |
| ------------ | ------------------------ | --------------------------------------------------------- | ---- |
| 用户 ID 字段 | `user_id`（snake_case） | `userId`（camelCase，msg canonical）+ `user_id`（legacy） | ✅ |
| 其他字段 | `event` / `data` / `ttl` | 保持不变 | ✅ |
**修改文件**：
- `internal/ws/handler.go` `PushHandler()`：
- 结构体同时定义 `UserID json:"userId"` 和 `UserIDLeg json:"user_id"`
- 绑定后若 `UserID` 为空则回退到 `UserIDLeg`
### 2.4 环境变量对齐
| v1 环境变量 | v2 规范环境变量 | 兼容性 |
| --------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------- |
| `INTERNAL_API_TOKEN` | `PUSH_INTERNAL_TOKEN` | v1 变量作为 fallback 别名保留 |
| `KAFKA_NOTIFICATION_TOPIC`（默认 `edu.notification.requested`） | `KAFKA_NOTIFICATION_TOPIC`（默认 `edu.notify.notification.sent`） | 环境变量名不变，默认值更新 |
**修改文件**：
- `infra/docker-compose.deploy.yml`：push-gateway 段使用 `PUSH_INTERNAL_TOKEN`（支持 `${PUSH_INTERNAL_TOKEN:-${INTERNAL_API_TOKEN:-edu-internal-token}}` 回退链）
- `infra/deploy.env.example`：`PUSH_INTERNAL_TOKEN` 为规范变量，`INTERNAL_API_TOKEN` 标注为兼容别名
### 2.5 部署配置更新
| 文件 | 修改内容 |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| `infra/docker-compose.deploy.yml` | `KAFKA_NOTIFICATION_TOPIC: edu.notify.notification.sent`；`PUSH_INTERNAL_TOKEN` 带回退链 |
| `infra/deploy.env.example` | 新增 `PUSH_INTERNAL_TOKEN`，保留 `INTERNAL_API_TOKEN` 作为兼容别名（留空） |
---
## 3. 本地 Docker 验证结果（2026-07-14 v2）
测试环境：本地 Docker Desktop，`edu-full_default` 网络，接入真实 edu-kafka / edu-redis / edu-iam-test。
```
镜像：edu/push-gateway:test
容器：edu-push-gateway-test（DEV_MODE=true, PUSH_INTERNAL_TOKEN=test-internal-token-v2）
网络：edu-full_default（直连 edu-kafka:29092 / edu-redis:6379 / edu-iam-test:3002）
```
| 验证项 | 结果 | 说明 |
| --------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `go vet ./...` | ✅ | 零警告 |
| `go build ./...` | ✅ | 零错误 |
| `go test ./...` | ✅ | config/hub/ws 全部通过（含新增 `TestLoadProdModeLegacyToken`） |
| Docker 镜像构建 | ✅ | `edu/push-gateway:test` 构建成功 |
| `/healthz` | ✅ | `{"service":"push-gateway","status":"ok"}` |
| `/readyz` | ✅ | `degraded:false`，kafka+redis 均 ok |
| 容器日志确认 topic | ✅ | `kafka_topic=edu.notify.notification.sent` |
| **v2 契约：X-Internal-Key + userId** | ✅ | `POST /internal/push` 返回 `{"success":true}` |
| **v1 兼容：X-Internal-Token + user_id** | ✅ | 旧调用方式仍正常工作 |
| **Kafka 全链路：新 topic → WS** | ✅ | 发布到 `edu.notify.notification.sent` → WebSocket 客户端收到消息 |
| **考试事件透传（3 类）** | ✅ | ExamExtended / ExamForceSubmitted / ExamQuestionReordered 全部经 Kafka → WS 投递成功 |
| Prometheus metrics | ✅ | `push_gateway_kafka_consumed_total{topic="edu.notify.notification.sent"}` 计数正确；`push_gateway_messages_pushed_total{event="ExamExtended",result="delivered"}` 等标签正确 |
### 3.1 测试脚本
| 脚本 | 用途 |
| ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `services/push-gateway/scripts/test-kafka-ws.mjs` | 验证单条 Kafka 消息经 `edu.notify.notification.sent` topic 到达 WebSocket 客户端 |
| `services/push-gateway/scripts/test-exam-events.mjs` | 验证 3 类考试事件（ExamExtended/ExamForceSubmitted/ExamQuestionReordered）的 event_type 透传 |
运行方式（需在仓库根目录）：
```bash
# 前置：push-gateway 容器已启动并接入 edu-full_default 网络
node services/push-gateway/scripts/test-kafka-ws.mjs
node services/push-gateway/scripts/test-exam-events.mjs
```
---
## 4. 上游依赖（调用 push-gateway 的模块）
### 4.1 4 个前端 Portal（teacher/student/parent/admin）— P0
| Portal | WebSocket 接入状态 | v2 新增工作 | 状态 |
| -------------- | --------------------------------------------- | ----------- | ---- |
| teacher-portal | ✅ 已接入（`useNotificationsWebSocket` hook） | 无 | ✅ |
| student-portal | ✅ 已接入（考试事件监听） | 无 | ✅ |
| parent-portal | ✅ 已接入 | 无 | ✅ |
| admin-portal | ✅ 已接入 | 无 | ✅ |
**说明**：4 个 portal 在 v1 阶段已完成 WebSocket 接入，使用 `?token=<jwt>` query param 鉴权。v2 的 API 契约变更（Kafka topic / 鉴权头 / 请求体字段）对 portal 透明，无需 portal 侧改动。
### 4.2 3 个 BFF（teacher-bff / student-bff / parent-bff）— P1
| BFF | 依赖 push-gateway 的方式 | v2 新增工作 | 状态 |
| ----------- | ------------------------------------- | ----------- | ---- |
| teacher-bff | 无直接依赖（BFF 不调用 push-gateway） | 无 | ✅ |
| student-bff | 无直接依赖（BFF 不调用 push-gateway） | 无 | ✅ |
| parent-bff | 无直接依赖（BFF 不调用 push-gateway） | 无 | ✅ |
**说明**：BFF 层不直接调用 push-gateway。推送由 msg 服务通过 HTTP `/internal/push` 或 Kafka 发起，push-gateway 负责投递到 portal 的 WebSocket。
---
## 5. 下游依赖（push-gateway 调用的模块）
### 5.1 iam 服务（ai06 负责）— P0
| 依赖项 | 用途 | 状态 |
| ----------------------------------- | ------------------------------------- | --------- |
| `GET /v1/iam/.well-known/jwks.json` | RS256 JWKS 公钥（WebSocket JWT 验签） | ✅ 已就绪 |
**环境变量**：`JWKS_URL=http://iam:3002/v1/iam/.well-known/jwks.json`
**说明**：shared-go/jwks Fetcher 每 5 分钟刷新 JWKS 缓存。DevMode 接受 `dev-token` 旁路 JWT 验签。
### 5.2 msg 服务（ai10 负责）— P0
| 依赖项 | 用途 | 状态 |
| -------------------------------------------- | ------------------------------------------------- | --------- |
| HTTP `POST /internal/push` | 定向推送（msg → push-gateway） | ✅ 已对齐 |
| Kafka topic `edu.notify.notification.sent` | 事件驱动推送（msg Outbox → Kafka → push-gateway） | ✅ 已对齐 |
| 鉴权头 `X-Internal-Key: PUSH_INTERNAL_TOKEN` | /internal/* API 鉴权 | ✅ 已对齐 |
| 请求体 `{ userId, event, data }` | camelCase 字段命名 | ✅ 已对齐 |
**环境变量**：
- push-gateway 侧：`PUSH_INTERNAL_TOKEN`（canonical）/ `INTERNAL_API_TOKEN`（fallback）
- msg 侧：`PUSH_INTERNAL_TOKEN`（已对齐）
**v2 对齐结果**：4 个不一致点（Kafka topic / 鉴权头 / 请求体字段 / 环境变量）全部修复，push-gateway 同时保持对 v1 调用方式的向后兼容。
### 5.3 Redis（基础设施）— P0
| 依赖项 | 用途 | 状态 |
| ------------------------ | --------------------------------------------------- | --------- |
| `redis://edu-redis:6379` | 在线状态 SET + 跨实例 Pub/Sub 扇出 + 事件去重 SETNX | ✅ 已就绪 |
**环境变量**：`REDIS_URL=redis://edu-redis:6379/0`
### 5.4 Kafka（基础设施）— P0
| 依赖项 | 用途 | 状态 |
| ----------------- | ----------------------------------------- | --------- |
| `edu-kafka:29092` | 消费 `edu.notify.notification.sent` topic | ✅ 已就绪 |
**环境变量**：
- `KAFKA_BROKERS=edu-kafka:29092`
- `KAFKA_NOTIFICATION_TOPIC=edu.notify.notification.sent`（ARB-013）
- `KAFKA_CONSUMER_GROUP=push-gateway`
### 5.5 OTel Collector（基础设施）— P1
| 依赖项 | 用途 | 状态 |
| ---------------------------- | --------------- | --------- |
| `http://otel-collector:4318` | OTLP trace 上报 | ⏳ 待部署 |
**环境变量**：`OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318`
**说明**：未配置时 push-gateway 跳过 trace 上报，不影响功能。
---
## 6. 待协调事项（需上下游配合）
### 6.1 core-edu 考试事件发布（下游阻塞 student-portal）
| 项 | 详情 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 阻塞方 | core-edu（ai07） |
| 影响方 | student-portal / student-bff |
| 问题 | student-portal 期望接收 `ExamExtended` / `ExamForceSubmitted` / `ExamQuestionReordered` 三类考试事件，但这些事件在 core-edu 源码中未找到发布逻辑 |
| 期望流程 | core-edu Outbox publisher → Kafka `edu.notify.notification.sent` → push-gateway → student-portal WebSocket |
| push-gateway 侧状态 | ✅ 已验证可消费这三类事件并透传到 WebSocket（见 §3 测试结果） |
| 协调动作 | 请 core-edu 在考试相关业务逻辑中发布这三类事件到 `edu.notify.notification.sent` topic |
### 6.2 msg 服务 Outbox 发布 topic 对齐（待确认）
| 项 | 详情 |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| 阻塞方 | msg（ai10） |
| 问题 | 需确认 msg 的 Outbox publisher 已将发布 topic 从 `edu.notification.requested` 改为 `edu.notify.notification.sent`（ARB-013） |
| push-gateway 侧状态 | ✅ 已消费 `edu.notify.notification.sent` |
| 协调动作 | 请 msg 确认 Outbox `TOPIC_MAP` 中 `NotificationSent` 事件映射到 `edu.notify.notification.sent`；如仍发往旧 topic，需更新 |
### 6.3 生产环境环境变量迁移（部署时）
| 项 | 详情 |
| ------------------- | -------------------------------------------------------------------------------------------------------------- |
| 阻塞方 | SRE AI / 人类决策者 |
| 问题 | 生产环境需将 `INTERNAL_API_TOKEN` 迁移为 `PUSH_INTERNAL_TOKEN`（或在 deploy.env 中同时设置两者） |
| push-gateway 侧状态 | ✅ 支持双环境变量（`PUSH_INTERNAL_TOKEN` 优先，`INTERNAL_API_TOKEN` 回退） |
| 协调动作 | 部署时在 `infra/security/secrets.example.env` 或 K8s Secret 中设置 `PUSH_INTERNAL_TOKEN`；旧变量可保留作为兼容 |
---
## 7. v2 文件变更清单
### 7.1 源码修改
| 文件 | 修改内容 |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `services/push-gateway/internal/config/config.go` | Kafka topic 默认值 → `edu.notify.notification.sent`；支持 `PUSH_INTERNAL_TOKEN` 环境变量（带 `INTERNAL_API_TOKEN` 回退） |
| `services/push-gateway/internal/ws/handler.go` | 鉴权头 `X-Internal-Key`（canonical）+ `X-Internal-Token`（legacy）；请求体 `userId`（canonical）+ `user_id`（legacy） |
| `services/push-gateway/internal/kafkaconsumer/consumer.go` | 包注释更新；metric label 使用 `event.EventType` 而非硬编码 |
| `services/push-gateway/internal/config/config_test.go` | 断言新 topic 名；新增 `TestLoadProdModeLegacyToken` 验证 fallback |
| `services/push-gateway/main.go` | 启动流程注释更新（topic 名 + 鉴权头名） |
### 7.2 部署配置修改
| 文件 | 修改内容 |
| --------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `infra/docker-compose.deploy.yml` | push-gateway 段：`KAFKA_NOTIFICATION_TOPIC: edu.notify.notification.sent`；`PUSH_INTERNAL_TOKEN` 带回退链 |
| `infra/deploy.env.example` | `PUSH_INTERNAL_TOKEN` 为规范变量；`INTERNAL_API_TOKEN` 标注为兼容别名 |
### 7.3 测试脚本新增
| 文件 | 用途 |
| ---------------------------------------------------- | ---------------------------------------- |
| `services/push-gateway/scripts/test-kafka-ws.mjs` | Kafka → WebSocket 全链路验证（单条消息） |
| `services/push-gateway/scripts/test-exam-events.mjs` | 3 类考试事件透传验证 |
### 7.4 根 package.json
| 文件 | 修改内容 |
| -------------- | --------------------------------------------------------- |
| `package.json` | `devDependencies` 新增 `kafkajs` + `ws`（仅用于测试脚本） |
---
## 8. 环境变量清单（v2）
| 环境变量 | 必填 | 默认值 | 用途 |
| ----------------------------- | -------- | ------------------------------ | ----------------------------------------------- |
| `PUSH_GATEWAY_PORT` | 否 | `8081` | HTTP 端口 |
| `JWT_SECRET` | 生产必填 | — | JWT HS256 签名密钥（DevMode 有默认值） |
| `DEV_MODE` | 否 | `false` | 开发模式（旁路 JWT + InternalToken 校验） |
| `REDIS_URL` | 是 | `redis://localhost:6379/0` | Redis 连接地址 |
| `KAFKA_BROKERS` | 是 | `localhost:9092` | Kafka broker 列表（逗号分隔） |
| `KAFKA_NOTIFICATION_TOPIC` | 否 | `edu.notify.notification.sent` | 消费的 Kafka topic（ARB-013） |
| `KAFKA_CONSUMER_GROUP` | 否 | `push-gateway` | Kafka 消费者组 |
| `PUSH_INTERNAL_TOKEN` | 生产必填 | — | /internal/* API 鉴权 token（ARB-013 canonical） |
| `INTERNAL_API_TOKEN` | 兼容别名 | — | /internal/* API 鉴权 token（fallback，v1 兼容） |
| `JWKS_URL` | 生产必填 | — | iam JWKS 端点（RS256 公钥） |
| `WS_ALLOWED_ORIGINS` | 生产必填 | — | WebSocket 允许的 Origin 白名单（逗号分隔） |
| `MAX_CONNS_PER_USER` | 否 | `5` | 单用户最大连接数 |
| `HEARTBEAT_INTERVAL_SECONDS` | 否 | `30` | 心跳间隔（秒） |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 否 | `localhost:4318` | OTLP collector 端点 |
| `INSTANCE_ID` | 否 | hostname | 实例标识（Redis SET 成员） |
---
## 9. API 契约（v2）
### 9.1 WebSocket 端点
```
GET /ws?token=<jwt>
```
- 鉴权：JWT RS256（via iam JWKS）或 DevMode `dev-token`
- 消息格式：`{ "type": "message", "event": "<event_type>", "data": {...}, "timestamp": "<RFC3339>" }`
- 心跳：RFC 6455 Ping/Pong（30s 间隔，60s 空闲超时）
### 9.2 内部 HTTP API
| 方法 | 路径 | 鉴权头 | 请求体 | 响应 |
| ---- | --------------------------- | ------------------------- | ------------------------------- | ---------------------------------------------------- |
| POST | `/internal/push` | `X-Internal-Key: <token>` | `{ userId, event, data, ttl? }` | `{ success, delivered?, online?, reached?, error? }` |
| POST | `/internal/broadcast` | `X-Internal-Key: <token>` | `{ event, data, filter? }` | `{ success, reached? }` |
| GET | `/internal/online/<userID>` | `X-Internal-Key: <token>` | — | `{ online: bool, instances: [] }` |
**向后兼容**：
- 鉴权头同时接受 `X-Internal-Token`（v1 legacy）
- `/internal/push` 请求体同时接受 `user_id`（snake_case，v1 legacy）
### 9.3 Kafka 消费
| Topic | 消息格式 | 来源 |
| ---------------------------------- | ---------------------------- | --------------------- |
| `edu.notify.notification.sent` | `NotificationRequested` JSON | msg Outbox publisher |
| `edu.notify.notification.sent.dlq` | 原始消息（失败 3 次后投递） | push-gateway 自动派生 |
**消息字段**：`event_id` / `user_id` / `event_type` / `channel` / `title` / `content` / `data` / `broadcast` / `occurred_at`
**event_type 透传**：push-gateway 从 Kafka 消息的 `event_type` 字段读取事件类型，作为 WebSocket 消息的 `event` 字段透传，不硬编码事件类型。
---
## 10. 后续工作（v3 展望）
| 工作项 | 优先级 | 说明 |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| P6 Reconnect 协议 | P1 | `session_id` + `last_seq` + ring buffer（100 条/用户）支持断线重连后补发 |
| P6 离线消息推送 | P2 | 与 msg 服务集成，离线用户消息落库后通过 SMS/邮件/应用内通知补发 |
| Prometheus 告警规则 | P2 | 配置 `push_gateway_kafka_consumed_total` 停止增长告警 |
| Grafana 面板 | P2 | WebSocket 连接数、Kafka 消费延迟、推送成功率面板 |
| 多副本部署验证 | P2 | 验证 Redis Pub/Sub 跨实例扇出在多副本场景下的正确性 |