# monitoring-dashboard

**Repository Path**: ksphere/monitoring-dashboard

## Basic Information

- **Project Name**: monitoring-dashboard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2025-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KSphere 监控仪表板

[![Go Report Card](https://goreportcard.com/badge/gitee.com/ksphere/monitoring-dashboard)](https://goreportcard.com/report/gitee.com/ksphere/monitoring-dashboard)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

KSphere 监控仪表板是一个受 Grafana 启发的云原生监控解决方案，专为 KSphere 环境设计。它基于 Kubernetes Custom Resource Definition (CRD) 架构，提供声明式的仪表板配置管理，支持多租户隔离和模板共享。

> **重要提示**: 本项目不是 Grafana 的替代品，而是与 KSphere 后端和前端协同工作，为 KSphere 生态系统提供原生的监控仪表板功能。

## 📋 目录

- [项目概述](#项目概述)
- [核心特性](#核心特性)
- [快速开始](#快速开始)
- [前置条件](#前置条件)
- [安装部署](#安装部署)
- [概念与设计](#概念与设计)
- [使用指南](#使用指南)
- [转换工具](#转换工具)
- [开发指南](#开发指南)
- [贡献指南](#贡献指南)
- [常见问题](#常见问题)

## 🎯 项目概述

KSphere 监控仪表板采用云原生设计理念，充分利用 Kubernetes 的声明式 API 和多租户特性，为企业级监控提供：

- **声明式配置**: 使用 YAML 文件定义仪表板，支持 GitOps 工作流
- **多租户隔离**: 基于命名空间的天然隔离机制
- **模板共享**: 内置丰富的仪表板模板库
- **Grafana 兼容**: 支持从 Grafana 仪表板转换
- **深度集成**: 与 KSphere 生态系统无缝集成

### 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 编程语言 | Go | 1.13+ |
| 容器编排 | Kubernetes | 1.17+ |
| 容器运行时 | Docker | 20.10+ |
| 构建工具 | Kubebuilder | 2.3.0 |
| 数据源 | Prometheus | 2.20+ |

## ✨ 核心特性

### 🏗️ 云原生架构
- **CRD 驱动**: 基于 Kubernetes Custom Resource Definition
- **声明式配置**: 使用 YAML 定义和管理仪表板
- **控制器模式**: 自动化状态管理和 reconciliation
- **API 版本化**: 支持 v1alpha1 和 v1alpha2 两个版本

### 🔐 多租户支持
- **命名空间隔离**: 基于 Kubernetes 命名空间的天然隔离
- **权限控制**: 集成 RBAC 权限管理
- **数据安全**: 自动注入命名空间选择器，确保数据隔离
- **资源配额**: 支持命名空间级别的资源限制

### 📊 丰富的可视化
- **多种面板类型**: 支持单值统计、图表、表格、文本等
- **动态变量**: 支持查询变量和时间间隔变量
- **时间范围控制**: 灵活的时间范围设置
- **PromQL 支持**: 完整支持 Prometheus Query Language

### 🔄 模板生态
- **预置模板**: 提供 MySQL、Redis、Kubernetes 等常用监控模板
- **Grafana 转换**: 支持从 Grafana JSON 模板转换
- **社区贡献**: 开放的模板贡献机制

## 🚀 快速开始

### 前置条件

- **Kubernetes 集群**: v1.17 或更高版本
- **KSphere**: v3.0 或更高版本
- **kubectl**: 已配置并能访问目标集群
- **Docker**: 用于构建镜像（可选）

### 一键部署

```bash
# 1. 克隆项目
git clone https://gitee.com/ksphere/monitoring-dashboard.git
cd monitoring-dashboard

# 2. 安装 CRD
make install

# 3. 部署控制器
make deploy IMG=kubesphere/monitoring-dashboard:latest

# 4. 验证部署状态
kubectl get pods -n monitoring-dashboard-system
```

### 导入示例仪表板

```bash
# 导入 MySQL 监控仪表板
kubectl apply -f contrib/gallery/mysql.yaml

# 导入 Redis 监控仪表板  
kubectl apply -f contrib/gallery/redis.yaml

# 查看已创建的仪表板
kubectl get dashboards -A
```

## 🛠️ 安装部署

### 本地开发模式

```bash
# 构建控制器
make manager

# 运行控制器（需要配置 kubeconfig）
make run
```

### 容器化部署

```bash
# 构建 Docker 镜像
make docker-build IMG=kubesphere/monitoring-dashboard:v1.0.0

# 推送到镜像仓库
make docker-push IMG=kubesphere/monitoring-dashboard:v1.0.0

# 部署到集群
make deploy IMG=kubesphere/monitoring-dashboard:v1.0.0
```

### Helm 部署（未来支持）

```bash
# 添加 Helm 仓库（计划中）
helm repo add kubesphere https://charts.kubesphere.io

# 安装
helm install monitoring-dashboard kubesphere/monitoring-dashboard
```

## 🎨 概念与设计

### 数据模型架构

KSphere 监控仪表板基于三种核心资源类型：

```
Dashboard (命名空间级别)      ┌─────────────────┐
                           │   CRD 定义      │
ClusterDashboard (集群级别)  │                 │
                           │   控制器        │
DashboardTemplate (模板)    │                 │
                           │   前端渲染      │
                           └─────────────────┘
```

### 核心组件

#### 1. Dashboard 资源

```yaml
apiVersion: monitoring.kubesphere.io/v1alpha2
kind: Dashboard
metadata:
  name: mysql-overview
  namespace: monitoring
spec:
  title: "MySQL 概览仪表板"
  description: "MySQL 数据库监控仪表板"
  datasource: "prometheus"
  time:
    from: "now-1h"
    to: "now"
  auto_refresh: "1m"
  panels: [...]
  templatings: [...]
```

#### 2. Panel 面板类型

| 面板类型 | 版本 | 用途 | 配置复杂度 |
|----------|------|------|------------|
| `row` | v1alpha1 | 行容器，用于组织面板 | ⭐ |
| `singlestat` | v1alpha1 | 单值统计，显示关键指标 | ⭐⭐ |
| `graph` | v1alpha1 | 时序图表，显示趋势 | ⭐⭐⭐ |
| `bargauge` | v1alpha2 | 条形仪表盘 | ⭐⭐ |
| `table` | v1alpha2 | 表格显示 | ⭐⭐⭐ |
| `text` | v1alpha2 | 文本展示 | ⭐ |

#### 3. 变量系统

```yaml
templatings:
  # 查询变量
  - name: "namespace"
    label: "命名空间"
    type: "query"
    query: "label_values(kube_pod_info, namespace)"
    
  # 时间间隔变量
  - name: "interval"
    label: "间隔"
    type: "interval"
    values: ["30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"]
```

### 多租户设计

```mermaid
graph TB
    A[用户请求] --> B[KSphere 后端]
    B --> C[命名空间检查]
    C --> D[注入选择器]
    D --> E[Prometheus 查询]
    E --> F[数据返回]
    
    G[仪表板 CR] --> H[控制器]
    H --> I[状态管理]
    I --> J[前端渲染]
```

**隔离机制**:
- 每个 Dashboard 绑定到特定命名空间
- 查询自动注入 `{namespace="<namespace>"}` 选择器
- RBAC 权限控制访问范围
- 数据源层面隔离

## 📖 使用指南

### 创建自定义仪表板

#### 1. 基础仪表板示例

```yaml
apiVersion: monitoring.kubesphere.io/v1alpha2
kind: Dashboard
metadata:
  name: app-overview
  namespace: production
spec:
  title: "应用概览"
  description: "应用核心指标监控"
  datasource: "prometheus"
  time:
    from: "now-1h"
    to: "now"
  panels:
    - type: singlestat
      title: "请求总数"
      targets:
        - expr: "sum(rate(http_requests_total[5m]))"
          legendFormat: "QPS"
      thresholds:
        - value: 100
          color: "green"
        - value: 500
          color: "yellow"
        - value: 1000
          color: "red"
    
    - type: graph
      title: "响应时间趋势"
      targets:
        - expr: "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
          legendFormat: "P95"
        - expr: "histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))"
          legendFormat: "P99"
```

#### 2. 使用变量

```yaml
apiVersion: monitoring.kubesphere.io/v1alpha2
kind: Dashboard
metadata:
  name: service-metrics
  namespace: monitoring
spec:
  title: "服务指标监控"
  templatings:
    - name: service
      label: "服务名称"
      type: query
      query: "label_values(http_requests_total, service)"
      refresh: 1
      
    - name: instance
      label: "实例"
      type: query
      query: "label_values(http_requests_total{service=\"$service\"}, instance)"
      
  panels:
    - type: graph
      title: "服务请求量 - $service"
      targets:
        - expr: "sum(rate(http_requests_total{service=\"$service\", instance=\"$instance\"}[5m]))"
          legendFormat: "$instance"
```

### 时间范围配置

| 时间表达式 | 说明 | 示例 |
|-----------|------|------|
| `now-5m` | 最近5分钟 | 短期监控 |
| `now-1h` | 最近1小时 | 小时级分析 |
| `now-1d` | 最近1天 | 日级分析 |
| `now-1w` | 最近1周 | 周级分析 |
| `now-3M` | 最近3个月 | 季度分析 |

### 查询最佳实践

#### 1. 使用标签过滤
```yaml
# 推荐：使用标签进行精确过滤
expr: "cpu_usage{namespace=\"$namespace\", pod=\"$pod\"}"

# 避免：全量数据查询
expr: "cpu_usage"
```

#### 2. 合理使用聚合函数
```yaml
# 推荐：适当的聚合粒度
expr: "sum(rate(container_cpu_usage_seconds_total[5m])) by (pod)"

# 推荐：使用比率而不是原始值
expr: "rate(container_cpu_usage_seconds_total[5m])"
```

#### 3. 阈值设置
```yaml
panels:
  - type: singlestat
    title: "CPU 使用率"
    targets:
      - expr: "cpu_usage_percent"
    thresholds:
      - value: 50    # 绿色阈值
        color: "green"
      - value: 80    # 黄色阈值  
        color: "yellow"
      - value: 90    # 红色阈值
        color: "red"
```

## 🔄 转换工具

### Grafana 仪表板转换

KSphere 提供了强大的 Grafana 仪表板转换工具，可以将现有的 Grafana JSON 模板转换为 KSphere CRD 格式。

#### 命令行使用

```bash
# 基本转换
go run ./cmd/converter \
  -inputPath=./grafana-dashboards \
  -outputPath=./converted-dashboards \
  -namespace=monitoring \
  -isClusterCrd=false

# 指定输出名称
go run ./cmd/converter \
  -inputPath=./mysql-dashboard.json \
  -outputPath=./output \
  -name=mysql-monitoring \
  -namespace=monitoring \
  -isClusterCrd=false

# 转换为集群级别仪表板
go run ./cmd/converter \
  -inputPath=./cluster-dashboard.json \
  -outputPath=./cluster-output \
  -isClusterCrd=true
```

#### 使用 Makefile

```bash
# 设置变量
export INPUT=./grafana-dashboards/mysql.json
export OUTPUT=./converted
export NAMESPACE=monitoring
export IS_CLUSTER_CRD=false
export NAME=mysql-dashboard

# 执行转换
make convert \
  INPUT=$(INPUT) \
  OUTPUT=$(OUTPUT) \
  NAMESPACE=$(NAMESPACE) \
  IS_CLUSTER_CRD=$(IS_CLUSTER_CRD) \
  NAME=$(NAME)
```

#### 程序化转换

```go
package main

import (
    "gitee.com/ksphere/monitoring-dashboard/tools/converter"
)

func main() {
    grafanaJSON := `{
        "title": "MySQL Overview",
        "panels": [...],
        "templating": {...}
    }`
    
    dashboard, err := converter.ConvertToDashboard([]byte(grafanaJSON))
    if err != nil {
        panic(err)
    }
    
    // 输出为 YAML
    yamlData, err := yaml.Marshal(dashboard)
    if err != nil {
        panic(err)
    }
    
    fmt.Println(string(yamlData))
}
```

### 转换映射关系

| Grafana 字段 | KSphere 字段 | 说明 |
|-------------|-----------------|------|
| `title` | `spec.title` | 仪表板标题 |
| `panels` | `spec.panels` | 面板配置 |
| `templating.list` | `spec.templatings` | 变量配置 |
| `time.from` | `spec.time.from` | 开始时间 |
| `time.to` | `spec.time.to` | 结束时间 |
| `refresh` | `spec.auto_refresh` | 自动刷新 |

## 👨‍💻 开发指南

### 开发环境设置

```bash
# 1. 克隆项目
git clone https://gitee.com/ksphere/monitoring-dashboard.git
cd monitoring-dashboard

# 2. 安装依赖
go mod download

# 3. 安装 kubebuilder (如需)
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/
```

### 项目结构

```
monitoring-dashboard/
├── api/                     # API 定义
│   ├── v1alpha1/           # API v1alpha1 版本
│   │   ├── dashboard_types.go
│   │   ├── panels/         # 面板类型定义
│   │   └── zz_generated.deepcopy.go
│   └── v1alpha2/           # API v1alpha2 版本 (storage version)
├── cmd/                    # 命令行工具
│   └── converter/          # Grafana 转换器
├── config/                 # Kubernetes 配置
│   ├── crd/               # CRD 定义
│   ├── manager/           # 控制器配置
│   ├── rbac/              # RBAC 配置
│   └── samples/           # 示例配置
├── contrib/               # 仪表板模板库
│   └── gallery/           # 预定义模板
├── tools/                 # 工具包
│   └── converter/         # 转换器实现
├── docs/                  # 文档
├── main.go               # 控制器入口
├── Makefile              # 构建脚本
└── go.mod                # Go 模块定义
```

### API 开发

#### 1. 添加新的面板类型

```go
// api/v1alpha2/panels/newpanel_types.go
package panels

type NewPanel struct {
    Type string `json:"type"`
    Title string `json:"title"`
    
    // 新面板特有字段
    CustomField string `json:"customField,omitempty"`
    Options map[string]interface{} `json:"options,omitempty"`
    
    // 通用字段
    Targets []Target `json:"targets"`
    DataSource string `json:"datasource,omitempty"`
}
```

#### 2. 更新 CRD 定义

```bash
# 生成 deepcopy 方法
make generate

# 更新 CRD 清单
make manifests
```

#### 3. 添加控制器逻辑（如需要）

```go
// internal/controller/dashboard_controller.go
func (r *DashboardReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
    // 添加新面板类型的处理逻辑
}
```

### 测试指南

#### 单元测试

```bash
# 运行所有测试
make test

# 运行特定包测试
go test ./api/v1alpha1/...

# 生成测试覆盖率报告
make test-cover
```

#### 集成测试

```bash
# 在 Kind 集群上测试
kind create cluster
export KUBECONFIG=$(kind get kubeconfig-path)

# 安装 CRD 并运行测试
make install && make run
```

### 代码规范

#### Go 代码规范

- 遵循 [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)
- 使用 `gofmt` 格式化代码
- 使用 `golint` 检查代码质量
- 添加适当的注释和文档

#### API 变更流程

1. **API 变更提议**: 在 GitHub Issue 中讨论
2. **API 设计**: 创建设计文档
3. **实现变更**: 修改 API 定义和控制器
4. **版本管理**: 遵循 Kubernetes API 版本约定
5. **测试验证**: 编写充分的测试用例

## 🤝 贡献指南

我们欢迎所有形式的贡献！无论是代码、文档、测试还是仪表板模板。

### 贡献方式

#### 1. 仪表板模板贡献

贡献仪表板模板是最直接的参与方式：

```bash
# 1. 创建新的模板文件
cp contrib/gallery/template.yaml contrib/gallery/my-dashboard.yaml

# 2. 编辑模板内容
vim contrib/gallery/my-dashboard.yaml

# 3. 添加说明文档
echo "# My Dashboard

这是一个用于监控 XXX 的仪表板模板。

## 面板说明
- 面板1: XXX指标
- 面板2: XXX趋势

## 使用要求
- Prometheus Exporter: xxx-exporter
- 标签要求: app=myapp
" > contrib/gallery/my-dashboard.md

# 4. 提交 Pull Request
git add contrib/gallery/my-dashboard.yaml contrib/gallery/my-dashboard.md
git commit -m "Add my dashboard template"
git push origin feature/my-dashboard
```

#### 2. 代码贡献

```bash
# 1. Fork 项目
# 2. 创建功能分支
git checkout -b feature/new-feature

# 3. 进行开发
# ... 编写代码 ...

# 4. 运行测试
make test

# 5. 提交代码
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

# 6. 创建 Pull Request
```

#### 3. 文档贡献

- 改进现有文档的准确性和可读性
- 添加使用案例和最佳实践
- 翻译文档到其他语言
- 创建教程和视频

### 代码审查标准

#### 必须满足

- [ ] 所有测试通过
- [ ] 代码符合 Go 规范
- [ ] 添加适当的文档
- [ ] 更新相关文档（如需要）
- [ ] 通过安全检查

#### 优先考虑

- [ ] 向后兼容性
- [ ] 性能优化
- [ ] 用户体验改进
- [ ] 代码可维护性

### 社区行为准则

我们致力于为每个人提供友好、安全、欢迎的环境。所有参与者必须遵守我们的行为准则：

- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心

## ❓ 常见问题

### 安装和部署问题

**Q: 控制器 Pod 无法启动？**

A: 检查以下几点：
```bash
# 检查 RBAC 权限
kubectl get clusterrole | grep monitoring-dashboard

# 检查 CRD 安装状态
kubectl get crd | grep monitoring.kubesphere.io

# 查看 Pod 日志
kubectl logs -n monitoring-dashboard-system -l app=monitoring-dashboard
```

**Q: 仪表板不显示数据？**

A: 可能的原因：
- Prometheus 数据源配置错误
- 命名空间隔离问题
- 查询表达式语法错误
- 数据源连接问题

### 查询问题

**Q: 如何查询跨命名空间的指标？**

A: 当前设计中，所有查询都会自动注入命名空间选择器。如需跨命名空间查询，需要使用 ClusterDashboard 或在 KSphere 后端进行特殊配置。

**Q: 变量替换不生效？**

A: 检查变量定义：
- 变量名称是否正确
- 查询表达式中的变量格式：`$variable_name`
- 变量是否有有效的返回值

### 性能问题

**Q: 仪表板加载缓慢？**

A: 优化建议：
- 减少查询的时间范围
- 使用预聚合数据
- 优化 PromQL 表达式
- 启用查询缓存

**Q: 内存使用过高？**

A: 可能的原因和解决方案：
- 大量并发查询：限制并发数
- 复杂的 PromQL：简化表达式
- 数据量大：增加采样间隔

### 兼容性问题

**Q: v1alpha1 和 v1alpha2 的区别？**

A: 主要差异：
- v1alpha2 是 storage version
- v1alpha2 支持更多面板类型（bargauge, table, text）
- v1alpha2 支持注释和自动刷新
- v1alpha2 有更多配置选项

**Q: 如何从 v1alpha1 升级到 v1alpha2？**

A: 升级步骤：
```bash
# 1. 备份现有仪表板
kubectl get dashboards -A -o yaml > dashboard-backup.yaml

# 2. 更新 CRD
kubectl apply -f config/crd/bases/

# 3. 仪表板会自动转换（大部分情况下）
# 4. 验证仪表板是否正常工作
kubectl get dashboards -A
```

## 📚 更多资源

### 官方文档

- [KSphere 官方网站](https://kubesphere.io/)
- [KSphere 开发者指南](https://gitee.com/ksphere/community/tree/master/developer-guide)
- [Kubernetes CRD 文档](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
- [Prometheus 查询语言](https://prometheus.io/docs/prometheus/latest/querying/basics/)

### 社区资源

- [KubeSlack](https://kubesphere.slack.com/): 实时聊天和讨论
- [GitHub Discussions](https://gitee.com/ksphere/monitoring-dashboard/discussions): 问题和讨论
- [YouTube 频道](https://www.youtube.com/c/KSphere): 视频教程

### 相关项目

- [KSphere Console](https://gitee.com/ksphere/console): 前端界面
- [KSphere Backend](https://gitee.com/ksphere/kubesphere): 后端服务
- [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator): Prometheus 部署和管理

## 📄 许可证

本项目采用 [Apache License 2.0](LICENSE) 许可证。

---

**感谢您对 KSphere 监控仪表板项目的关注！** 🎉

如果您觉得这个项目有用，请给我们一个 ⭐️，并考虑贡献代码或分享您的使用经验。