BigDataTool/docs/user-manual.md

DataTools Pro 用户使用手册

1. 系统介绍

1.1 产品概述

DataTools Pro 是一个企业级数据处理与比对工具平台，专为数据工程师和运维人员设计，提供高效、精准、可视化的数据分析解决方案。

1.2 主要功能

• Cassandra数据比对: 支持生产环境与测试环境的数据差异分析
• Redis集群比对: 支持多种数据类型的Redis集群数据比对
• 分表查询: 支持TWCS时间分表的智能查询
• 多主键查询: 支持复合主键的批量查询
• 配置管理: 可视化的数据库配置管理
• 查询历史: 完整的查询历史记录和结果复用
• 实时日志: 详细的查询执行日志和性能监控

1.3 系统要求

• 浏览器: Chrome 61+, Firefox 60+, Safari 10.1+, Edge 16+
• 网络: 能够访问目标Cassandra和Redis集群
• 权限: 具备目标数据库的读取权限

2. 快速入门

2.1 访问系统

1. 打开浏览器，访问系统地址（如：http://your-domain.com）
2. 系统首页展示了可用的工具模块和功能介绍
3. 选择需要使用的工具进入相应的功能页面

2.2 界面概览

DataTools Pro 界面布局:
┌─────────────────────────────────────────────────────────────┐
│                    导航栏                                    │
│  DataTools Pro | 首页 | Cassandra比对 | Redis比对          │
├─────────────────────────────────────────────────────────────┤
│                   面包屑导航                                 │ 
│  首页 > Cassandra数据比对工具                               │
├─────────────────────────────────────────────────────────────┤
│  配置管理面板           │        查询操作面板               │
│  ┌─────────────────┐    │    ┌─────────────────────────────┐ │
│  │ • 配置组管理    │    │    │ • 查询模式选择              │ │
│  │ • 数据库配置    │    │    │ • Key值输入                │ │
│  │ • 查询历史      │    │    │ • 比对字段配置              │ │
│  │ • 查询日志      │    │    │ • 执行按钮                  │ │
│  └─────────────────┘    │    └─────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                      结果展示区域                           │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │ • 统计信息卡片                                          │ │
│  │ • 差异详情 | 相同结果 | 原始数据 | 比较总结             │ │
│  │ • 分页导航和搜索过滤                                    │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

2.3 键盘快捷键

• Ctrl/Cmd + H: 返回首页
• Ctrl/Cmd + 1: 切换到Cassandra工具
• Ctrl/Cmd + 2: 切换到Redis工具
• ?: 显示/隐藏快捷键提示

3. Cassandra数据比对工具

3.1 功能概述

Cassandra数据比对工具支持对生产环境和测试环境的Cassandra数据库进行精确的数据比对分析，支持单表查询、分表查询和多主键查询三种模式。

3.2 配置管理

3.2.1 配置组管理

配置组功能允许您保存和管理常用的数据库配置，避免重复输入。

创建配置组:

1. 点击"保存配置组"按钮
2. 输入配置组名称和描述
3. 系统将保存当前的所有配置信息
4. 配置组创建成功后可在下拉列表中选择

加载配置组:

1. 在配置组下拉列表中选择已保存的配置组
2. 点击"加载"按钮
3. 系统将自动填充所有相关配置

管理配置组:

1. 点击"管理配置组"按钮
2. 查看所有已保存的配置组
3. 可以删除不需要的配置组

3.2.2 数据库配置

生产环境配置:

配置项说明:
• 集群名称: Cassandra集群的标识名称
• 数据中心: 数据中心名称 (如: datacenter1)
• 主机地址: Cassandra节点地址列表 (支持多个，逗号分隔)
• 端口: 连接端口 (默认: 9042)
• 用户名: 数据库用户名 (可选)
• 密码: 数据库密码 (可选)
• 键空间: Keyspace名称
• 表名: 要查询的表名

测试环境配置: 配置项与生产环境相同，用于配置测试环境的Cassandra连接信息。

一键导入功能:

1. 点击"一键导入"按钮
2. 可以从生产环境配置快速复制到测试环境
3. 根据需要修改测试环境的特定配置

3.3 查询模式

3.3.1 单表查询模式

默认的查询模式，适用于普通的Cassandra表查询。

操作步骤:

1. 确保分表模式开关处于关闭状态
2. 配置生产和测试环境的数据库连接
3. 设置查询参数
4. 输入要查询的Key值
5. 点击"执行查询比对"

3.3.2 分表查询模式

适用于使用TWCS (Time Window Compaction Strategy) 分表策略的Cassandra表。

启用分表模式:

1. 打开"分表模式"开关
2. 分别配置生产和测试环境的分表参数

分表参数配置:

配置说明:
• 生产环境分表: 是否对生产环境启用分表查询
• 测试环境分表: 是否对测试环境启用分表查询
• 时间间隔(秒): 分表的时间间隔，默认604800秒(7天)
• 分表数量: 总分表数量，默认14张表

分表算法说明:

• 系统从Key中提取时间戳（删除所有非数字字符）
• 计算公式: shard_index = timestamp // interval_seconds % table_count
• 示例: Key为"wmid_1609459200"，提取时间戳1609459200，计算得到分表索引

3.3.3 多主键查询模式

支持复合主键的批量查询，适用于具有多个主键字段的表。

配置多主键:

1. 在"主键字段"中输入多个字段名，用逗号分隔
   • 示例: user_id,timestamp 或 docid,id
2. 在查询Key值中输入复合主键值，每行一组，字段值用逗号分隔
   • 示例:

     1001,1609459200
     1002,1609545600
     

3.4 查询配置

3.4.1 基础查询参数

参数说明:
• 主键字段: 表的主键字段名，支持单个或多个字段
• 比对字段: 指定要比对的字段列表 (空表示全部字段)
• 排除字段: 指定要排除的字段列表
• 查询Key值: 要查询的主键值列表，每行一个

3.4.2 字段配置技巧

• 全字段比对: 比对字段留空，系统将比对所有字段
• 指定字段比对: 在比对字段中列出需要比对的字段名
• 排除字段: 在排除字段中列出不需要比对的字段（如时间戳字段）
• 字段名格式: 使用英文逗号分隔多个字段名

3.5 执行查询

3.5.1 查询执行流程

1. 配置验证: 系统验证数据库连接配置的完整性
2. 连接测试: 尝试连接到生产和测试环境
3. 并行查询: 同时执行生产和测试环境的数据查询
4. 数据比对: 对查询结果进行字段级比对分析
5. 结果展示: 生成详细的比对报告和统计信息

3.5.2 执行过程监控

• 查询执行时显示进度指示器
• 实时显示执行状态和进度信息
• 可以通过查询日志查看详细的执行过程

3.6 结果分析

3.6.1 统计信息卡片

查询完成后，系统会显示以下统计信息:

统计指标:
• 查询总数: 本次查询的Key总数量
• 生产记录数: 生产环境查询到的记录数
• 测试记录数: 测试环境查询到的记录数
• 差异数量: 发现的数据差异数量
• 相同数量: 数据完全相同的记录数量
• 匹配率: 数据匹配的百分比

3.6.2 结果选项卡

差异详情选项卡:

• 显示所有发现的数据差异
• 每条差异记录包含:
  • Key信息 (支持复合主键显示)
  • 字段名
  • 生产环境值
  • 测试环境值
  • 差异类型说明
• 支持分页浏览和搜索过滤

相同结果选项卡:

• 显示数据完全相同的记录
• 包含生产和测试环境的完整字段值
• 可用于验证数据同步的正确性

原始数据选项卡:

• 显示生产和测试环境的原始查询数据
• 支持格式化和原始两种显示模式
• 提供数据导出功能

比较总结选项卡:

• 提供详细的数据质量分析报告
• 包含匹配率统计和字段级差异分析
• 给出数据改进建议

3.6.3 分表查询信息

当使用分表查询模式时，结果页面会显示额外的分表信息:

分表信息包含:
• 分表映射关系: 每个Key对应的分表名称
• 分表统计: 使用的分表列表和分布情况
• 时间戳提取: 时间戳提取成功率
• 失败Key列表: 时间戳提取失败的Key

3.7 查询历史管理

3.7.1 保存查询历史

1. 查询执行完成后，点击"保存历史"按钮
2. 输入历史记录名称和描述
3. 系统将保存完整的查询配置和结果数据

3.7.2 查看查询历史

1. 点击"查询历史"按钮
2. 浏览所有已保存的历史记录
3. 可以查看历史记录的详细信息:
   • 查询配置
   • 执行时间
   • 结果统计
   • 完整的差异和相同数据

3.7.3 历史记录操作

• 加载历史: 从历史记录恢复查询配置
• 查看结果: 查看历史查询的完整结果
• 删除记录: 删除不需要的历史记录

3.8 查询日志

3.8.1 日志功能

查询日志记录了查询执行过程中的所有关键信息:

• SQL语句执行记录
• 数据库连接状态
• 查询耗时统计
• 错误和警告信息

3.8.2 日志查看

1. 点击"查询日志"按钮
2. 可以按日志级别过滤:
   • INFO: 一般信息
   • WARNING: 警告信息
   • ERROR: 错误信息
3. 支持按时间范围查看日志

3.8.3 日志管理

• 实时刷新: 实时查看最新的日志信息
• 清空日志: 清除所有历史日志记录
• 日志导出: 导出日志用于分析和故障排查

4. Redis集群比对工具

4.1 功能概述

Redis集群比对工具专门用于对比两个Redis集群之间的数据差异，支持所有Redis数据类型，提供随机采样和指定Key两种查询模式。

4.2 Redis集群配置

4.2.1 集群配置参数

配置项说明:
• 集群名称: Redis集群的标识名称
• Redis节点: 集群节点列表，支持添加多个节点
  - 主机地址: Redis节点IP地址
  - 端口: Redis端口 (默认: 6379)
• 密码: Redis认证密码 (可选)
• 连接超时: Socket连接超时时间 (默认: 3秒)
• 建立超时: Socket建立连接超时时间 (默认: 3秒)
• 最大连接数: 每个节点的最大连接数 (默认: 16)

4.2.2 集群节点管理

添加节点:

1. 在节点配置区域点击"添加节点"按钮
2. 输入节点的IP地址和端口
3. 可以添加多个节点以支持集群模式

删除节点:

1. 点击节点右侧的删除按钮
2. 确认删除操作

测试连接:

1. 配置完成后点击"测试连接"按钮
2. 系统将测试与集群的连接状态
3. 显示连接结果和节点状态

4.3 查询模式

4.3.1 随机采样模式

适用于对Redis集群进行数据质量抽查和整体数据一致性验证。

配置参数:

参数说明:
• 采样数量: 随机采样的Key数量 (1-10000)
• Key模式: Key的匹配模式 (默认: *)
• 源集群: 选择从哪个集群获取Key列表

操作步骤:

1. 选择"随机采样模式"
2. 设置采样数量 (建议100-1000)
3. 设置Key模式 (如: user:, session:, 或 *)
4. 选择源集群 (通常选择数据较完整的集群)
5. 点击"开始Redis数据比较"

4.3.2 指定Key模式

适用于对特定Key进行精确的数据比对。

操作步骤:

1. 选择"指定Key模式"
2. 在Key列表文本框中输入要查询的Key
3. 每行一个Key，支持大批量Key查询
4. 建议单次不超过1000个Key
5. 点击"开始Redis数据比较"

Key输入示例:

user:1001
user:1002
session:abc123
cache:product:12345

4.4 数据类型支持

4.4.1 支持的Redis数据类型

Redis集群比对工具支持以下数据类型的比对:

• String: 字符串类型，包括JSON字符串
• Hash: 哈希表，支持字段级比对
• List: 列表，支持顺序和内容比对
• Set: 集合，支持成员比对(顺序无关)
• Sorted Set: 有序集合，支持成员和分数比对

4.4.2 数据比对逻辑

比对规则:
• String类型: 直接比较字符串值
• Hash类型: 逐字段比较，显示字段级差异
• List类型: 比较列表长度和元素内容
• Set类型: 比较集合成员，忽略顺序
• ZSet类型: 比较成员和分数的对应关系

4.5 结果分析

4.5.1 统计信息

Redis比对完成后显示以下统计信息:

统计指标:
• 查询总数: 本次查询的Key总数
• 集群1找到: 集群1中存在的Key数量
• 集群2找到: 集群2中存在的Key数量
• 差异数量: 值不同的Key数量
• 相同数量: 值完全相同的Key数量
• 缺失数量: 在某个集群中不存在的Key数量

4.5.2 结果选项卡

差异详情选项卡:

• 显示值不同的Key详细信息
• 包含Key名称、数据类型、两个集群的值
• 对于复杂数据类型，显示具体的差异字段

相同结果选项卡:

• 显示完全相同的Key和值
• 用于验证数据同步的正确性

缺失数据选项卡:

• 显示在某个集群中不存在的Key
• 分为"集群1缺失"和"集群2缺失"两个部分

原生数据选项卡:

• 显示两个集群的原始查询数据
• 支持格式化和原始数据两种视图
• 提供数据导出功能

比较总结选项卡:

• 生成性能报告和数据质量分析
• 包含集群连接状态和响应时间统计
• 提供数据一致性改进建议

4.6 性能监控

4.6.1 集群状态监控

系统实时监控Redis集群的运行状态:

监控指标:
• 连接状态: 显示每个节点的连接状态
• 平均响应时间: 集群的平均响应时间
• 节点状态: 各个节点的运行状态
• 数据传输量: 本次查询的数据传输量

4.6.2 性能统计

查询完成后显示性能统计信息:

• 总执行时间
• 每秒处理Key数量
• 数据传输量统计
• 集群负载分析

5. 高级功能

5.1 配置导入导出

5.1.1 配置导出

1. 在任何工具页面点击"导出配置"按钮
2. 系统将生成包含所有配置信息的JSON文件
3. 文件包含数据库配置、查询参数、分表配置等

5.1.2 配置导入

1. 点击"一键导入"或相关导入按钮
2. 选择导入方式:
   • 文本粘贴: 直接粘贴YAML或JSON配置
   • 文件上传: 上传配置文件或拖拽文件
3. 预览配置内容
4. 确认导入

5.1.3 支持的配置格式

YAML格式示例:

clusterName: "production-cluster"
clusterAddress: "10.0.1.100:9042,10.0.1.101:9042"
keyspace: "production_ks"
table: "user_data"
username: "cassandra_user"
password: "password"

JSON格式示例:

{
  "cluster_name": "production-cluster",
  "hosts": ["10.0.1.100", "10.0.1.101"],
  "port": 9042,
  "keyspace": "production_ks",
  "table": "user_data"
}

5.2 数据导出功能

5.2.1 结果导出格式

支持多种数据导出格式:

• Excel格式 (.xlsx): 适合数据分析和报告
• CSV格式 (.csv): 通用的数据交换格式
• JSON格式 (.json): 适合程序处理
• HTML报告: 可打印的详细报告

5.2.2 导出内容选择

可以选择导出以下内容:

• 差异数据详情
• 相同数据记录
• 原始查询数据
• 统计分析报告
• 完整的比对结果

5.2.3 导出操作步骤

1. 在结果页面点击"导出结果"按钮
2. 选择导出格式和内容范围
3. 系统生成并下载导出文件
4. 文件名包含时间戳，便于管理

5.3 批量操作

5.3.1 批量Key导入

支持大批量Key的导入和处理:

• 文件导入: 支持.txt, .csv, .xlsx格式
• 粘贴导入: 直接粘贴Key列表
• 去重处理: 自动去除重复的Key
• 格式验证: 验证Key格式的正确性

5.3.2 批量查询优化

系统对批量查询进行了优化:

• 分批处理: 大量Key自动分批查询
• 并行执行: 多线程并行处理提高效率
• 进度显示: 实时显示查询进度
• 错误处理: 单个Key失败不影响整体查询

5.4 数据过滤和搜索

5.4.1 实时搜索

在结果页面提供实时搜索功能:

• Key搜索: 根据Key名称搜索
• 字段搜索: 根据字段名搜索
• 值搜索: 根据字段值搜索
• 模糊匹配: 支持部分匹配和通配符

5.4.2 高级过滤

提供多种过滤条件:

• 差异类型过滤: 按差异类型筛选
• 字段名过滤: 按特定字段筛选
• 数据类型过滤: 按Redis数据类型筛选
• 时间范围过滤: 按查询时间筛选

6. 故障排查

6.1 常见问题

6.1.1 连接问题

问题: 无法连接到Cassandra/Redis集群 解决方案:

1. 检查网络连通性: ping <host>
2. 检查端口是否开放: telnet <host> <port>
3. 验证用户名和密码
4. 确认防火墙设置
5. 检查集群状态

问题: 连接超时 解决方案:

1. 增加连接超时时间
2. 检查网络延迟
3. 确认集群负载情况
4. 检查DNS解析

6.1.2 查询问题

问题: 查询结果为空 解决方案:

1. 验证Key是否存在于数据库中
2. 检查表名和键空间是否正确
3. 确认主键字段名拼写
4. 检查数据权限

问题: 分表查询失败 解决方案:

1. 验证分表参数配置
2. 检查Key中是否包含时间戳
3. 确认分表命名规则
4. 验证分表数量设置

6.1.3 性能问题

问题: 查询速度慢 解决方案:

1. 减少单次查询的Key数量
2. 优化网络连接
3. 检查数据库负载
4. 使用更高效的查询模式

问题: 内存使用过高 解决方案:

1. 分批处理大量数据
2. 减少比对字段数量
3. 清理历史查询记录
4. 重启浏览器释放内存

6.2 错误信息解读

6.2.1 连接错误

错误类型及解决方案:

• "Connection refused"
  - 检查目标主机是否可达
  - 确认端口是否正确
  - 检查防火墙设置

• "Authentication failed"  
  - 验证用户名和密码
  - 检查用户权限
  - 确认认证方式

• "Timeout occurred"
  - 增加超时时间设置
  - 检查网络延迟
  - 确认集群健康状态

6.2.2 查询错误

错误类型及解决方案:

• "Keyspace not found"
  - 检查键空间名称拼写
  - 确认键空间是否存在
  - 验证用户访问权限

• "Table not found"
  - 检查表名拼写
  - 确认表是否存在于指定键空间
  - 验证表访问权限

• "Invalid primary key"
  - 检查主键字段名
  - 确认主键值格式
  - 验证复合主键配置

6.3 性能优化建议

6.3.1 查询优化

1. 合理设置批次大小: 建议单次查询1000个Key以内
2. 选择合适的比对字段: 只比对必要的字段
3. 使用分表查询: 对于大表使用分表查询提高效率
4. 定期清理历史数据: 删除不需要的历史记录和日志

6.3.2 网络优化

1. 就近部署: 在靠近数据库的网络环境中使用工具
2. 稳定网络: 确保网络连接稳定，避免频繁重连
3. 并发控制: 合理设置并发连接数
4. 压缩传输: 启用数据传输压缩

6.3.3 数据库优化

1. 读取权限: 确保使用只读权限账户
2. 索引优化: 确保查询字段有适当的索引
3. 分区策略: 合理设计Cassandra分区键
4. 连接池: 使用连接池避免频繁建立连接

7. 最佳实践

7.1 数据比对策略

7.1.1 渐进式比对

1. 小范围测试: 先用少量Key测试配置和连接
2. 分批比对: 将大量数据分批进行比对
3. 重点字段: 优先比对关键业务字段
4. 定期验证: 建立定期数据比对的流程

7.1.2 差异分析方法

1. 分类分析: 按字段类型分类分析差异
2. 趋势观察: 观察差异随时间的变化趋势
3. 根因分析: 深入分析差异产生的根本原因
4. 修复验证: 修复后重新验证数据一致性

7.2 配置管理最佳实践

7.2.1 配置组织

1. 命名规范: 使用有意义的配置组名称
2. 环境区分: 清楚标识生产、测试、开发环境
3. 版本管理: 记录配置变更历史
4. 权限控制: 限制敏感配置的访问权限

7.2.2 安全考虑

1. 密码管理: 避免在配置中硬编码密码
2. 权限最小化: 使用最小必要权限的数据库账户
3. 网络隔离: 在安全的网络环境中使用工具
4. 审计日志: 记录重要操作的审计日志

7.3 团队协作

7.3.1 工作流程标准化

1. 操作文档: 制定标准的操作流程文档
2. 结果记录: 建立查询结果的记录和归档制度
3. 问题跟踪: 建立差异问题的跟踪和解决流程
4. 知识分享: 定期分享使用经验和最佳实践

7.3.2 质量控制

1. 双人验证: 重要数据比对结果需要双人确认
2. 结果审核: 建立结果审核和批准流程
3. 变更控制: 对配置变更进行严格控制
4. 定期回顾: 定期回顾和改进数据比对流程

8. 技术支持

8.1 获取帮助

• 在线文档: 访问系统内置的帮助文档
• 技术支持: 联系技术支持团队
• 社区论坛: 参与用户社区讨论
• 培训资源: 获取相关的培训材料

8.2 反馈和建议

我们欢迎您的反馈和建议:

• 功能建议: 提出新功能需求
• 问题报告: 报告使用中遇到的问题
• 改进意见: 提供用户体验改进建议
• 文档更新: 建议文档内容的改进

8.3 版本更新

• 更新通知: 关注系统版本更新通知
• 新功能: 了解新版本的功能特性
• 兼容性: 注意版本兼容性说明
• 升级指南: 遵循版本升级指南

---

DataTools Pro v2.0 用户使用手册
更新日期: 2024-08-05
版权所有: DataTools Pro Team