# es-archive

**Repository Path**: slcnx/es-archive

## Basic Information

- **Project Name**: es-archive
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-31
- **Last Updated**: 2025-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ES Archive

🚀 **企业级 Elasticsearch 数据备份和恢复工具**

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/your-repo/es-archive)

ES Archive 是一个专为生产环境设计的 Elasticsearch 数据备份和恢复解决方案，提供高性能、高可靠性的数据保护能力。

## ✨ 核心特性

### 🎯 **多种备份策略**
- **完整备份**：备份索引的所有数据
- **时间范围备份**：备份指定时间段的数据
- **增量备份**：只备份新增或修改的数据
- **选择性备份**：基于查询条件的精确备份

### ⚡ **高性能处理**
- **并行处理**：多线程并发备份/恢复，最大化吞吐量
- **智能分片**：自动数据分片优化传输效率
- **压缩存储**：支持 gzip、lz4 等压缩算法，节省存储空间
- **批量操作**：高效的批量数据处理机制

### 🔒 **数据安全**
- **完整性验证**：SHA256 校验和确保数据完整性
- **原子操作**：确保备份过程的一致性
- **错误恢复**：自动重试和智能错误处理
- **审计日志**：详细的操作记录和追踪

### 🛠️ **易于使用**
- **简单配置**：直观的 YAML 配置文件
- **命令行工具**：功能完整的 CLI 界面
- **进度显示**：实时备份/恢复进度和 ETA
- **详细日志**：丰富的日志信息和错误诊断

### 🌐 **生产就绪**
- **时区支持**：智能时区处理和转换
- **监控集成**：内置监控指标和告警
- **Docker 支持**：容器化部署和编排
- **自动化友好**：完善的脚本和 API 支持

## 🚀 快速开始

### 安装

```bash
# 使用 pip 安装
pip install es-archive

# 使用 uv 安装（推荐）
uv pip install es-archive

# 验证安装
es-archive --version
```

```bash
make build-ustc
```

### 5分钟上手

#### 1. 创建配置文件

```bash
cat > es_config.yaml << EOF
elasticsearch:
  hosts: ["http://localhost:9200"]
  timeout: 30

backup:
  chunk_size: "100MB"
  parallel_workers: 4
  validate_data: true

restore:
  batch_size: 1000
  parallel_workers: 2

storage:
  backend: "local"
  local:
    base_path: "./backups"
EOF
```

## 快速开始

### 基本备份

```bash
# 全量备份
es-archive backup my_index /path/to/backup

# 增量备份（最近24小时）
es-archive backup my_index /path/to/backup --strategy incremental --start-time "2023-01-01T00:00:00Z"

# 时间范围备份
es-archive backup my_index /path/to/backup --strategy time_range --start-time "2023-01-01" --end-time "2023-01-02"
```

### 数据恢复

```bash
# 恢复到新索引
es-archive restore backup_id new_index

# 覆盖现有索引
es-archive restore backup_id existing_index --overwrite

# 选择性恢复
es-archive restore backup_id target_index --strategy selective
```

### 管理和监控

```bash
# 列出所有备份
es-archive list-backups

# 验证备份完整性
es-archive validate backup_id

# 分析索引结构
es-archive analyze my_index
```

## 配置

### 配置文件示例

```yaml
# config.yaml
elasticsearch:
  hosts: ["localhost:9200"]
  username: "elastic"
  password: "password"
  timeout: 60

backup:
  default_strategy: "full"
  batch_size: 1000
  compression: "gzip"
  parallel_workers: 4
  validate_data: true

storage:
  root_path: "/var/lib/es-archive"
  max_storage_size: "100GB"
  retention_days: 30

monitoring:
  enable_metrics: true
  collection_interval: 5.0
  
alerts:
  email:
    smtp_server: "smtp.example.com"
    username: "alerts@example.com"
    password: "password"
    to_addrs: ["admin@example.com"]
```

## 架构设计

### 核心模块

```
src/es_archive/
├── core/                 # 核心功能模块
│   ├── backup.py        # 备份管理
│   ├── restore.py       # 恢复管理
│   ├── storage.py       # 存储管理
│   ├── metadata.py      # 元数据管理
│   └── validator.py     # 数据验证
├── utils/               # 工具模块
│   ├── es_client.py     # ES客户端
│   ├── time_utils.py    # 时间处理
│   ├── file_utils.py    # 文件处理
│   └── query_builder.py # 查询构建
├── monitoring/          # 监控模块
│   ├── progress.py      # 进度监控
│   ├── metrics.py       # 指标收集
│   └── alerts.py        # 告警通知
├── cli/                 # 命令行界面
│   ├── main.py          # 主入口
│   └── commands/        # 命令实现
└── config/              # 配置管理
    └── settings.py      # 配置处理
```

### 数据流

1. **备份流程**: 索引分析 → 策略制定 → 数据提取 → 分片存储 → 完整性验证
2. **恢复流程**: 备份验证 → 索引准备 → 数据导入 → 完整性检查 → 状态报告
3. **监控流程**: 指标收集 → 状态分析 → 告警检查 → 通知发送

## 开发

### 运行测试

```bash
# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_backup.py

# 生成覆盖率报告
pytest --cov=src/es_archive --cov-report=html
```

### 代码质量

```bash
# 代码格式化
black src/ tests/

# 代码检查
flake8 src/ tests/

# 类型检查
mypy src/
```

## 许可证

本项目采用 MIT 许可证。