498 lines
14 KiB
Markdown
498 lines
14 KiB
Markdown
# BigDataTool - 大数据查询比对工具
|
||
|
||
[](https://python.org)
|
||
[](https://flask.palletsprojects.com/)
|
||
[](LICENSE)
|
||
|
||
BigDataTool是一个功能强大的数据库查询比对工具，专门用于Cassandra数据库和Redis集群的数据一致性验证。支持单表查询、TWCS分表查询、多主键查询等多种复杂场景。
|
||
|
||
## 🚀 核心功能
|
||
|
||
### Cassandra数据比对
|
||
- **单表查询**：标准的生产环境与测试环境数据比对
|
||
- **分表查询**：基于TWCS策略的时间分表查询支持
|
||
- **多主键查询**：支持复合主键的精确匹配和比对
|
||
- **智能数据比较**：JSON、数组等复杂数据类型的深度比较
|
||
|
||
### Redis数据比对
|
||
- **全类型支持**：String、Hash、List、Set、ZSet、Stream等所有Redis数据类型
|
||
- **集群支持**：单节点和集群模式的自动检测和连接
|
||
- **随机采样**：支持随机Key采样和指定Key比对两种模式
|
||
- **性能监控**：详细的连接时间和查询性能统计
|
||
|
||
### 配置管理
|
||
- **配置组管理**：数据库连接配置的保存、加载和复用
|
||
- **查询历史**：查询记录的持久化存储和一键回放
|
||
- **实时日志**：详细的操作日志和性能监控
|
||
- **YAML导入**：支持YAML格式配置的一键导入
|
||
|
||
## 📋 系统要求
|
||
|
||
- Python 3.8+
|
||
- Flask 2.3.3
|
||
- Cassandra Driver 3.29.1
|
||
- Redis 5.0.1
|
||
|
||
## 🛠️ 安装部署
|
||
|
||
### 快速开始
|
||
|
||
#### 方式1：直接运行（推荐开发环境）
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://github.com/your-org/BigDataTool.git
|
||
cd BigDataTool
|
||
|
||
# 2. 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 3. 启动应用
|
||
python app.py
|
||
```
|
||
|
||
#### 方式2：Docker容器化部署（推荐生产环境）
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://github.com/your-org/BigDataTool.git
|
||
cd BigDataTool
|
||
|
||
# 2. 构建并启动（简化版本）
|
||
make build
|
||
make run
|
||
|
||
# 或者使用Docker Compose直接启动
|
||
docker-compose -f docker-compose.simple.yml up -d
|
||
```
|
||
|
||
#### 方式3：完整Docker环境（包含缓存和监控）
|
||
```bash
|
||
# 启动完整服务栈
|
||
docker-compose up -d
|
||
|
||
# 查看服务状态
|
||
make ps
|
||
```
|
||
|
||
### 容器化部署详情
|
||
|
||
#### 🐳 Docker镜像特性
|
||
- **基础镜像**: Python 3.9 Alpine（轻量级）
|
||
- **镜像大小**: < 200MB
|
||
- **安全性**: 非root用户运行
|
||
- **健康检查**: 内置应用健康监控
|
||
- **多架构**: 支持AMD64和ARM64
|
||
|
||
#### 🚀 一键部署命令
|
||
```bash
|
||
# 查看所有可用命令
|
||
make help
|
||
|
||
# 构建镜像
|
||
make build
|
||
|
||
# 启动服务（简化版本）
|
||
make run
|
||
|
||
# 启动完整服务（包含Redis缓存）
|
||
make run-full
|
||
|
||
# 启动生产环境（包含Nginx反向代理）
|
||
make run-prod
|
||
|
||
# 查看服务日志
|
||
make logs
|
||
|
||
# 进入容器调试
|
||
make shell
|
||
|
||
# 健康检查
|
||
make health
|
||
|
||
# 停止服务
|
||
make stop
|
||
|
||
# 清理资源
|
||
make clean
|
||
```
|
||
|
||
#### 🔧 环境变量配置
|
||
```bash
|
||
# 设置应用密钥（生产环境必须设置）
|
||
export SECRET_KEY="your-super-secret-key-change-in-production"
|
||
|
||
# 设置运行环境
|
||
export FLASK_ENV=production
|
||
export FLASK_DEBUG=False
|
||
|
||
# 数据库配置
|
||
export DATABASE_URL="sqlite:///config_groups.db"
|
||
|
||
# 安全配置
|
||
export FORCE_HTTPS=true
|
||
```
|
||
|
||
#### 📊 服务端点
|
||
启动后可访问以下地址：
|
||
|
||
**简化部署**:
|
||
- 主应用: http://localhost:5000
|
||
|
||
**完整部署**:
|
||
- 主应用: http://localhost:5000
|
||
- Redis缓存: localhost:6379
|
||
- Prometheus监控: http://localhost:9090
|
||
|
||
**生产环境**:
|
||
- HTTP: http://localhost
|
||
- HTTPS: https://localhost
|
||
|
||
### 传统部署方式
|
||
|
||
#### Python虚拟环境部署
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# 或 venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 启动应用
|
||
python app.py
|
||
```
|
||
|
||
#### 生产环境部署（Gunicorn）
|
||
```bash
|
||
# 安装Gunicorn
|
||
pip install gunicorn
|
||
|
||
# 启动生产服务
|
||
gunicorn -w 4 -b 0.0.0.0:5000 app:app
|
||
```
|
||
|
||
## 🎯 快速开始
|
||
|
||
### Cassandra数据比对
|
||
|
||
1. 访问 `http://localhost:5000/db-compare`
|
||
2. 配置生产环境和测试环境的Cassandra连接信息
|
||
3. 设置主键字段和查询参数
|
||
4. 输入要比对的Key值列表
|
||
5. 点击"开始查询"执行比对
|
||
|
||
#### 单主键查询示例
|
||
```
|
||
主键字段: id
|
||
查询Key值:
|
||
1001
|
||
1002
|
||
1003
|
||
```
|
||
|
||
#### 复合主键查询示例
|
||
```
|
||
主键字段: docid,id
|
||
查询Key值:
|
||
8825C293B3609175B2224236E984FEDB,8825C293B3609175B2224236E984FED
|
||
9925C293B3609175B2224236E984FEDB,9925C293B3609175B2224236E984FED
|
||
```
|
||
|
||
### Redis数据比对
|
||
|
||
1. 访问 `http://localhost:5000/redis-compare`
|
||
2. 配置两个Redis集群的连接信息
|
||
3. 选择查询模式（随机采样或指定Key）
|
||
4. 设置查询参数
|
||
5. 执行比对分析
|
||
|
||
## 🏗️ 系统架构
|
||
|
||
BigDataTool采用模块化分层架构设计：
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 前端界面层 │
|
||
│ (HTML + JavaScript + Bootstrap) │
|
||
└─────────────┬───────────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────────┐
|
||
│ API路由层 │
|
||
│ (Flask Routes) │
|
||
└─────────────┬───────────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────────┐
|
||
│ 业务逻辑层 │
|
||
│ ┌─────────────┬─────────────────┐ │
|
||
│ │ 查询引擎 │ 比对引擎 │ │
|
||
│ │Query Engine │ Comparison │ │
|
||
│ └─────────────┴─────────────────┘ │
|
||
└─────────────┬───────────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────────┐
|
||
│ 数据访问层 │
|
||
│ ┌─────────────┬─────────────────┐ │
|
||
│ │ Cassandra │ Redis │ │
|
||
│ │ Client │ Client │ │
|
||
│ └─────────────┴─────────────────┘ │
|
||
└─────────────┬───────────────────────────┘
|
||
│
|
||
┌─────────────▼───────────────────────────┐
|
||
│ 数据存储层 │
|
||
│ ┌──────┬──────┬─────────────────┐ │
|
||
│ │SQLite│Cassandra│ Redis │ │
|
||
│ │(配置) │ (生产) │ (缓存) │ │
|
||
│ └──────┴──────┴─────────────────┘ │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 核心组件
|
||
- **查询引擎**: 负责Cassandra和Redis的查询执行
|
||
- **比对引擎**: 实现智能数据比对算法
|
||
- **配置管理**: SQLite存储的配置持久化
|
||
- **日志系统**: 实时查询日志收集和展示
|
||
|
||
### 数据比对引擎
|
||
- **智能JSON比较**：自动处理JSON格式差异和嵌套结构
|
||
- **数组顺序无关比较**：忽略数组元素顺序的深度比较
|
||
- **字段级差异分析**：详细的字段差异统计和热点分析
|
||
- **数据质量评估**：自动生成数据一致性报告和改进建议
|
||
|
||
### 分表查询支持
|
||
- **TWCS策略**：基于Time Window Compaction Strategy的分表计算
|
||
- **时间戳提取**：智能从Key中提取时间戳信息
|
||
- **混合查询**：支持生产分表+测试单表等组合场景
|
||
- **并行查询**：多分表并行查询以提高性能
|
||
|
||
### 用户界面
|
||
- **响应式设计**：基于Bootstrap的现代化界面
|
||
- **实时反馈**：查询进度和结果的实时显示
|
||
- **分页展示**：大数据集的高效分页显示
|
||
- **多视图模式**：原始数据、格式化、差异对比等多种视图
|
||
|
||
## 🔧 配置说明
|
||
|
||
### Cassandra配置
|
||
```json
|
||
{
|
||
"cluster_name": "示例集群",
|
||
"hosts": ["127.0.0.1", "127.0.0.2"],
|
||
"port": 9042,
|
||
"datacenter": "dc1",
|
||
"username": "cassandra",
|
||
"password": "password",
|
||
"keyspace": "example_keyspace",
|
||
"table": "example_table"
|
||
}
|
||
```
|
||
|
||
### Redis配置
|
||
```json
|
||
{
|
||
"name": "示例Redis",
|
||
"nodes": [
|
||
{"host": "127.0.0.1", "port": 6379},
|
||
{"host": "127.0.0.2", "port": 6379}
|
||
],
|
||
"password": "redis_password",
|
||
"socket_timeout": 3,
|
||
"socket_connect_timeout": 3,
|
||
"max_connections_per_node": 16
|
||
}
|
||
```
|
||
|
||
## 📈 性能指标
|
||
|
||
### 响应时间
|
||
- 单表查询（100条记录）：< 10秒
|
||
- 分表查询（100条记录）：< 15秒
|
||
- Redis查询（100个Key）：< 10秒
|
||
- 页面加载时间：< 3秒
|
||
|
||
### 系统容量
|
||
- 最大并发查询数：10个
|
||
- 单次最大查询记录：10,000条
|
||
- 支持的数据库连接数：无限制
|
||
- 内存使用峰值：< 1GB
|
||
|
||
### 数据处理能力
|
||
- Cassandra分表自动计算准确率：> 95%
|
||
- JSON深度比较支持嵌套层级：无限制
|
||
- Redis全数据类型支持：100%
|
||
- 查询历史存储容量：无限制
|
||
|
||
## 🔄 版本更新
|
||
|
||
### v2.0 (2024-08)
|
||
- ✨ 新增Redis集群比对功能
|
||
- ✨ 支持多主键复合查询
|
||
- ✨ 智能数据类型检测和比对
|
||
- 🚀 性能优化和UI改进
|
||
- 📚 完整文档体系建设
|
||
|
||
### v1.0 (2024-07)
|
||
- 🎉 基础Cassandra数据比对功能
|
||
- 🎉 TWCS分表查询支持
|
||
- 🎉 配置管理和查询历史
|
||
- 🎉 Web界面和API接口
|
||
|
||
## 🔍 故障排查
|
||
|
||
### 常见问题
|
||
|
||
1. **Cassandra连接失败**
|
||
- 检查网络连通性：`telnet <host> <port>`
|
||
- 验证认证信息：用户名、密码、keyspace
|
||
- 确认防火墙设置
|
||
|
||
2. **Redis连接失败**
|
||
- 检查Redis服务状态：`redis-cli ping`
|
||
- 验证集群配置：节点地址和端口
|
||
- 确认密码设置
|
||
|
||
3. **查询超时**
|
||
- 调整连接超时参数
|
||
- 检查数据库服务器负载
|
||
- 优化查询条件和索引
|
||
|
||
4. **内存使用过高**
|
||
- 减少单次查询的记录数量
|
||
- 使用分批查询处理大数据集
|
||
- 定期清理查询历史和日志
|
||
|
||
5. **分表查询失败**
|
||
- 检查Key中是否包含有效时间戳
|
||
- 确认分表参数配置正确
|
||
- 验证目标分表是否存在
|
||
|
||
|
||
## 📝 API文档
|
||
|
||
### 主要API端点
|
||
|
||
- `POST /api/query` - 单表查询比对
|
||
- `POST /api/sharding-query` - 分表查询比对
|
||
- `POST /api/redis/compare` - Redis数据比对
|
||
- `GET /api/config-groups` - 获取配置组列表
|
||
- `POST /api/config-groups` - 创建配置组
|
||
- `GET /api/query-history` - 获取查询历史
|
||
- `GET /api/query-logs` - 获取查询日志
|
||
|
||
## 🤝 贡献指南
|
||
|
||
我们欢迎所有形式的贡献！请遵循以下步骤：
|
||
|
||
### 基本流程
|
||
1. **Fork项目**
|
||
```bash
|
||
git clone https://github.com/your-username/BigDataTool.git
|
||
cd BigDataTool
|
||
```
|
||
|
||
2. **创建功能分支**
|
||
```bash
|
||
git checkout -b feature/amazing-feature
|
||
```
|
||
|
||
3. **遵循代码规范**
|
||
- 查看 [代码规范](docs/coding-standards.md)
|
||
- 使用PEP 8 Python风格
|
||
- 添加必要的测试用例
|
||
- 更新相关文档
|
||
|
||
4. **提交更改**
|
||
```bash
|
||
git commit -m 'feat: Add some AmazingFeature'
|
||
```
|
||
|
||
5. **推送到分支**
|
||
```bash
|
||
git push origin feature/amazing-feature
|
||
```
|
||
|
||
6. **创建Pull Request**
|
||
- 描述变更内容和原因
|
||
- 确保所有测试通过
|
||
- 添加必要的截图或演示
|
||
|
||
### 贡献类型
|
||
- 🐛 Bug修复
|
||
- ✨ 新功能开发
|
||
- 📚 文档改进
|
||
- 🎨 界面优化
|
||
- 🚀 性能优化
|
||
- 🔧 配置和工具
|
||
|
||
### 代码审查
|
||
所有贡献都将经过代码审查，包括：
|
||
- 功能正确性验证
|
||
- 代码质量检查
|
||
- 安全性评估
|
||
- 文档完整性确认
|
||
|
||
详细开发指南请参考 [开发者文档](docs/developer-guide.md)
|
||
|
||
## 🛡️ 安全声明
|
||
|
||
BigDataTool致力于数据安全：
|
||
|
||
- 🔒 **传输加密**: 支持HTTPS/TLS加密传输
|
||
- 🔐 **认证机制**: 预留身份认证和权限控制接口
|
||
- 🔍 **输入验证**: 严格的输入参数验证和过滤
|
||
- 📝 **审计日志**: 完整的操作日志和安全事件记录
|
||
- 🛡️ **数据保护**: 敏感信息不明文存储
|
||
|
||
如发现安全漏洞，请发送邮件至安全团队或创建私密Issue。
|
||
|
||
详细安全规范请参考 [安全指南](docs/security-guidelines.md)
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情
|
||
|
||
## 👥 项目团队
|
||
|
||
### 核心开发者
|
||
- **项目负责人**: BigDataTool项目组
|
||
- **架构师**: 系统架构设计团队
|
||
- **前端开发**: UI/UX开发团队
|
||
- **后端开发**: 数据处理引擎团队
|
||
- **测试工程师**: 质量保证团队
|
||
|
||
### 贡献者统计
|
||
感谢所有为项目做出贡献的开发者！
|
||
|
||
## 📞 支持与反馈
|
||
|
||
### 问题报告
|
||
- 🐛 [Bug报告](https://github.com/your-org/BigDataTool/issues/new?template=bug_report.md)
|
||
- ✨ [功能请求](https://github.com/your-org/BigDataTool/issues/new?template=feature_request.md)
|
||
- ❓ [问题讨论](https://github.com/your-org/BigDataTool/discussions)
|
||
|
||
### 社区支持
|
||
- 📚 查看 [用户手册](docs/user-manual.md) 获取详细使用说明
|
||
- 🔧 查看 [故障排查指南](docs/operations.md) 解决常见问题
|
||
- 💬 加入社区讨论组获取实时帮助
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢以下开源项目和技术社区的支持：
|
||
|
||
- **[Flask](https://flask.palletsprojects.com/)** - 轻量级Web框架
|
||
- **[Cassandra](https://cassandra.apache.org/)** - 分布式NoSQL数据库
|
||
- **[Redis](https://redis.io/)** - 高性能键值存储
|
||
- **[Bootstrap](https://getbootstrap.com/)** - 前端UI框架
|
||
- **[jQuery](https://jquery.com/)** - JavaScript库
|
||
|
||
特别感谢所有提供反馈、bug报告和功能建议的用户！
|
||
|
||
---
|
||
|
||
## 📊 项目状态
|
||
|
||
**最后更新**: 2024年8月6日
|
||
**当前版本**: v2.0
|
||
**开发状态**: 持续维护中
|
||
|
||
> ⚠️ **重要提示**: 本工具主要用于开发测试环境的数据比对，生产环境使用请谨慎评估并做好安全防护。建议在使用前详细阅读 [安全指南](docs/security-guidelines.md)。
|