xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Edu/docs/architecture/issues/worklines/push-gateway_workline.md

20 KiB
Raw Permalink Blame History

push-gateway 工作排期

负责人：ai02 关联：workline.md、coord.md、contracts/push-gateway_contract.md、objections/push-gateway_issue.md 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试） 依据：ai-allocation.md §7.2、02-architecture-design.md §12 实施优先级、president-final-rulings.md §3.4 回写义务

§1 总览

push-gateway 是 Go 实现的实时推送基础设施服务（L3 网关层），管理 WebSocket 长连接，接收 msg 服务的推送请求投递到在线客户端。无业务状态，仅持有连接池 + Redis 跨实例广播。

全阶段目标：

  • 批次 0（等待期）：复审 02 文档 + 回写 ISSUE-053/055/056/058 裁决 + 提请 ISSUE-001~007 仲裁
  • 批次 4（P5，13 天）：完整实现 /internal/push + WebSocket 生命周期 + Redis Pub/Sub + Kafka 消费 + /readyz + /metrics + OTel + 多阶段 Dockerfile + slog + shared-go 接入 + 集成测试
  • 批次 5（P6 硬化，5 天）：Reconnect 协议 + Redis Stream 持久化 + 测试覆盖率 ≥ 80% + ADR/非功能性需求/失败模式章节补全

关键路径依赖：

  • 批次 0.14：shared-go 包骨架（coord）—— tracer/logger/jwks/env 4 模块
  • 批次 1：iam P2.1（JWT RS256 + JWKS 端点）—— WebSocket 鉴权前置
  • 批次 4：msg gRPC 50056 + edu.notification.requested topic —— 推送事件来源

§2 全阶段甘特图（批次 0 + 批次 4 + 批次 5）

gantt
    title ai02 push-gateway 全阶段排期（批次 0 + 批次 4 P5 + 批次 5 P6）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    section 批次0 等待期 2天
    0.1 复审01/02文档+核查已有仲裁 :crit, a0a, 2026-07-10, 1d
    0.2 回写ISSUE-053/055/056/058到02文档 :crit, a0b, after a0a, 1d
    0.3 提请ISSUE-001~007待coord仲裁 :a0c, after a0a, 1d

    section 批次4 P5-P0 安全加固 3天
    4.1 Origin校验+CheckOrigin白名单 :crit, a4a, after b3a, 1d
    4.2 /internal/*鉴权对齐X-Internal-Token :crit, a4b, after a4a, 1d
    4.3 心跳改WebSocket控制帧+SetReadDeadline :crit, a4c, after a4a, 1d
    4.4 单用户连接数限制MaxConn=5 :crit, a4d, after a4c, 1d
    4.5 Send通道满时指标+日志 :a4e, after a4d, 1d

    section 批次4 P5-P0 基础设施 2天
    4.6 Dockerfile重构多阶段+非root+healthcheck+ldflags :crit, a4f, after b3a, 1d
    4.7 引入log/slog替换标准log :a4g, after a4f, 1d
    4.8 接入shared-go tracer/logger/jwks/env :a4h, after a4g, 1d

    section 批次4 P5-P1 横向扩展 3天
    4.9 Redis Pub/Sub跨实例广播 :crit, a4i, after a4h, 2d
    4.10 Redis SET在线状态+启动重建(ISSUE-058) :crit, a4j, after a4i, 1d
    4.11 /metrics自定义指标+/readyz软失败(ISSUE-055) :a4k, after a4j, 1d
    4.12 优雅关闭所有WebSocket连接 :a4l, after a4k, 1d

    section 批次4 P5-P2 高级功能 3天
    4.13 Kafka消费edu.notification.requested(ISSUE-053) :a4m, after a4j, 2d
    4.14 JWT RS256升级+JWKS fetcher :a4n, after a4m, 1d
    4.15 设计决策记录章节回写(ISSUE-056) :a4o, after a4n, 1d

    section 批次4 P5-P2 集成 2天
    4.16 与msg联调/internal/push双通道 :crit, a4p, after a4o, 1d
    4.17 集成测试+端到端验证 :crit, a4q, after a4p, 1d

    section 批次5 P6 硬化 5天
    5.1 Reconnect协议session_id+last_seq :a5a, after a4q, 2d
    5.2 Redis Stream替代Pub/Sub持久化 :a5b, after a5a, 2d
    5.3 测试覆盖率≥80% :crit, a5c, after a4q, 3d
    5.4 ADR+非功能性需求+失败模式章节(ISSUE-007) :a5d, after a4q, 2d

依赖锚点：b3a = 批次 3 完成信号（content + data-ana 就绪，见 workline.md §1 批次 3） 总工期：批次 0（2 天）+ 批次 4（13 天）+ 批次 5（5 天）= 20 天

§3 详细任务

3.1 批次 0：等待期（2 天）

任务 0.1：复审 01/02 文档 + 核查已有仲裁

  • 负责人：ai02
  • 依赖：无
  • 交付物：
  • 验收标准：
    • 5 项已有仲裁（ISSUE-053/055/056/058 + ARB /internal/push）核查完成
    • 01 文档 7 项偏差登记
    • 02 文档 4 项未回写 + 3 项规范缺失登记

任务 0.2：回写 ISSUE-053/055/056/058 到 02 文档

  • 负责人：ai02
  • 依赖：任务 0.1
  • 交付物：02-architecture-design.md 修订
    • §5.1 topic 改为 edu.notification.requested（ISSUE-053）
    • §6.7 增 Kafka 软失败逻辑 + Redis 软失败（ISSUE-055/058，待 ISSUE-006 仲裁最终策略）
    • 新增 §5.4"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"（ISSUE-056）
    • §3.1/§8.4 补 Hub 启动 Redis SET 重建 + 60s 不一致窗口文档化 + push_gateway_redis_set_rebuild_total 指标（ISSUE-058）
  • 验收标准：4 项裁决全部回写，objections/push-gateway_issue.md §0 核查矩阵状态更新为 ✅

任务 0.3：提请 ISSUE-001~007 待 coord 仲裁

3.2 批次 4（P5）：完整实现（13 天）

任务 4.1：Origin 校验 + CheckOrigin 白名单（P0，1 天）

  • 负责人：ai02
  • 依赖：批次 3 完成信号 b3a
  • 交付物：internal/ws/handler.go 修订
    • upgrader.CheckOrigin 从 return true 改为读 WS_ALLOWED_ORIGINS 环境变量白名单
    • 无 Origin 头拒绝
  • 验收标准：
    • 非白名单 Origin 返 403
    • 白名单来源（teacher/student/parent portal 域名）通过

任务 4.2：/internal/* 鉴权对齐 X-Internal-Token（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.1 + ISSUE-002 仲裁结果
  • 交付物：
  • 验收标准：无 token/错 token 返 401 + PUSH_UNAUTHORIZED；DevMode 跳过

任务 4.3：心跳改用 WebSocket 控制帧 + SetReadDeadline（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.1
  • 交付物：internal/ws/handler.go 重构
    • 移除文本消息 ping/pong 逻辑（handler.go#L82-L84）
    • 改用 conn.SetReadDeadline(60s) + conn.SetPongHandler
    • 客户端 Ping 控制帧 → gorilla 自动回 Pong
    • 60s 无任何消息则关闭连接
  • 验收标准：
    • 僵尸连接 60s 后自动清理
    • 心跳走 RFC 6455 控制帧，不再走文本消息

任务 4.4：单用户连接数限制 MaxConn=5（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.3
  • 交付物：internal/hub/hub.go 修订
    • Hub 增加 counters map[string]int（02 文档 §2）
    • Register 检查 counters[userID] >= 5 返 ErrTooManyConnections
    • 超限返 close 帧（code=1008 policy violation）
  • 验收标准：第 6 个连接被拒，错误码 PUSH_TOO_MANY_CONNECTIONS 429

任务 4.5：Send 通道满时指标 + 日志（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.4
  • 交付物：internal/hub/hub.go Send 方法修订
    • 通道满时 slog.Warn + messages_dropped_total Counter
  • 验收标准：/metrics 暴露 push_gateway_messages_dropped_total{reason="channel_full"}

任务 4.6：Dockerfile 重构（P0，1 天）

  • 负责人：ai02
  • 依赖：批次 3 完成信号 b3a
  • 交付物：Dockerfile 重构
    • 多阶段（已有，保留）
    • 非 root 用户（adduser -D appuser + USER appuser）
    • healthcheck（wget --spider http://localhost:8081/healthz）
    • ldflags 优化（-ldflags="-s -w -X main.Version=$(git rev-parse --short HEAD)"）
    • go.mod 与 Dockerfile 版本对齐（1.25.0 vs golang:1.22-alpine）
  • 验收标准：docker build 通过，容器以非 root 运行，healthcheck 工作

任务 4.7：引入 log/slog 替换标准 log（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.6
  • 交付物：新增 internal/observability/logger.go
    • slog.NewJSONHandler + slog.SetDefault
    • 日志字段：timestamp level service=push-gateway request_id trace_id user_id conn_id event
    • main.go / handler.go / hub.go 替换所有 log.Printf 为 slog
  • 验收标准：日志输出 JSON 格式，包含 trace_id 字段

任务 4.8：接入 shared-go（P0，1 天）

  • 负责人：ai02
  • 依赖：任务 4.7 + 批次 0.14（shared-go 骨架）
  • 交付物：
    • go.mod 引入 github.com/edu-cloud/shared-go
    • 替换本地 observability/tracer.go 为 shared-go/observability/tracer
    • 引入 shared-go/observability/logger（替换任务 4.7 本地实现）
    • 引入 shared-go/config/env（替换 config.go getEnv）
    • 引入 shared-go/auth/jwks（任务 4.14 使用）
  • 验收标准：本地 tracer.go/logger.go 删除，统一从 shared-go import

任务 4.9：Redis Pub/Sub 跨实例广播（P1，2 天）

  • 负责人：ai02
  • 依赖：任务 4.8
  • 交付物：新增 internal/redis/pubsub.go + Hub 改造
    • 订阅 edu.push.channel.user.* + edu.push.channel.broadcast
    • 本实例无目标用户时 PUBLISH 到对应 channel
    • 持有该用户的实例订阅后投递到本地连接
    • 引入 github.com/redis/go-redis/v9 依赖
  • 验收标准：
    • 双实例部署，msg 调实例 A /internal/push user=B，实例 B 持有 B → 收到推送
    • 广播 PUBLISH 一次，所有实例投递本地连接

任务 4.10：Redis SET 在线状态 + 启动重建（P1，1 天）

  • 负责人：ai02
  • 依赖：任务 4.9
  • 交付物：Hub 改造（对齐 ISSUE-058）
    • 连接建立：SADD edu:push:online:<userID> <instanceID> + EXPIRE 60s
    • 心跳续期：EXPIRE 60s
    • 连接断开：SREM + 空 SET 则 DEL
    • Hub 启动重建：遍历内存连接 SADD + EXPIRE；先清空 Redis 中本 instanceID 旧成员（避免幽灵）
    • 实例崩溃 SET 自然过期（60s）
  • 验收标准：
    • 实例重启后 60s 内 Redis SET 重建完成
    • push_gateway_redis_set_rebuild_total 指标暴露

任务 4.11：/metrics 自定义指标 + /readyz 软失败（P1，1 天）

  • 负责人：ai02
  • 依赖：任务 4.10
  • 交付物：新增 internal/observability/metrics.go + /readyz 重构
    • 指标清单（02 文档 §6.4）：active_connections messages_pushed_total messages_dropped_total heartbeat_total disconnect_total redis_pubsub_latency_seconds kafka_consumed_total redis_set_rebuild_total
    • /readyz 检查 Redis PING + Kafka consumer lag
    • Redis/Kafka 软失败（ISSUE-055/058，待 ISSUE-006 仲裁）：返 200 + degraded: true
  • 验收标准：
    • /metrics 暴露 8+ 自定义指标
    • Redis 故障时 /readyz 返 200 + degraded: true（不返 503）

任务 4.12：优雅关闭所有 WebSocket 连接（P1，1 天）

  • 负责人：ai02
  • 依赖：任务 4.11
  • 交付物：main.go + Hub 改造
    • Hub 新增 CloseAll() 方法，向所有连接发 close 帧（code=1001 going away）
    • SIGTERM → 标记 Hub closing（拒新连接）→ CloseAll → 等 10s → srv.Shutdown → 关 Kafka consumer → 关 Redis subscriber → tracerShutdown
  • 验收标准：SIGTERM 后所有连接收到 close 帧，无连接泄漏

任务 4.13：Kafka 消费 edu.notification.requested（P2，2 天）

  • 负责人：ai02
  • 依赖：任务 4.10 + msg 就绪信号
  • 交付物：新增 internal/kafka/consumer.go
    • Consumer Group push-gateway
    • 订阅 edu.notification.requested（ISSUE-053 裁决的 topic 名）
    • 至少一次 + 重试 3 次入 DLQ
    • 幂等：event_id Redis SETNX TTL 24h
    • 消费 → 调 Hub.SendToUser / Broadcast
  • 验收标准：
    • msg 发布 NotificationRequested → push-gateway 消费 → 推送到在线客户端
    • 重复 event_id 不重投

任务 4.14：JWT RS256 升级 + JWKS fetcher（P2，1 天）

  • 负责人：ai02
  • 依赖：任务 4.8（shared-go/jwks）+ iam 就绪信号
  • 交付物：internal/ws/handler.go authenticate 重构
    • 移除 HS256 共享密钥校验
    • 改用 RS256：通过 shared-go/auth/jwks 拉取 iam /.well-known/jwks.json 公钥
    • 缓存公钥 + 定期刷新（5 分钟）
  • 验收标准：
    • iam 签发的 RS256 JWT 通过校验
    • 公钥轮换后 5 分钟内生效

任务 4.15：设计决策记录章节回写（P2，1 天）

  • 负责人：ai02
  • 依赖：任务 4.13
  • 交付物：02-architecture-design.md 新增 §5.4（ISSUE-056）
    • 标题："设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"
    • 正文标注"coord 已采纳，见 coord-final-decisions P1/P5/P6"
    • 记录决策背景、方案对比、采纳理由
  • 验收标准：章节存在且标注正确

任务 4.16：与 msg 联调 /internal/push 双通道（P2，1 天）

  • 负责人：ai02
  • 依赖：任务 4.13 + 任务 4.14 + msg 就绪
  • 交付物：联调测试报告
    • 定向推送：msg → HTTP /internal/push → push-gateway → WebSocket
    • 广播：msg → Kafka NotificationRequested → push-gateway → 全在线客户端
    • 离线场景：delivered: false, online: false → msg 走 SMS/邮件
  • 验收标准：matrix.md §9.5 推送链路检查清单全通过

任务 4.17：集成测试 + 端到端验证（P2，1 天）

  • 负责人：ai02
  • 依赖：任务 4.16
  • 交付物：集成测试用例 + 端到端验证报告
    • 单实例 1000 连接压测
    • 双实例跨实例推送验证
    • Redis 故障降级验证
    • Kafka 消费积压验证
  • 验收标准：

3.3 批次 5（P6）：硬化（5 天）

任务 5.1：Reconnect 协议（2 天）

  • 负责人：ai02
  • 依赖：批次 4 完成
  • 交付物：02 文档 §7.3 落地
    • 首次连接返 {type:"hello", session_id, seq:0}
    • 每条推送带递增 seq
    • 重连 /ws?token=&session_id=&last_seq= → 从 msg 拉取 last_seq+1 到当前补推
  • 验收标准：客户端断线 30s 内重连，未送达消息补推成功

任务 5.2：Redis Stream 替代 Pub/Sub（2 天）

  • 负责人：ai02
  • 依赖：任务 5.1
  • 交付物：internal/redis/stream.go
    • Pub/Sub → Redis Stream（持久化）
    • Consumer Group push-gateway
    • ACK 机制：投递成功后 XACK
    • 崩溃恢复：未 ACK 消息重新投递
  • 验收标准：实例崩溃时未投递消息不丢失（msg 落库兜底 + Stream 持久化双保险）

任务 5.3：测试覆盖率 ≥ 80%（3 天，可与 5.1/5.2 并行）

  • 负责人：ai02
  • 依赖：批次 4 完成
  • 交付物：
    • hub_test.go：注册/注销/推送/广播/连接数限制
    • ws_test.go：鉴权/心跳/Origin 校验
    • config_test.go：环境变量加载
    • redis_test.go：Pub/Sub + SET 重建
    • kafka_test.go：消费 + 幂等
  • 验收标准：go test -cover ./... ≥ 80%

任务 5.4：ADR + 非功能性需求 + 失败模式章节补全（2 天，可与 5.1/5.2 并行）

  • 负责人：ai02
  • 依赖：批次 4 完成 + ISSUE-007 仲裁
  • 交付物：02-architecture-design.md 新增章节
    • §14 ADR（Architecture Decision Records）
      • ADR-001：gorilla/websocket 选型（vs nhooyr/websocket）
      • ADR-002：Redis Pub/Sub vs Stream（P5 Pub/Sub → P6 Stream 演进）
      • ADR-003：心跳间隔 30s/60s 选型依据
      • ADR-004：10w 容量依据（goroutine-per-connection 内存估算）
      • ADR-005：HTTP + Kafka 双通道（vs 单通道）
    • §15 非功能性需求（可用性 SLO 99.9% / 安全合规 / 容量 SLA）
    • §16 失败模式（实例崩溃 / Redis 故障 / 网络分区 / Kafka 积压降级）
    • §17 容量估算（10w 连接内存/CPU/带宽）
  • 验收标准：4 章节齐全，符合 arc42 规范

§4 依赖与就绪信号

4.1 我依赖的上游就绪标志

依赖项 提供方 就绪信号 当前状态 影响任务
shared-go 包骨架 coord（批次 0.14） packages/shared-go 含 tracer/logger/jwks/env 4 模块 ⏳ 任务 4.8
iam JWT RS256 + JWKS 端点 ai06（批次 1） iam gRPC 50052 + /.well-known/jwks.json 可访问 ⏳ 任务 4.14
msg gRPC + Kafka topic ai10（批次 4） msg gRPC 50056 + edu.notification.requested topic 有事件 ⏳ 任务 4.13/4.16
Redis 基础设施 coord（P1） Redis 7.x 可访问 ✅ P1 已就绪 任务 4.9/4.10
Kafka 基础设施 coord（P1） Kafka 可访问 ✅ P1 已就绪 任务 4.13
ISSUE-001~007 仲裁 coord coord.md 追加 ARB-003+ ⏳ 任务 4.2/4.11/4.15/5.4

4.2 我的就绪信号（供下游消费）

就绪标志 验证方式 供消费方
push-gateway HTTP :8081 启用 GET /healthz 返 200 k8s 探针 / 监控
/readyz 返 200（含 Redis/Kafka 软失败检查） GET /readyz 返 200 + degraded 字段 k8s 探针
WebSocket /ws 端点可升级（JWT RS256 鉴权） 客户端 ws://host:8081/ws?token=JWT 建立连接 teacher-portal / student-portal / parent-portal
/internal/push + /internal/broadcast 接收 msg 推送 msg 调用返 {success:true, delivered:true} msg (ai10)
/internal/online/ 查在线状态 返 {online:bool, instances:[]} msg (ai10)
Kafka consumer edu.notification.requested 订阅成功 Consumer Group push-gateway lag=0 msg (ai10)
/metrics 暴露 8+ 自定义指标 GET /metrics 含 push_gateway_* 指标 Prometheus

4.3 Mock 策略（开发期间）

我提供的 mock（push-gateway 未就绪前，供前端 portal）：

  • WebSocket mock：前端用 mock-socket 库模拟 WS 连接，每 30s 推 1 条 mock 通知
  • HTTP mock：/internal/* 返 200 success

我消费的 mock（上游未就绪前）：

  • NotificationEvent mock：msg 未就绪前，push-gateway 内置定时器每 30s 生成 mock 事件推所有在线客户端
  • JWT 验签 mock：iam 未就绪前使用本地固定 RS256 公钥（或 DevMode dev-token）
  • Kafka 订阅 mock：msg 未就绪前不启动 Kafka consumer，用本地定时器替代

§5 风险与缓解

风险 概率 影响 缓解措施
ISSUE-001~007 仲裁延迟 中 阻塞批次 4 启动 ai02 先按建议方案推进，仲裁结果出来后调整
msg 就绪延迟 中 阻塞任务 4.13/4.16 用 mock NotificationEvent 先完成 Kafka 消费逻辑
10w 连接压测不达标 低 容量目标降级 P6 阶段压测，若不达标则 horizontal scaling 兜底
Redis Pub/Sub 消息丢失 中 跨实例推送丢失 msg 落库兜底 + P6 升级 Redis Stream
shared-go 接口变更 低 任务 4.8 返工 紧跟 coord 0.14 任务，接口冻结后立即对接
Reference in New Issue View Git Blame Copy Permalink