docker-compose下Alembic迁移版本不同步本地报错如何解决

你遇到的报错本质是容器销毁重建后，容器内生成的Alembic迁移版本文件丢失，数据库中存储的迁移版本号无法匹配到本地/新容器中的版本文件，通过Docker挂载卷绑定两个目录即可解决，具体步骤如下：

1. 配置docker-compose挂载映射 #

在docker-compose.yml的FastAPI服务配置下新增alembic目录的挂载规则，示例配置如下：

services:
  # 替换为你自己的FastAPI服务名称
  fastapi-app:
    build: .
    volumes:
      # 前面是本地项目alembic目录的相对路径，后面是容器内alembic目录的绝对路径
      # 请根据你自己的项目路径调整容器内路径，示例为工作目录为/app的情况
      - ./alembic:/app/alembic
      # 其余原有挂载规则保留即可

注意：请确保.dockerignore文件中没有排除alembic目录，避免构建镜像时相关文件被忽略。

2. 修正迁移操作流程 #

配置挂载后所有Alembic操作都通过运行中的容器执行，生成的版本文件会自动同步到本地：

• 生成迁移脚本：执行docker exec -it <你的FastAPI容器名> alembic revision --autogenerate -m "迁移描述"，执行完成后本地alembic/versions目录会自动生成对应的版本文件
• 执行迁移：执行docker exec -it <你的FastAPI容器名> alembic upgrade head

3. 现有报错修复 #

如果已经触发Can't locate revision identified by ...报错，可任选一种方式修复：

• 进入数据库删除alembic_version表，重新执行迁移生成全新的版本记录
• 如果之前容器还未销毁，进入容器将alembic/versions目录下缺失的版本文件手动复制到本地对应目录，再重新执行迁移即可

内容的提问来源于stack exchange，提问作者Mojtaba Arezoomand