docs/v1.0/server/changelogs/2026-01-29-folder-migration-duplicate-fix.md

修复文件夹迁移脚本重复创建表问题

日期: 2026-01-29
类型: Bug 修复
影响范围: 数据库迁移系统

问题描述

使用 ./start_docker.sh -c 清除数据库后重新部署时，迁移脚本执行失败：

asyncpg.exceptions.DuplicateTableError: relation "users" already exists

根本原因

1. 初始迁移 3a3a2a1417de 已经创建了 users 和 user_sessions 表
2. 后续迁移 20260129_1500 又尝试创建相同的表
3. 导致迁移链重复创建表，在清空数据库后重新迁移时失败

解决方案

1. 删除重复的迁移脚本

删除 server/alembic/versions/20260129_1500_create_users_and_sessions.py，因为：

• users 表已在初始迁移 3a3a2a1417de 中创建
• user_sessions 表也已在初始迁移中创建
• 该迁移脚本完全重复，无实际作用

2. 修复迁移链依赖

修改 20260129_1600_fix_folder_timestamp_timezone.py：

# 修改前
down_revision = '20260129_1500'

# 修改后
down_revision = '20260129_1410'

修改文件

删除文件

• server/alembic/versions/20260129_1500_create_users_and_sessions.py

修改文件

• server/alembic/versions/20260129_1600_fix_folder_timestamp_timezone.py
  • 修改 down_revision 从 20260129_1500 改为 20260129_1410

验证结果

迁移链验证

$ docker exec jointo-server-app alembic current
20260129_1600 (head)

数据库表验证

$ docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\d folders"

确认 folders 表的时间字段正确使用 TIMESTAMPTZ：

• created_at: timestamp with time zone
• updated_at: timestamp with time zone
• deleted_at: timestamp with time zone

影响

正面影响

• ✅ 修复了 ./start_docker.sh -c 清空数据库后无法重新迁移的问题
• ✅ 清理了重复的迁移脚本，保持迁移历史清晰
• ✅ 确保迁移链的完整性和一致性

注意事项

• ⚠️ 已部署的环境不受影响（迁移版本已经跳过 20260129_1500）
• ⚠️ 新部署的环境将直接跳过已删除的迁移脚本

最佳实践

避免重复迁移

1. 检查初始迁移：创建新迁移前，先检查表是否已在初始迁移中创建
2. 使用 alembic history：查看完整的迁移历史
3. 测试清空重建：定期测试 ./start_docker.sh -c 确保迁移链完整

迁移脚本规范

# 查看迁移历史
docker exec jointo-server-app alembic history

# 查看当前版本
docker exec jointo-server-app alembic current

# 检查表是否存在
docker exec jointo-server-postgres psql -U jointoAI -d jointo -c "\dt"

相关文档

• Alembic 迁移指南
• 数据库时间字段规范
• 文件夹服务实现

技术债务

无

后续工作

• 运行文件夹 API 集成测试
• 验证所有服务的迁移脚本无重复
• 更新部署文档，说明迁移链的维护规范