API 对齐数据库迁移运行手册

适用迁移

MessageService：20260909000100_ApiAlignmentFixes
MessageService：20260911000100_ConversationUniqueness
GroupService：20260909000200_ApiAlignmentFixes
FileService：20260909000300_AsyncUploadResult

发布前检查

先完成三个库的可恢复备份，并在对应数据库执行：

-- MessageService：记录迁移将处理的活动会话重复项。
SELECT UserId, ChatType, TargetId, COUNT(*) AS duplicate_count
FROM conversations
WHERE IsDeleted = 0
GROUP BY UserId, ChatType, TargetId
HAVING COUNT(*) > 1;

-- GroupService：新增 Id 唯一索引前必须无重复。
SELECT Id, COUNT(*) AS duplicate_count
FROM group_join_requests
GROUP BY Id
HAVING COUNT(*) > 1;

-- FileService：收紧 longtext 前检查历史最大长度。
SELECT
  MAX(CHAR_LENGTH(FileName)) AS max_file_name,
  MAX(CHAR_LENGTH(ContentType)) AS max_content_type,
  MAX(CHAR_LENGTH(checksum_algorithm)) AS max_checksum_algorithm,
  MAX(CHAR_LENGTH(checksum_value)) AS max_checksum_value,
  MAX(CHAR_LENGTH(storage_provider)) AS max_storage_provider,
  MAX(CHAR_LENGTH(storage_bucket)) AS max_storage_bucket,
  MAX(CHAR_LENGTH(storage_key)) AS max_storage_key,
  MAX(CHAR_LENGTH(storage_region)) AS max_storage_region
FROM upload_files;

上面的长度必须分别不超过 255/255/16/128/64/255/1024/128。对 upload_tasks 执行同样检查。超长值应先人工确认和修正，不要依赖数据库静默截断。

执行迁移

在仓库根目录设置目标数据库连接字符串后执行。不要把真实密码写入仓库或命令记录。

$env:DefaultDB_ConnStr = '<MessageService MySQL connection string>'
dotnet ef database update --project MessageService.Infrastructure --startup-project MessageService.WebApi --context MessageDbContext

$env:DefaultDB_ConnStr = '<GroupService MySQL connection string>'
dotnet ef database update --project GroupService.Infrastructure --startup-project GroupService.WebApi --context GroupDbContext

$env:DefaultDB_ConnStr = '<FileService MySQL connection string>'
dotnet ef database update --project FileService.Infrastructure --startup-project FileService.WebApi --context FileDbContext

建议顺序为 Message → Group → File，随后发布后端，再发布最终前端包。

本地具备 Docker 时执行 MessageService 的 MySQL 8 集成测试：

$env:RUN_DOCKER_TESTS = '1'
dotnet test MessageService.Tests/MessageService.Tests.csproj

未设置该变量时，dotnet test IM_API_NEW.sln 仍会运行领域模型和迁移脚本检查，并明确跳过需要 Docker 的两项测试。

数据兼容说明

所有新业务列均可空或有安全默认值，不删除历史记录。
历史文件的 IsPublic 默认 false，无法确认作用域的旧文件因此只允许所有者读取。
新上传文件会写入 SourceTaskId/ChatType/TargetId/ResultFileId；不要批量猜测旧文件作用域。
群退出、群解散和会话隐藏使用软删除。
会话唯一性迁移不会物理删除记录；它保留更新时间最新的一条活动会话，将其他重复项软删除，并创建只约束活动记录的生成列唯一索引。
Docker Compose 要求从环境注入 MySQL、RabbitMQ 和内部 API 凭据，可复制 .env.example 后填入部署环境的真实值；不得提交 .env。

回滚

只有在已经回滚依赖新字段/接口的前后端版本后，才允许回滚数据库迁移：

$env:DefaultDB_ConnStr = '<MessageService MySQL connection string>'
dotnet ef database update 20260423115234_InitMessageDb --project MessageService.Infrastructure --startup-project MessageService.WebApi --context MessageDbContext

$env:DefaultDB_ConnStr = '<GroupService MySQL connection string>'
dotnet ef database update 20260429103435_removeGroupRequestOperatorProfile --project GroupService.Infrastructure --startup-project GroupService.WebApi --context GroupDbContext

$env:DefaultDB_ConnStr = '<FileService MySQL connection string>'
dotnet ef database update 20260509073447_InitFileDb --project FileService.Infrastructure --startup-project FileService.WebApi --context FileDbContext

FileService 回滚会删除新作用域和任务结果列，并把收紧的字符串列恢复为 longtext；回滚前应另行导出这些新列的数据。

20260913000100 会话活动时间与消息搜索

部署消息服务前先备份数据库，并在 MySQL 8 测试库执行 20260913000100_ConversationActivityAndMessageSearch。

迁移新增可空 conversations.LastMessageTime，按相同 StreamKey 的最新未删除消息时间回填；没有消息时回退到会话创建时间。
新增 messages(StreamKey, MsgType, State, SequenceId) 复合索引，为会话内文本搜索和独占游标分页提供支持。
迁移只更新内部存储结构，不改变现有 DTO；发布后确认旧会话排序未因已读操作变化，并抽查搜索翻页无重复。

4.9 KiB Raw Permalink Blame History Unescape Escape