Buildah 常见问题排查指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00518/article/details/148441744

Buildah 常见问题排查指南

buildah A tool that facilitates building OCI images. 项目地址: https://gitcode.com/gh_mirrors/bui/buildah

前言

Buildah 是一个用于构建符合 OCI 标准的容器镜像的工具，它提供了比传统 Docker 构建更灵活的方式。在使用过程中，开发者可能会遇到各种问题。本文将针对 Buildah 常见问题进行详细分析，并提供解决方案。

1. 镜像拉取失败问题

问题现象

当执行 buildah pull 或 buildah build 命令时，系统提示找不到常见的基础镜像（如 alpine）。

$ sudo buildah build -f Dockerfile .
STEP 1: FROM alpine
error creating build container: 2 errors occurred:
* Error determining manifest MIME type for docker://localhost/alpine:latest...
* Error determining manifest MIME type for docker://registry.access.redhat.com/alpine:latest...
error building: error creating build container: no such image "alpine" in registry: image not known

原因分析

这个问题通常是由于以下原因导致：

缺少 /etc/containers/registries.conf 配置文件
配置文件中的 registry 搜索路径配置不正确
尝试拉取的镜像不是完全限定名称（Fully Qualified Name）
私有镜像仓库认证失败

解决方案

检查 /etc/containers/registries.conf 文件是否存在
确保 containers-common 软件包已安装
验证 [registries.search] 部分的 registry 地址是否正确且可达
对于私有镜像，确保已执行登录操作
检查其他必要的配置文件是否已正确安装

2. HTTPS 客户端收到 HTTP 响应问题

问题现象

在执行 buildah push 等操作时，出现 HTTP 和 HTTPS 协议不匹配的错误。

# buildah push alpine docker://localhost:5000/myalpine:latest
Getting image source signatures
Get https://localhost:5000/v2/: http: server gave HTTP response to HTTPS client

原因分析

Buildah 默认启用 TLS 验证，当 registry 未配置 HTTPS 或不需要认证时，会导致此错误。

解决方案

临时解决方案（不推荐生产环境使用）：

buildah push --tls-verify=false alpine docker://localhost:5000/myalpine:latest

推荐解决方案：为 registry 配置正确的 HTTPS 证书和认证

3. 管道和重定向命令失败问题

问题现象

在 buildah run 命令中使用管道 (|) 或重定向 (>>) 时，命令执行失败。

# buildah run $container echo "daemon off;" >> /etc/nginx/nginx.conf

原因分析

管道和重定向是 shell 特性，直接传递给 buildah run 时不会被正确处理。

解决方案

使用 bash -c 包装命令：

buildah run $container bash -c 'echo "daemon off;" >> /etc/nginx/nginx.conf'

或者考虑使用替代工具如 Podman 执行这类命令

4. 路径中包含波浪号(~)的问题

问题现象

在 buildah push 命令中使用包含波浪号 (~) 的路径时，出现文件不存在的错误。

$ sudo buildah push alpine oci:~/myalpine:latest
lstat /home/myusername/~: no such file or directory

原因分析

波浪号仅在单词开头时才会被 shell 扩展为家目录路径。

解决方案

使用 $HOME 替代波浪号：

$ sudo buildah push alpine oci:${HOME}/myalpine:latest

或者使用完整路径：

$ sudo buildah push alpine oci:/home/myusername/myalpine:latest

5. 非 root 用户在 NFS 上构建失败问题

问题现象

在 NFS 存储上以非 root 用户执行构建时，出现权限被拒绝的错误。

$ buildah build .
ERRO[0014] Error while applying layer: ApplyLayer exit status 1 stdout:  stderr: open /root/.bash_logout: permission denied

原因分析

NFS 不支持用户命名空间，无法正确处理不同 UID 的文件创建请求。

解决方案

将容器存储配置到非 NFS 目录
使用 root 权限执行构建：
```
$ sudo buildah build .
```
避免在 NFS、Lustre、GPFS 等分布式文件系统上运行 rootless 容器

6. 非 root 用户使用 OverlayFS 失败问题

问题现象

非 root 用户使用 OverlayFS 存储驱动时，构建过程中出现操作不允许的错误。

buildah build --storage-driver overlay .
Error: error creating build container: Error committing the finished image: error adding layer with blob...

原因分析

OverlayFS 需要 mknod 权限来创建 whiteout 文件，非 root 用户无此权限。

解决方案

使用 root 权限执行构建
配置 fuse-overlayfs：
- 安装 fuse-overlayfs 软件包
- 在 ~/.config/containers/storage.conf 中添加：
```
[storage.options]
mount_program = "/usr/bin/fuse-overlayfs"
```