# es-upgrade

**Repository Path**: zeus-maker/es-upgrade

## Basic Information

- **Project Name**: es-upgrade
- **Description**: ES升级脚本
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-07-07
- **Last Updated**: 2025-08-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ES索引迁移工具

## 项目概述
这是一个智能的Elasticsearch索引结构迁移工具，支持多种ES版本间的索引结构迁移。工具会自动检测源ES和目标ES的版本，并选择相应的迁移策略。

## 最新更新
- **2025-07-08**
  - 🔄 优化reindex操作的参数设置
  - 🛠️ 移除了reindex操作中的超时限制
  - 🔒 修复了认证信息处理，将认证信息从reindex请求体中移除
  - ⚡️ 简化了reindex参数，移除了不必要的参数（如slices）
  - �� 提高了reindex操作的稳定性

## 版本兼容性

### 支持的迁移场景
- **ES6 -> ES6**: 保持原有索引结构不变
- **ES7 -> ES7**: 保持原有索引结构不变  
- **ES6 -> ES7**: 自动转换索引结构（移除类型，调整映射格式）
- **ES7 -> ES8**: 兼容性调整
- **其他跨版本**: 自定义处理

### 自动版本检测
工具启动时会自动：
1. 检测源ES和目标ES的版本
2. 分析版本兼容性
3. 选择合适的迁移策略
4. 输出详细的版本分析报告

## 功能特性

### 核心功能
1. **智能版本检测**: 自动检测ES版本并选择迁移策略
2. **索引结构导出**: 从源ES环境导出所有索引的映射(mapping)和设置(settings)
3. **索引结构导入**: 在目标ES环境中根据导出的结构创建新索引
4. **智能兼容性处理**: 根据版本自动处理差异
5. **SSL和X-PACK支持**: 支持ES环境的SSL认证和X-PACK安全功能

### 主要脚本

#### `es_index_migrator.py`
主要的迁移脚本，包含以下功能：

**类和方法说明:**
- `ESIndexMigrator`: 主要的迁移类
  - `export_index_structures()`: 导出源ES中的所有索引结构
  - `import_index_structures()`: 在目标ES中创建索引
  - `convert_mapping()`: 根据版本智能处理映射兼容性
  - `convert_settings()`: 根据版本智能处理设置兼容性
  - `_analyze_version_compatibility()`: 分析版本兼容性并选择迁移策略

**配置参数:**
- 源ES配置 (ES 6.8)
- 目标ES配置 (ES 7.17.27, 带SSL和X-PACK)
- 导出文件路径
- 日志级别

**使用方法:**
```python
# 基本使用
migrator = ESIndexMigrator(source_config, target_config)
migrator.export_index_structures('exported_indices.json')
migrator.import_index_structures('exported_indices.json')
```

## 系统架构

本工具采用分层架构设计，支持多种使用方式：

### 界面层
- **Web界面**: 现代化的图形界面，支持实时日志和进度显示
- **命令行界面**: 交互式配置和执行

### API层
- **Flask后端**: 提供RESTful API接口
- **WebSocket**: 实时通信，支持日志推送和状态更新

### 核心层
- **迁移引擎**: 负责索引结构的导出、转换和导入
- **版本转换器**: 处理ES6.8到ES7.17.27的兼容性问题
- **日志处理**: 多种输出方式的日志管理

## 迁移策略详解

### ES6 -> ES6 迁移
- **策略**: 保持原有索引结构不变
- **处理**: 仅移除只读设置（如creation_date、uuid等）
- **适用场景**: 同版本ES集群间的索引复制

### ES6 -> ES7 迁移
- **策略**: 自动转换索引结构
- **主要变化**:
  1. **类型(Type)移除**: ES7.x移除了索引类型概念
  2. **映射参数变化**: 某些映射参数在ES7中被弃用或修改
  3. **设置参数变化**: 部分索引设置在新版本中有所调整
- **自动处理**:
  - 移除已弃用的映射参数
  - 转换类型定义为无类型结构
  - 调整不兼容的设置参数

### ES7 -> ES7 迁移
- **策略**: 保持原有索引结构不变
- **处理**: 仅移除只读设置
- **适用场景**: 同版本ES集群间的索引复制

### 跨版本迁移支持
- **ES7 -> ES8**: 基础兼容性处理
- **其他版本**: 提示用户可能需要自定义处理

## 安装和配置

### 1. 安装依赖库
```bash
pip install -r requirements.txt
```

### 2. 配置文件设置
编辑 `config.py` 文件，配置你的ES环境连接信息：

#### 源ES 6.8配置
```python
SOURCE_ES_CONFIG = {
    'host': 'your-es6-host',
    'port': 9200,
    'scheme': 'http',
    'username': None,  # 如果没有认证
    'password': None,
    'verify_certs': False
}
```

#### 目标ES 7.17.27配置（带X-PACK）
```python
TARGET_ES_CONFIG = {
    'host': 'your-es7-host',
    'port': 9200,
    'scheme': 'http',
    'username': 'elastic',
    'password': 'your_password',
    'verify_certs': False
}
```

### 3. 使用方法

#### Web界面（推荐使用）
```bash
# 启动Web界面
python web_interface.py

# 然后在浏览器访问: http://localhost:5000
```

Web界面提供：
- 📝 图形化配置ES连接信息
- 🔍 一键测试连接
- 👁️ 智能预览迁移（ES版本信息、索引统计、重复检查）
- 📦 **选择性迁移**：可选择特定索引进行迁移
- 🔄 **异步Reindex**：支持异步数据迁移操作
- 📋 **任务管理**：实时查看和管理所有迁移任务
- 📊 **进度跟踪**：详细的任务进度和状态显示
- 📝 彩色实时日志查看

#### 快速开始（命令行交互）
```bash
# 使用交互式快速启动脚本
python quick_start.py
```

#### 直接运行
```bash
# 直接运行主脚本（需要先配置config.py）
python es_index_migrator.py

# 查看使用示例
python example_usage.py
```

#### 分步执行
```python
from es_index_migrator import ESIndexMigrator

# 创建迁移器
migrator = ESIndexMigrator()

# 步骤1: 导出索引结构
migrator.export_index_structures('exported_indices.json')

# 步骤2: 在目标ES中创建索引
migrator.import_index_structures('exported_indices.json')
```

#### 预览模式（推荐先使用）
在 `config.py` 中设置 `MIGRATION_CONFIG['dry_run'] = True`，这样可以预览而不实际创建索引。

## SSL和X-PACK配置说明

### 获取CA证书
如果你的ES7.17.27使用了自签名证书，需要获取CA证书：
```bash
# 从ES容器中复制证书
docker cp es01:/usr/share/elasticsearch/config/certs/ca/ca.crt ./ca.crt

# 或从ES安装目录获取
cp /etc/elasticsearch/certs/ca/ca.crt ./ca.crt
```

### X-PACK用户配置
确保你有合适的用户权限：
```bash
# 创建专用迁移用户（在ES7环境中执行）
curl -X POST "localhost:9200/_security/user/migration_user" -H "Content-Type: application/json" -d'
{
  "password" : "migration_password",
  "roles" : [ "superuser" ],
  "full_name" : "Migration User"
}'
```

## 注意事项

### 重要提醒
1. **本工具只迁移索引结构，不迁移数据**
2. **运行前请先在测试环境验证**
3. **建议先使用预览模式（dry_run=True）**
4. **确保目标ES环境可正常访问**

### 🔧 分析器兼容性处理

工具具备智能分析器兼容性处理功能，自动解决常见的分析器不兼容问题：

**🔍 自动检测功能**
- 自动检测目标ES环境中安装的插件
- 识别IK中文分词器等常用插件的安装状态
- 预警分析器兼容性问题

**🔄 智能替换策略**
- **IK分词器映射**：
  - `ik_smart` → `standard`（智能分词 → 标准分词）
  - `ik_max_word` → `standard`（细粒度分词 → 标准分词）
- **其他分析器映射**：
  - 自定义分析器自动替换为相近的内置分析器
  - 未知分析器默认替换为`standard`分析器

**📝 详细日志提示**
- 实时显示分析器替换操作
- 提供插件安装建议和下载链接
- 警告潜在的功能影响

**💡 最佳实践建议**

对于IK分词器问题，推荐以下解决方案：

```bash
# 方案1：在目标ES中安装IK插件（推荐）
# ES7.17版本
./elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v7.17.0/elasticsearch-analysis-ik-7.17.0.zip

# ES6.8版本  
./elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v6.8.0/elasticsearch-analysis-ik-6.8.0.zip

# 安装后重启ES服务
sudo systemctl restart elasticsearch
```

```bash
# 方案2：接受自动替换（功能略有差异但保证兼容）
# 工具会自动将ik_smart/ik_max_word替换为standard分析器
# 优点：无需安装插件，立即可用
# 缺点：中文分词效果不如IK插件
```

### 版本兼容性
- **支持多版本**: ES6、ES7、ES8等多版本间迁移
- **自动版本检测**: 自动识别源ES和目标ES版本
- **智能策略选择**: 根据版本组合自动选择迁移策略
- **ES6->ES6**: 保持原有索引结构不变
- **ES6->ES7**: 自动处理类型(type)移除和映射转换
- **ES7->ES7**: 保持原有索引结构不变

### 智能预览功能

预览迁移提供详细的迁移前分析：

**📊 版本兼容性分析**
- 自动检测源ES和目标ES版本
- 显示迁移策略（es6_to_es6、es6_to_es7等）
- 说明是否需要结构转换

**📋 索引统计信息**
- 总索引数量统计
- 新建索引 vs 重复索引分析
- 每个索引的字段数量统计

**⚠️ 重复索引检测**
- 检查目标ES中已存在的索引
- 列出重复索引名称（前10个）
- 提供处理建议

**📝 实时彩色日志**
- INFO：蓝色 - 正常处理信息
- WARNING：黄色 - 警告信息（如重复索引）
- ERROR：红色 - 错误信息

### 智能文件管理

基于IP地址的文件命名机制，避免文件覆盖：

**📁 文件名生成规则**
- 预览文件：`preview_源IP_端口_to_目标IP_端口.json`
- 迁移文件：`migration_源IP_端口_to_目标IP_端口_时间戳.json`

**🔄 文件命名示例**
```
# 预览文件（固定名称，便于临时查看）
preview_10_120_133_127_9200_to_10_196_175_50_9200.json

# 迁移文件（带时间戳，保留历史记录）
migration_10_120_133_127_9200_to_10_196_175_50_9200_20250707_163544.json
```

**✨ 文件管理优势**
- 不同IP对生成不同文件，避免相互覆盖
- 预览文件名固定，多次预览复用同一文件
- 迁移文件包含时间戳，保留完整操作历史

### 高级功能

#### 🎯 选择性索引迁移

支持灵活的索引选择策略：

**📋 索引选择界面**
- 预览迁移后显示所有可用索引
- 多选checkbox界面，支持全选/全不选
- 实时显示每个索引的详细信息：
  - 字段数量统计
  - 设置参数数量
  - 是否在目标ES中已存在

**🚀 迁移方式**
- **选择性迁移**：只迁移用户选中的特定索引
- **全量迁移**：迁移所有索引（保持原有功能）
- **智能跳过**：自动跳过目标ES中已存在的索引

#### 🔄 异步Reindex功能

强大的数据迁移能力：

**📊 异步操作特性**
- 支持远程reindex，从源ES直接复制数据到目标ES
- 异步任务执行，不阻塞其他操作
- 实时进度跟踪和状态监控
- 支持大数据量索引的长时间传输

**🛡️ 安全性保障**
- 自动处理认证信息
- 支持SSL/TLS加密传输
- 错误重试机制

#### 📋 任务管理系统

全面的任务监控和管理：

**🎛️ 任务管理功能**
- **任务列表**：显示所有迁移和reindex任务
- **实时状态**：pending（等待）、running（运行）、completed（完成）、failed（失败）
- **进度监控**：百分比进度条和当前处理步骤
- **任务详情**：创建时间、持续时间、处理结果
- **任务取消**：支持取消正在运行的任务

**📊 详细进度跟踪**
- **ES原生任务监控**：通过ES的`_tasks`接口获取真实进度
- **每个索引的详细信息**：
  - 已处理文档数/总文档数
  - 实时处理速度（文档/秒）
  - 预计剩余时间
  - 微型进度条显示
- **文档级别统计**：创建、更新、删除的文档数量
- **版本冲突跟踪**：显示版本冲突数量，但不影响任务继续执行
- **智能预估**：基于当前速度计算完成时间

**📈 实时监控特性**
- **异步Reindex**：使用`wait_for_completion=false`启动后台任务
- **冲突处理**：配置`conflicts=proceed`，遇到版本冲突时继续执行
- **5秒级进度更新**：实时显示任务进度变化
- **ES任务ID跟踪**：监控每个ES原生任务状态
- **错误恢复**：自动处理任务异常和超时

**🔄 智能更新机制**
- WebSocket实时推送任务状态变化
- 运行中任务每5秒刷新一次
- 全部任务每10秒刷新一次
- 任务完成时立即通知

**🛑 任务控制**
- **取消功能**：支持取消正在运行的任务
- **ES任务取消**：自动取消对应的ES原生任务
- **优雅停止**：确保资源正确释放

**📋 任务详情查看**
- **完整记录**：查看任务完成后的详细处理结果
- **处理日志**：完整的任务执行过程日志记录
- **索引结果**：每个索引的详细处理状态和结果
- **错误追踪**：详细的错误信息和失败原因
- **统计汇总**：成功/失败数量、处理时间等统计信息

#### 💡 使用流程

**第一步：预览索引**
1. 配置源ES和目标ES连接信息
2. 点击"👁️ 预览迁移"
3. 查看索引列表和兼容性分析

**第二步：选择操作类型**
- **选择性迁移**：只创建索引结构，不复制数据
  1. 在索引列表中选择需要的索引
  2. 点击"🚀 开始选择性迁移"
  3. 任务在后台异步执行

- **异步Reindex**：复制索引数据
  1. 在索引列表中选择需要reindex的索引
  2. 点击"🔄 开始Reindex"
  3. 数据开始异步传输

**第三步：监控任务**
1. 切换到"📋 任务管理"标签页
2. 实时查看任务进度和状态
3. 查看详细的执行结果
- 支持域名、IP、localhost等各种主机格式

### 性能建议
- 大量索引时建议分批处理
- 调整 `batch_size` 配置
- 监控目标ES集群资源使用情况

## 重要：ES7查询语法变化

迁移完成后，**查询语法需要调整**。在ES7中，对文本字段进行聚合、排序等操作时，必须使用`.keyword`子字段：

### 常见查询错误修复

| 操作类型 | ❌ ES6语法（会报错） | ✅ ES7语法（正确） |
|---------|-------------------|------------------|
| 聚合查询 | `"field": "app_id"` | `"field": "app_id.keyword"` |
| 排序 | `"sort": [{"app_id": "asc"}]` | `"sort": [{"app_id.keyword": "asc"}]` |
| 精确匹配 | `{"term": {"app_id": "value"}}` | `{"term": {"app_id.keyword": "value"}}` |
| 范围查询 | `{"range": {"app_id": {"gte": "a"}}}` | `{"range": {"app_id.keyword": {"gte": "a"}}}` |

### 查询规则

1. **全文搜索（模糊匹配）**：直接使用字段名，如 `app_id`
2. **精确匹配、聚合、排序**：使用keyword子字段，如 `app_id.keyword`

### 典型错误信息

如果看到以下错误：
```
Text fields are not optimised for operations that require per-document field data like aggregations and sorting
```

**解决方案**：查询中使用了text字段进行聚合或排序，需要改为使用对应的`.keyword`子字段。

例如：将查询中的 `app_id` 改为 `app_id.keyword`

### 故障排除
- 检查网络连接
- 验证认证信息
- 查看详细日志文件 `es_migration.log`
- 确认SSL证书配置正确
- **查询报错时检查是否使用了正确的字段名（text字段需要加.keyword后缀）**

## 文件说明
- `web_interface.py`: Web界面后端API（推荐使用）
- `templates/index.html`: Web界面前端页面  
- `es_index_migrator.py`: 核心迁移脚本
- `config.py`: 配置文件
- `quick_start.py`: 交互式快速启动脚本
- `example_usage.py`: 详细使用示例
- `requirements.txt`: 依赖库列表
- `README.md`: 本说明文档
- `WEB_USAGE_GUIDE.md`: Web界面详细使用指南

## 错误处理和监控
- ✅ 完整的日志记录
- ✅ 详细的错误信息输出  
- ✅ 迁移进度跟踪
- ✅ 失败索引统计和报告
- ✅ 连接状态检测

## 项目状态

✅ **项目已完成并测试通过**

**完成功能:**
- 核心迁移引擎开发完成
- Web界面和命令行界面
- ES6.8到ES7.17.27版本兼容性转换（已修复映射格式问题）
- 完整的错误处理和日志记录
- 多种使用方式支持

**实际测试验证:**
- ✅ 源ES: 10.120.133.127:9200 (ES 6.8.23)
- ✅ 目标ES: 10.196.175.50:9200 (ES 7.17.27)
- ✅ 成功导出68个索引结构
- ✅ 映射转换逻辑验证通过，解决了字段直接在根级别定义的兼容性问题
- ✅ 所有功能模块运行正常

**关键问题解决:**
- 修复了ES6映射中字段直接在根级别定义导致的ES7创建索引失败问题
- 实现了三种映射格式的自动识别和转换：
  1. 带类型定义的映射 → 提取properties到根级别
  2. 已有properties结构 → 保持ES7格式不变
  3. 字段直接在根级别 → 自动包装到properties中