# BigDataTool - 大数据查询比对工具 [![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org) [![Flask Version](https://img.shields.io/badge/flask-2.3.3-green.svg)](https://flask.palletsprojects.com/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](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 ` - 验证认证信息：用户名、密码、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)。