使用说明

🤖 AI SRE - 智能站点可靠性工程

一个轻量级的、容器化的工具箱，用于支持AI驱动的站点可靠性工程（Site Reliability Engineering）操作。此项目提供了一个 符合模型上下文协议（MCP）的服务器 该工具通过标准化的MCP工具暴露Kubernetes、Git和Flux的操作，旨在与N8N的MCP客户端节点实现无缝集成。

🚀 准备就绪，可投入生产轻量级（< 256MB 内存）、启动快速（< 10 秒），并且已在使用 Flux GitOps 进行 Kubernetes 操作中经过实战检验。 现在已全面支持MCP协议！

🏗️ 建筑学

集装箱无状态命令执行器（< 256MB RAM，< 500MB 镜像）
**编曲；调度（在音乐或戏剧等领域中，指安排和协调各个部分以形成整体）**外部（N8N负责智能处理、警报处理、RAG/向量存储）
**GitOps（Git 操作）**仅使用流的方法简化操作
协议： 模型上下文协议（MCP） - 通过WebSocket/HTTP的JSON-RPC
整合与N8N的MCP客户端节点直接兼容

🚀 快速入门

先决条件

Docker & Docker Compose
Kubernetes 集群（本地或远程）
Flux CLI（用于GitOps操作）
Git仓库访问

安装

# Clone and setup
git clone https://github.com/nachtschatt3n/ai-sre.git
cd ai-sre

# Configure environment
cp env.template .env
# Edit .env with your configuration

# Build and run
make init
make build
make run

# Test the MCP server
curl http://localhost:8080/health

# Test MCP protocol
curl -X POST http://localhost:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

Git仓库配置

AI SRE服务器在启动时可以自动克隆并管理您的Kubernetes GitOps仓库。

环境变量

创建一个 .env 从模板中获取文件：

cp env.template .env
nano .env

所需的Git配置：

# Kubernetes GitOps repository
K8S_GIT_REPO=git@github.com:your-org/your-k8s-repo.git
K8S_GIT_BRANCH=main
K8S_REPO_PATH=/app/k8s-repo

# Git user configuration
GITHUB_USER=AI-SRE
GITHUB_EMAIL=ai-sre@your-org.com

# Authentication (choose one)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx  # For HTTPS
# OR mount SSH keys: ${HOME}/.ssh:/home/aisre/.ssh:ro

认证方法

选项1：SSH密钥（推荐）

# Mount SSH keys in docker-compose.yaml
volumes:
  - ${HOME}/.ssh:/home/aisre/.ssh:ro

# Set repository URL to SSH
K8S_GIT_REPO=git@github.com:your-org/your-k8s-repo.git

选项2：GitHub令牌

# Set repository URL to HTTPS
K8S_GIT_REPO=https://github.com/your-org/your-k8s-repo.git
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

自动仓库初始化

启动时，服务器将：

✅ 如果仓库不存在，则克隆它
✅ 如果仓库存在，则拉取最新更改
✅ 切换到指定的分支
✅ 显示仓库状态和最新提交

Docker Compose（推荐）

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f ai-sre

# Stop services
docker-compose down

Kubernetes 部署

# Deploy to Kubernetes
kubectl apply -f k8s-repo/manifests/

# Check deployment
kubectl get pods -n ai-sre

# Port forward for testing
kubectl port-forward svc/ai-sre 8080:8080 -n ai-sre

✨ 主要特点

🎯（瞄准目标） AI驱动的运营

智能事件响应自动化诊断与修复
模式识别从事件中吸取教训，防止未来出现问题
预测性监控基于学习模式的主动预警
自我修复自动恢复常见的Kubernetes问题

🔧 修理工具或螺丝刀的符号，常用于表示需要修理或使用工具的情境。 MCP协议工具

Kubernetes 运维

kubectl_get - 获取Kubernetes资源（Pods、节点、服务等）
kubectl_describe - 使用详细信息描述 Kubernetes 资源
kubectl_logs - 获取Pod日志以进行故障排除

GitOps 与 Flux

flux_status - 获取Flux GitOps的同步状态和健康状况

Git 操作

git_status - 检查Git仓库状态
git_pull - 从Kubernetes Git仓库拉取最新更改
git_commit - 将更改提交到 Kubernetes Git 仓库
git_push - 将更改推送到 Kubernetes Git 仓库

命令行工具与诊断

cli_tool - 执行CLI工具（jq、grep、sed、curl、cat、tree、find等）
health_check - 检查系统和服务的健康状态

MCP协议支持

WebSocket 连接实时双向通信
JSON-RPC 2.0标准化消息格式
工具发现自动工具列表生成和能力协商
资源管理访问配置和版本信息

系统与健康

GET /health - 健康检查端点
GET /ready - 就绪性探针
WebSocket: ws://host:port/mcp - MCP协议端点
HTTP MCP（此处“MCP”可能代表特定上下文中的某个概念或协议，但无具体上下文时可直译为“HTTP MCP”，若“MCP”有特定含义，需根据上下文调整）： POST /mcp/http - 基于HTTP的MCP用于测试

📦 表示“包裹”或“箱子”。集装箱规格

规格	值	备注
图像尺寸	< 500MB	基于Alpine优化的镜像
内存使用情况	< 256MB	高效资源利用
CPU使用率	< 0.2 核	轻量级处理
启动时间	< 10 秒	快速容器初始化
依赖项	最小配置	仅使用 Python + aiohttp

📚 书籍全面的运行手册系统

4,212+ 行内容包含模板和最佳实践的广泛知识库
静态模板事件响应、修复及事后分析模板
动态内容实时事件追踪与模式识别
学习系统持续的知识库更新和模式演化
最佳实践监控、警报和操作指南
搜索与发现智能搜索索引，快速知识检索

🛡️ 译为中文是“护盾”。安全与可靠性

RBAC集成全面支持 Kubernetes RBAC（基于角色的访问控制）
秘密管理安全处理凭证和令牌
审计日志记录完整的操作审计追踪
错误处理优雅的故障恢复
资源限制内置资源限制

💡 使用示例

N8N MCP 客户端集成

AI SRE服务器与N8N的MCP客户端节点完全兼容，为自动化事件响应和GitOps工作流提供了无缝集成。

{
  "connectionType": "WebSocket",
  "serverUrl": "ws://ai-sre.ai.svc.cluster.local:8080/mcp",
  "authentication": {
    "type": "none"
  }
}

可用的N8N集成资源

**机器人🤖 代理提示（或“智能体提示”）**针对不同场景的12项全面提示
**📝（注：这个符号本身是一个记录或便签的图标，没有直接的中文翻译，但可以理解为“记录”或“便签”的意思。）事件示例**实际场景中的Pod CrashLoop响应工作流程
**🧠 表示“大脑”或“思考”的意思。学习提示**持续学习和知识更新
**🔗（链接符号，无直接对应中文翻译，可保持原样或根据上下文替换为“链接”等表述）集成指南**完整的安装与配置指南

MCP工具执行示例

获取 Kubernetes Pods

{
  "method": "tools/call",
  "params": {
    "name": "kubectl_get",
    "arguments": {
      "resource": "pods",
      "namespace": "default",
      "output": "json"
    }
  }
}

获取Pod日志

{
  "method": "tools/call",
  "params": {
    "name": "kubectl_logs",
    "arguments": {
      "pod": "my-app-7d4b8c9f-x2k9m",
      "namespace": "production",
      "lines": 100
    }
  }
}

检查Flux GitOps状态

{
  "method": "tools/call",
  "params": {
    "name": "flux_status",
    "arguments": {
      "namespace": "flux-system"
    }
  }
}

执行CLI工具

{
  "method": "tools/call",
  "params": {
    "name": "cli_tool",
    "arguments": {
      "tool": "jq",
      "args": [".status.phase"],
      "input": "{{ $json.kubectl_output }}"
    }
  }
}

健康检查

{
  "method": "tools/call",
  "params": {
    "name": "health_check",
    "arguments": {}
  }
}

Git 仓库操作

{
  "method": "tools/call",
  "params": {
    "name": "git_pull",
    "arguments": {
      "branch": "main",
      "force": false
    }
  }
}

提交更改

{
  "method": "tools/call",
  "params": {
    "name": "git_commit",
    "arguments": {
      "message": "fix: update resource limits",
      "files": ["manifests/deployment.yaml"],
      "all": false
    }
  }
}

推送更改

{
  "method": "tools/call",
  "params": {
    "name": "git_push",
    "arguments": {
      "branch": "main",
      "force": false
    }
  }
}

MCP协议测试

# Test health endpoint
curl http://localhost:8080/health

# Test MCP initialization
curl -X POST http://localhost:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {"tools": {}},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

# List available tools
curl -X POST http://localhost:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# Execute a tool
curl -X POST http://localhost:8080/mcp/http \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "kubectl_get",
      "arguments": {
        "resource": "pods",
        "namespace": "default"
      }
    }
  }'

WebSocket 连接（JavaScript）

const ws = new WebSocket('ws://localhost:8080/mcp');

ws.onopen = () => {
  // Initialize MCP connection
  ws.send(JSON.stringify({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {"tools": {}},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
  }));
};

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log('MCP Response:', response);
};

📁 项目结构

ai-sre/
├── 📄 README.md                    # This comprehensive guide
├── 📄 LICENSE                      # MIT License
├── 🐳 Dockerfile                   # Lean container definition
├── 🐳 docker-compose.yaml          # Local development setup
├── 🔧 Makefile                     # Build and management commands
├── ⚙️  env.template                 # Environment variables template
├── 🧪 test_mcp.py                  # MCP server testing script
├── 📁 docs/                        # Documentation
│   ├── 📋 REQUIREMENTS.md          # Comprehensive requirements
│   ├── 🏗️  ARCHITECTURE.md          # Architecture overview
│   ├── 📚 RUNBOOK_SYSTEM.md        # Runbook system documentation
│   ├── 🚀 QUICKSTART.md            # Developer quick start guide
│   ├── 🔗 N8N_INTEGRATION_GUIDE.md # Complete N8N integration guide
│   ├── 🤖 n8n-agent-prompts.md     # N8N Agent node prompts
│   ├── 📝 n8n-incident-example.md  # Real-world incident example
│   └── 🧠 n8n-learning-prompts.md  # Learning and knowledge prompts
├── 📁 runbooks/                    # Comprehensive runbook system
│   ├── 📁 static/                  # Static runbook templates
│   │   ├── 📝 agent.md             # AI knowledge base and capabilities
│   │   ├── 📁 templates/           # Incident response templates
│   │   │   ├── 📋 incident.md      # Incident response template
│   │   │   ├── 🔧 remediation.md   # Remediation process template
│   │   │   └── 📊 postmortem.md    # Postmortem analysis template
│   │   └── 📁 best-practices/      # Best practices and guidelines
│   │       └── 📈 monitoring.md    # Monitoring best practices
│   ├── 📁 dynamic/                 # Dynamic runbook content
│   │   ├── 📁 incidents/           # Real incident documentation
│   │   │   └── 🚨 2025-10-15-pod-crashloop.md
│   │   ├── 📁 patterns/            # Learned patterns and trends
│   │   │   └── 💾 memory-pressure.md
│   │   └── 📁 resolutions/         # Resolution strategies
│   │       ├── 📁 auto-generated/  # Automated resolutions
│   │       │   └── 🔧 memory-limit-increase.md
│   │       └── 📁 manual/          # Manual resolution procedures
│   └── 📁 cache/                   # Runbook system cache
│       ├── 🔍 search-index.json    # Search index for runbooks
│       ├── 📊 patterns.json        # Pattern recognition cache
│       └── 📈 metrics.json         # Usage metrics and analytics
├── 📁 src/
│   └── 🐍 mcp_server_protocol.py   # MCP Protocol compliant server
├── 📁 scripts/
│   └── 🚀 entrypoint.sh            # Container initialization
├── 📁 config/
│   └── ⚙️  config.yaml              # Runtime configuration
├── 📁 k8s-repo/                    # Kubernetes deployment manifests
│   ├── 📋 configmap.yaml           # Kubernetes ConfigMap & Secrets
│   ├── 📋 storage.yaml             # Persistent storage claims
│   └── 📋 deployment.yaml          # Complete deployment manifests
├── 📁 logs/                        # Application logs
└── 📁 work/                        # Working directory

🔧 开发

看见 docs/QUICKSTART.md（文件名，可翻译为“文档/快速入门指南.md”）以获取详细的开发说明。

本地开发

# Install dependencies
pip install aiohttp pyyaml

# Run MCP server locally
python src/mcp_server_protocol.py

# Test MCP server
python test_mcp.py

# Run tests
make test-mcp
make test-git-tools

# Lint code
make lint

测试

# Test MCP protocol
make test-mcp

# Test Git tools
make test-git-tools

# Test kubectl tools
make test-kubectl

# Test Flux tools
make test-flux

# Test with Docker Compose
docker-compose up -d

📖 文档

📋 表格或清单要求 - 全面的项目需求
🏗️ 这个符号可以翻译为“建筑工地”或“正在施工”。架构概述 - 系统架构细节
📚 书籍或学习的象征运行手册系统 - 完整的运行手册系统文档
🚀 表示火箭或快速上升的意象，常用于比喻快速发展、进步或兴奋的事物。快速入门指南 - 开发者快速入门指南
🔗 N8N 集成指南 - 完整的N8N集成指南
🤖 机器人 N8N代理提示 - 12个详细的N8N代理节点提示
📝 事件示例 - 真实世界中的事件响应示例
🧠 表示“大脑”或“思考”，可翻译为“大脑”或“思考中”。学习提示 - 持续学习和知识更新提示
📝（记事本或笔记的图标，无具体文字含义，常用于表示记录或笔记）人工智能知识库 - 人工智能代理的能力和知识库

🤝 贡献（或“参与贡献”）

我们欢迎贡献！本项目遵循精益架构原则，其中：

集装箱保持无状态且轻量级
智力外部处理（N8N，AI代理）
**GitOps（Git 操作）**为简化起见，采用仅流量的方法
API为所有操作提供干净的REST端点

贡献指南

叉子仓库
创造一个特性分支（git checkout -b feature/amazing-feature）
提交（或：提交更改） 你的更改（git commit -m 'Add amazing feature'）
推到（某）分店git push origin feature/amazing-feature)
开放一个拉取请求（Pull Request）

代码标准

遵循PEP 8规范编写Python代码
在适当的地方使用类型提示
为新功能添加测试
更新API变更的文档
保持容器尺寸最小化

🆘 支持与社区

📧 电子邮件符号，无实际翻译内容，可直接表示为“电子邮件”或保持原样使用。问题： GitHub Issues（GitHub问题）
💬 讨论: GitHub 讨论区
📚 书籍维基: 项目维基
🐛 蝉（或指小虫子） 错误报告使用 GitHub Issues 与 bug 标签

🏆 致谢

Flux（在计算机科学和软件开发领域）可译为“数据流”或“流量”（根据上下文具体含义） - Kubernetes的GitOps工具包
Kubernetes（通常简称为K8s） - 容器编排平台
N8N - 工作流自动化平台
MCP - 模型上下文协议规范

📊 项目状态

📄 许可证

这个项目采用MIT许可证授权——详见许可证详情见文件。

🚀 为Kubernetes和GitOps社区倾情打造

⭐ 给这个仓库点星（即收藏/关注这个仓库） | 🐛 报告错误 | 💡 请求功能