junhong_cmp_fiber/docs/polling-system/operations.md

轮询系统运维文档

日常监控

1. 监控面板

访问监控接口获取系统状态：

# 总览统计
curl http://localhost:3000/api/admin/polling-stats

# 队列状态
curl http://localhost:3000/api/admin/polling-stats/queues

# 任务统计
curl http://localhost:3000/api/admin/polling-stats/tasks

# 初始化进度
curl http://localhost:3000/api/admin/polling-stats/init-progress

2. 关键指标

指标	正常范围	告警阈值	说明
队列长度	< 10000	> 50000	队列积压严重需关注
成功率	> 95%	< 90%	任务执行成功率
平均耗时	< 500ms	> 2000ms	单任务处理时间
并发使用率	50-80%	> 95%	接近上限需扩容

3. Redis 监控命令

# 查看队列长度
redis-cli ZCARD polling:queue:realname
redis-cli ZCARD polling:queue:carddata
redis-cli ZCARD polling:queue:package

# 查看手动触发队列
redis-cli LLEN polling:manual:realname
redis-cli LLEN polling:manual:carddata
redis-cli LLEN polling:manual:package

# 查看当前并发数
redis-cli GET polling:concurrency:current:realname
redis-cli GET polling:concurrency:current:carddata
redis-cli GET polling:concurrency:current:package

# 查看统计数据
redis-cli HGETALL polling:stats:realname
redis-cli HGETALL polling:stats:carddata
redis-cli HGETALL polling:stats:package

# 查看初始化进度
redis-cli HGETALL polling:init:progress

告警配置

1. 默认告警规则

建议配置以下告警规则：

# 队列积压告警
curl -X POST http://localhost:3000/api/admin/polling-alert-rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "队列积压告警",
    "rule_type": "queue_backlog",
    "task_type": "realname",
    "threshold": 50000,
    "comparison": ">",
    "is_enabled": true,
    "notify_channels": ["webhook"],
    "webhook_url": "https://your-webhook-url"
  }'

# 成功率告警
curl -X POST http://localhost:3000/api/admin/polling-alert-rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "成功率告警",
    "rule_type": "success_rate",
    "task_type": "realname",
    "threshold": 90,
    "comparison": "<",
    "is_enabled": true,
    "notify_channels": ["webhook"],
    "webhook_url": "https://your-webhook-url"
  }'

# 平均耗时告警
curl -X POST http://localhost:3000/api/admin/polling-alert-rules \
  -H "Content-Type: application/json" \
  -d '{
    "name": "耗时告警",
    "rule_type": "avg_duration",
    "task_type": "realname",
    "threshold": 2000,
    "comparison": ">",
    "is_enabled": true,
    "notify_channels": ["webhook"],
    "webhook_url": "https://your-webhook-url"
  }'

2. 告警历史查询

# 查看告警历史
curl "http://localhost:3000/api/admin/polling-alert-history?page=1&page_size=20"

# 按规则筛选
curl "http://localhost:3000/api/admin/polling-alert-history?rule_id=1"

故障排查

问题 1: 队列积压

现象: 队列长度持续增长，任务处理速度跟不上

排查步骤:

1. 检查并发使用情况

   redis-cli GET polling:concurrency:current:realname
   redis-cli GET polling:concurrency:config:realname
   

2. 检查 Gateway 接口响应时间

   # 查看统计中的平均耗时
   redis-cli HGET polling:stats:realname avg_duration_ms
   

3. 检查是否有大量失败重试

   redis-cli HGET polling:stats:realname failed
   

解决方案:

1. 增加并发数

   curl -X PUT http://localhost:3000/api/admin/polling-concurrency/realname \
     -H "Content-Type: application/json" \
     -d '{"max_concurrency": 100}'
   

2. 临时禁用非关键配置

   curl -X PUT http://localhost:3000/api/admin/polling-configs/1 \
     -H "Content-Type: application/json" \
     -d '{"status": 0}'
   

问题 2: 任务执行失败率高

现象: 成功率低于 90%

排查步骤:

1. 查看 Worker 日志

   grep -i "error" logs/worker.log | tail -100
   

2. 检查 Gateway 服务状态

3. 检查网络连接

解决方案:

1. 如果是 Gateway 问题，联系运营商解决
2. 如果是网络问题，检查防火墙和 DNS 配置
3. 临时降低并发数，减少压力

问题 3: 初始化卡住

现象: 初始化进度长时间不变

排查步骤:

1. 检查初始化进度

   redis-cli HGETALL polling:init:progress
   

2. 查看 Worker 日志是否有错误

   grep -i "初始化" logs/worker.log | tail -50
   

解决方案:

1. 重启 Worker 服务
2. 如果持续失败，检查数据库连接

问题 4: 并发信号量泄漏

现象: 当前并发数异常高，但实际没有那么多任务在运行

排查步骤:

# 检查当前并发数
redis-cli GET polling:concurrency:current:realname

解决方案:

重置信号量：

curl -X POST http://localhost:3000/api/admin/polling-concurrency/reset \
  -H "Content-Type: application/json" \
  -d '{"task_type": "realname"}'

数据清理

1. 查看清理配置

curl http://localhost:3000/api/admin/data-cleanup-configs

2. 手动触发清理

# 预览清理范围
curl http://localhost:3000/api/admin/data-cleanup/preview

# 手动触发清理
curl -X POST http://localhost:3000/api/admin/data-cleanup/trigger

# 查看清理进度
curl http://localhost:3000/api/admin/data-cleanup/progress

3. 调整保留天数

curl -X PUT http://localhost:3000/api/admin/data-cleanup-configs/1 \
  -H "Content-Type: application/json" \
  -d '{"retention_days": 60}'

手动触发操作

1. 单卡触发

curl -X POST http://localhost:3000/api/admin/polling-manual-trigger/single \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": 12345,
    "task_type": "realname"
  }'

2. 批量触发

curl -X POST http://localhost:3000/api/admin/polling-manual-trigger/batch \
  -H "Content-Type: application/json" \
  -d '{
    "card_ids": [12345, 12346, 12347],
    "task_type": "carddata"
  }'

3. 条件触发

curl -X POST http://localhost:3000/api/admin/polling-manual-trigger/by-condition \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "realname",
    "carrier_id": 1,
    "status": 1
  }'

4. 取消触发

curl -X POST http://localhost:3000/api/admin/polling-manual-trigger/cancel \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "xxx"
  }'

性能优化

1. 并发数调优

根据 Gateway 接口响应时间和服务器资源调整并发数：

场景	建议并发数
Gateway 响应 < 100ms	100-200
Gateway 响应 100-500ms	50-100
Gateway 响应 > 500ms	20-50

2. 轮询间隔调优

根据业务需求调整间隔：

任务类型	建议间隔	说明
实名检查（未实名）	60s	需要快速获知实名状态
实名检查（已实名）	3600s	状态稳定，低频检查
流量检查	1800s	30分钟一次
套餐检查	1800s	与流量检查同步

3. 批量处理优化

• 渐进式初始化：每批 10 万张卡，间隔 1 秒
• 数据清理：每批 10000 条，避免长事务

备份与恢复

1. 配置备份

# 备份轮询配置
pg_dump -h $HOST -U $USER -d $DB -t tb_polling_config > polling_config_backup.sql
pg_dump -h $HOST -U $USER -d $DB -t tb_polling_concurrency_config > concurrency_config_backup.sql
pg_dump -h $HOST -U $USER -d $DB -t tb_polling_alert_rule > alert_rules_backup.sql
pg_dump -h $HOST -U $USER -d $DB -t tb_data_cleanup_config > cleanup_config_backup.sql

2. 恢复配置

psql -h $HOST -U $USER -d $DB < polling_config_backup.sql

日志说明

日志位置

• Worker 日志：logs/worker.log
• API 日志：logs/api.log
• 访问日志：logs/access.log

关键日志关键词

关键词	含义
轮询调度器启动	Worker 启动成功
渐进式初始化	初始化进行中
实名检查完成	实名检查任务完成
流量检查完成	流量检查任务完成
套餐检查完成	套餐检查任务完成
告警触发	告警规则触发
数据清理完成	清理任务完成