commit

2025-11-10 15:30:21 +08:00
parent 4716b82f29
commit df39693dff
43 changed files with 6864 additions and 5 deletions
--- a/cmd/message-migrator/README.md
+++ b/cmd/message-migrator/README.md
@@ -0,0 +1,146 @@
+# Message Migrator 数据迁移工具
+
+这个工具用于将指定项目的消息数据从源数据库迁移到目标数据库。
+
+## 功能特性
+
+- ✅ 按项目ID迁移数据
+- ✅ 支持可选的UID替换
+- ✅ 自动处理表之间的ID关联映射
+- ✅ 使用事务保证数据一致性
+- ✅ 按正确的依赖顺序迁移：`m_stream_messages` → `m_stream_contents` → `m_context_messages` → `m_task_messages`
+
+## 涉及的表
+
+1. `m_stream_messages` - 流式消息记录表（主表）
+2. `m_stream_contents` - 流式消息内容详情及分段表
+3. `m_context_messages` - Agent上下文消息记录表
+4. `m_task_messages` - 任务聚合消息记录表
+
+## 安装依赖
+
+```bash
+go get github.com/go-sql-driver/mysql
+```
+
+## 配置
+
+在使用前，请修改 `main.go` 中的数据库连接配置：
+
+```go
+const (
+    // 源数据库 DSN 格式: user:password@tcp(host:port)/database?parseTime=true
+    SOURCE_DSN = "user:password@tcp(localhost:3306)/goalfymax_prod?parseTime=true"
+    // 目标数据库 DSN
+    TARGET_DSN = "user:password@tcp(localhost:3306)/goalfymax_archive?parseTime=true"
+)
+```
+
+## 使用方法
+
+### 基本用法（保持原始UID）
+
+```bash
+go run main.go -project <project_id>
+```
+
+示例：
+```bash
+go run main.go -project 123
+```
+
+### 替换UID
+
+```bash
+go run main.go -project <project_id> -uid <new_uid>
+```
+
+示例：
+```bash
+go run main.go -project 123 -uid 456
+```
+
+### 自定义数据库连接
+
+```bash
+go run main.go -project 123 \
+  -source "root:pass@tcp(source-host:3306)/goalfymax_prod?parseTime=true" \
+  -target "root:pass@tcp(target-host:3306)/goalfymax_archive?parseTime=true"
+```
+
+### 编译后使用
+
+```bash
+# 编译
+go build -o message-migrator
+
+# 运行
+./message-migrator -project 123
+./message-migrator -project 123 -uid 456
+```
+
+## 参数说明
+
+| 参数       | 必需 | 说明                                        | 示例                                    |
+| ---------- | ---- | ------------------------------------------- | --------------------------------------- |
+| `-project` | 是   | 要迁移的项目ID                              | `-project 123`                          |
+| `-uid`     | 否   | 新的用户ID（不指定则使用原始UID）           | `-uid 456`                              |
+| `-source`  | 否   | 源数据库DSN（不指定则使用代码中的默认值）   | `-source "user:pass@tcp(host:3306)/db"` |
+| `-target`  | 否   | 目标数据库DSN（不指定则使用代码中的默认值） | `-target "user:pass@tcp(host:3306)/db"` |
+
+## 迁移流程
+
+1. **连接数据库**：连接到源数据库和目标数据库
+2. **开启事务**：在两个数据库上分别开启事务
+3. **迁移主表**：迁移 `m_stream_messages`，记录旧ID到新ID的映射
+4. **迁移关联表**：
+   - 迁移 `m_stream_contents`，使用映射更新 `main_message_id`
+   - 迁移 `m_context_messages`，使用映射更新 `main_message_id`
+   - 迁移 `m_task_messages`，使用映射更新 `main_message_id`
+5. **提交事务**：所有数据迁移成功后提交事务
+
+## 注意事项
+
+⚠️ **重要提示**：
+
+1. **备份数据**：在执行迁移前，请务必备份源数据库和目标数据库
+2. **目标表存在**：工具不会创建表，请确保目标数据库中已存在所有需要的表结构
+3. **事务一致性**：迁移过程使用事务，如果中途失败会自动回滚
+4. **ID映射**：工具会自动处理 `main_message_id` 的映射关系，确保关联正确
+5. **UID替换**：如果指定了 `-uid` 参数，所有表中的 `uid` 字段都会被替换为新值
+6. **重复执行**：请注意，重复执行相同的迁移命令可能会导致数据重复
+
+## 日志输出
+
+工具会输出详细的迁移日志：
+
+```
+2025/11/07 10:00:00 Starting migration for project_id=123
+2025/11/07 10:00:00 Will replace UID with: 456
+2025/11/07 10:00:01 Step 1: Migrating m_stream_messages...
+2025/11/07 10:00:02   Migrated 150 stream messages
+2025/11/07 10:00:02 Step 2: Migrating m_stream_contents...
+2025/11/07 10:00:03   Migrated 300 stream contents
+2025/11/07 10:00:03 Step 3: Migrating m_context_messages...
+2025/11/07 10:00:04   Migrated 200 context messages
+2025/11/07 10:00:04 Step 4: Migrating m_task_messages...
+2025/11/07 10:00:05   Migrated 180 task messages
+2025/11/07 10:00:05 Migration completed successfully!
+```
+
+## 错误处理
+
+如果迁移过程中遇到错误：
+
+- 事务会自动回滚，不会产生部分数据
+- 错误信息会显示在日志中
+- 检查数据库连接、权限和表结构是否正确
+
+## 性能建议
+
+对于大量数据的迁移：
+
+1. 在非高峰期执行
+2. 确保数据库有足够的临时空间
+3. 可以考虑先迁移到测试环境验证
+4. 监控数据库性能指标