Docker-Compose构建时Poetry安装失败的排查与解决

错误解释 #

执行docker-compose build时触发的这个RuntimeError，核心是Poetry安装本地依赖commons（版本0.1.0）时哈希校验失败：

• Poetry计算出的commons-0.1.0-py3-none-any.whl包SHA256哈希，和pyproject.toml里记录的已知哈希不一致
• 原因通常是本地commons代码改动后未更新依赖哈希、缓存残留旧包，或是Docker构建上下文里的包文件过时

错误日志原文：

#0 2.217   • Installing pytest (7.2.0)
#0 2.249 
#0 2.249   RuntimeError
#0 2.249 
#0 2.249   Hash for commons (0.1.0 /app/commons/dist/commons-0.1.0-py3-none-any.whl) from archive commons-0.1.0-py3-none-any.whl not found in known hashes (was: sha256:c5c93a9a5d1b69db27187040231b429caaf464f743251b7b26d2e4706e9f912e)
#0 2.249 
#0 2.249   at /usr/local/lib/python3.8/site-packages/poetry/installation/executor.py:754 in _validate_archive_hash
#0 2.267       750│         archive_hash: str = "sha256:" + get_file_hash(archive)
#0 2.267       751│         known_hashes = {f["hash"] for f in package.files}
#0 2.267       752│ 
#0 2.267       753│         if archive_hash not in known_hashes:
#0 2.267     → 754│             raise RuntimeError(
#0 2.267       755│                 f"Hash for {package} from archive {archive.name} not found in"
#0 2.267       756│                 f" known hashes (was: {archive_hash})"
#0 2.267       757│             )
#0 2.267       758│ 
#0 2.267 
------
failed to solve: executor failed running [/bin/sh -c poetry install --with aag-plato]: exit code: 1

解决方案 #

1. 更新依赖哈希（最直接） #

• 进入commons目录，重新构建包：

  cd commons
  poetry build
  

• 回到主项目，手动替换pyproject.toml里commons依赖的哈希值为错误提示中的新哈希：sha256:c5c93a9a5d1b69db27187040231b429caaf464f743251b7b26d2e4706e9f912e
• 或者让Poetry自动同步依赖信息：

  poetry add ./commons
  

2. 清理缓存避免冲突 #

• 清理Docker构建缓存：

  docker builder prune
  

• 清理Poetry本地缓存：

  poetry cache clear --all pypi
  

• 不带缓存重新构建：

  docker-compose build --no-cache
  

3. 检查Docker构建上下文 #

• 确认commons目录未被.dockerignore文件排除，保证构建时能获取到最新的包文件

预防措施 #

• 修改本地依赖（如commons）代码后，必须重新执行poetry build，并通过poetry add ./路径让Poetry自动更新哈希，禁止手动修改pyproject.toml内的哈希值
• 若涉及本地依赖更新，构建Docker镜像时优先使用--no-cache参数，避免缓存旧包
• 可在Dockerfile中添加本地依赖的构建步骤：先拷贝commons源码、执行poetry build，再安装依赖，确保每次构建用最新代码生成的包
• 定期清理Poetry和Docker的缓存，避免残留过期文件引发哈希不匹配

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