Podman 基本使用指南

从安装到日常操作，每一个命令都解释清楚。如果你用过 Docker，大部分命令只需要替换名字。

安装 Podman#

各发行版安装命令

# Fedora / RHEL / AlmaLinux（是否预装取决于镜像与版本）
sudo dnf install podman

# Ubuntu（22.04 及以上）
sudo apt update && sudo apt install -y podman

# Arch Linux
sudo pacman -Syu podman

# openSUSE
sudo zypper install podman

# macOS
brew install podman
podman machine init    # 首次需要创建 Linux VM
podman machine start   # 启动 VM 后才能用 podman 命令

安装后验证：

podman version     # 显示版本信息
podman info        # 显示完整系统信息（内核版本、存储驱动、rootless 状态等）
podman system df   # 查看磁盘使用情况

如果你在 NixOS 上：见第七篇 NixOS 管理实践。

镜像操作#

"镜像"是容器的蓝图。就像程序的安装包。

搜索和拉取镜像

# 搜索镜像（列出可用的 nginx 镜像）
podman search nginx

# 搜索镜像并限制结果数量
podman search nginx --limit 10

# 搜索符合特定条件的镜像（只看官方镜像）
podman search nginx --filter=is-official=true

# 从 Docker Hub 拉取镜像（这里使用完整名称，避免短名解析歧义）
podman pull docker.io/library/nginx:alpine
#           │     └─ 标签（版本），alpine 表示基于 Alpine Linux 的精简版
#           └─────── 镜像名

# 从指定仓库拉取
podman pull docker.io/library/nginx:latest
#           └────────────────────┘ └──┘ └─────┘
#                  仓库地址          镜像   标签
#                                   名

# 一次性拉取并运行
podman run docker.io/library/nginx:alpine

查看和管理镜像

# 列出本机所有镜像
podman images
# 输出列：REPOSITORY（来源） TAG（版本） IMAGE ID（唯一标识） CREATED SIZE

# 只列出指定镜像
podman images nginx

# 查看镜像的详细信息和各层
podman inspect docker.io/library/nginx:alpine

# 查看镜像的修改历史（每一层做了什么）
podman history docker.io/library/nginx:alpine

# 删除镜像
podman rmi docker.io/library/nginx:alpine
# 如果镜像正被某个容器使用，需要加 -f 强制删除
podman rmi -f docker.io/library/nginx:alpine

# 清理所有未使用的镜像（释放磁盘空间）
podman image prune -a
# -a 表示删除所有未使用的镜像；不加 -a 只删除"悬空"镜像（标签为 <none> 的）

构建自己的镜像

# 从当前目录的 Dockerfile 构建镜像
podman build -t myapp:1.0 .
#           └─┘ └─────┘ └─┘
#      给镜像打标签  镜像名:版本  构建上下文路径

# 构建时指定 Dockerfile 路径
podman build -t myapp:1.0 -f ./docker/Dockerfile .

一个最简 Dockerfile 示例（用于理解上面的命令在干什么）：

# 以哪个镜像为基础
FROM docker.io/library/alpine:latest
# 在基础镜像上做什么改动
RUN apk add --no-cache python3
# 把本地文件复制进去
COPY app.py /app/
# 容器启动时执行什么程序
CMD ["python3", "/app/app.py"]

容器操作#

运行容器（核心命令）

# 最简运行
podman run docker.io/library/nginx:alpine

# 后台运行 + 端口映射 + 指定名称
podman run -d --name myweb -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
#         └┘ └────────┘ └───────┘
#    后台运行  给容器取名   把宿主机的 8080 端口映射到容器的 80 端口
#    (detach)

# 运行后自动删除（一次性任务）
podman run --rm docker.io/library/alpine echo "hello, 我只跑一次就消失"

# 交互式运行（进入容器内 shell）
podman run -it docker.io/library/ubuntu bash
#         └┘└┘
#   交互模式  分配虚拟终端，这样才能看到提示符
# (interactive) (tty)

常用 run 参数速查：

参数	作用	示例
`-d`	后台运行	`podman run -d ...`
`--name`	给容器命名	`--name myweb`
`-p`	端口映射	`-p 8080:80` 或 `-p 127.0.0.1:8080:80`
`-v`	挂载目录	`-v /host/path:/container/path`
`--rm`	退出时自动删除容器	`--rm`
`-e`	设置环境变量	`-e DATABASE_URL=postgres://...`
`-it`	交互模式 + 终端	`-it`
`--restart`	重启策略	`--restart=always`

查看容器状态

# 列出正在运行的容器
podman ps

# 列出所有容器（包括已停止的）
podman ps -a

# 输出含义：
# CONTAINER ID  — 容器唯一 ID（可以用前几位缩写）
# IMAGE         — 从哪个镜像启动的
# COMMAND       — 容器里执行的命令
# CREATED       — 什么时候创建的
# STATUS        — 当前状态（Up X minutes / Exited / Created）
# PORTS         — 端口映射情况
# NAMES         — 容器名称（--name 指定的）

管理容器生命周期

# 停止容器（默认停止信号通常是 SIGTERM，也可由镜像/配置指定，超时后强杀）
podman stop myweb

# 立即强杀（发送 SIGKILL，不等待）
podman kill myweb

# 启动已存在的容器（不是新建，是重启之前创建过的）
podman start myweb

# 重启容器
podman restart myweb

# 暂停/恢复容器（暂停期间不消耗 CPU）
podman pause myweb
podman unpause myweb

# 删除已停止的容器
podman rm myweb

# 强制删除（即使容器正在运行）
podman rm -f myweb

# 清理所有已停止的容器
podman container prune

stop vs kill：stop 礼貌地通知程序"请退出"，按配置的停止信号与超时给程序清理机会（默认值依配置与版本）；kill 直接拔电源。

查看容器内部信息

# 查看容器内的输出（日志）
podman logs myweb

# 实时跟踪日志（类似 tail -f）
podman logs -f myweb

# 只显示最近 20 行
podman logs --tail 20 myweb

# 进入正在运行的容器内部
podman exec -it myweb sh
#          └┘└┘ └───┘ └──┘
#    交互 终端  容器名  要执行的命令

# 查看容器内运行的进程
podman top myweb

# 查看容器详细信息（JSON 格式，含 IP 地址、挂载点等）
podman inspect myweb

卷（Volume）：持久化数据#

删除容器会丢失其可写层中的数据；命名卷和 bind mount 的生命周期不同。卷把数据存在宿主机上，可以跨容器共享。

# 创建命名卷
podman volume create mydata

# 列出所有卷
podman volume ls

# 使用卷：把卷挂载到容器的 /data 目录
podman run -d --name db --env-file /path/to/private/postgres.env \
  -v mydata:/var/lib/postgresql/data docker.io/library/postgres:16
#                               └──┬──┘ └──────────┬──────────┘
#                            宿主机卷名      容器内路径

# 也可以直接挂载宿主机普通目录
podman run -v /path/to/project:/app docker.io/library/nginx:alpine
#           └──────┬──────┘ └─┘
#           宿主机绝对路径   容器内路径

# 查看卷详情
podman volume inspect mydata

# 清理未使用的卷
podman volume prune

命名卷 (volume) vs 目录挂载 (bind mount)：

命名卷由 Podman 管理，rootful 通常在 /var/lib/containers/storage/volumes/；rootless 位置由用户 storage 配置决定，用 podman volume inspect 查询，不知道路径也没关系
目录挂载直接指定宿主机路径，适合开发时实时同步代码

网络（Network）：让容器互通#

# 列出所有网络
podman network ls

# 创建自定义网络
podman network create mynet

# 查看网络详情（含接入的容器和 IP）
podman network inspect mynet

# 在指定网络中运行容器
podman run -d --name web --network mynet docker.io/library/nginx:alpine
podman run -d --name db --network mynet --env-file /path/to/private/postgres.env docker.io/library/postgres:16

# 同一网络中的容器可以用容器名互相访问
# 若网络 DNS 已启用，通常可解析容器名；ping 工具/ICMP 权限与应用可达性仍需分别检查

# 删除网络
podman network rm mynet

日常维护命令#

# 查看磁盘使用情况
podman system df      # 总览
podman system df -v   # 详细（每个镜像/容器/卷分别占用多少）

# 一键清理（谨慎！会删除所有未在运行的容器和未使用的镜像）
podman system prune -a

# 查看 Podman 自身日志
podman events    # 实时显示所有容器事件（创建/启动/停止/删除）

# 复制文件：宿主机 → 容器
podman cp /host/file.txt myweb:/container/path/

# 复制文件：容器 → 宿主机
podman cp myweb:/container/path/file.txt /host/dest/

Docker 命令兼容#

常用 CLI 形式相近，但不是完全兼容。对熟悉的基本命令可以使用别名：

# 如果你用过 Docker，直接别名
alias docker=podman

# 此后 docker ps/build 等映射到 Podman；Compose 仍需要外部 provider

但是需要注意：docker 命令本身可能不存在于系统中（如果没装 Docker），所以通常的做法是：

# 安装 podman-docker 包（会创建 docker → podman 的软链接）
# Fedora
sudo dnf install podman-docker
# Ubuntu
sudo apt install podman-docker
# 之后直接敲 docker 命令，实际调用的是 podman

上述安装命令针对可变发行版；NixOS 通过 Nix 模块声明，应用前由管理员检查并授权。数据库示例的 env 文件需在仓库外受限保存并提供 POSTGRES_PASSWORD 等必需值；这里不提供任何有效凭据。prune、rm、rmi -f 会删除资源；先检查使用关系与备份，镜像强制删除可能连带移除依赖容器。普通端口 -p 8080:80 通常绑定全部接口；需要本机访问时显式写 loopback。

参考与延伸

根据技术笔记重新整理，示例使用通用名称。