🚀 MCP-DevOps Kubernetes 管理系统

!GitHub release (latest SemVer)

智能化的 Kubernetes 资源管理与故障诊断系统

系统架构 • 功能特性 • 环境要求 • 快速开始 • 使用示例 • 安全注意事项

MCP-DevOps 是一个基于 Go 语言开发的 Kubernetes 资源管理系统，它提供了简单易用的命令行界面来管理 Kubernetes 集群资源。该系统使用客户端-服务器架构，通过语义化交互提供直观的操作方式。

🏗️ 系统架构

系统由两部分组成：

1. Server ⚙️：运行在有权限访问 Kubernetes 集群的环境中，提供 Kubernetes 资源操作的 API 接口
2. Client 🖥️：命令行交互客户端，连接到服务器并提供自然语言交互界面

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│             │       │             │       │             │
│   Client    │◄─────►│   Server    │◄─────►│ Kubernetes  │
│  (AI 交互)   │       │ (API 服务)  │       │   集群      │
│             │       │             │       │             │
└─────────────┘       └─────────────┘       └─────────────┘

🌟 功能特性

🔄 Kubernetes 资源管理

🚨 故障诊断与告警处理

• 🏥 集群健康检查：获取集群整体健康状态，包括节点、Pod 和命名空间状态
• 🔍 Pod 诊断：深入分析 Pod 问题，检查容器状态、事件和日志，提供解决建议
• 📊 节点诊断：检查节点状态、资源使用情况和运行的 Pod，识别潜在问题
• 🚀 Deployment 诊断：分析 Deployment 部署和更新问题，检查副本状态和事件
• ⚠️ 告警分析：处理和分析 Prometheus/Alertmanager 告警，提供根本原因分析和解决方案
• 📱 企业微信通知：支持发送文本、Markdown 和卡片类型的企业微信消息，用于告警通知和状态报告
• 🔔 Alertmanager Webhook 集成：客户端内置 Webhook 监听器（默认端口 9094），可接收 Alertmanager 告警，交由 AI 分析并通过企业微信发送通知

📜 Loki日志分析与通知

• 🔎 日志查询：查询指定服务的Loki日志，支持最近30分钟或自定义时间范围的日志查看
• 📊 日志分析：分析服务日志，提取关键信息和模式，提供运行状态总结
• 📤 通知发送：将日志分析结果通过企业微信发送，支持中文内容，确保团队及时了解服务状态

🔍 ClickHouse 链路追踪分析

• 📊 服务深度分析：针对单个服务进行全方位性能分析，包括调用模式、错误率、延迟分布等
• 🔗 Trace 链路分析：深度分析单个 trace_id 的完整调用链路，识别性能瓶颈和异常行为
• 🎯 异常追踪：自动查找包含错误 spans 的 trace，快速定位问题来源
• ⚡ 性能优化：识别慢查询、大跨度链路和性能异常，提供优化建议
• 📈 时间趋势：分析服务在不同时间段的性能表现，识别性能劣化趋势
• 🔄 依赖分析：分析服务间的调用关系和依赖模式，优化服务架构
• 🚨 健康评估：基于错误率和延迟自动评估服务健康状态，提供诊断建议

🐧 Linux 系统排查

• 💻 系统信息：获取主机基本信息，包括操作系统、内核版本、资源使用情况等
• ⚙️ 进程管理：查看和分析进程状态，识别高 CPU 或内存使用的进程
• 📈 资源监控：监控 CPU、内存和磁盘使用情况，识别资源瓶颈
• 🌐 网络诊断：检查网络连接、接口状态和路由配置，排查网络问题
• 📝 日志分析：分析系统日志文件，查找错误和警告信息
• 🔄 服务状态：检查系统服务运行状态，管理服务启停

⚙️ Kubernetes 组件排查

• 🔄 Kubelet 状态：检查 Kubelet 服务状态和日志，排查节点问题
• 🐳 容器运行时：检查 Docker、Containerd 或 CRI-O 状态，排查容器问题
• 🔌 Kube-Proxy：检查 Kube-Proxy 状态和配置，排查服务网络问题
• 🌐 CNI 状态：检查网络插件状态和配置，排查 Pod 网络问题
• 📝 组件日志：分析 Kubernetes 组件日志，查找错误和警告信息
• 🔍 容器检查：检查容器详情和日志，深入排查应用问题

🔑 Redis 工具

• 📊 Redis 信息：获取 Redis 服务器运行时信息
• ⏱️ 慢查询分析：分析 Redis 慢查询日志
• 🔍 大键查找：查找 Redis 中的大键（超过 1MB）
• 🔥 热键查找：查找 Redis 中的热键
• 👀 命令监控：实时查看 Redis 执行的命令流（高负载，慎用）
• 📉 延迟测量：测量 Redis 的延迟
• 📈 延迟历史：测量 Redis 延迟并获取历史数据
• 📊 统计信息：实时查看 Redis 简洁统计信息

🤖 交互与用户体验

• 💬 自然语言交互：通过自然语言描述你想执行的操作
• 🇨🇳 中文支持：系统默认使用中文进行交互
• 🧠 智能故障分析：AI 自动分析故障模式并提供解决方案
• 🚨 告警智能处理：自动分析告警信息，执行诊断步骤，提供详细报告

🛠️ 环境要求

🚀 快速开始

cd server
go run main.go

cd client
go run main.go

💬 使用示例

客户端启动后，您可以使用自然语言输入以下示例命令：

🔒 安全注意事项

📁 项目结构

mcp-devops/
├── client/                # 客户端代码
│   ├── main.go            # 客户端主程序
│   └── pkg/               # 客户端包
│       ├── model/         # 模型相关代码
│       └── mcp/           # MCP 客户端实现
├── server/                # 服务器代码
│   ├── main.go            # 服务器主程序
│   ├── k8s/               # Kubernetes 操作工具
│   │   ├── client.go      # Kubernetes 客户端
│   │   ├── pod.go         # Pod 相关操作
│   │   ├── deployment.go  # Deployment 相关操作
│   │   ├── service.go     # Service 相关操作
│   │   ├── statefulset.go # StatefulSet 相关操作
│   │   ├── namespace.go   # Namespace 相关操作
│   │   ├── ingress.go     # Ingress 相关操作
│   │   ├── configmap.go   # ConfigMap 相关操作
│   │   ├── secret.go      # Secret 相关操作
│   │   ├── troubleshoot.go # 故障诊断工具
│   │   └── wechat.go      # 企业微信通知
│   ├── clickhouse/        # ClickHouse 链路追踪分析工具
│   │   └── tools.go       # 链路追踪分析、服务性能分析
│   ├── linux/             # Linux 系统操作工具
│   │   ├── system.go      # 系统信息和资源监控
│   │   └── kubernetes.go  # Kubernetes 组件排查
│   └── sse/               # SSE 服务实现
│       └── server.go      # SSE 服务器
├── .env                   # 环境配置文件
├── go.mod                 # Go 模块定义
└── go.sum                 # Go 依赖校验

🔧 开发与扩展

// 1. 创建 server/k8s/cronjob.go 文件实现相关功能
// 2. 在 server/sse/server.go 中注册工具：
svr.AddTool(mcp.NewTool("list_cronjobs",
    mcp.WithDescription("列出指定命名空间中的所有CronJob"),
    mcp.WithString("namespace",
        mcp.Description("要查询的命名空间, 默认为default"),
        mcp.DefaultString("default"),
    ),
), k8s.ListCronJobsTool)
// 3. 重启服务器和客户端

⚠️ 注意事项

🐛 故障排除

# 检查服务器是否正在运行
netstat -tlnp | grep 12345

# 检查防火墙设置
sudo ufw status

# 检查配置文件中的服务器地址
cat .env | grep MCP_SERVER

# 检查当前用户的 kubeconfig
kubectl config current-context

# 测试集群连接
kubectl cluster-info

# 检查权限
kubectl auth can-i get pods --all-namespaces

# 测试 API 密钥有效性
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.openai.com/v1/models

🔄 版本信息

📋 更新日志

🤝 贡献指南

我们欢迎社区贡献！以下是参与项目的方式：

📋 贡献类型

🔄 开发流程

1. Fork 项目

   git clone https://github.com/yourusername/mcp-devops.git
   cd mcp-devops
   

2. 创建特性分支

   git checkout -b feature/your-feature-name
   

3. 开发和测试

   # 安装依赖
   go mod tidy
   
   # 运行测试
   go test ./...
   
   # 代码格式化
   go fmt ./...
   

4. 提交更改

   git add .
   git commit -m "feat: 添加新功能描述"
   

5. 提交 Pull Request

   • 详细描述更改内容
   • 包含相关的测试
   • 更新文档（如需要）

📝 代码规范

• 遵循 Go 语言标准代码规范
• 为新功能添加适当的注释
• 确保向后兼容性
• 包含必要的错误处理

🚀 添加新的 Kubernetes 资源支持

如需添加对新 Kubernetes 资源的支持：

// 1. 在 server/k8s/ 目录创建资源处理文件
// 例如：server/k8s/persistentvolume.go

func ListPersistentVolumesTool(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // 实现 PV 列表功能
}

// 2. 在 server/sse/server.go 中注册工具
svr.AddTool(mcp.NewTool("list_persistent_volumes",
    mcp.WithDescription("列出集群中的 PersistentVolume"),
), k8s.ListPersistentVolumesTool)

📚 API 文档

🔗 MCP 工具接口

list_pods:
  description: "列出指定命名空间中的 Pod"
  parameters:
    namespace: 
      type: string
      default: "default"
      description: "命名空间名称"

pod_logs:
  description: "获取 Pod 日志"
  parameters:
    name:
      type: string
      required: true
      description: "Pod 名称"
    namespace:
      type: string
      default: "default"
    container:
      type: string
      description: "容器名称（可选）"

pod_diagnostic:
  description: "诊断 Pod 问题"
  parameters:
    name:
      type: string
      required: true
    namespace:
      type: string
      default: "default"

cluster_health:
  description: "检查集群健康状态"
  parameters: {}

analyze_service:
  description: "深度分析服务性能"
  parameters:
    service_name:
      type: string
      required: true
    time_range_hours:
      type: number
      default: 24

trace_analysis:
  description: "分析特定 trace"
  parameters:
    trace_id:
      type: string
      required: true

📡 Webhook 接口

Alertmanager 告警接收

POST http://client-host:9094/webhook
Content-Type: application/json

{
  "alerts": [
    {
      "labels": {
        "alertname": "HighCPUUsage",
        "instance": "worker-1",
        "severity": "warning"
      },
      "annotations": {
        "description": "CPU usage high",
        "summary": "CPU 使用率过高"
      },
      "status": "firing"
    }
  ]
}

🔬 测试指南

🧪 单元测试

# 运行所有测试
go test ./...

# 运行特定模块测试
go test ./server/k8s/...

# 生成测试覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

🔍 集成测试

1. Kubernetes 集群测试

   # 确保有可访问的 K8s 集群
   kubectl cluster-info
   
   # 运行 K8s 相关测试
   cd test/kubernetes
   go run main.go
   

2. ClickHouse 连接测试

   # 测试 ClickHouse 连接
   cd test/clickhouse
   go run main.go
   

3. Loki 日志查询测试

   # 测试 Loki 查询
   cd test/loki
   go run main.go
   

🎯 性能测试

# 使用 go tool pprof 进行性能分析
go test -bench=. -benchmem -cpuprofile=cpu.prof
go tool pprof cpu.prof

🏆 致谢

感谢以下开源项目和贡献者：

Kubernetes

ClickHouse

Loki

Redis

核心依赖

• mark3labs/mcp-go - MCP 协议实现
• cloudwego/eino - AI 模型集成
• kubernetes/client-go - Kubernetes API 客户端

📄 许可证

本项目采用 Apache License 2.0 许可证。

Copyright 2024 MCP-DevOps Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

📞 联系我们