huang
931e140e8e
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 6m35s
实现功能： - 实名状态检查轮询（可配置间隔） - 卡流量检查轮询（支持跨月流量追踪） - 套餐检查与超额自动停机 - 分布式并发控制（Redis 信号量） - 手动触发轮询（单卡/批量/条件筛选） - 数据清理配置与执行 - 告警规则与历史记录 - 实时监控统计（队列/性能/并发） 性能优化： - Redis 缓存卡信息，减少 DB 查询 - Pipeline 批量写入 Redis - 异步流量记录写入 - 渐进式初始化（10万卡/批） 压测工具（scripts/benchmark/）： - Mock Gateway 模拟上游服务 - 测试卡生成器 - 配置初始化脚本 - 实时监控脚本 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
112 lines
8.5 KiB
Markdown
112 lines
8.5 KiB
Markdown
## Why
|
||
|
||
当前系统管理百万级别（1000万+）的 IoT 卡资产，需要定期检查卡的实名状态、流量使用情况和套餐流量消耗，以实现自动化监控、及时停机和状态同步。现有系统缺乏轮询机制，无法高效处理大规模卡的定期检查需求，导致需要人工干预或依赖外部触发，运营成本高且响应不及时。本变更实现基于 Redis Sorted Set 的高性能轮询调度系统，支持灵活配置、动态并发控制、监控告警和数据清理，满足百万级卡量的自动化管理需求。
|
||
|
||
## What Changes
|
||
|
||
- **新增轮询调度系统**：基于 Redis Sorted Set 实现时间驱动的轮询队列，支持百万级卡的高效调度
|
||
- **新增三种轮询处理器**：
|
||
- 实名检查轮询：定期调用 Gateway API 查询卡的实名状态，支持梯度配置（未实名卡高频、已实名卡低频）
|
||
- 卡流量检查轮询：定期查询卡的流量使用情况，处理跨月流量计算（自然月重置），记录流量历史
|
||
- 套餐流量检查轮询：检查套餐使用情况（单卡套餐、设备级套餐），超额自动停机
|
||
- **新增轮询配置管理**：支持按卡状态、卡类型、运营商配置不同的轮询策略和间隔时间
|
||
- **新增并发控制机制**：基于 Redis 实现动态并发数调整，支持通过管理接口实时修改，无需重启 Worker
|
||
- **新增监控面板接口**：实时查看轮询队列状态、任务执行统计、成功率、平均耗时等监控指标
|
||
- **新增告警系统**：支持配置告警规则（队列积压、成功率、耗时），多种通知渠道（邮件、短信、Webhook）
|
||
- **新增数据清理机制**：定期清理流量历史记录、操作日志等数据，支持配置保留天数
|
||
- **新增手动触发接口**：支持手动触发单张或批量卡的立即检查，最高优先级处理
|
||
- **修改 IotCard 模型**：增加月流量追踪字段（`current_month_usage_mb`, `current_month_start_date`, `last_month_total_mb`），用于处理跨月流量计算
|
||
- **修改 Worker 进程**：集成轮询调度器，支持渐进式初始化（10秒启动，后台异步加载卡数据）
|
||
- **新增管理接口**：提供轮询配置 CRUD、并发控制调整、手动触发、监控面板、告警管理等完整的管理接口
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `polling-configuration`: 轮询配置管理 - 支持创建、查询、更新、删除轮询配置，配置卡匹配条件（卡状态、卡类型、运营商）和检查间隔（实名、流量、套餐），支持优先级和启用/禁用控制
|
||
- `polling-scheduler`: 轮询调度器 - 核心调度引擎，负责读取配置、匹配卡、计算下次检查时间、生成 Asynq 任务、管理 Redis 队列，支持渐进式初始化和懒加载机制
|
||
- `polling-realname-check`: 实名检查轮询 - 定期调用 Gateway API 查询卡实名状态，更新数据库和 Redis 缓存，支持状态变更时自动切换轮询配置，处理行业卡无需实名的特殊逻辑
|
||
- `polling-carddata-check`: 卡流量检查轮询 - 定期查询卡流量使用情况，处理跨月流量计算（自然月重置），记录流量历史到 `data_usage_records` 表，触发关联套餐的流量检查
|
||
- `polling-package-check`: 套餐流量检查轮询 - 检查套餐流量使用（单卡套餐直接读取、设备级套餐汇总所有卡），判断是否超额（基于虚流量），超额自动调用 Gateway 停机并更新卡状态
|
||
- `polling-concurrency-control`: 并发控制管理 - 基于 Redis 信号量实现动态并发数控制，支持分类型配置（实名、流量、套餐、停复机），提供管理接口实时调整并发数，无需重启 Worker
|
||
- `polling-monitoring`: 监控面板 - 提供轮询系统监控接口，查询队列状态（队列长度、逾期任务数、下个待处理任务）、任务执行统计（成功率、平均耗时、总执行次数）、实时并发数等监控指标
|
||
- `polling-alert`: 告警系统 - 支持配置告警规则（队列积压、成功率、平均耗时、正在处理任务数），支持多种告警级别（info/warning/error/critical）和通知渠道（邮件、短信、Webhook），定期检查规则并发送告警通知
|
||
- `data-cleanup`: 数据清理 - 定期清理流量历史记录（`data_usage_records`）、操作日志等数据，支持配置保留天数，使用定时任务每日凌晨执行清理
|
||
- `polling-manual-trigger`: 手动触发 - 提供手动触发接口，支持单张或批量卡的立即检查（实名、流量、套餐），使用独立的高优先级队列，确保立即处理
|
||
|
||
### Modified Capabilities
|
||
|
||
- `iot-card`: IoT 卡管理 - 增加月流量追踪字段（`current_month_usage_mb`：本月已用流量，`current_month_start_date`：本月开始日期，`last_month_total_mb`：上月结束时总流量），用于处理 Gateway 返回的自然月流量总量并计算增量，支持跨月流量计算
|
||
|
||
## Impact
|
||
|
||
### 数据模型变更
|
||
|
||
**新增表**：
|
||
- `tb_polling_config`：轮询配置表，存储轮询策略（卡匹配条件、检查间隔、优先级）
|
||
- `tb_polling_concurrency_config`：并发控制配置表，存储各类型任务的最大并发数
|
||
- `tb_polling_alert_rule`：告警规则表，存储告警配置（指标类型、阈值、通知渠道）
|
||
- `tb_data_cleanup_config`：数据清理配置表，存储各表的保留天数
|
||
|
||
**修改表**：
|
||
- `tb_iot_card`：增加字段 `current_month_usage_mb`、`current_month_start_date`、`last_month_total_mb`
|
||
|
||
### Redis 数据结构
|
||
|
||
- **轮询队列**（Sorted Set）：
|
||
- `polling:queue:realname`：实名检查队列
|
||
- `polling:queue:carddata`：卡流量检查队列
|
||
- `polling:queue:package`：套餐流量检查队列
|
||
- **卡信息缓存**（Hash）：`polling:card:{card_id}`，缓存卡的基本信息和轮询状态
|
||
- **配置缓存**（String）：`polling:configs`，缓存所有轮询配置（JSON 格式）
|
||
- **配置匹配索引**（Set）：`polling:config:cards:{config_id}`，记录匹配该配置的所有卡 ID
|
||
- **并发控制**（String）：`polling:concurrency:config:{type}` 和 `polling:concurrency:current:{type}`
|
||
- **手动触发队列**（List）：`polling:manual:{type}`，高优先级手动触发队列
|
||
- **监控统计**（Hash）：`polling:stats:{type}`，存储监控指标
|
||
|
||
### 系统集成
|
||
|
||
- **Worker 进程**：集成轮询调度器 Goroutine，启动时快速初始化（10秒），后台异步加载卡数据（20-30分钟）
|
||
- **Asynq 任务队列**：新增任务类型 `iot:realname:check`、`iot:carddata:check`、`iot:package:check`，新增队列 `iot_polling_realname`、`iot_polling_carddata`、`iot_polling_package`
|
||
- **Gateway 集成**：调用已有的 Gateway HTTP 接口（`QueryRealnameStatus`、`QueryFlow`、`StopCard`、`StartCard`）
|
||
|
||
### API 接口
|
||
|
||
**新增管理接口**（`/api/admin/polling-*`）：
|
||
- 轮询配置管理：CRUD、启用/禁用
|
||
- 并发控制管理：查询、更新并发数
|
||
- 手动触发：单卡/批量立即检查
|
||
- 监控面板：总览统计、队列状态、任务详情
|
||
- 告警管理：CRUD 告警规则
|
||
|
||
### 性能影响
|
||
|
||
- **内存占用**：Redis 增加约 3-5 GB 内存（1000万卡 × 200字节缓存 + Sorted Set 队列）
|
||
- **数据库负载**：渐进式初始化平缓负载（每秒10万行 + 1秒休息），运行时查询负载分散到轮询周期
|
||
- **网络带宽**：Gateway API 调用频率可控（通过并发数和轮询间隔配置）
|
||
- **Worker 进程**：新增 1 个调度器 Goroutine，Asynq Worker 并发数可配置
|
||
|
||
### 依赖项
|
||
|
||
- **已有依赖**：Gateway Client（`internal/gateway`）、Asynq（`pkg/queue`）、Redis、PostgreSQL
|
||
- **无新增外部依赖**
|
||
|
||
### 测试影响
|
||
|
||
- **单元测试**：轮询配置匹配逻辑、跨月流量计算逻辑、并发控制逻辑
|
||
- **集成测试**：轮询处理器端到端测试（含 Gateway Mock）、配置变更影响测试、手动触发测试
|
||
- **性能测试**：百万级卡初始化性能测试、Redis 队列性能测试、并发控制压力测试
|
||
|
||
### 运维影响
|
||
|
||
- **部署要求**：Worker 进程需要访问 Gateway API（网络连通性）
|
||
- **配置管理**：新增轮询配置、并发控制配置、告警规则配置（通过管理接口或数据库初始化）
|
||
- **监控告警**：需要配置告警通知渠道（邮件、短信、Webhook）
|
||
- **数据备份**：轮询配置表、告警规则表需要备份
|
||
|
||
### 向后兼容性
|
||
|
||
- ✅ 完全向后兼容，不影响现有 API 和业务逻辑
|
||
- ✅ 新增字段有默认值，不影响已有数据
|
||
- ✅ 轮询系统可独立启用/禁用（通过配置）
|