containerd/nerdctl 常见问题与解决方案指南

containerd/nerdctl 常见问题与解决方案指南

nerdctl contaiNERD CTL - Docker-compatible CLI for containerd, with support for Compose, Rootless, eStargz, OCIcrypt, IPFS, ... 项目地址: https://gitcode.com/gh_mirrors/ne/nerdctl

前言

containerd/nerdctl 作为新一代容器管理工具，为开发者提供了更接近 containerd 原生功能的操作体验。本文将系统性地梳理 nerdctl 使用过程中的常见问题，帮助开发者快速定位和解决问题。

项目定位与差异

与 Docker 的差异

nerdctl 的核心目标是让开发者能够体验 containerd 的前沿功能，这些功能可能尚未集成到 Docker 中。主要差异功能包括：

1. 按需镜像拉取（懒加载）：优化镜像拉取效率
2. 镜像加密/解密：增强镜像安全性
3. 更丰富的容器网络配置：提供更灵活的网络管理

需要注意的是，nerdctl 并非旨在替代 Docker，而是作为 containerd 功能的实验平台。

与 ctr/crictl 的差异

ctr 是 containerd 自带的调试工具，相比 nerdctl 缺少以下关键功能：

• 端口映射 (-p 参数)
• 容器自动重启功能
• 镜像仓库认证集成
• 日志查看功能
• 镜像构建功能
• Compose 支持

crictl 作为 Kubernetes CRI 工具，也有类似的限制。

跨平台支持

macOS 支持方案

通过 Linux 虚拟机实现 macOS 支持，推荐方案：

1. Lima 方案：

brew install lima
limactl start
lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

2. Rancher Desktop 和 colima 也提供了集成支持

Windows 支持方案

• Windows 容器：实验性支持
• Linux 容器：通过 WSL2 实现，Rancher Desktop 提供了封装好的 nerdctl.exe

配置管理

镜像仓库认证

支持两种认证方式：

1. 使用 nerdctl login 命令
2. 直接创建 ~/.docker/config.json 文件

还支持各类认证助手工具，如 docker-credential-ecr-login。

非 HTTPS 仓库配置

使用 --insecure-registry 参数：

nerdctl --insecure-registry run <IMAGE>

CA 证书配置

创建配置文件路径：

• Rootless：~/.config/containerd/certs.d/<HOST:PORT>/hosts.toml
• Rootful：/etc/containerd/certs.d/<HOST:PORT>/hosts.toml

示例配置：

server = "https://192.168.12.34:5000"
[host."https://192.168.12.34:5000"]
  ca = "/path/to/ca.crt"

核心配置项调整

Cgroup 驱动

配置方式：

1. 命令行参数：--cgroup-manager=(cgroupfs|systemd|none)
2. 配置文件：nerdctl.toml 中的 cgroup_manager 属性

默认值策略：

• cgroup v2 主机：systemd
• cgroup v1 rootful 主机：cgroupfs
• cgroup v1 rootless 主机：none

快照驱动

配置方式：

1. 命令行参数：--snapshotter=(overlayfs|native|btrfs|...)
2. 环境变量：$CONTAINERD_SNAPSHOTTER
3. 配置文件：nerdctl.toml

默认值：overlayfs

运行时配置

通过 --runtime 参数指定：

nerdctl run --runtime=<RUNTIME>

可指定：

• containerd 运行时插件名（如 io.containerd.runc.v2）
• runc 兼容二进制路径（如 /usr/local/sbin/runc）

CNI 路径配置

配置方式：

1. 命令行参数：--cni-path=<PATH>
2. 环境变量：$CNI_PATH
3. 配置文件：nerdctl.toml

默认自动检测路径包括：

• ~/.local/libexec/cni
• /usr/local/lib/cni
• /opt/cni/bin 等

Kubernetes 集成

查看 Kubernetes 容器

使用 k8s.io 命名空间：

sudo nerdctl --namespace=k8s.io ps -a

k3s 用户需要额外指定地址：

sudo nerdctl --address=/run/k3s/containerd/containerd.sock --namespace=k8s.io ps -a

构建 Kubernetes 镜像

多节点集群方案：

nerdctl build -t example.com/foo /some-dockerfile-directory
nerdctl push example.com/foo

单节点集群无仓库方案：

nerdctl --namespace k8s.io build -t foo /some-dockerfile-directory

Rootless 模式实践

基础配置

安装与启动：

containerd-rootless-setuptool.sh install
nerdctl run -d --name nginx -p 8080:80 nginx:alpine

常见问题解决

源 IP 传播问题

默认 rootlesskit 端口驱动不传播源 IP，解决方案： 改用 slirp4netns 端口驱动（性能会有所下降）

低端口号限制

设置系统参数：

sudo sysctl net.ipv4.ip_unprivileged_port_start=0

Ping 功能限制

设置系统参数：

sudo sysctl net.ipv4.ping_group_range="0 2147483647"

开机自启动

启用 linger 服务：

sudo loginctl enable-linger $(whoami)

权限错误解决

安装并启动 dbus 用户会话：

sudo apt-get install -y dbus-user-session
systemctl --user start dbus

卸载清理

完整卸载步骤：

containerd-rootless-setuptool.sh uninstall
rootlesskit rm -rf ~/.local/share/containerd ~/.local/share/nerdctl ~/.config/containerd

Buildkit 缓存清理

清理命令：

nerdctl builder prune

缓存位置：

• Rootless：$HOME/.local/share/buildkit/
• Rootful：/var/lib/buildkit/

总结

本文全面梳理了 containerd/nerdctl 使用中的各类问题，从基础配置到高级功能，从本地开发到 Kubernetes 集成，为开发者提供了完整的参考指南。掌握这些问题的解决方案，将帮助您更高效地使用 nerdctl 进行容器管理。

nerdctl contaiNERD CTL - Docker-compatible CLI for containerd, with support for Compose, Rootless, eStargz, OCIcrypt, IPFS, ... 项目地址: https://gitcode.com/gh_mirrors/ne/nerdctl