云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载Buildah 是一款面向 OCI 镜像构建的命令行工具在日常使用中镜像拉取、TLS 校验、buildah run命令执行、无根rootless模式下的存储后端选择等问题常常让开发者困惑。本文以仓库中的 troubleshooting.md 为核心骨架逐条拆解六类高频故障的报错特征、底层成因与可落地的修复方案并结合仓库源码与测试用例补充参数细节与验证依据。读完本文你将能够独立诊断 Buildah 在镜像拉取、推送、运行指令和 rootless 构建中的常见报错并快速给出正确解法。1) No such image基础镜像拉取失败执行buildah pull或buildah build时如果提示某个常见镜像无法拉取最可能的原因是/etc/containers/registries.conf文件缺失或配置错误。此外install.md 中列出的其他必需配置文件如mounts.conf、seccomp.json、policy.json未安装到位也可能引发同类问题。症状$ 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: pinging docker registry returned: Get https://localhost/v2/: dial tcp [::1]:443: connect: connection refused * Error determining manifest MIME type for docker://registry.access.redhat.com/alpine:latest: Error reading manifest latest in registry.access.redhat.com/alpine: unknown: Not Found error building: error creating build container: no such image alpine in registry: image not known注意报错中出现了docker://localhost/alpine:latest和docker://registry.access.redhat.com/alpine:latest两个候选地址这正是 Buildah 在镜像名未携带 registry 前缀时按照registries.conf中unqualified-search-registries列表逐个尝试解析的结果列表里配置了localhost和registry.access.redhat.com而两者要么不可达、要么不存在该镜像最终综合报出no such image。解决方案确认registries.conf文件是否存在详见 containers-registries.conf(5) 手册。该文件通常由containers-common软件包提供缺失时先安装该包。确认unqualified-search-registries选项中的 registry 是否有效且可达。确认请求的镜像是完全限定名fully qualified或者确实存在于某个搜索 registry 中。确认镜像是公开的或者你已登录至少一个包含该私有镜像的搜索 registry。确认 Configuration Files 一节列出的其他必需配置文件均已安装。源码与配置佐证registries.conf的标准搜索路径为/usr/share/containers/registries.conf、/etc/containers/registries.conf和$HOME/.config/containers/registries.conf。Fedoracontainers-common包中的典型配置如下unqualified-search-registries [registry.fedoraproject.org, registry.access.redhat.com, docker.io, quay.io] # # An array of host[:port] registries to try when pulling an unqualified image, in order. # # [[registry]] # # The prefix field is used to choose the relevant [[registry]] TOML table # prefix example.com/foo # # # If true, unencrypted HTTP as well as TLS connections with untrusted # # certificates are allowed. # insecure false # # # If true, pulling images with matching names is forbidden. # blocked false # # # The physical location of the prefix-rooted namespace. # location internal-registry-for-example.com/bar # # # (Possibly-partial) mirrors for the prefix-rooted namespace. # [[registry.mirror]] # location example-mirror-0.local/mirror-for-foo # [[registry.mirror]] # location example-mirror-1.local/mirrors/foo # insecure true # Enforcing mode for short names is default for Fedora 34 and newer short-name-modeenforcing仓库测试也直接验证了这一机制tests/registries.conf.block与tests/registries.conf.hub分别通过调整unqualified-search-registries来模拟镜像被屏蔽与仅从 docker.io 搜索的场景而tests/pull.bats中大量用例使用--registries-conf指向这些测试配置来断言拉取行为。由此可见registries.conf的搜索顺序直接决定了未限定镜像名的解析结果排查时优先检查它是最稳妥的路径。2) http: server gave HTTP response to HTTPS clientTLS 校验与本地 registry执行build,commit,from或push等命令向 registry 通信时Buildah 默认开启 TLS 校验。如果目标 registry 是本地搭建、未启用 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 默认对所有 registry 通信开启 TLS 校验。若目标 registry 不需要认证build,commit,from,pull等命令都会失败除非显式关闭 TLS 校验通过--tls-verifyfalse关闭 TLS 校验。例如buildah push --tls-verifyfalse alpine docker://localhost:5000/myalpine:latest注意强烈不建议与 registry 通信时关闭 TLS 校验。该选项仅适用于本地测试 registry 或可信内网环境生产环境务必保持校验开启。源码与测试佐证在 pkg/cli/common.go 中--tls-verify被定义为默认值为true的布尔开关fs.BoolVar(flags.TLSVerify, tls-verify, true, require HTTPS and verify certificates when accessing the registry)pkg/cli/build.go中也会在构建流程里读取该标志并将结果传递给底层镜像复制逻辑。测试侧同样覆盖了这一行为例如tests/authenticate.bats中使用--tls-verifyfalse --creds ...对自签名证书的本地 registry 推送成功使用--tls-verifytrue对同一自签名 registry 推送时用例明确断言返回码为125失败验证了默认校验开启、自签名证书被拒绝的行为。tests/bud.bats中大量构建用例也都配合--tls-verifyfalse与本地 registry 协同工作。因此在实际排障时可以先确认目标 registry 是否真正支持 HTTPS如果确为 HTTP 服务再考虑用--tls-verifyfalse绕过校验。3)buildah run使用管道或输出重定向失败buildah run执行包含管道|或输出重定向、的命令时常常以command not found一类错误告终。症状以下命令都会导致buildah run无法完成并抛出错误# buildah run $whalecontainer /usr/games/fortune -a | cowsay # buildah run $newcontainer echo daemon off; /etc/nginx/nginx.conf # buildah run $newcontainer echo nginx on Fedora /usr/share/nginx/html/index.html原因在于shell 的管道与重定向符号是在宿主机的 shell 层面解析的而buildah run只会把参数当作单一命令原样交给容器内的运行时执行容器内找不到cowsay等命令或无法理解重定向语义自然报错。解决方案两种修法任选其一改用podman run代替buildah runpodman run对这类场景支持更友好。继续使用buildah run则用单引号包裹整条命令并通过bash -c交给容器内的 shell 解释执行# buildah run $whalecontainer bash -c /usr/games/fortune -a | cowsay # buildah run $newcontainer bash -c echo daemon off; /etc/nginx/nginx.conf # buildah run $newcontainer bash -c echo nginx on Fedora /usr/share/nginx/html/index.html原理补充buildah run的核心实现位于 run_linux.go以及run_common.go、run_unix.go等平台相关文件它通过容器运行时默认runc在容器内执行命令。而bash -c ...的写法把整条带管道的命令作为一个字符串传给容器内的/bin/bash由容器内 shell 完成管道与重定向解析从而规避宿主机 shell 的干预。这与仓库文档 buildah-run.1.md 中对运行指令的说明一致凡是涉及 shell 特性管道、重定向、通配符、环境变量展开的复杂命令都应显式通过bash -c或等价 shell执行。4)buildah push alpine oci:~/myalpine:latest报 lstat 错误当buildah push的目标镜像名中包含波浪号~时会触发 lstat 错误提示文件或目录不存在。症状$ sudo pull alpine $ sudo buildah push alpine oci:~/myalpine:latest lstat /home/myusername/~: no such file or directory成因与解决方案这是 shell 波浪号展开tilde expansion的预期行为~只会在单词开头被 shell 展开出现在路径中间时会被原样当作普通字符传给 Buildah于是它按字面值去查找/home/myusername/~这个路径自然失败。修复方法是用$HOME或完整的绝对路径替换~$ sudo buildah push alpine oci:${HOME}/myalpine:latest注意在oci:这种非 docker 传输格式下myalpine:latest会被解析为本地目录布局myalpine目录 latest标签因此路径中任何未展开的特殊字符都会被直接用于文件系统访问——这正是 lstat 报错的直接来源。同样的规则也适用于dir:、docker-archive:等基于本地路径的传输格式凡是路径含~、$VAR等需要展开的内容都建议在宿主机 shell 中先完成展开再传给 Buildah。5) Rootless 模式下 NFS 文件系统上的构建失败EPERMNFS 在服务端按 UID 强制文件创建权限且不理解用户命名空间user namespace——而这正是 rootless 容器如 rootless Podman / Buildah运行的前提。当容器内的 root 进程例如 YUM尝试创建由其他 UID 拥有的文件时NFS 服务端会拒绝创建。此外文件锁放在 NFS 上同样是问题来源。其他分布式文件系统如 Lustre、Spectrum Scale、General Parallel File System/GPFS在 rootless 模式下同样不受支持因为这些文件系统同样不理解用户命名空间。症状$ buildah build . ERRO[0014] Error while applying layer: ApplyLayer exit status 1 stdout: stderr: open /root/.bash_logout: permission denied error creating build container: Error committing the finished image: error adding layer with blob sha256:a02a4930cb5d36f3290eb84f4bfa30668ef2e9fe3a1fb73ec015fc58b9958b17: ApplyLayer exit status 1 stdout: stderr: open /root/.bash_logout: permission denied解决方案二选一将 containers/storage 的数据目录迁移到非 NFS 共享的路径上如本机磁盘。或者直接以 root 身份运行sudo buildah build。原理说明Buildah 的容器存储由containers/storage库负责其目录默认/var/lib/containers/storage或 rootless 下的~/.local/share/containers/storage必须位于支持用户命名空间语义的文件系统上。NFS 等分布式文件系统在服务端强校验 UID无法映射容器内通过用户命名空间重映射的 UID导致层解压ApplyLayer阶段写文件时被拒绝。这是文件系统与 rootless 模型之间的结构性不兼容单纯调整目录权限无法根治只能更换存储位置或提升运行权限。6) Rootless 模式使用 OverlayFS 构建失败OverlayFS 在解压镜像、创建 whiteout 文件时需要调用mknod而 rootless 用户没有此权限导致构建失败。症状buildah build --storage-driver overlay . STEP 1: FROM docker.io/ubuntu:xenial Getting image source signatures Copying blob edf72af6d627 done Copying blob 3e4f86211d23 done Copying blob 8d3eac894db4 done Copying blob f7277927d38a done Copying config 5e13f8dd4c done Writing manifest to image destination Storing signatures Error: error creating build container: Error committing the finished image: error adding layer with blob sha256:8d3eac894db4dc4154377ad28643dfe6625ff0e54bcfa63e0d04921f1a8ef7f8: Error processing tar file(exit status 1): operation not permitted $ buildah build . ERRO[0014] Error while applying layer: ApplyLayer exit status 1 stdout: stderr: open /root/.bash_logout: permission denied error creating build container: Error committing the finished image: error adding layer with blob sha256:a02a4930cb5d36f3290eb84f4bfa30668ef2e9fe3a1fb73ec015fc58b9958b17: ApplyLayer exit status 1 stdout: stderr: open /root/.bash_logout: permission denied解决方案二选一以特权用户身份完成构建即sudo buildah。安装并配置 fuse-overlayfs为你的 Linux 发行版安装 fuse-overlayfs 软件包在~/.config/containers/storage.conf的[storage.options]段添加mount_program /usr/bin/fuse-overlayfs。源码与配置佐证在 pkg/overlay/overlay_linux.go 中overlay 驱动会优先检查是否配置了 mount helper即 fuse-overlayfs若未指定mount_program则回退到尝试原生 overlay 挂载——而原生 overlay 在 rootless 下正是触发operation not permitted的根源。相关选项键如overlay.mount_program、overlay2.mount_program在 pkg/overlay/overlay.go 中统一注册解析支持通过storage.conf或--storage-opt传入。storage.conf的完整写法示例[storage] driver overlay [storage.options] mount_program /usr/bin/fuse-overlayfs仓库测试也印证了这条修复路径tests/overlay.bats与tests/bud_overlay_leaks.bats会先检查/usr/bin/fuse-overlayfs是否存在若不存在且处于 rootless 模式则直接跳过相关用例tests/chroot.bats则通过overlay.mount_program/usr/bin/fuse-overlayfs构造存储选项来运行测试。可见 fuse-overlayfs 是 rootless 下 overlay 存储的标准配套方案。排障速查表故障现象根因首选修复no such imageregistries.conf缺失/配置错误搜索 registry 不可达安装 containers-common核对unqualified-search-registriesHTTP response to HTTPS client目标 registry 未启用 HTTPSTLS 校验默认开启本地测试环境用--tls-verifyfalse生产禁用buildah run管道/重定向报错宿主机 shell 与容器内命令解析错位改用podman run或bash -c ...包裹lstat 错误~未在路径中间展开用$HOME或绝对路径替代~NFS 上 rootless 构建 EPERMNFS 不理解用户命名空间存储迁移到本地盘或sudo buildahOverlayFS rootless 构建失败rootless 无权调用mknod配置 fuse-overlayfs 或改用特权用户以上六类问题覆盖了 Buildah 日常使用中最常见的故障面从镜像解析与 registry 通信问题 1、2、4到容器内命令执行问题 3再到 rootless 存储后端的文件系统约束问题 5、6。排查时建议遵循先确认配置、再核对命令、最后审视运行环境的顺序多数问题都能在 troubleshooting.md 与 install.md 的范围内找到答案。赞分享云原生【免费下载链接】buildahA tool that facilitates building OCI images.项目地址https://gitcode.com/gh_mirrors/bu/buildah点击查看免费下载相关推荐Podman 与 Buildah 容器镜像构建故障排查指南六大常见错误与修复方案Podman 与 Buildah 容器镜像构建故障排查指南六大常见错误与修复方案 Buildah 是构建 OCI 容器镜像的命令行工具也是 Podman 生容器运行时云原生CLIPostHog 本地 Session Replay 排障实战六大常见故障的症状、诊断与修复PostHog 本地 Session Replay 排障实战六大常见故障的症状、诊断与修复 PostHog 的本地开发环境中Session Replay 数数据分析后端前端数据可视化大数据Zoom AI Services Scribe 常见漂移与故障排查9 类典型问题的根因定位与修复实战Zoom AI Services Scribe 常见漂移与故障排查9 类典型问题的根因定位与修复实战 本篇指南以 Zoom 官方示例仓库中 Scribe 技能AI 技能AI 插件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考