第一次提交

backend/README_ALEMBIC.md

@@ -0,0 +1,156 @@
+# Alembic 数据库迁移使用说明
+
+## 概述
+
+本项目使用 Alembic 进行数据库版本管理和迁移。Alembic 是 SQLAlchemy 的数据库迁移工具，可以自动生成迁移脚本并管理数据库结构变更。
+
+## 目录结构
+
+```
+backend/
+├── alembic/
+│   ├── versions/          # 迁移脚本目录
+│   │   └── 001_initial_migration.py
+│   ├── env.py             # Alembic 环境配置
+│   └── script.py.mako     # 迁移脚本模板
+├── alembic.ini            # Alembic 配置文件
+└── migrations/            # 手动SQL脚本（备用）
+```
+
+## 基本命令
+
+### 1. 创建新的迁移脚本
+
+```bash
+# 自动生成迁移脚本（推荐）
+alembic revision --autogenerate -m "描述信息"
+
+# 手动创建空迁移脚本
+alembic revision -m "描述信息"
+```
+
+### 2. 执行迁移
+
+```bash
+# 升级到最新版本
+alembic upgrade head
+
+# 升级到指定版本
+alembic upgrade <revision>
+
+# 降级到指定版本
+alembic downgrade <revision>
+
+# 降级一个版本
+alembic downgrade -1
+```
+
+### 3. 查看迁移历史
+
+```bash
+# 查看所有迁移版本
+alembic history
+
+# 查看当前数据库版本
+alembic current
+
+# 查看待执行的迁移
+alembic heads
+```
+
+## 使用流程
+
+### 首次使用（初始化数据库）
+
+1. 确保数据库已创建：
+   ```sql
+   CREATE DATABASE IF NOT EXISTS agent_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+   ```
+
+2. 执行初始迁移：
+   ```bash
+   alembic upgrade head
+   ```
+
+### 修改模型后创建迁移
+
+1. 修改 `backend/app/models/` 中的模型文件
+
+2. 自动生成迁移脚本：
+   ```bash
+   alembic revision --autogenerate -m "添加新字段"
+   ```
+
+3. 检查生成的迁移脚本（`alembic/versions/` 目录）
+
+4. 执行迁移：
+   ```bash
+   alembic upgrade head
+   ```
+
+## 注意事项
+
+1. **模型导入**：确保 `alembic/env.py` 中导入了所有模型，这样 Alembic 才能检测到模型变更。
+
+2. **迁移脚本检查**：自动生成的迁移脚本可能不完美，需要手动检查和调整：
+   - 检查索引创建/删除
+   - 检查外键约束
+   - 检查默认值设置
+   - 检查字符集和排序规则
+
+3. **生产环境**：
+   - 在生产环境执行迁移前，务必先备份数据库
+   - 在测试环境充分测试迁移脚本
+   - 考虑数据迁移的兼容性
+
+4. **回滚**：如果迁移出现问题，可以使用 `alembic downgrade` 回滚到之前的版本。
+
+## 常见问题
+
+### 1. 迁移脚本检测不到模型变更
+
+**原因**：模型没有被正确导入
+
+**解决**：检查 `alembic/env.py` 中的模型导入，确保所有模型都被导入。
+
+### 2. 迁移执行失败
+
+**原因**：可能是数据库连接问题、权限问题或迁移脚本错误
+
+**解决**：
+- 检查数据库连接配置
+- 检查数据库用户权限
+- 查看错误日志，修复迁移脚本
+
+### 3. 迁移冲突
+
+**原因**：多人同时创建迁移脚本导致版本冲突
+
+**解决**：
+- 使用 `alembic merge` 合并分支
+- 或者手动解决冲突，调整 `down_revision`
+
+## 与手动SQL脚本的关系
+
+项目中的 `backend/migrations/` 目录包含手动SQL脚本，这些脚本用于：
+- 快速初始化数据库（不依赖Alembic）
+- 特定场景的数据库操作
+- 数据迁移脚本
+
+**建议**：优先使用 Alembic 进行数据库结构管理，手动SQL脚本作为补充。
+
+## 示例
+
+### 添加新表
+
+1. 在 `app/models/` 中创建新模型
+2. 运行 `alembic revision --autogenerate -m "添加新表"`
+3. 检查生成的迁移脚本
+4. 运行 `alembic upgrade head`
+
+### 修改现有表
+
+1. 修改模型定义
+2. 运行 `alembic revision --autogenerate -m "修改表结构"`
+3. 检查生成的迁移脚本（可能需要手动调整）
+4. 运行 `alembic upgrade head`