skillhub/scanner/docs/monitoring-guide.md

Scanner 运维监控指南

概述

本文档提供 Scanner 服务的运维监控指南，包括关键指标、告警规则和故障排查方法。

关键监控指标

1. 版本状态监控

SCANNING 状态的版本数量

-- 查询当前处于 SCANNING 状态的版本数量
SELECT COUNT(*) as scanning_count
FROM skill_versions
WHERE status = 'SCANNING';

告警阈值：

• ⚠️ 警告：> 10 个版本
• 🔴 严重：> 50 个版本

SCAN_FAILED 状态的版本数量

-- 查询最近 1 小时内扫描失败的版本数量
SELECT COUNT(*) as failed_count
FROM skill_versions
WHERE status = 'SCAN_FAILED'
  AND updated_at > NOW() - INTERVAL 1 HOUR;

告警阈值：

• ⚠️ 警告：> 5 个版本/小时
• 🔴 严重：> 20 个版本/小时

卡死的扫描任务

-- 查找卡在 SCANNING 状态超过 10 分钟的版本
SELECT id, skill_id, version, status, created_at, updated_at
FROM skill_versions
WHERE status = 'SCANNING'
  AND updated_at < NOW() - INTERVAL 10 MINUTE
ORDER BY updated_at ASC;

告警阈值：

• 🔴 严重：任何超过 10 分钟的 SCANNING 状态

2. Redis Stream 监控

消息堆积情况

# 查看 scan 队列的消息堆积情况
redis-cli XPENDING skillhub:scan:requests skillhub-scanners

# 查看队列长度
redis-cli XLEN skillhub:scan:requests

告警阈值：

• ⚠️ 警告：队列长度 > 100
• 🔴 严重：队列长度 > 500

消费者状态

# 查看消费者组信息
redis-cli XINFO GROUPS skillhub:scan:requests

# 查看消费者信息
redis-cli XINFO CONSUMERS skillhub:scan:requests skillhub-scanners

检查项：

• 消费者是否在线
• 是否有长时间未确认的消息

3. 临时文件监控

磁盘空间使用

# 检查临时文件目录大小
du -sh /tmp/skillhub-scans/

# 检查 /tmp 分区剩余空间
df -h /tmp

告警阈值：

• ⚠️ 警告：/tmp 剩余空间 < 5GB
• 🔴 严重：/tmp 剩余空间 < 1GB

孤儿文件清理

# 查找超过 1 小时的临时文件（可能是孤儿文件）
find /tmp/skillhub-scans/ -type f -mmin +60

# 清理孤儿文件（谨慎操作）
find /tmp/skillhub-scans/ -type f -mmin +60 -delete

4. Scanner 服务健康检查

HTTP 健康检查

# 检查 Scanner 服务是否可用
curl -f http://localhost:8000/health || echo "Scanner service is down"

# 检查响应时间
time curl -s http://localhost:8000/health > /dev/null

告警阈值：

• ⚠️ 警告：响应时间 > 5 秒
• 🔴 严重：服务不可用

扫描成功率

-- 计算最近 1 小时的扫描成功率
SELECT
    COUNT(CASE WHEN status = 'PENDING_REVIEW' THEN 1 END) as success_count,
    COUNT(CASE WHEN status = 'SCAN_FAILED' THEN 1 END) as failed_count,
    ROUND(
        COUNT(CASE WHEN status = 'PENDING_REVIEW' THEN 1 END) * 100.0 /
        NULLIF(COUNT(*), 0),
        2
    ) as success_rate
FROM skill_versions
WHERE updated_at > NOW() - INTERVAL 1 HOUR
  AND status IN ('PENDING_REVIEW', 'SCAN_FAILED');

告警阈值：

• ⚠️ 警告：成功率 < 80%
• 🔴 严重：成功率 < 50%

Prometheus 告警规则示例

groups:
  - name: scanner_alerts
    interval: 30s
    rules:
      # Scanner 服务不可用
      - alert: ScannerServiceDown
        expr: up{job="skill-scanner"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Scanner service is down"
          description: "Scanner service has been down for more than 2 minutes"

      # 扫描失败率过高
      - alert: ScannerHighFailureRate
        expr: rate(scanner_failures_total[5m]) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Scanner failure rate > 50%"
          description: "Scanner failure rate is {{ $value | humanizePercentage }} in the last 5 minutes"

      # 版本卡在 SCANNING 状态
      - alert: ScanStuckTooLong
        expr: skillhub_scanning_versions{status="SCANNING"} > 0
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Versions stuck in SCANNING state"
          description: "{{ $value }} versions have been in SCANNING state for more than 10 minutes"

      # 临时文件磁盘空间不足
      - alert: TempFilesDiskUsage
        expr: node_filesystem_avail_bytes{mountpoint="/tmp"} < 1e9
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Temp files disk usage high"
          description: "Only {{ $value | humanize1024 }}B available in /tmp"

      # Redis Stream 消息堆积
      - alert: ScanQueueBacklog
        expr: redis_stream_length{stream="skillhub:scan:requests"} > 100
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Scan queue backlog"
          description: "{{ $value }} messages pending in scan queue"

故障排查手册

问题 1：版本卡在 SCANNING 状态

症状：

• 用户反馈技能包一直在扫描中
• 数据库中版本状态为 SCANNING 超过 10 分钟

排查步骤：

1. 检查 Redis Stream 消费者是否在线

redis-cli XINFO CONSUMERS skillhub:scan:requests skillhub-scanners

2. 检查是否有对应的消息

redis-cli XPENDING skillhub:scan:requests skillhub-scanners

3. 检查应用日志

kubectl logs -l app=skillhub-backend --tail=100 | grep "versionId=<VERSION_ID>"

解决方案：

如果确认消息丢失或消费者异常，手动修复版本状态：

-- 将卡死的版本标记为 SCAN_FAILED
UPDATE skill_versions
SET status = 'SCAN_FAILED', updated_at = NOW()
WHERE id = <VERSION_ID> AND status = 'SCANNING';

-- 创建人工审核任务
INSERT INTO review_tasks (skill_version_id, namespace_id, requester_id, created_at)
SELECT id, (SELECT namespace_id FROM skills WHERE id = skill_id), created_by, NOW()
FROM skill_versions
WHERE id = <VERSION_ID>;

问题 2：Scanner 服务不可用

症状：

• 所有扫描任务失败
• HTTP 连接超时

排查步骤：

1. 检查 Scanner 服务状态

# Docker 环境
docker ps | grep scanner

# Kubernetes 环境
kubectl get pods -l app=skill-scanner

2. 检查 Scanner 日志

# Docker 环境
docker logs skill-scanner --tail=100

# Kubernetes 环境
kubectl logs -l app=skill-scanner --tail=100

3. 检查网络连通性

curl -v http://localhost:8000/health

解决方案：

• 重启 Scanner 服务
• 检查配置是否正确（API key、base URL 等）
• 检查资源限制（CPU、内存）

问题 3：临时文件占满磁盘

症状：

• /tmp 分区空间不足
• 扫描任务失败，日志显示 "No space left on device"

排查步骤：

1. 检查磁盘使用情况

df -h /tmp
du -sh /tmp/skillhub-scans/

2. 查找大文件

find /tmp/skillhub-scans/ -type f -size +100M -exec ls -lh {} \;

3. 查找孤儿文件

find /tmp/skillhub-scans/ -type f -mmin +60

解决方案：

# 清理超过 1 小时的临时文件
find /tmp/skillhub-scans/ -type f -mmin +60 -delete

# 清理空目录
find /tmp/skillhub-scans/ -type d -empty -delete

问题 4：Redis Stream 消息堆积

症状：

• 扫描任务延迟严重
• Redis Stream 队列长度持续增长

排查步骤：

1. 检查队列长度

redis-cli XLEN skillhub:scan:requests

2. 检查消费者数量和状态

redis-cli XINFO CONSUMERS skillhub:scan:requests skillhub-scanners

3. 检查应用实例数量

kubectl get pods -l app=skillhub-backend

解决方案：

• 增加应用实例数量（水平扩展）
• 检查 Scanner 服务性能
• 临时禁用扫描功能，清空队列后再启用

日常巡检清单

每日检查

• 检查 SCANNING 状态的版本数量
• 检查 SCAN_FAILED 状态的版本数量
• 检查 Scanner 服务健康状态
• 检查 /tmp 磁盘空间使用情况

每周检查

• 检查扫描成功率趋势
• 检查 Redis Stream 消息堆积情况
• 清理孤儿临时文件
• 检查告警规则是否触发

每月检查

• 审查扫描失败的原因分布
• 评估 Scanner 服务性能
• 优化告警阈值
• 更新运维文档

相关文档

• 故障影响分析
• 改进建议
• 配置说明