yovinchen/BigDataTool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

增加文档

Browse Source
This commit is contained in:
YoVinchen
2025-08-05 23:27:25 +08:00
parent 8097e9b769
commit 0ac375eb50
7 changed files with 5677 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

708
docs/user-manual.md Normal file
View File

@@ -0,0 +1,708 @@
# 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格式示例**:
```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格式示例**:
```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