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>
197 lines
8.6 KiB
Markdown
197 lines
8.6 KiB
Markdown
# 轮询系统
|
||
|
||
## 概述
|
||
|
||
轮询系统是 IoT 卡管理平台的核心模块，负责定期检查卡的实名状态、流量使用情况和套餐流量余额。系统采用分布式架构，支持高并发处理和动态配置。
|
||
|
||
## 核心功能
|
||
|
||
### 1. 实名检查轮询（Realname Check）
|
||
|
||
- 定期查询卡的实名认证状态
|
||
- 自动跳过行业卡（无需实名）
|
||
- 状态变化时重新匹配配置
|
||
|
||
### 2. 流量检查轮询（Carddata Check）
|
||
|
||
- 定期查询卡的流量使用情况
|
||
- 支持跨月流量自动重置
|
||
- 记录流量使用历史
|
||
|
||
### 3. 套餐检查轮询（Package Check）
|
||
|
||
- 监控套餐流量使用率
|
||
- 超额自动停机（>100%）
|
||
- 临近超额预警（>=95%）
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Worker 进程 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Scheduler │ │ AlertChecker │ │ CleanupTask │ │
|
||
│ │ 调度器 │ │ 告警检查器 │ │ 清理任务 │ │
|
||
│ └──────┬───────┘ └──────────────┘ └──────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ Asynq 任务队列 │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ Realname │ │ Carddata │ │ Package │ │
|
||
│ │ Handler │ │ Handler │ │ Handler │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ Redis │
|
||
│ - 轮询队列 (Sorted Set) │
|
||
│ - 手动触发队列 (List) │
|
||
│ - 卡信息缓存 (Hash) │
|
||
│ - 配置缓存 │
|
||
│ - 并发信号量 │
|
||
│ - 监控统计 │
|
||
└─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ PostgreSQL │
|
||
│ - tb_polling_config │
|
||
│ - tb_polling_concurrency_config │
|
||
│ - tb_polling_alert_rule │
|
||
│ - tb_polling_alert_history │
|
||
│ - tb_data_cleanup_config │
|
||
│ - tb_data_cleanup_log │
|
||
│ - tb_polling_manual_trigger_log │
|
||
│ - tb_data_usage_record │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
### 1. 数据库迁移
|
||
|
||
```bash
|
||
make migrate-up
|
||
```
|
||
|
||
### 2. 初始化配置
|
||
|
||
```bash
|
||
psql $DATABASE_URL -f scripts/init_polling_config.sql
|
||
```
|
||
|
||
### 3. 启动 Worker
|
||
|
||
```bash
|
||
go run cmd/worker/main.go
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 轮询配置（tb_polling_config）
|
||
|
||
| 字段 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| name | 配置名称 | - |
|
||
| priority | 优先级（数字越大越优先） | 0 |
|
||
| carrier_id | 运营商 ID（可选） | - |
|
||
| status | 卡状态条件（可选） | - |
|
||
| card_category | 卡类别条件（可选） | - |
|
||
| realname_check_interval | 实名检查间隔（秒） | 3600 |
|
||
| carddata_check_interval | 流量检查间隔（秒） | 7200 |
|
||
| package_check_interval | 套餐检查间隔（秒） | 14400 |
|
||
| is_enabled | 是否启用 | true |
|
||
|
||
### 并发控制配置（tb_polling_concurrency_config）
|
||
|
||
| 任务类型 | 默认并发数 | 说明 |
|
||
|----------|-----------|------|
|
||
| realname | 50 | 实名检查并发数 |
|
||
| carddata | 100 | 流量检查并发数 |
|
||
| package | 30 | 套餐检查并发数 |
|
||
|
||
## API 接口
|
||
|
||
### 轮询配置管理
|
||
|
||
- `POST /api/admin/polling-configs` - 创建配置
|
||
- `GET /api/admin/polling-configs` - 配置列表
|
||
- `GET /api/admin/polling-configs/:id` - 配置详情
|
||
- `PUT /api/admin/polling-configs/:id` - 更新配置
|
||
- `DELETE /api/admin/polling-configs/:id` - 删除配置
|
||
|
||
### 并发控制管理
|
||
|
||
- `GET /api/admin/polling-concurrency` - 获取并发配置
|
||
- `PUT /api/admin/polling-concurrency/:type` - 更新并发数
|
||
- `POST /api/admin/polling-concurrency/reset` - 重置信号量
|
||
|
||
### 监控面板
|
||
|
||
- `GET /api/admin/polling-stats` - 总览统计
|
||
- `GET /api/admin/polling-stats/queues` - 队列状态
|
||
- `GET /api/admin/polling-stats/tasks` - 任务统计
|
||
- `GET /api/admin/polling-stats/init-progress` - 初始化进度
|
||
|
||
### 告警管理
|
||
|
||
- `POST /api/admin/polling-alert-rules` - 创建告警规则
|
||
- `GET /api/admin/polling-alert-rules` - 规则列表
|
||
- `PUT /api/admin/polling-alert-rules/:id` - 更新规则
|
||
- `DELETE /api/admin/polling-alert-rules/:id` - 删除规则
|
||
- `GET /api/admin/polling-alert-history` - 告警历史
|
||
|
||
### 数据清理
|
||
|
||
- `POST /api/admin/data-cleanup-configs` - 创建清理配置
|
||
- `GET /api/admin/data-cleanup-configs` - 配置列表
|
||
- `PUT /api/admin/data-cleanup-configs/:id` - 更新配置
|
||
- `DELETE /api/admin/data-cleanup-configs/:id` - 删除配置
|
||
- `POST /api/admin/data-cleanup/trigger` - 手动触发清理
|
||
- `GET /api/admin/data-cleanup/preview` - 清理预览
|
||
- `GET /api/admin/data-cleanup/progress` - 清理进度
|
||
|
||
### 手动触发
|
||
|
||
- `POST /api/admin/polling-manual-trigger/single` - 单卡触发
|
||
- `POST /api/admin/polling-manual-trigger/batch` - 批量触发
|
||
- `POST /api/admin/polling-manual-trigger/by-condition` - 条件触发
|
||
- `GET /api/admin/polling-manual-trigger/status` - 触发状态
|
||
- `GET /api/admin/polling-manual-trigger/history` - 触发历史
|
||
- `POST /api/admin/polling-manual-trigger/cancel` - 取消触发
|
||
|
||
## Redis Key 说明
|
||
|
||
| Key 模式 | 类型 | 说明 |
|
||
|----------|------|------|
|
||
| polling:queue:realname | Sorted Set | 实名检查队列 |
|
||
| polling:queue:carddata | Sorted Set | 流量检查队列 |
|
||
| polling:queue:package | Sorted Set | 套餐检查队列 |
|
||
| polling:manual:{type} | List | 手动触发队列 |
|
||
| polling:card:{card_id} | Hash | 卡信息缓存 |
|
||
| polling:configs | Hash | 配置缓存 |
|
||
| polling:concurrency:config:{type} | String | 并发配置 |
|
||
| polling:concurrency:current:{type} | String | 当前并发数 |
|
||
| polling:stats:{type} | Hash | 监控统计 |
|
||
| polling:init:progress | Hash | 初始化进度 |
|
||
|
||
## 性能指标
|
||
|
||
- Worker 启动时间：< 10 秒
|
||
- 渐进式初始化：每批 10 万张卡，间隔 1 秒
|
||
- API 响应时间：P95 < 200ms
|
||
- 数据库查询：< 50ms
|
||
|
||
## 相关文档
|
||
|
||
- [部署文档](deployment.md)
|
||
- [运维文档](operations.md)
|