内容
# 开源搜索运维
> Claude 代码插件：OpenSearch MCP 服务器 + 故障调查/日志分析技能
**"支付失败似乎在2月25日5点到7点之间发生。请检查OpenSearch并找出后端代码的原因。"** — 通过这种自然语言请求分析故障原因。
## 功能
| 技能 | 描述 |
|------|------|
| `/opensearch-ops:investigate` | 故障调查（日志 + 代码分析） |
| `/opensearch-ops:search-logs` | 条件日志搜索 |
| `/opensearch-ops:analyze-patterns` | 两个时间段日志模式比较分析 |
| `/opensearch-ops:cluster-health` | 集群状态检查 |
### MCP 工具（自动连接）
[opensearch-mcp-server-py](https://github.com/opensearch-project/opensearch-mcp-server-py) 自动连接后，以下工具可用：
- **SearchIndexTool** — 基于 Query DSL 的搜索
- **LogPatternAnalysisTool** — 基线 vs 选择异常模式检测
- **DataDistributionTool** — 时间段数据分布分析
- **ListIndexTool** — 索引列表查询
- **ClusterHealthTool** — 集群状态检查
- **GenericOpenSearchApiTool** — 所有 OpenSearch API 调用
## 安装
### 一键安装
```bash
git clone https://github.com/nathankim0/opensearch-ops.git
cd opensearch-ops
chmod +x setup.sh && ./setup.sh
```
### 从市场安装
```bash
# 市场注册
claude plugin marketplace add nathankim0/opensearch-ops
# 插件安装
claude plugin install opensearch-ops
```
### 本地开发模式
```bash
claude --plugin-dir /path/to/opensearch-ops
```
## 身份验证设置
MCP 服务器是**服务器到服务器通信**，因此不支持基于浏览器的身份验证（Google OAuth，SAML 等）。请选择以下三种方式之一。
### 方法 1：Basic Auth — 内部用户（推荐）
最简单的方法。在 OpenSearch 控制面板中创建一个 API 专用的内部用户。
**创建方法：** 控制面板 → 安全 → 内部用户 → 创建内部用户
> 如果您没有管理员权限，请向基础设施管理员请求：
> “请为 OpenSearch 创建一个 API 查询的内部用户。 `readall` 角色就足够了。”
```bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export OPENSEARCH_URL="https://your-opensearch-cluster:9200"
export OPENSEARCH_USERNAME="mcp-reader"
export OPENSEARCH_PASSWORD="颁发的密码"
export OPENSEARCH_SSL_VERIFY="true"
```
### 方法 2：AWS IAM 身份验证（SigV4）
IAM 用户/角色必须具有 OpenSearch 访问权限（`es:ESHttp*`）。
```bash
export OPENSEARCH_URL="https://your-domain.ap-northeast-2.es.amazonaws.com"
export AWS_REGION="ap-northeast-2"
# 需要设置 AWS_ACCESS_KEY_ID，AWS_SECRET_ACCESS_KEY 或 AWS_PROFILE
```
> **注意：** S3 专用 IAM 用户等没有 OpenSearch 权限的用户将产生 403 错误。
### 方法 3：自行管理 OpenSearch
如果您运行自己的集群：
```bash
export OPENSEARCH_URL="https://localhost:9200"
export OPENSEARCH_USERNAME="admin"
export OPENSEARCH_PASSWORD="admin"
export OPENSEARCH_SSL_VERIFY="false" # 自签名证书
```
### 不支持的身份验证方式
| 方式 | 支持情况 | 替代方案 |
|------|-----------|------|
| Basic Auth（内部用户） | **支持** | — |
| AWS IAM（SigV4） | **支持** | — |
| Google OAuth / SAML / OIDC | **不支持** | 创建内部用户 |
| 浏览器令牌拦截 | **不支持** | 创建内部用户 |
## 使用示例
### 故障调查
```
/opensearch-ops:investigate 支付失败集中发生在2月25日5点到7点之间。请检查OpenSearch日志并找出后端代码原因。
```
### 日志搜索
```
/opensearch-ops:search-logs 今天上午10点到11点之间 ERROR 级别的日志中搜索包含 "timeout" 关键词的日志。
```
### 模式比较
```
/opensearch-ops:analyze-patterns 比较部署前（2月24日14点到16点）和部署后（2月24日16点到18点）的错误模式。
```
### 集群状态
```
/opensearch-ops:cluster-health
```
## 结构
```
opensearch-ops/
├── .claude-plugin/
│ ├── plugin.json # 插件清单
│ └── marketplace.json # 市场元数据
├── .mcp.json # OpenSearch MCP 服务器设置
├── skills/
│ ├── investigate/ # 故障调查（主要技能）
│ │ └── SKILL.md
│ ├── search-logs/ # 日志搜索
│ │ └── SKILL.md
│ ├── analyze-patterns/ # 模式比较分析
│ │ └── SKILL.md
│ └── cluster-health/ # 集群状态
│ └── SKILL.md
├── setup.sh # 一键安装脚本
├── LICENSE
└── README.md
```
## 要求
- [Claude Code](https://claude.ai/code) (CLI)
- Python 3.10+ (uv 或 pip)
- 可访问的 OpenSearch 集群
## 许可证
MIT
