Docker Compose --force-recreate 报错 'ContainerConfig' 问题解决

问题描述

在使用 Docker Compose 部署 Redis 服务时，执行带 --force-recreate 参数的重新创建命令出现异常报错：

docker-compose -f docker-compose.prod.yml up -d --force-recreate

输出错误信息：

ERROR: for app_redis_1  'ContainerConfig'
Traceback (most recent call last):
...
KeyError: 'ContainerConfig'
[88001] Failed to execute script docker-compose

异常特征：

1. 使用 docker-compose down + docker-compose up -d 组合命令可正常运行
2. Redis 服务配置简单（如下），无明显配置错误
3. 错误发生在系统更新后，之前功能正常

version: '3.8'
services:
  redis:
    image: redis:latest
    restart: always
    ports:
      - "6379"

根本原因

此问题由 Docker Compose 版本兼容性 导致：

1. 使用旧版 docker-compose 命令（带连字符）操作
2. Docker 更新后 V1 版本存在兼容缺陷
3. --force-recreate 参数触发新版 Docker 引擎的 V1 兼容层异常

解决方案

方法一：使用 Docker Compose V2 命令（推荐）

直接替换旧版命令语法：
将 docker-compose → 改为 docker compose（移除连字符）

# 问题命令（旧版）
docker-compose -f docker-compose.prod.yml up -d --force-recreate

# 修复命令（新版）
docker compose -f docker-compose.prod.yml up -d --force-recreate

优势

• 无需额外安装
• 直接利用内置 V2 版本（Docker 20.10+ 默认包含）
• 完全兼容 Docker 引擎最新功能

方法二：重新安装 Docker Compose V2

若未预装 V2 版本，手动安装流程：

Linux/macOS 手动安装

# 卸载旧版
sudo apt-get remove docker-compose   # Debian/Ubuntu
brew uninstall docker-compose        # macOS

# 下载 V2 二进制文件
sudo curl -SL https://github.com/docker/compose/releases/download/v2.26.1/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

# 授予执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose --version

APT 仓库安装

# 安装官方插件包
sudo apt-get update
sudo apt-get install docker-compose-plugin

# 检查安装
docker compose version

版本冲突注意事项

当同时存在 V1/V2 版本时，docker-compose（带'-'）调用 V1，docker compose（空格）调用 V2。建议统一使用 docker compose 命令避免混淆。

方法三：Ubuntu/Debian 专属方案

# 安装 V2 专用包
sudo apt-get install docker-compose-v2

# 验证命令功能
docker compose version

技术解析

为什么会出现 ContainerConfig 报错？

1. Docker 引擎更新
   2024年后新版 Docker Engine 内部数据结构变更
2. V1 兼容层缺陷
   docker-compose V1 的 merge_volume_bindings 方法无法解析新引擎配置
3. 关键路径故障
   service.py → get_container_data_volumes() 无法获取 ContainerConfig 字段

新旧版本核心差异

特性	Compose V1 (docker-compose)	Compose V2 (docker compose)
架构	Python 独立二进制文件	Go 语言编写，集成到 Docker CLI
维护状态	已弃用（2023年停止更新）	官方维护（持续更新）
--force-recreate	存在兼容问题	完整支持最新引擎特性
启动速度	较慢	提升 3-5 倍

最佳实践建议

1. 统一使用 V2 语法
   所有脚本/文档替换为 docker compose 命令格式

2. 环境一致性管理
   在 Dockerfile 中加入版本验证：

   RUN docker compose version || (echo "需要Docker Compose V2" && exit 1)

3. 容器更新策略优化

   # 安全更新流程
   docker compose down
   docker compose pull     # 拉取新镜像
   docker compose up -d    # 创建新容器

4. 多环境验证
   重要操作前使用 docker compose config 验证配置合法性

长期维护建议

• CI/CD 管道中固定 Docker Compose 版本

docker compose version --short
> v2.26.1

• 定期检查更新：docker compose alpha self-update