02 - 安装与配置
第 02 章 — 安装与配置
2.1 平台支持概览
| 平台 | 支持状态 | Rootless | 说明 |
|---|---|---|---|
| Fedora | ✅ 原生 | ✅ | Podman 开发主战场，版本最新 |
| RHEL / CentOS Stream | ✅ 原生 | ✅ | 企业级支持，LTS 版本 |
| Ubuntu / Debian | ✅ 原生 | ✅ | Kubic 项目维护的包 |
| Arch Linux | ✅ 原生 | ✅ | 官方仓库 |
| macOS | ✅ Podman Machine | ✅ | 通过 Linux 虚拟机运行 |
| Windows | ✅ Podman Machine | ✅ | WSL2 后端 |
| Alpine Linux | ✅ | ✅ | 轻量级环境 |
2.2 Linux 安装
2.2.1 Fedora（推荐）
Fedora 是 Podman 的首选开发平台，版本更新最快。
# Fedora 已预装 Podman，直接更新到最新版即可
sudo dnf update podman
# 验证安装
podman --version
# 安装完整工具链（推荐）
sudo dnf install -y podman podman-compose buildah skopeo
# 安装 Rootless 所需依赖
sudo dnf install -y fuse-overlayfs slirp4netns
2.2.2 RHEL 9 / CentOS Stream 9
# RHEL 9 / CentOS Stream 9
sudo dnf install -y podman
# 安装完整工具链
sudo dnf install -y podman-compose buildah skopeo
# 安装 Rootless 所需依赖
sudo dnf install -y fuse-overlayfs slirp4netns
2.2.3 Ubuntu 24.04
# 方法一：使用 Ubuntu 官方仓库（推荐）
sudo apt update
sudo apt install -y podman
# 方法二：使用 Kubic 仓库获取最新版本
# 添加 GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL "https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/xUbuntu_$(lsb_release -rs)/Release.key" \
| gpg --dearmor \
| sudo tee /etc/apt/keyrings/devel_kubic_libcontainers_unstable.gpg > /dev/null
# 添加仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/devel_kubic_libcontainers_unstable.gpg] \
https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/unstable/xUbuntu_$(lsb_release -rs)/ /" \
| sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:unstable.list
sudo apt update
sudo apt install -y podman
# 安装 Rootless 所需依赖
sudo apt install -y fuse-overlayfs slirp4netns uidmap
2.2.4 Debian 12
sudo apt update
sudo apt install -y podman
# Rootless 依赖
sudo apt install -y fuse-overlayfs slirp4netns uidmap
2.2.5 Arch Linux
sudo pacman -S podman buildah skopeo
# Rootless 依赖
sudo pacman -S fuse-overlayfs slirp4netns
2.2.6 Alpine Linux
# Alpine 通常用于 Docker 镜像中嵌套使用
apk add podman
# Rootless 需要额外配置
apk add fuse-overlayfs slirp4netns shadow-uidmap
2.3 macOS 安装
Podman 在 macOS 上通过 Podman Machine 运行一个轻量级 Linux 虚拟机来提供容器功能。
方法一：Homebrew（推荐）
# 安装 Podman
brew install podman
# 初始化虚拟机（首次使用）
podman machine init
# 启动虚拟机
podman machine start
# 验证
podman info
方法二：Podman Desktop
从 podman-desktop.io 下载 GUI 应用，提供类似 Docker Desktop 的图形界面。
macOS 高级配置
# 自定义虚拟机资源（默认 1 CPU、2GB 内存、20GB 磁盘）
podman machine init \
--cpus 4 \
--memory 4096 \
--disk-size 50
# 查看虚拟机状态
podman machine list
# 进入虚拟机 Shell（调试用）
podman machine ssh
# 停止虚拟机
podman machine stop
# 删除虚拟机
podman machine rm
💡 提示
macOS 用户如果遇到网络问题，可以在虚拟机中配置代理：
podman machine ssh # 在虚拟机内编辑 sudo mkdir -p /etc/systemd/system/podman.service.d
2.4 Windows 安装
前置要求
- Windows 10/11 64 位
- WSL2（Windows Subsystem for Linux 2）已启用
- Hyper-V 或 Windows Hypervisor Platform
安装步骤
# 1. 启用 WSL2（管理员 PowerShell）
wsl --install
# 2. 重启系统后，从以下方式安装 Podman：
# 方法一：winget
winget install RedHat.Podman
# 方法二：Chocolatey
choco install podman
# 方法三：Scoop
scoop install podman
# 3. 初始化并启动 Podman Machine
podman machine init
podman machine start
# 4. 验证
podman --version
podman info
WSL2 后端配置
# 查看当前 WSL 版本
wsl --list --verbose
# 确保默认使用 WSL2
wsl --set-default-version 2
# 在 WSL2 内直接安装 Podman（可选方案）
# 进入 WSL2 发行版后按 Ubuntu 安装步骤操作
wsl -d Ubuntu
2.5 安装后配置
2.5.1 Rootless 环境配置（Linux 必做）
# 确认用户 UID 范围已分配
cat /etc/subuid
# 应显示类似：
# username:100000:65536
cat /etc/subgid
# 应显示类似：
# username:100000:65536
# 如果没有，手动添加
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(whoami)
# 验证
podman unshare cat /proc/self/uid_map
# 应显示 UID 映射关系
2.5.2 存储驱动配置
Rootless 模式默认使用 fuse-overlayfs，编辑 ~/.config/containers/storage.conf：
# ~/.config/containers/storage.conf
[storage]
driver = "overlay"
[storage.options.overlay]
mount_program = "/usr/bin/fuse-overlayfs"
# 启用 metacopy（性能优化）
mountopt = "nodev,metacopy=on"
2.5.3 镜像加速器配置（国内用户）
编辑 /etc/containers/registries.conf（全局）或 ~/.config/containers/registries.conf（用户级）：
# ~/.config/containers/registries.conf
# 搜索顺序
[registries.search]
registries = [
'docker.io', # Docker Hub（默认）
'ghcr.io', # GitHub Container Registry
'quay.io', # Red Hat Quay
]
# 不可信仓库黑名单
[registries.block]
registries = ['docker.io/untrusted']
配置 Docker Hub 镜像加速（国内网络优化）：
# /etc/containers/registries.conf.d/mirrors.conf
# 配置 Docker Hub 的镜像站
[[registry]]
prefix = "docker.io"
location = "docker.io"
[[registry.mirror]]
location = "mirror.gcr.io" # Google 镜像（需翻墙）
[[registry.mirror]]
location = "registry.docker-cn.com"
2.5.4 网络配置
# 检查网络后端（Podman 4.0+ 默认使用 Netavark）
podman info | grep networkBackend
# networkBackend: netavark
# 如需切换到 CNI（旧版网络后端）
# 编辑 /etc/containers/containers.conf
[engine]
network_backend = "cni"
2.5.5 containers.conf 全局配置
containers.conf 是 Podman 的核心配置文件，位置：
| 路径 | 作用域 |
|---|---|
/usr/share/containers/containers.conf | 系统默认（不要手动修改） |
/etc/containers/containers.conf | 系统级覆盖 |
~/.config/containers/containers.conf | 用户级覆盖 |
# ~/.config/containers/containers.conf
[containers]
# 默认 DNS 服务器
dns_servers = ["8.8.8.8", "114.114.114.114"]
# 默认日志驱动
log_driver = "journald"
# 默认挂载选项
# volumes = []
[engine]
# 容器运行时（推荐 crun）
runtime = "crun"
# 并发拉取镜像数
num_locks = 2048
# 容器停止超时（秒）
stop_timeout = 10
[machine]
# macOS/Windows 虚拟机配置
cpus = 4
memory = 4096
disk_size = 50
2.6 验证安装
运行以下命令进行全面验证：
# 1. 版本信息
podman --version
# podman version 5.x.x
# 2. 系统信息
podman info | head -30
# 3. Rootless 状态
podman info | grep rootless
# rootless: true
# 4. 运行测试容器
podman run --rm docker.io/library/hello-world
# 5. 检查 UID 映射
podman unshare cat /proc/self/uid_map
# 6. 检查网络后端
podman info | grep -i network
# 7. 检查存储驱动
podman info | grep -i graphDriver
# 8. 列出已下载镜像
podman images
健康检查脚本
#!/bin/bash
# podman-healthcheck.sh
echo "=== Podman 健康检查 ==="
echo -n "版本: "
podman --version
echo -n "Rootless: "
podman info --format '{{.Host.Rootless}}' 2>/dev/null && echo "✅" || echo "❌"
echo -n "运行时: "
podman info --format '{{.Host.OCIRuntime.Name}}' 2>/dev/null
echo -n "存储驱动: "
podman info --format '{{.Store.GraphDriverName}}' 2>/dev/null
echo -n "网络后端: "
podman info --format '{{.Host.NetworkBackend}}' 2>/dev/null
echo -n "测试容器: "
podman run --rm docker.io/library/alpine echo "✅ OK" 2>/dev/null || echo "❌ FAIL"
echo "=== 检查完成 ==="
2.7 常见安装问题
问题 1：cannot open /etc/subuid
Error: cannot open /etc/subuid: No such file or directory
解决：
# 创建文件并添加用户映射
sudo touch /etc/subuid /etc/subgid
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 $(whoami)
问题 2：fuse-overlayfs not found
Error: overlay: can't stat program /usr/bin/fuse-overlayfs
解决：
# Fedora/RHEL
sudo dnf install fuse-overlayfs
# Ubuntu/Debian
sudo apt install fuse-overlayfs
问题 3：Rootless 无法绑定 80 端口
Error: rootlessport cannot expose privileged port 80
解决（三选一）：
# 方法一：使用 setcap（推荐）
sudo setcap cap_net_bind_service=ep /usr/bin/podman
# 方法二：使用 sysctl
sudo sysctl net.ipv4.ip_unprivileged_port_start=80
# 永久生效
echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee /etc/sysctl.d/podman.conf
# 方法三：使用端口转发（非特权端口 → 特权端口）
# iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
问题 4：macOS 虚拟机启动失败
Error: unable to start host networking
解决：
# 重置虚拟机
podman machine stop
podman machine rm
podman machine init
podman machine start
# 如果仍然失败，检查 VPN 软件冲突
# 某些 VPN 会修改路由表影响虚拟机网络
问题 5：镜像拉取超时
Error: reading blob: timeout
解决：
# 配置镜像加速器（见 2.5.3 节）
# 或使用代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
podman pull docker.io/library/alpine
2.8 本章小结
| 步骤 | 内容 |
|---|---|
| 安装 | 根据平台选择对应安装方式 |
| Rootless 配置 | /etc/subuid + /etc/subgid 必须正确 |
| 存储驱动 | Rootless 推荐 fuse-overlayfs |
| 网络后端 | Podman 4.0+ 默认 Netavark |
| 运行时 | 推荐 crun（比 runc 更快） |
| 镜像加速 | 国内用户需配置镜像站 |
下一步
- 👉 第 03 章：基础操作 — 学习容器和镜像的基本操作