# ceph-pilot

**Repository Path**: cdevel/ceph-pilot

## Basic Information

- **Project Name**: ceph-pilot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ceph-pilot

Ceph 运维操作领航员 — 基于 MCP (Model Context Protocol) 的 Ceph 集群运维智能辅助服务。

在执行运维操作前，ceph-pilot 帮你预测影响、诊断故障、推荐修复方案，避免操作事故。

## 功能

| 工具 | 说明 |
|------|------|
| `predict_impact` | 预测运维操作影响 — OSD/Pool/PG/CRUSH/RBD/Mon/MGR/RADOS/CephFS |
| `diagnose_cluster` | 诊断集群健康问题 — 磁盘/网络/CPU内存/CephFS 根因分析 |
| `suggest_remediation` | 推荐修复方案 — 50+ 故障场景修复指南 |
| `plan_rolling_update` | 规划滚动更新 — 安全步长和 PG 稳定性检查 |
| `simulate_crush_change` | 模拟 CRUSH 变更 — 预测 PG 重映射和数据迁移 |
| `inject_cluster_state` | 注入集群状态 — 提供实时数据提升预测精度 |
| `check_operation_safety` | 操作安全检查 — 多维度风险评估 |
| `explain_pg_state` | 解释 PG 状态 — 异常状态原因和恢复路径 |

### 支持的操作类型

- **OSD 生命周期**: osd_out, osd_in, osd_down, osd_up, osd_mark_lost, osd_scrub, osd_deep_scrub, osd_reweight...
- **Pool 管理**: pool_create, pool_delete, pool_set_size, pool_enable_rbd, pool_set_quota...
- **PG 重映射**: pg_upmap, pg_upmap_items, pg_remap...
- **RBD**: rbd_image_create/remove/resize/clone/flatten, rbd_snap_create/remove/protect/rollback, rbd_mirror_enable/promote/demote...
- **Mon**: mon_add, mon_remove, mon_compact, mon_quorum_enter/exit...
- **MGR**: mgr_module_enable/disable, mgr_fail, mgr_daemon_restart...
- **RADOS/CephFS/Auth**: rados_object_put/remove/copy, cephfs_*...

### 根因分析

自动识别 5 类根因：
- **磁盘** (15 种信号): commit/apply 延迟、SMART 预警、BlueFS 慢、scrub 错误...
- **网络** (13 种信号): 心跳延迟、时钟偏移、网络分区、连接重置...
- **CPU/内存** (4 种信号): OOM Kill、CPU 高负载、内存压力、请求节流...
- **CephFS** (3 种信号): MDS 元数据慢、缓存压力、客户端超时...
- **混合**: 多根因综合分析

### HDD/SSD 自适应阈值

根据 `ceph osd metadata` 中的 `device_class` 自动选择阈值：
- SSD: commit 50ms, apply 30ms
- HDD: commit 500ms, apply 1000ms

可通过 `thresholds` 参数自定义。

## 快速开始

### 前置条件

- Podman 或 Docker
- Python 3.11+（本地开发）

### 一键构建 + 部署

```bash
# 构建
./build.sh

# 部署（默认端口 80）
./deploy.sh

# 自定义镜像名/标签/端口
./build.sh my-registry/ceph-pilot v1.0
./deploy.sh my-registry/ceph-pilot v1.0 9090
```

### 手动操作

```bash
# 构建
podman build -t ceph-pilot .

# 部署
podman run -d --name ceph-pilot -p 80:8000 ceph-pilot

# 查看日志
podman logs -f ceph-pilot
```

### 本地开发

```bash
pip install -r requirements.txt
python run_server.py
```

## 配置

编辑 `config.yaml`：

```yaml
server:
  host: "0.0.0.0"
  port: 8000

ceph:
  # 集群连接配置（可选，用于自动获取集群状态）
  conf_path: "/etc/ceph/ceph.conf"
  keyring_path: "/etc/ceph/ceph.client.admin.keyring"
```

## 使用示例

### 通过 MCP 客户端

```python
from mcp import ClientSession
from mcp.client.sse import sse_client

async def main():
    async with sse_client("http://localhost:80/sse") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # 预测 OSD out 的影响
            result = await session.call_tool("predict_impact", {
                "action": "osd_out",
                "targets": ["3"]
            })

            # 诊断集群问题
            result = await session.call_tool("diagnose_cluster", {
                "health_detail_json": '<ceph health detail JSON>'
            })
```

### 配合 Claude Code

在 `.mcp.json` 中添加：

```json
{
  "mcpServers": {
    "ceph-pilot": {
      "url": "http://localhost:80/sse"
    }
  }
}
```

## 测试

```bash
# 运行全部测试
pytest tests/ -v

# 运行特定模块测试
pytest tests/test_rbd_predictor_core.py -v
pytest tests/test_root_cause_analyzer.py -v
```

## 项目结构

```
ceph-pilot/
├── build.sh                    # 一键构建脚本
├── deploy.sh                   # 一键部署脚本
├── Containerfile               # 容器构建文件
├── requirements.txt            # Python 依赖
├── config.yaml                 # 服务配置
├── run_server.py               # 入口
├── src/
│   ├── mcp_server.py           # MCP 服务主文件 (8 tools)
│   ├── root_cause_analyzer.py  # 根因分析 (35 信号)
│   ├── crush_simulator.py      # CRUSH 变更模拟
│   ├── rbd_predictor.py        # RBD 影响预测
│   ├── mon_predictor.py        # Mon 影响预测
│   ├── mgr_predictor.py        # MGR 影响预测
│   └── rados_predictor.py      # RADOS/CephFS/Auth 预测
├── knowledge/
│   └── operation_types.yaml    # 操作类型元数据
└── tests/
    ├── test_rbd_predictor_core.py
    ├── test_mon_predictor.py
    ├── test_mgr_predictor.py
    ├── test_rados_predictor.py
    ├── test_root_cause_analyzer.py
    ├── test_mcp_server.py
    └── test_crush_simulator.py
```

## License

MIT