ljwx-health/docs/05-features/health-monitoring/data-flow-dashboard.md

健康数据流Dashboard完整部署指南

文档版本: v1.0 创建日期: 2026-01-04 适用系统: LJWX Health 方案: ECharts Sankey + WebSocket + Grafana（企业级完整方案）

---

📑 目录

1. 部署架构
2. 前置条件检查
3. 后端部署
4. 前端部署
5. Grafana Dashboard部署
6. 验证测试
7. 故障排查
8. 性能优化

---

1. 部署架构

1.1 系统架构图

┌─────────────────────────────────────────────────────────────┐
│  应用层 (ljwx-admin)                                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ECharts Sankey 数据流可视化                          │   │
│  │  - 实时数据流拓扑图                                    │   │
│  │  - 关键指标卡片                                        │   │
│  │  - WebSocket 实时更新                                 │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓ WebSocket (/ws/data-flow)
┌─────────────────────────────────────────────────────────────┐
│  后端层 (ljwx-boot)                                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  DataFlowWebSocketHandler                             │   │
│  │  - 定时推送指标 (每3秒)                               │   │
│  │  - 会话管理                                            │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  DataUpload 指标记录                                   │   │
│  │  - 数据接收统计                                        │   │
│  │  - 去重统计                                            │   │
│  │  - 告警触发统计                                        │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓ Redis (health:stats:*)
┌─────────────────────────────────────────────────────────────┐
│  存储层 (Redis)                                              │
│  - health:stats:http_throughput                             │
│  - health:stats:ble_throughput                              │
│  - health:stats:total_received                              │
│  - health:stats:after_dedup                                 │
│  - health:stats:alert_triggered                             │
│  - health:stats:avg_latency                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓ Prometheus Metrics
┌─────────────────────────────────────────────────────────────┐
│  监控层 (Grafana)                                            │
│  - 数据流吞吐量面板                                          │
│  - 去重率仪表盘                                              │
│  - 告警触发统计                                              │
│  - 处理延迟监控                                              │
└─────────────────────────────────────────────────────────────┘

1.2 文件清单

后端文件

ljwx-boot/
├── ljwx-boot-modules/src/main/java/com/ljwx/modules/
│   ├── monitor/websocket/
│   │   └── DataFlowWebSocketHandler.java       # WebSocket推送处理器
│   └── health/upload/
│       └── DataUpload.java                      # 已修改：添加指标记录
└── ljwx-boot-admin/src/main/java/com/ljwx/config/
    └── WebSocketConfig.java                     # WebSocket配置

前端文件

ljwx-admin/
└── src/views/monitor/data-flow/
    └── index.vue                                # ECharts数据流组件

监控配置文件

deploy/monitoring/grafana/dashboards/
└── ljwx-health-data-flow.json                   # Grafana Dashboard配置

---

2. 前置条件检查

2.1 环境要求

# 检查Java版本（需要21+）
java -version
# 输出: openjdk version "21.0.x"

# 检查Node.js版本（需要18+）
node -v
# 输出: v18.x.x 或更高

# 检查pnpm版本
pnpm -v
# 输出: 8.x.x 或更高

# 检查Redis连接
redis-cli ping
# 输出: PONG

# 检查MySQL连接
mysql -uroot -p -e "SELECT VERSION();"

2.2 服务状态检查

# 检查ljwx-boot是否运行
curl -s http://localhost:9998/actuator/health | jq '.status'
# 输出: "UP"

# 检查Redis连接
redis-cli -h localhost -p 6379 -a 123456 ping
# 输出: PONG

# 检查Grafana（如果已部署）
kubectl get pods -n infra | grep grafana
# 输出: grafana-0   1/1   Running

---

3. 后端部署

3.1 编译后端

cd ljwx-boot

# 清理并编译
mvn clean install -DskipTests

# 检查编译结果
ls -lh ljwx-boot-admin/target/ljwx-boot-admin-*.jar

3.2 启动后端（本地开发）

cd ljwx-boot

# 使用启动脚本
./run-local.sh

# 等待启动完成，查看日志
tail -f logs/ljwx-boot-admin_info.log | grep -E "WebSocket|DataFlow"

预期日志输出:

🔌 注册WebSocket处理器: /ws/data-flow
✅ WebSocket配置完成
🚀 DataUpload 初始化:
   CPU核心: 8, 内存: 2048MB
   批次大小: 200, 工作线程: 20

3.3 验证WebSocket端点

# 使用websocat测试WebSocket连接
websocat ws://localhost:9998/ws/data-flow

# 或使用curl测试HTTP升级
curl -i -N -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: test" \
  http://localhost:9998/ws/data-flow

预期响应:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

3.4 测试指标记录

# 检查Redis中的统计键
redis-cli -a 123456 KEYS "health:stats:*"
# 输出:
# 1) "health:stats:total_received"
# 2) "health:stats:after_dedup"
# 3) "health:stats:http_throughput"
# ...

# 查看具体指标值
redis-cli -a 123456 GET "health:stats:total_received"
# 输出: "1250"

---

4. 前端部署

4.1 安装依赖

cd ljwx-admin

# 安装依赖
pnpm install

# 检查ECharts是否已安装
pnpm list echarts
# 输出: echarts 5.x.x

4.2 配置环境变量

编辑 ljwx-admin/.env.development:

# API Base URL
VITE_API_URL=http://localhost:9998

# WebSocket URL (自动根据VITE_API_URL推导)
# ws://localhost:9998/ws/data-flow

4.3 启动前端

cd ljwx-admin

# 启动开发服务器
pnpm dev

# 访问地址
# http://localhost:3333

4.4 访问数据流Dashboard

1. 打开浏览器访问: http://localhost:3333
2. 登录系统
3. 导航到: 系统监控 → 数据流监控 (或直接访问 /monitor/data-flow)

预期界面:

• 顶部显示实时桑基图
• 下方显示4个关键指标卡片
• WebSocket连接状态显示为"已连接"
• 数据每3秒自动更新

---

5. Grafana Dashboard部署

5.1 部署Grafana（K8s环境）

# 部署完整监控栈（Grafana + Prometheus + Loki）
./scripts/deploy-observability.sh

# 等待Pod启动完成
kubectl get pods -n infra | grep grafana
# 输出: grafana-0   1/1   Running

5.2 导入Dashboard配置

方法1: 通过UI导入

# 1. 端口转发Grafana
kubectl port-forward -n infra svc/grafana 3000:3000

# 2. 浏览器访问 http://localhost:3000
# 3. 登录: admin / admin123
# 4. 点击 Dashboards → Import
# 5. 上传文件: deploy/monitoring/grafana/dashboards/ljwx-health-data-flow.json

方法2: 通过ConfigMap部署

# 创建ConfigMap
kubectl create configmap ljwx-health-data-flow-dashboard \
  --from-file=ljwx-health-data-flow.json=deploy/monitoring/grafana/dashboards/ljwx-health-data-flow.json \
  -n infra

# 重启Grafana加载Dashboard
kubectl rollout restart statefulset/grafana -n infra

5.3 配置Prometheus数据源

# 检查Prometheus数据源
kubectl port-forward -n infra svc/grafana 3000:3000

# 浏览器访问: http://localhost:3000/datasources
# 确认 Prometheus 数据源已配置:
# - Name: prometheus
# - URL: http://prometheus.infra.svc.cluster.local:9090

5.4 验证Dashboard

1. 访问 Grafana: http://localhost:3000
2. 导航到: Dashboards → LJWX Health - 数据流监控
3. 确认面板显示:
   • 数据流吞吐量（折线图）
   • 去重率（仪表盘）
   • 告警触发率（统计卡片）
   • 处理延迟（折线图）
   • Redis缓存命中率（仪表盘）
   • 数据流节点统计（表格）

---

6. 验证测试

6.1 完整功能测试脚本

创建测试脚本 scripts/verify-data-flow-dashboard.sh:

#!/bin/bash

echo "🔍 开始验证数据流Dashboard部署..."

# 颜色定义
GREEN='\033[0;32m'
RED='\033[0;31m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 1. 检查后端WebSocket
echo ""
echo "📍 1. 检查后端WebSocket端点..."
response=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: test" \
  http://localhost:9998/ws/data-flow)

if [ "$response" == "101" ]; then
  echo -e "${GREEN}✅ WebSocket端点正常 (HTTP 101 Switching Protocols)${NC}"
else
  echo -e "${RED}❌ WebSocket端点异常 (HTTP $response)${NC}"
  exit 1
fi

# 2. 检查Redis统计键
echo ""
echo "📍 2. 检查Redis统计数据..."
redis_keys=$(redis-cli -a 123456 --no-auth-warning KEYS "health:stats:*" 2>/dev/null)

if [ -n "$redis_keys" ]; then
  echo -e "${GREEN}✅ Redis统计键存在:${NC}"
  echo "$redis_keys" | sed 's/^/   /'
else
  echo -e "${YELLOW}⚠️  Redis统计键为空（正常，等待数据上传后会自动创建）${NC}"
fi

# 3. 检查前端访问
echo ""
echo "📍 3. 检查前端服务..."
if curl -s http://localhost:3333 > /dev/null; then
  echo -e "${GREEN}✅ 前端服务运行正常 (http://localhost:3333)${NC}"
else
  echo -e "${RED}❌ 前端服务无法访问${NC}"
  exit 1
fi

# 4. 检查Grafana Dashboard
echo ""
echo "📍 4. 检查Grafana Dashboard..."
if command -v kubectl &> /dev/null; then
  grafana_pod=$(kubectl get pods -n infra -l app=grafana -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)
  if [ -n "$grafana_pod" ]; then
    echo -e "${GREEN}✅ Grafana Pod运行正常: $grafana_pod${NC}"
    echo -e "${YELLOW}   提示: 访问 Grafana Dashboard:${NC}"
    echo -e "${YELLOW}   kubectl port-forward -n infra svc/grafana 3000:3000${NC}"
    echo -e "${YELLOW}   http://localhost:3000 (admin/admin123)${NC}"
  else
    echo -e "${YELLOW}⚠️  Grafana未部署（可选）${NC}"
  fi
else
  echo -e "${YELLOW}⚠️  kubectl未安装，跳过Grafana检查${NC}"
fi

# 5. 功能测试总结
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo -e "${GREEN}✅ 数据流Dashboard部署验证完成！${NC}"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📌 访问地址:"
echo "   - 数据流Dashboard: http://localhost:3333/monitor/data-flow"
echo "   - Grafana监控: http://localhost:3000 (需kubectl port-forward)"
echo ""
echo "📊 实时数据流更新频率: 每3秒"
echo "🔍 监控指标包括: 吞吐量、去重率、延迟、告警数"
echo ""

6.2 运行验证脚本

chmod +x scripts/verify-data-flow-dashboard.sh
./scripts/verify-data-flow-dashboard.sh

6.3 模拟数据上传测试

# 使用curl模拟健康数据上传
curl -X POST http://localhost:9998/api/health/upload \
  -H "Content-Type: application/json" \
  -d '[
    {
      "deviceSn": "test-device-001",
      "userId": 1,
      "heart_rate": 75,
      "blood_oxygen": 98,
      "temperature": 36.5,
      "timestamp": '$(date +%s000)'
    }
  ]'

# 检查Redis统计是否更新
redis-cli -a 123456 GET "health:stats:total_received"

---

7. 故障排查

7.1 WebSocket连接失败

现象: 前端显示"WebSocket 未连接"

排查步骤:

# 1. 检查后端日志
tail -f ljwx-boot/logs/ljwx-boot-admin_error.log | grep WebSocket

# 2. 检查端口监听
netstat -tuln | grep 9998

# 3. 测试WebSocket连接
curl -i -N -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  http://localhost:9998/ws/data-flow

# 4. 检查防火墙
sudo firewall-cmd --list-ports | grep 9998

常见问题:

• ❌ 后端未启动 → 运行 ./run-local.sh
• ❌ 端口被占用 → 更换端口或关闭占用进程
• ❌ 跨域问题 → 检查 WebSocketConfig.java 的 setAllowedOrigins

7.2 数据不更新

现象: Dashboard显示但数据不刷新

排查步骤:

# 1. 检查WebSocket推送日志
tail -f ljwx-boot/logs/ljwx-boot-admin_info.log | grep "推送数据流指标"

# 2. 检查Redis统计数据
redis-cli -a 123456 KEYS "health:stats:*"
redis-cli -a 123456 GET "health:stats:total_received"

# 3. 检查DataUpload是否记录指标
tail -f ljwx-boot/logs/ljwx-boot-admin_info.log | grep "📊"

常见问题:

• ❌ 无数据上传 → 使用curl模拟数据上传测试
• ❌ Redis键过期 → 检查TTL设置（默认1分钟）
• ❌ 指标记录失败 → 检查DataUpload中的异常日志

7.3 Grafana Dashboard无数据

现象: Grafana面板显示"No Data"

排查步骤:

# 1. 检查Prometheus数据源
kubectl port-forward -n infra svc/prometheus 9090:9090
# 访问: http://localhost:9090/targets

# 2. 检查Prometheus指标
curl http://localhost:9998/actuator/prometheus | grep health_data

# 3. 检查Prometheus查询
curl 'http://localhost:9090/api/v1/query?query=health_data_insert_total'

常见问题:

• ❌ Prometheus未采集 → 检查ServiceMonitor配置
• ❌ 指标未导出 → 检查ljwx-boot的Actuator配置
• ❌ 查询语法错误 → 验证PromQL语法

---

8. 性能优化

8.1 WebSocket连接数优化

优化配置 (application.yml):

server:
  tomcat:
    threads:
      max: 200              # 最大线程数
    max-connections: 10000  # 最大连接数

8.2 Redis键过期策略

当前设置:

• TTL: 1分钟（适合实时监控）
• 自动过期，无需手动清理

调整方法 (DataFlowWebSocketHandler.java):

// 调整过期时间为5分钟
private static final Duration STATS_TTL = Duration.ofMinutes(5);

8.3 推送频率调整

当前设置:

• 推送间隔: 3秒

调整方法 (DataFlowWebSocketHandler.java):

// 调整为每5秒推送一次
@Scheduled(fixedRate = 5000)
public void pushDataFlowMetrics() { ... }

8.4 前端性能优化

<!-- ECharts图表优化 -->
<script setup>
// 节流更新，避免频繁重绘
const updateChart = useDebounceFn((data) => {
  chartInstance.setOption(option, { notMerge: false })
}, 500)
</script>

---

9. 生产环境部署

9.1 K8s部署清单

ljwx-boot Deployment (已包含WebSocket支持):

apiVersion: v1
kind: Service
metadata:
  name: ljwx-boot-ws
  namespace: ljwx-health
spec:
  type: ClusterIP
  ports:
    - port: 9998
      targetPort: 9998
      protocol: TCP
      name: websocket
  selector:
    app: ljwx-boot

9.2 Nginx反向代理配置

# WebSocket代理
location /ws/ {
    proxy_pass http://ljwx-boot:9998;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400; # 24小时
}

9.3 环境变量配置

生产环境 (.env.production):

# API Base URL (使用域名)
VITE_API_URL=https://health.ljwx.com

# WebSocket自动推导为:
# wss://health.ljwx.com/ws/data-flow

---

10. 监控和告警

10.1 关键指标监控

Prometheus告警规则 (prometheus-rules.yml):

groups:
  - name: data_flow_alerts
    rules:
      - alert: HighDataLoss
        expr: health_data_dedup_rate > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "数据去重率过高"
          description: "去重率 {{ $value }}% 超过阈值50%"

      - alert: WebSocketDisconnected
        expr: absent(health_data_insert_total)
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "WebSocket推送中断"
          description: "超过2分钟未收到数据流指标"

---

附录

A. 完整目录结构

ljwx-health/
├── ljwx-boot/
│   ├── ljwx-boot-admin/src/main/java/com/ljwx/config/
│   │   └── WebSocketConfig.java
│   └── ljwx-boot-modules/src/main/java/com/ljwx/modules/
│       ├── monitor/websocket/
│       │   └── DataFlowWebSocketHandler.java
│       └── health/upload/
│           └── DataUpload.java (已修改)
│
├── ljwx-admin/
│   └── src/views/monitor/data-flow/
│       └── index.vue
│
├── deploy/monitoring/grafana/dashboards/
│   └── ljwx-health-data-flow.json
│
├── scripts/
│   └── verify-data-flow-dashboard.sh
│
└── DATA_FLOW_DASHBOARD_DEPLOYMENT.md (本文档)

B. 端口清单

服务	端口	协议	用途
ljwx-boot	9998	HTTP/WebSocket	后端API和WebSocket
ljwx-admin	3333	HTTP	前端应用
Redis	6379	Redis	统计数据存储
Grafana	3000	HTTP	监控Dashboard
Prometheus	9090	HTTP	指标采集

C. 参考资源

• ECharts Sankey官方文档
• Spring WebSocket文档
• Grafana Dashboard配置
• Prometheus查询语法

---

部署完成！ 🎉

如有问题，请参考故障排查章节或联系技术支持。