CircleCI中Docker Compose镜像已最新仍重建容器问题排查

该异常是Docker Compose v1版本的配置哈希判断逻辑缺陷，叠加部署脚本的执行顺序问题共同导致，具体触发逻辑如下：

• Docker Compose重建容器的判断依据不是镜像是否更新，而是当前计算出的服务配置哈希（由compose文件内容、加载的环境变量、挂载规则、镜像元数据等共同生成），和运行中容器内置标签存储的历史哈希是否一致。只要哈希不匹配，即使镜像提示up-to-date、没有传--force-recreate参数，也会触发容器重建。
• 新提交首次触发部署时，setup.sh会先执行git reset --hard origin/${CIRCLE_BRANCH}将本地代码强制重置为最新版本，此时compose配置文件、.env文件会被还原为仓库原始版本，随后执行的find_replace.sh会对配置做动态替换（如注入镜像标签、部署相关元数据）。此时配置文件的修改时间、脚本隐式注入的动态值（如CI运行ID、提交哈希等非业务配置）、刚执行完docker pull刷新的镜像元数据，都会导致Docker Compose v1误判配置发生变化，触发全量容器重建。
• 重跑任务/手动执行脚本时正常的原因：首次重建完成后，本地配置已经稳定为运行态，容器存储的配置哈希和本地文件完全匹配；重跑时没有新的提交导致git重置后文件无变化、镜像元数据也已经完成同步，重新计算的哈希和运行中容器一致，因此会正常提示up-to-date，不会重建。

首次部署触发异常重建后，立即在服务器上手动执行一次相同的部署命令，会发现不会再次触发重建；通过命令docker inspect <容器名> | grep com.docker.compose.config-hash对比重建前后的容器哈希值，可以看到差异来自非业务配置的元数据项。

• 优先升级到Docker Compose v2，v2版本已经修复了v1中大量并行pull、元数据不同步导致的误重建bug。
• 调整部署脚本执行顺序：在执行docker-compose pull之后、up -d之前，先执行docker-compose config > /dev/null让Compose提前完成配置解析和元数据同步，避免临时状态导致的哈希误判。
• 优化find_replace.sh保证幂等性，不要将CI运行ID、构建时间这类动态变化的非必要参数注入到compose配置或环境变量文件中，确保相同代码版本生成的配置文件内容完全一致。
• 如果不需要动态修改compose配置，可以直接在yaml文件中写死镜像标签，移除find_replace.sh的替换步骤，从根源避免配置被动态修改导致的哈希变化。

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