Podman 使用教學手冊

項目內容
文件版本3.0
最後更新2026 年 11 月 6 日
適用版本Podman 6.1.4(主要基準);6.2.0-rc1 預覽(標示 🔭);兼述 Podman 5.8.9 維護線與 RHEL 9.8/10.2 隨附的 5.8.2
周邊元件Buildah 1.45.2(隨 Podman 6.1.4;獨立版 1.46.0)、Skopeo 1.24.1、Netavark/Aardvark-dns 2.1.0、crun 1.30.1、Podman Desktop 1.30.5、podman-compose 1.6.0
適用對象後端與前端工程師、系統架構師、SRE/平台工程、DevOps、資安與稽核人員
文件定位企業標準技術白皮書/內部標準教材
使用情境大型企業、金融業(銀行、證券、保險)內部開發環境與 Linux 主機上的容器化服務
文件維護內部技術團隊
Created byEric Cheng

🆕 v3.0 改版說明(2026-11-06):本版以 2026-10-12 發布的 Podman 6.1.4/5.8.9 為基準逐章查證,並預覽 2026-10-26 發布的 6.2.0-rc1。重點如下:

  • 安全修補基準:新增 6.1.1~6.1.4 的 CVE 對照與「最低可接受版本」檢查腳本(10.9)。
  • checkpoint 映像檔:6.1.3/5.8.8 起,podman run 不能再直接執行 checkpoint 映像檔(13.6)。
  • 6.2 預覽:新功能有 kube play --validate/--multiple-pods/--label、Quadlet SetMountsDependency=/Umask=、auto-update --filter、push --platform。
  • RHEL 對照表:補上 RHEL 9.7/10.1 → 5.6.0、9.8/10.2 → 5.8.2。
  • Windows MSI:補上 MSI 靜默安裝的參數。
  • Podman Desktop:更新到 1.30.5。
  • 審查與驗證清單:每章結尾新增「✅ 本章審查與驗證清單」,讓讀者能自行 review 與驗證。

完整更正請見 D.4,查證來源請見 E.2。

標示說明:

標示意思
🆕新增內容
⚠️更正或注意事項
🔭尚未發布正式版(RC)的功能,正式環境不要依賴
✅可以照著執行的驗證步驟

⚠️ v2.0 重大改版說明:本版以 2026 年 6 月發布的 Podman 6.0 與 2026 年 8 月的 6.1 為基準全面改寫。Podman 6 移除了 CNI、iptables、slirp4netns、cgroups v1、BoltDB,也不再支援 Intel Mac 與 Windows 10。v1.0 以 Podman 4.x 時代為基準,部分安裝方式、網路說明、映像檔範例與 EX180 考照內容已不適用,也缺少以 systemd(Quadlet)長期執行服務的做法。專案也已移入 CNCF 組織 podman-container-tools。完整更正清單請見附錄 D:版本紀錄,查證來源請見附錄 E:查證紀錄。

目錄


執行摘要

一句話結論:Podman 是一套不需要常駐 daemon、預設以一般使用者(rootless)執行的 OCI 容器引擎。它的 CLI 與 Docker 高度相容,並原生支援 Pod、Kubernetes YAML 與 systemd(Quadlet)。對重視最小權限、稽核與 Red Hat 生態系的企業來說,是 Linux 主機上執行單機容器服務的首選工具。

本手冊回答的五個問題

#決策問題建議章節
1開發者桌面要用 Docker Desktop 還是 Podman?一般開發用 Podman Desktop 加 podman machine 就足夠;依賴 Docker 專屬擴充功能的團隊再評估第 2 章、第 9 章
2Linux 主機上的單機服務要怎麼長期運行?用 Quadlet 交給 systemd 管理,搭配 AutoUpdate=registry 與 healthcheck;不要再用 podman generate systemd第 8 章
3要不要一律採 rootless?預設 rootless。只有在需要綁定低埠號、特殊裝置或 macvlan 時才評估 rootful,並寫進例外清單第 10 章
4要升級到 Podman 6 嗎?新主機直接用 6.x;既有主機先稽核 CNI、iptables、slirp4netns、cgroups v1、BoltDB 五項依賴,再依序升級第 15 章
5本機開發跟 Kubernetes/OpenShift 怎麼銜接?在本機用 Pod 與 podman kube generate/play 驗證 YAML,正式環境交給 K8s/OpenShift第 7 章
6主機上的 Podman 至少要更新到哪一版?6.x 至少 6.1.3,5.x 至少 5.8.8(修正 CVE-2026-94603 與 CVE-2025-11395);RHEL 以 Red Hat 回補後的套件版本為準10.9

企業導入路線圖

flowchart LR
    P1["階段一<br/>開發者桌面<br/>Podman Desktop"] --> P2["階段二<br/>CI 建置<br/>Buildah/Podman rootless"]
    P2 --> P3["階段三<br/>供應鏈治理<br/>簽章、SBOM、掃描、mirror"]
    P3 --> P4["階段四<br/>主機服務<br/>Quadlet+auto-update"]
    P4 --> P5["階段五<br/>平台銜接<br/>kube YAML → K8s/OpenShift"]

v3.0 的主要變化

  • 🆕 每章結尾新增「✅ 本章審查與驗證清單」:每個項目都附上檢查指令與預期結果,讓審查者不必依賴作者的說明。
  • 🆕 新增 10.9 安全修補版本基準,以及 6.2 預覽內容:7.3.2、8.6.1、8.8.1。
  • ⚠️ 更正 checkpoint 映像檔的用法(6.1.3 起 podman run 不再接受 checkpoint 映像檔)、RHEL 版本對照、周邊工具版本,以及 Windows 大量佈署方式。

v2.0 的主要變化

  • 🆕 新增 Quadlet、Pod 與 Kubernetes 整合、企業 Registry 與供應鏈、監控維運、Docker 遷移與 Podman 6 升級等 7 個章節。
  • ⚠️ 更正網路架構(CNI → Netavark、slirp4netns → pasta)、log 選項、Docker rootless 的比較說法,以及已停止發布的基底映像檔(openjdk:*、node:16)。
  • ⚠️ 考照章節改以現行的 EX188 為主。EX180 已於 2023 年退役,v1.0 裡沒有出處的「題型比例」已經刪除。

1. Podman 概觀與架構

1.1 什麼是 Podman

Podman(Pod Manager)是開源的容器引擎,用來在 Linux 上尋找、執行、建置、分享與部署 OCI 容器與容器映像檔。它最早由 Red Hat 發起,2025 年 1 月以「Podman Container Tools」之名成為 CNCF Sandbox 專案。2026 年 8 月起,Podman、Buildah、Skopeo 的原始碼倉庫都已移到 CNCF 名下的 GitHub 組織 podman-container-tools。

1.1.1 主要特色

特色說明對企業的意義
Daemonless每次 podman 指令直接 fork/exec 出容器,不需要常駐、以 root 執行的背景服務沒有單點故障;也沒有「能存取 daemon socket 就等於 root」的風險
Rootless 優先一般使用者就能執行容器,透過 user namespace 把容器內的 root 對應到主機上的非特權 UID符合最小權限原則,容器逃逸的衝擊範圍較小
原生 Pod支援與 Kubernetes 相同概念的 Pod(多容器共享 network/IPC namespace)本機就能模擬 K8s 的部署單位
Kubernetes YAMLpodman kube generate 與 podman kube play 可雙向轉換開發到平台的銜接成本低
systemd 整合(Quadlet)用宣告式的 .container、.pod 等檔案,由 systemd 管理容器的生命週期單機服務不需要額外的編排工具
Docker 相容CLI 幾乎一對一,另提供相容於 Docker Engine API(v1.44)的 REST socket既有腳本、docker-compose、Testcontainers 可以沿用
OCI 標準映像檔、執行期、發佈規格都遵循 OCI不會被單一廠商綁住

1.1.2 適用場景

graph TD
    A[Podman 適用場景] --> B[開發者桌面]
    A --> C[CI/CD 建置]
    A --> D[Linux 主機單機服務]
    A --> E[邊緣與地端環境]
    A --> F[Kubernetes 前置驗證]

    B --> B1[Podman Desktop]
    B --> B2[Compose 開發環境]
    C --> C1[rootless 建置映像檔]
    C --> C2[簽章與推送]
    D --> D1[Quadlet+systemd]
    D --> D2[auto-update]
    E --> E1[離線部署 air-gapped]
    E --> E2[bootc 映像式作業系統]
    F --> F1[kube play 驗證 YAML]

不適合的場景:需要跨多台主機排程、自動擴縮、服務網格的工作負載,應交給 Kubernetes/OpenShift。Podman 定位在「單一主機」與「開發者本機」。

1.2 架構與元件

1.2.1 Daemonless 執行模型

graph LR
    subgraph Docker
        DC[docker CLI] -->|REST API| DD[dockerd<br/>root daemon]
        DD --> CT[containerd]
        CT --> SH[containerd-shim]
        SH --> R1[runc]
    end
    subgraph Podman
        PC[podman CLI<br/>libpod] -->|fork/exec| CM[conmon<br/>每個容器一個監控程序]
        CM --> R2[crun / runc]
        PC -.-> NV[netavark<br/>aardvark-dns]
        PC -.-> PS[pasta<br/>rootless 網路]
    end
  • podman 指令本身就是 libpod 函式庫的前端。狀態保存在本機資料庫(SQLite)與 containers/storage 裡,不需要 daemon。
  • 每個容器各有一個 conmon 監控程序,負責保持 TTY、收集日誌、記錄結束碼。podman 指令結束後,容器仍會繼續執行。
  • 需要 REST API 時(例如 docker-compose、Podman Desktop、Testcontainers),可以用 socket activation 啟動 podman system service(podman.socket)。這個服務是按需啟動的,不是常駐 daemon。

1.2.2 元件一覽

元件角色備註
libpod容器、Pod、Volume、網路的生命週期管理Podman 的核心函式庫
conmon容器監控程序每個容器一個
crun/runcOCI runtime,實際建立 namespace 與 cgroupRHEL/Fedora 預設 crun(C 實作,啟動快、記憶體用量低)
containers/storage映像檔層與容器檔案系統預設 overlay driver
containers/image拉取、推送、簽章驗證與 Skopeo 共用
Netavark網路設定(bridge、macvlan、ipvlan),用 nftables 設定防火牆規則Podman 6 起是唯一的網路後端
Aardvark-dns自訂網路內的容器名稱解析與 Netavark 搭配
pasta(passt 專案)rootless 容器的使用者空間網路5.0 起為預設;6.0 起取代已移除的 slirp4netns
Buildah建置映像檔(podman build 內部就是用 Buildah)也可以單獨在 CI 裡使用
Skopeo在 registry 之間檢視、複製、同步映像檔,不需要先拉到本機離線環境必備
Quadletsystemd generator,把 .container 等檔案轉成 service unit4.4 起內建
Podman Desktop跨平台 GUI,可管理 Podman、Kind、Minikube、OpenShift Local獨立專案,版本號另計

1.2.3 OCI 規範

Open Container Initiative 定義了三份規格,Podman 全部遵循:

規格目前版本內容Podman 對應
Runtime Specificationv1.3.0(2025-11)容器的設定(config.json)與生命週期crun/runc
Image Specificationv1.1.1(2025-03)映像檔 manifest、config、layer 的格式;v1.1 起有 artifactType 與 subject(referrers)containers/image、Buildah
Distribution Specificationv1.1.1(2025-01)registry 的 HTTP API;v1.1 起有 Referrers APIpush/pull、podman artifact、sigstore 附件

🆕 v3.0 新增:image-spec 與 distribution-spec v1.1 的 subject/Referrers API,讓簽章、SBOM 可以「掛在」映像檔上,不必另外取 tag。Podman 的 podman manifest add --artifact --subject 用的就是這個機制。要確認公司的 registry 是否支援 Referrers API,可以呼叫 GET /v2/<repo>/referrers/<digest>:回傳 200 和一份 OCI image index 表示支援;回傳 404 表示不支援,這時 client 會改用 tag 命名的備援方式(sha256-<digest>)。

OCI 映像檔也可以用來承載非容器內容,例如 AI 模型、設定檔、SBOM。這類內容在 Podman 裡稱為 OCI artifact,由 podman artifact 系列指令管理(5.4 起提供預覽版,5.6 起穩定),詳見第 11 章。

1.3 Podman 與 Docker 的差異

面向PodmanDocker Engine
架構無 daemon,fork/execclient/server,由 dockerd 管理所有容器
預設權限預設 rootless預設 rootful;另有 Rootless mode 可選(需另外安裝設定)
Pod原生支援不支援(Compose 以 service 為單位)
systemdQuadlet 原生整合,容器即 service由 dockerd 的 restart policy 管理
Kubernetes YAMLkube generate 與 kube play無原生支援
API相容 Docker API(v1.44),另有 libpod APIDocker Engine API
Composepodman compose 呼叫外部 provider(docker-compose 或 podman-compose)內建 Compose v2
建置Buildah(相容 Dockerfile/Containerfile)BuildKit
映像檔名稱建議使用完整名稱,短名稱依 registries.conf 解析短名稱預設指向 Docker Hub
桌面授權Podman Desktop 採 Apache-2.0Docker Desktop 對一定規模以上的企業需付費訂閱

⚠️ v2.0 更正:v1.0 寫「Docker 需要 root 權限」並不精確。Docker 從 20.10 起就有正式的 Rootless mode,只是預設仍以 root 執行 daemon。兩者真正的差別在於「預設值」與「是否有常駐 daemon」。

1.3.1 指令對比範例

# Docker 指令
docker run -d --name web -p 8080:80 nginx
docker ps
docker logs web

# Podman 指令(語法相同;建議寫完整映像檔名稱)
podman run -d --name web -p 8080:80 docker.io/library/nginx:stable
podman ps
podman logs web

# 讓既有腳本不用修改:安裝 podman-docker 套件,或設定 alias
alias docker=podman

1.3.2 主要的行為差異

情境DockerPodman處理方式
短名稱 nginx自動從 Docker Hub 拉取依 unqualified-search-registries 搜尋;short-name-mode="enforcing" 時,名稱有歧義會詢問或失敗一律寫完整名稱,例如 docker.io/library/nginx
綁定 1024 以下的埠root daemon 可以直接綁定rootless 預設不行改用高埠號,或調整 net.ipv4.ip_unprivileged_port_start
Volume 權限以 root 寫入以 user namespace 對應後的 UID 寫入用 :U、--userns=keep-id 或 podman unshare chown
SELinux視設定而定RHEL/Fedora 預設強制bind mount 加上 :z/:Z
restart policydaemon 重啟時會自動拉起容器沒有 daemon用 Quadlet,或啟用 podman-restart.service

1.4 版本演進

1.4.1 近期版本時間軸

版本發布時間重點
4.42023-02推出 Quadlet
4.72023-09新增 podman compose;podman generate systemd 標示為棄用(不會移除,但不再加新功能)
4.82023-11新安裝預設改用 SQLite 資料庫
5.02024-03rootless 網路預設改為 pasta;podman machine 重寫(macOS 改用 applehv);Quadlet 支援 .pod 與範本
5.22024-08macOS 可使用 libkrun(支援 GPU);Quadlet 支援 .build
5.3–5.52024-11~2025-05podman update 可修改 healthcheck;podman artifact 預覽;podman machine cp
5.62025-08新增 podman quadlet install/list/print/rm;podman artifact 標為穩定
5.72025-11遠端 API 支援 TLS/mTLS;Quadlet .artifact;podman kube play 可一次處理多個檔案
5.82026-02BoltDB 自動遷移至 SQLite;5.x 最後一個次版本,目前持續發布修補版(最新 5.8.9:2026-10-12)
6.02026-06-24移除 CNI、iptables、slirp4netns、cgroups v1、BoltDB、Intel Mac、Windows 10;預設啟用 network isolation;Quadlet 安裝結構改版;podman machine 可跨 provider 操作
6.12026-08-12podman volume rename、podman machine restart、Quadlet ImageVolume=;最新修補版 6.1.4(2026-10-12)
🔭 6.22026-10-26(rc1)kube play --validate/--multiple-pods/--label;Quadlet SetMountsDependency=、Umask=;push --platform;auto-update --filter 與遠端支援;kube play 的 seccomp 註解標為棄用(7.0 移除)

1.4.2 6.1.x/5.8.x 修補版重點

🆕 v3.0 新增:修補版也可能有 breaking change,升級前請先看這張表。

修補版(發布日)類型內容對企業的影響
6.1.1(2026-09-02)安全CVE-2026-17106:惡意 tar 透過連結寫出解壓目錄;修正 WSL 上 IPv4/IPv6 埠號轉送使用 podman machine(WSL)的開發者要升級
6.1.2/5.8.7(2026-09-16)安全CVE-2025-11395:podman load 匯入特製的 layer tar,或 podman volume import 匯入特製的 symlink,可以覆寫主機檔案會匯入外部 tar 的離線環境與備份還原流程必須升級
6.1.3/5.8.8(2026-09-29)安全+breakingCVE-2026-94603:podman run 執行 checkpoint 映像檔時會停用所有沙箱。修正方式是移除 podman run 對 checkpoint 映像檔的支援改用 podman container restore,見 13.6
6.1.4/5.8.9(2026-10-12)修正gvproxy 0.9.0(CVE-2026-107935);修正 WSL 3 下無法運作;Buildah 1.45.2podman machine 使用者要升級

📌 年月依 GitHub Releases 與官方部落格整理;精確的查證紀錄見附錄 E。

1.4.3 Podman 6 對企業的影響

移除/變更項目受影響的對象替代方案
CNI 網路在 /etc/cni/net.d 自訂網路的舊主機Netavark(4.0 起的預設)
iptables仍使用 iptables-legacy 的主機nftables
slirp4netns明確指定 --network slirp4netns 的腳本pasta
cgroups v1RHEL 8 或改過開機參數的主機改用 cgroups v2(RHEL 9/10 預設)
BoltDB早期由 4.x 升級上來的主機啟動時自動遷移到 SQLite;建議升級前先備份
Intel Mac、Windows 10舊的開發者筆電維持 5.8.x,或更換設備
volume prune 行為自動化清理腳本預設只清匿名 volume;要清全部請加 --all
network isolation 預設開啟依賴不同網路之間可互通的環境改用同一個網路,或明確把容器接到多個網路

詳細的升級步驟見第 15 章。

1.5 生態系工具

工具用途目前版本(2026-11)
Podman DesktopGUI;管理容器、Pod、映像檔、Kubernetes context、擴充功能1.30.5(穩定版,內建 Podman 6.1.4/5.8.9)
Buildah細部控制映像檔建置,適合 CI1.46.0(Podman 6.1.4 內建的是 1.45.2)
Skopeo在 registry 之間檢視、複製、同步映像檔,也可處理簽章1.24.1
podman-compose以 Python 實作的 Compose 規格1.6.0
prometheus-podman-exporter匯出 Prometheus 指標2.0.0
bootc以容器映像檔交付整個作業系統(image mode)與 RHEL image mode 搭配

1.6 💡 本章實務建議

  1. 把 Podman 定位為「單機容器引擎」:跨主機的排程交給 Kubernetes/OpenShift,不要自己用腳本拼湊叢集。
  2. 統一版本基準:開發者桌面、CI runner、正式主機的 Podman 主版本要一致;跨 5.x 與 6.x 混用時,要特別注意網路與 volume prune 的差異。
  3. 一律寫完整映像檔名稱:可以避開短名稱解析的歧義,也能防範 typosquatting。
  4. 引用官方文件時使用新網址:GitHub 倉庫已移到 podman-container-tools,舊的 containers/podman 網址目前會重新導向,但文件與腳本裡應該更新。

1.7 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1沒有常駐 daemonps -ef | grep -c '[p]odman system service'0(除非刻意啟用 socket)
2版本在公司基準以上podman --version6.1.3 以上或 5.8.8 以上(見 10.9)
3主要元件符合 Podman 6 的要求podman info --format '{{.Host.OCIRuntime.Name}} {{.Host.NetworkBackend}} {{.Host.DatabaseBackend}}'crun netavark sqlite
4文件與腳本已改用新的倉庫網址grep -rn 'github.com/containers/podman' docs/ scripts/沒有結果

2. 安裝與環境設定

2.1 平台支援矩陣

平台執行方式Podman 6.x備註
RHEL 9/10原生尚未提供;9.8/10.2 隨附 5.8.2(見 2.2.1)由 Container Tools AppStream 滾動更新,每年最多四次
Fedora原生Fedora 45 起隨附 6.x新功能最早在這裡出現
Ubuntu原生官方套件庫尚未提供 6.x(26.04 LTS 隨附 5.7.0,24.04 LTS 隨附 4.9.3)版本落後,見 2.2.3
Debian原生experimental 已有 6.1.1;13(trixie)隨附 5.4.2同上
Windows 11podman machine(WSL2 或 Hyper-V)支援6.0 起不支援 Windows 10
macOS(Apple Silicon)podman machine(libkrun 或 applehv)支援6.0 起不支援 Intel Mac

🆕 v2.0 新增:舊筆電(Windows 10、Intel Mac)只能留在 5.8.x。這一點要列入 IT 資產盤點。

2.2 Linux 安裝

2.2.1 RHEL 9/10

# 只安裝 Podman
sudo dnf -y install podman

# 或安裝完整的 Container Tools(podman、buildah、skopeo、crun、netavark 等)
sudo dnf -y install container-tools

# 確認版本與執行環境
podman version
podman info --format '{{.Host.CgroupsVersion}} {{.Host.NetworkBackend}} {{.Store.GraphDriverName}}'
# 預期輸出:v2 netavark overlay

RHEL 9 與 10 的 Container Tools 以單一的滾動 Application Stream 提供,每年最多更新四次。每個 RHEL 次版本發布後的前三個月版本固定,之後在 EUS 期間只回補安全修正。所以同樣是「RHEL 10」,不同次版本的 Podman 版本也不同,部署前要用 podman version 確認。

🆕 v3.0 新增:RHEL 次版本與 Podman 版本對照

RHEL 次版本隨附 PodmanBuildah/Skopeo備註
9.55.2.2—
9.6/10.05.4.0—
9.7/10.15.6.0Buildah 1.41.0、Skopeo 1.20.0有 podman quadlet 管理指令
9.8/10.2(2026-05)5.8.2—Quadlet .container 支援 AppArmor;podman update --ulimit;Sequoia-PGP 簽章後端

⚠️ 上表依 Red Hat 的 Jira 與 Release Notes 整理,並以社群維護的對照表交叉核對(見 E.2)。RHEL 會把上游的安全修正回補到同一個版本號,所以 RHEL 上的 5.8.2 不等於上游的 5.8.2。要判斷有沒有修補某個 CVE,請查 RHSA 公告或 rpm -q --changelog podman,不要只看版本號。

✅ 驗證方式:

cat /etc/redhat-release                       # 例:Red Hat Enterprise Linux release 10.2
rpm -q podman buildah skopeo                  # 例:podman-5.8.2-x.el10_2
rpm -q --changelog podman | grep -m3 CVE-     # 確認 Red Hat 已回補的 CVE

2.2.2 Fedora

sudo dnf -y install podman

# 想先試用下一版(不建議在正式環境使用)
sudo dnf -y --enablerepo=updates-testing upgrade podman

2.2.3 Ubuntu/Debian

sudo apt-get update
sudo apt-get -y install podman

# 視需要安裝
sudo apt-get -y install podman-compose   # Compose 規格實作
sudo apt-get -y install podman-docker    # 提供 docker 指令的相容包裝

⚠️ 版本落差提醒:Ubuntu 與 Debian 的 Podman 版本明顯落後上游(例如 Ubuntu 24.04 LTS 仍是 4.9.3)。企業做法建議如下:

  • 開發者桌面若需要新功能(Quadlet 管理指令、podman artifact),改用 Fedora、RHEL,或 Windows/macOS 的 podman machine。
  • 正式主機優先使用 RHEL 或其衍生版本,以取得有支援的版本。
  • 不要在正式環境使用 Copr 或第三方靜態建置版本,否則無法取得安全更新。

2.2.4 其他發行版

發行版指令
Alpinesudo apk add podman
Arch Linuxsudo pacman -S podman
openSUSEsudo zypper install podman

2.2.5 Rootless 前置條件

# 1. 確認使用者有 subordinate UID/GID 範圍(通常建立帳號時會自動加入)
grep "^$(whoami):" /etc/subuid /etc/subgid
# 例:alice:524288:65536

# 2. 若沒有,由管理員新增
sudo usermod --add-subuids 524288-589823 --add-subgids 524288-589823 alice

# 3. 修改 subuid 後,讓 Podman 重新套用設定
podman system migrate

# 4. 確認 cgroups v2(Podman 6 必要;Quadlet 也需要)
podman info --format '{{.Host.CgroupsVersion}}'

# 5. 讓使用者登出後,rootless 服務仍能繼續執行(Quadlet 服務需要)
sudo loginctl enable-linger alice

2.3 Windows 安裝

2.3.1 安裝方式

  1. 確認是 Windows 11,並且已啟用 WSL2(wsl --install);若要使用 Hyper-V provider,需要專業版或企業版。

  2. 從 GitHub Releases 下載 podman-installer-windows-amd64.msi(或 arm64 版),或使用 winget:

    # 安裝 Podman CLI
    winget install RedHat.Podman
    
    # 安裝 Podman Desktop(GUI,選用)
    winget install RedHat.Podman-Desktop
  3. 安裝程式可以選擇 VM provider(WSL2 或 Hyper-V),也可以選擇安裝範圍:使用者範圍(預設,不需要管理員權限,裝在 %LOCALAPPDATA%\Programs\Podman)或電腦範圍(需要管理員權限,裝在 %PROGRAMFILES%\Podman)。安裝程式不會自動安裝 WSL,要先執行 wsl --install。

2.3.2 🆕 大量佈署:MSI 靜默安裝

🆕 v3.0 新增(E.1 #8 已結案):參數名稱取自上游 contrib/win-installer 的 WiX 定義與安裝測試腳本(v6.1.4)。

MSI 屬性值作用
MACHINE_PROVIDERwsl(預設)或 hyperv寫入 99-podman-machine-provider.conf,決定新建 VM 預設使用的 provider
ALLUSERS=1—電腦範圍安裝(需要管理員)
MSIINSTALLPERUSER=1—使用者範圍安裝
SKIP_CONFIG_FILE_CREATION0(預設)或 1設為 1 時不產生 provider 設定檔,改由公司自己派送 containers.conf
# 電腦範圍、指定 Hyper-V,並保留安裝紀錄(以系統管理員身分執行)
msiexec /package podman-installer-windows-amd64.msi /quiet /l*v C:\Temp\podman-msi.log `
  ALLUSERS=1 MACHINE_PROVIDER=hyperv

# 移除
msiexec /uninstall podman-installer-windows-amd64.msi /quiet

✅ 驗證方式:

podman --version                                                   # 預期:podman version 6.1.4
Get-Content "$env:ProgramData\containers\containers.conf.d\99-podman-machine-provider.conf"
# 預期內容含有:provider = "hyperv"
Select-String -Path C:\Temp\podman-msi.log -Pattern 'Installation success|completed successfully'

⚠️ 安裝新版 MSI 前,必須先移除舊架構(5.7.0 以前的 setup.exe bundle 安裝程式)安裝的 Podman。移除後容器、映像檔與 VM 都會保留。詳細說明見官方 Podman for Windows 指南。

2.3.3 建立與啟動虛擬機

# 建立預設 VM(podman-machine-default)並立即啟動
podman machine init --now

# 指定資源(CPU 數、記憶體 MiB、磁碟 GiB)
podman machine init --cpus 4 --memory 8192 --disk-size 100 --now dev-vm

# 驗證
podman info
podman run --rm quay.io/podman/hello

2.3.4 WSL2 與 Hyper-V 的選擇

項目WSL2(預設)Hyper-V
VM 映像檔以 Fedora 為基礎的客製映像檔Fedora CoreOS 為基礎的 machine-os
建立 VM一般使用者即可需要系統管理員權限;6.0 起啟動/停止不再需要
更新 VM 作業系統podman machine ssh dnf updatepodman machine os update(6.0 新增)
從 Windows 轉送埠號6.1 起需要 force_port_listen,新建的 VM 會自動設定原生支援
企業管理受 WSL 政策影響管理員可以用 podman system hyperv-prep 預先準備主機,讓一般使用者建立 VM

🆕 v2.0 新增:6.0 起所有 podman machine 指令都能操作任何 provider 的 VM。在設定檔裡指定的 provider 只決定「新建 VM 預設用哪一個」,建立時也可以用 podman machine init --provider hyperv 覆寫。

2.4 macOS 安裝

# 建議:從 podman.io 或 GitHub Releases 下載官方安裝程式 podman-installer-macos-arm64.pkg
# Homebrew 版本由社群維護,官方不保證穩定性
brew install podman   # 選用

podman machine init --now
podman info
Provider說明
libkrun(6.0 起預設)可以把 GPU 帶進 VM,適合本機 AI 推論
applehvApple Virtualization.framework,5.x 的預設

Apple Silicon 預設啟用 Rosetta 2,可以直接執行 x86_64 映像檔(效能會下降)。

2.5 podman machine 生命週期管理

podman machine list                     # 列出所有 VM(6.0 起包含所有 provider)
podman machine start / stop [name]
podman machine restart [name]           # 6.1 新增
podman machine ssh [name]               # 進入 VM
podman machine inspect [name]
podman machine set --cpus 6 --memory 12288 [name]   # VM 必須先停止
podman machine set --rootful [name]     # 切換成 rootful 模式
podman machine cp ./file.txt podman-machine-default:/tmp/   # 5.5 新增
podman machine os update                # 更新 VM 作業系統(6.0 新增;WSL 不支援)
podman machine rm [name]
podman machine reset                    # 刪除所有 VM 與相關設定

主機目錄掛載:macOS 預設會把 /Users、/private、/var/folders 掛載到 VM 裡;可以用 podman machine init -v <host>:<vm> 自訂。WSL 會自動把所有磁碟掛在 /mnt,所以 --volume 對 WSL 沒有作用。

⚠️ 注意:6.0 起,Linux 主機上的 podman machine 改由 systemd 掛載主機目錄。5.x 建立的 Linux VM 掛載會失效,必須重建。

2.6 Podman Desktop

Podman Desktop 是跨平台的 GUI,目前穩定版為 1.30.5(2026-10-13),內建 Podman 6.1.4(Windows 11、Apple Silicon)與 5.8.9(舊平台)。主要功能:

  • 以圖形介面管理容器、Pod、映像檔、Volume,並檢視日誌、進入終端機。1.30 起可以一次選取多個容器並停止。
  • 建立與管理 podman machine,並提供 Docker 相容 socket 的設定精靈。1.30 起,每個 Docker context 都會顯示成獨立的容器連線。
  • 整合 Kind、Minikube、OpenShift Local、Developer Sandbox,可以一鍵把 Pod 部署到 Kubernetes。
  • 可安裝擴充功能(例如 AI Lab、bootc、Red Hat 帳號登入)。
  • 偵測到 CI 環境時會自動關閉遙測(1.30)。
  • Red Hat 另提供 Red Hat build of Podman Desktop,RHEL 9/10 可以從 Extensions 套件庫安裝。

2.6.1 🆕 企業管理設定(managed configuration)

🆕 v3.0 新增:v2.0 只寫了「企業可以用設定檔鎖定選項」,沒有說明怎麼做。

Podman Desktop 會讀取三個檔案:

檔案誰可以修改作用
settings.json使用者使用者在 UI 中設定的值
default-settings.json管理員預設值;啟動時只複製使用者還沒設定的項目
locked.json管理員列出要鎖定的 key;鎖定的 key 一律使用 default-settings.json 的值,UI 會顯示鎖頭
平台管理員檔案目錄
Windows%PROGRAMDATA%\Podman Desktop\
macOS/Library/Application Support/io.podman_desktop.PodmanDesktop/
Linux/usr/share/podman-desktop/

範例:強制使用公司 proxy,並關閉遙測。

{
  "proxy.http": "http://proxy.corp.example:8080",
  "telemetry.enabled": false
}

上面是 default-settings.json;下面是 locked.json:

{
  "locked": ["proxy.http", "telemetry.enabled"]
}

✅ 驗證方式:

  1. 把兩個檔案派送到上表的目錄,然後重新啟動 Podman Desktop。
  2. 到「Settings → Proxy」,確認欄位有鎖頭,而且無法修改。
  3. 在使用者的 settings.json 手動改成其他值,重新啟動後,UI 仍然顯示公司的值。代表鎖定生效。

2.7 設定檔體系

2.7.1 主要設定檔

檔案用途系統路徑使用者路徑
containers.conf引擎預設值(runtime、網路、日誌、machine 等)/etc/containers/、/usr/share/containers/~/.config/containers/
registries.confregistry 搜尋清單、mirror、封鎖、短名稱策略/etc/containers/~/.config/containers/
storage.confstorage driver 與路徑/etc/containers/~/.config/containers/
policy.json映像檔信任與簽章驗證策略/etc/containers/~/.config/containers/
auth.jsonregistry 登入憑證/run/containers/0/(root)$XDG_RUNTIME_DIR/containers/

儲存位置:rootful 為 /var/lib/containers/storage,rootless 為 ~/.local/share/containers/storage。

2.7.2 Podman 6 的設定檔解析規則

⚠️ v2.0 更正:Podman 6 大幅改寫了設定檔的解析邏輯,containers.conf、storage.conf、registries.conf 現在採用同一套規則。

  1. 主檔只取一個:依序尋找 $XDG_CONFIG_HOME/containers/<name>.conf → /etc/containers/<name>.conf → /usr/share/containers/<name>.conf,找到第一個就停止(5.x 會把所有檔案合併)。
  2. Drop-in 目錄全部載入:包含 <name>.conf.d/,以及依身分區分的 <name>.rootful.conf.d/、<name>.rootless.conf.d/、<name>.rootless.conf.d/<UID>/(分別位於 /usr/share/containers/、/etc/containers/),最後是 $XDG_CONFIG_HOME/containers/<name>.conf.d/。同一目錄內依檔名字典序載入,後面的覆蓋前面的。
  3. 陣列可以附加:field = ["value", {append=true}] 會附加到既有的值,不會整個取代。
  4. 已移除的舊做法:containers.rootless.conf 主檔、registries.conf 的 V1 格式;storage.conf 的 rootless_storage_path 已經棄用。
  5. 環境變數:CONTAINERS_CONF 只讀取指定的檔案;CONTAINERS_CONF_OVERRIDE 在正常解析完成後再疊加指定的檔案(適合測試)。

企業建議:公司的標準設定放在 /etc/containers/containers.conf.d/10-corp.conf 這類 drop-in 檔。這樣發行版在 /usr/share 的預設值與使用者的個人設定可以並存,升級時也不會被覆蓋。

2.7.3 企業標準 containers.conf 範例

# /etc/containers/containers.conf.d/10-corp.conf
[containers]
# 預設時區與日誌
tz = "Asia/Taipei"
log_driver = "journald"
# 每個容器的程序數上限(預設 1024)
pids_limit = 2048

[engine]
# Compose provider 的優先順序
compose_providers = ["/usr/bin/podman-compose", {append=true}]
compose_warning_logs = false
events_logger = "journald"

[network]
# 預設網路 podman 的子網路(預設 10.88.0.0/16),避開公司內網網段
default_subnet = "10.89.0.0/24"
# 新建網路自動配置子網路時使用的位址池
default_subnet_pools = [
  {"base" = "10.90.0.0/16", "size" = 24},
]

📌 欄位的完整說明請見 man containers.conf。default_subnet 與 default_subnet_pools 要依公司的網段規劃調整,避免與 VPN 或內網衝突。no-new-privileges 等安全選項沒有對應的 containers.conf 欄位,要在執行時或 Quadlet 裡設定(見第 10 章)。

2.8 企業網路環境:Proxy、自簽 CA 與內部 Mirror

# 1. Proxy:Podman 會讀取 HTTP_PROXY/HTTPS_PROXY/NO_PROXY 環境變數
export HTTPS_PROXY=http://proxy.corp.example:8080
export NO_PROXY=localhost,127.0.0.1,.corp.example
# 容器預設會繼承 proxy 變數(--http-proxy=true);若不需要,可加上 --http-proxy=false

# 2. 自簽 CA:放到系統信任庫
sudo cp corp-root-ca.crt /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
# 或只信任特定 registry
sudo mkdir -p /etc/containers/certs.d/registry.corp.example:5000
sudo cp corp-root-ca.crt /etc/containers/certs.d/registry.corp.example:5000/ca.crt

# 3. podman machine:每次開機自動匯入主機信任的 CA(6.0 新增)
podman machine init --import-native-ca --now
podman machine set --import-native-ca     # 既有 VM

內部 mirror 的設定方式見第 11 章。

2.9 💡 本章實務建議

  1. 先盤點作業系統版本:Windows 10、Intel Mac、cgroups v1 主機都無法使用 Podman 6。
  2. 正式主機優先用 RHEL 系列,由 Container Tools AppStream 取得有支援的版本。Ubuntu/Debian 要接受版本落後,或改用 VM。
  3. 設定集中在 drop-in 檔:公司標準放在 /etc/containers/*.conf.d/,用組態管理工具(Ansible 等)發佈。
  4. rootless 服務帳號一定要 enable-linger,否則使用者登出後服務會被停止。
  5. 開發者桌面統一使用 Podman Desktop 加上 --import-native-ca,可以減少 proxy 與 SSL 攔截造成的拉取失敗。

2.10 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1cgroups v2podman info --format '{{.Host.CgroupsVersion}}'v2
2rootless 使用者有 subordinate IDgrep "^$USER:" /etc/subuid /etc/subgid兩個檔案各有一行,範圍至少 65536
3需要常駐的 rootless 帳號已啟用 lingerloginctl show-user "$USER" --property=LingerLinger=yes
4公司派送的設定檔有被讀取(6.x)podman --log-level=debug info 2>&1 | grep 'Read config file'列出公司派送的 drop-in,例如 10-corp.conf
5Windows 的 provider 符合公司政策podman machine info --format '{{.Host.DefaultMachine}} {{.Host.VMType}}'例如 podman-machine-default hyperv
6Podman Desktop 的鎖定設定生效在 UI 開啟 Settings → Proxy欄位顯示鎖頭,無法修改

3. 核心概念與基本操作

3.1 三個核心物件

3.1.1 映像檔(Image)

映像檔是唯讀的分層檔案系統,加上執行設定(entrypoint、環境變數、使用者、暴露埠等)。完整的映像檔名稱由四個部分組成:

registry.access.redhat.com/ubi10/ubi-minimal:10.0@sha256:3f2a...
└──────── registry ───────┘└ 命名空間/名稱 ┘└ tag ┘└─── digest(不可變)───┘
  • tag 是可以移動的標籤(例如 latest、1.2);digest 是內容的雜湊值,永遠指向同一個映像檔。
  • 正式環境建議至少固定到次版本的 tag;對稽核要求高的系統,要固定 digest。

3.1.2 容器(Container)

容器是映像檔的執行個體:在唯讀層上加一層可寫層,並放進獨立的 namespace(PID、網路、掛載、UTS、IPC、user)與 cgroup 資源限制中執行。

stateDiagram-v2
    [*] --> Created: podman create
    Created --> Running: podman start
    Running --> Paused: podman pause
    Paused --> Running: podman unpause
    Running --> Exited: 程序結束或 podman stop
    Exited --> Running: podman start/restart
    Exited --> [*]: podman rm
    Created --> [*]: podman rm

3.1.3 Pod

Pod 是一組共享網路與 IPC namespace 的容器,概念與 Kubernetes 相同。每個 Pod 預設有一個 infra 容器(pause 程序),負責持有這些 namespace;Pod 內的容器可以互相用 localhost 通訊。

graph TB
    subgraph "Pod: web-app(對外 8080)"
        I[infra 容器<br/>持有 network/IPC namespace]
        W[nginx<br/>:8080]
        A[api<br/>:9000]
        L[log-shipper<br/>sidecar]
    end
    W -->|localhost:9000| A
    L -.->|讀取共享 volume| W

Pod 的詳細操作與 Kubernetes 整合見第 7 章。

3.2 映像檔管理

# 搜尋(依 registries.conf 的 unqualified-search-registries)
podman search --limit 5 nginx
podman search --list-tags docker.io/library/nginx

# 拉取:建議寫完整名稱
podman pull docker.io/library/nginx:stable
podman pull registry.access.redhat.com/ubi10/ubi-minimal

# 指定平台(多架構映像檔)
podman pull --platform linux/arm64 docker.io/library/alpine:3

# 列出與檢視
podman images
podman image ls --format "table {{.Repository}}:{{.Tag}} {{.Size}}"
podman image inspect docker.io/library/nginx:stable
podman image history docker.io/library/nginx:stable
podman image tree docker.io/library/nginx:stable    # 以樹狀顯示層次

# 標記、移除、清理
podman tag docker.io/library/nginx:stable registry.corp.example/web/nginx:1.28
podman rmi registry.corp.example/web/nginx:1.28
podman image prune          # 清理 dangling 映像檔
podman image prune -a       # 清理所有沒有被容器使用的映像檔

3.3 容器管理

# 執行
podman run -d --name web -p 8080:80 docker.io/library/nginx:stable
podman run -it --rm registry.access.redhat.com/ubi10/ubi-minimal bash   # 互動式,結束後自動刪除

# 列出
podman ps                   # 執行中
podman ps -a                # 全部
podman ps --pod             # 顯示所屬 Pod
podman ps --format "table {{.Names}} {{.Status}} {{.Ports}}"

# 生命週期
podman stop web             # 送 SIGTERM,預設逾時 10 秒後送 SIGKILL
podman start web
podman restart web
podman pause web && podman unpause web
podman rm web               # 刪除已停止的容器
podman rm -f web            # 強制停止並刪除

# 觀察與除錯
podman logs -f --tail 100 web
podman exec -it web sh
podman top web
podman stats --no-stream
podman inspect web --format '{{.State.Status}} {{.NetworkSettings.IPAddress}}'
podman port web
podman diff web             # 檢視容器檔案系統的變更
podman cp web:/etc/nginx/nginx.conf ./nginx.conf

# 修改執行中容器的資源與設定(不必重建)
podman update --memory 512m --cpus 1.5 web
podman update --restart=always web
podman update --health-cmd 'curl -fsS http://localhost/ || exit 1' --health-interval 30s web

3.4 常用選項

選項說明範例
-d, --detach背景執行podman run -d ...
-it互動式並配置 TTYpodman run -it ... bash
--name容器名稱--name api
--replace同名容器已存在時,先刪除再建立--name api --replace
--rm結束後自動刪除一次性工作
-p, --publish埠號對應 [主機IP:]主機埠:容器埠[/協定]-p 127.0.0.1:8080:80
-e, --env/--env-file環境變數--env-file ./app.env
-v, --volume掛載 volume 或主機目錄-v data:/var/lib/data:Z
--mount較明確的掛載語法--mount type=volume,src=data,dst=/data
--network指定網路--network backend
--pod加入 Pod--pod web-app
--memory/--cpus資源限制--memory 1g --cpus 2
--restart重啟策略--restart=on-failure:3
--health-*健康檢查--health-cmd、--health-interval
--user容器內的執行身分--user 1001:0
--usernsuser namespace 模式--userns=keep-id
--read-only根檔案系統唯讀搭配 --tmpfs /tmp
--secret掛載機密--secret db_pw,type=env,target=DB_PASSWORD
--pull拉取策略--pull=newer

3.5 實務範例

3.5.1 Nginx 靜態網站

mkdir -p ~/site && echo '<h1>Hello Podman</h1>' > ~/site/index.html

# :Z 會為這個目錄設定 SELinux 私有標籤(沒有 SELinux 的系統會忽略)
podman run -d --name site -p 8080:80 \
  -v ~/site:/usr/share/nginx/html:ro,Z \
  docker.io/library/nginx:stable

curl -s http://localhost:8080
podman logs site
podman rm -f site

3.5.2 Java 應用程式快速驗證

# 直接用 JDK 映像檔執行本機編譯好的 JAR
podman run --rm -p 8080:8080 \
  -v "$PWD/target:/app:ro,Z" \
  docker.io/library/eclipse-temurin:21-jre \
  java -jar /app/demo.jar

⚠️ v2.0 更正:v1.0 使用的 openjdk:* 官方映像檔已經停止發布,請改用 eclipse-temurin、registry.access.redhat.com/ubi9/openjdk-21-runtime 等仍在維護的映像檔。

3.5.3 健康檢查

podman run -d --name api -p 9000:9000 \
  --health-cmd 'curl -fsS http://localhost:9000/actuator/health || exit 1' \
  --health-interval 30s --health-timeout 5s --health-retries 3 \
  --health-start-period 60s \
  --health-on-failure restart \
  registry.corp.example/app/api:1.4.2

podman healthcheck run api      # 手動執行一次
podman inspect api --format '{{.State.Health.Status}}'

--health-on-failure 可以設為 none、kill、restart、stop。在 Quadlet 裡搭配 systemd 的 restart 設定,效果最完整(見第 8 章)。

3.6 📝 基礎實務練習

目標:熟悉映像檔與容器的完整生命週期。

  1. 拉取 docker.io/library/nginx:stable 與 registry.access.redhat.com/ubi10/ubi-minimal,比較兩者的大小與層數(podman image history)。
  2. 以 -p 127.0.0.1:8080:80 啟動 Nginx,並掛載自訂首頁(記得加 :Z)。
  3. 用 podman exec 進入容器修改首頁,再用 podman diff 觀察可寫層的變化。
  4. 用 podman update --memory 256m 調整記憶體上限,並用 podman stats 確認。
  5. 加上健康檢查,故意讓檢查失敗,觀察 --health-on-failure restart 的行為。
  6. 清理所有練習資源:podman rm -fa && podman image prune -a。

驗證標準

  • 能說明 tag 與 digest 的差異
  • 能使用 inspect --format 取出指定欄位
  • 能說明 :z 與 :Z 的差異
  • 能在不重建容器的情況下調整資源與 healthcheck

3.7 💡 本章實務建議

  1. 容器是「用完即丟」的:設定與資料放在映像檔、volume、secret 裡,不要依賴容器的可寫層。
  2. 對外埠號預設綁定 127.0.0.1:只有需要對外服務時才綁定 0.0.0.0,避免開發機意外暴露服務。
  3. 善用 --replace 與 podman update:腳本可以保持冪等,也能減少停機時間。
  4. 每個服務都要有 healthcheck:這是 auto-update 回滾與 systemd 監控的基礎。

3.8 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1映像檔一律使用完整名稱grep -rnE 'podman (run|pull) [a-z0-9]+(:|$| )' scripts/沒有結果(沒有短名稱)
2容器有設定資源上限podman inspect -f '{{.HostConfig.Memory}} {{.HostConfig.PidsLimit}}' <容器>兩個值都大於 0
3正式容器有 healthcheckpodman inspect -f '{{.Config.Healthcheck}}' <容器>不是 <nil>
4沒有殘留的停止容器podman ps -a --filter status=exited -q | wc -l符合團隊的上限(例如 0)

4. 映像檔建置(Containerfile 與 Buildah)

4.1 Containerfile 基礎

Podman 使用 Buildah 建置映像檔,可以直接讀取 Containerfile 或 Dockerfile(兩者語法相同;同一目錄兩者都有時,優先使用 Containerfile)。

指令用途企業注意事項
FROM基底映像檔固定 tag 或 digest;只使用核准的基底
ARG/ENV建置參數與環境變數機密不要放在 ARG/ENV,會留在映像檔的 metadata 裡
COPY/ADD複製檔案優先用 COPY;ADD 會自動解壓縮並可以抓取 URL,行為較難預測
RUN建置時執行指令合併指令並在同一層清理快取
USER執行身分使用非 root 的 UID(OpenShift 相容做法是 USER 1001 並讓 GID 0 可寫)
WORKDIR工作目錄使用絕對路徑
EXPOSE宣告埠號只是文件用途,實際對應要靠 -p
HEALTHCHECK健康檢查必須用 --format docker 建置才會保留(OCI 格式沒有這個欄位)
ENTRYPOINT/CMD啟動指令使用 exec 形式(JSON 陣列),訊號才能正確送達
LABEL中繼資料使用 org.opencontainers.image.* 標準標籤

⚠️ v2.0 更正:HEALTHCHECK 不在 OCI 映像檔規格裡。podman build 預設產生 OCI 格式,會忽略這個指令並顯示警告。要保留的話,請加上 --format docker,或改在執行時用 --health-cmd、在 Quadlet 裡用 HealthCmd= 設定。

4.2 建置指令

# 基本建置
podman build -t registry.corp.example/app/api:1.4.2 .

# 指定檔案、建置參數、標籤
podman build -f Containerfile.prod \
  --build-arg APP_VERSION=1.4.2 \
  --label org.opencontainers.image.revision="$(git rev-parse HEAD)" \
  -t registry.corp.example/app/api:1.4.2 .

# 保留 HEALTHCHECK(Docker 格式)
podman build --format docker -t api:1.4.2 .

# 不使用快取、每次都重新拉取基底映像檔(CI 建議)
podman build --no-cache --pull=always -t api:1.4.2 .

# 指定目標階段
podman build --target test -t api:test .

4.3 多階段建置:Spring Boot

# Containerfile
# ---- 建置階段 ----
FROM docker.io/library/maven:3.9-eclipse-temurin-21 AS build
WORKDIR /workspace
# 先複製 pom.xml,讓相依套件層可以被快取
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 mvn -B -q dependency:go-offline
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 mvn -B -q package -DskipTests \
 && java -Djarmode=tools -jar target/*.jar extract --layers --launcher --destination /workspace/extracted

# ---- 執行階段 ----
FROM docker.io/library/eclipse-temurin:21-jre
LABEL org.opencontainers.image.title="order-api" \
      org.opencontainers.image.vendor="Corp"
WORKDIR /app
# Spring Boot 分層:相依套件變動少,放在前面的層
COPY --from=build /workspace/extracted/dependencies/ ./
COPY --from=build /workspace/extracted/spring-boot-loader/ ./
COPY --from=build /workspace/extracted/snapshot-dependencies/ ./
COPY --from=build /workspace/extracted/application/ ./
USER 1001
EXPOSE 8080
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError"
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

重點:

  • RUN --mount=type=cache 讓 Maven 的本機倉庫在多次建置之間重複使用,但不會進入映像檔。
  • -XX:MaxRAMPercentage 讓 JVM 依照容器的記憶體上限調整 heap,不需要寫死 -Xmx。
  • 使用 Spring Boot 的 layertools(-Djarmode=tools),程式碼變動時只需要重建最上面那一層。
podman build -t order-api:1.0.0 .
podman run -d --name order-api -p 8080:8080 \
  -e SPRING_PROFILES_ACTIVE=dev \
  --health-cmd 'curl -fsS http://localhost:8080/actuator/health || exit 1' \
  order-api:1.0.0

📌 使用 Red Hat 生態系的團隊,可以把基底換成 registry.access.redhat.com/ubi9/openjdk-21(建置)與 registry.access.redhat.com/ubi9/openjdk-21-runtime(執行)。UBI 映像檔可以自由散佈,並且有 Red Hat 的安全更新。

4.4 多階段建置:前端(React/Vue)

FROM docker.io/library/node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
COPY . .
RUN npm run build

# 使用非 root 版的 Nginx(監聽 8080)
FROM docker.io/nginxinc/nginx-unprivileged:stable-alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 8080
# nginx.conf:SPA 路由與 API 反向代理
server {
    listen 8080;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://order-api:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

⚠️ v2.0 更正:v1.0 的範例在 nginx:alpine 裡切換成自建使用者並監聽 80 埠,實際上會因為權限不足而無法啟動。另外 npm ci --only=production 會漏掉建置需要的 devDependencies。這兩個問題都已修正。Node.js 16 已經 EOL,範例改用 24(Active LTS)。

4.5 .containerignore

# .containerignore(也支援 .dockerignore)
.git
.gitignore
**/node_modules
**/target
**/*.log
.env
*.pem
Containerfile*
README.md

作用:縮小建置 context、加快建置,並避免把憑證、.env 等機密複製進映像檔。

4.6 建置期機密與快取

# 把私有套件庫的 token 以 secret 形式傳入,不會留在任何一層
podman build --secret id=npmrc,src=$HOME/.npmrc -t web:1.0 .
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
掛載類型用途
--mount=type=cache套件管理器的快取(Maven、npm、pip、dnf)
--mount=type=secret建置時需要的 token、憑證
--mount=type=bind暫時掛載 context 裡的檔案,不複製進映像檔

4.7 映像檔瘦身與層最佳化

# ❌ 不佳:每個 RUN 都是一層,快取也留在映像檔裡
FROM registry.access.redhat.com/ubi10/ubi
RUN dnf install -y python3
RUN dnf install -y python3-pip
COPY . /app
RUN pip3 install -r /app/requirements.txt

# ✅ 較佳:先複製相依清單以利用快取,同一層內清理
FROM registry.access.redhat.com/ubi10/ubi-minimal
RUN microdnf install -y python3 python3-pip \
 && microdnf clean all
WORKDIR /app
COPY requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt
COPY . .
USER 1001
CMD ["python3", "app.py"]
基底映像檔類型例子適用情境
完整版ubi10/ubi、debian需要完整工具鏈的建置階段
精簡版ubi10/ubi-minimal、alpine大多數執行階段
micro/distrolessubi10/ubi-micro、gcr.io/distroless/java21-debian12極小的攻擊面;沒有 shell,除錯要另外處理
語言執行環境eclipse-temurin:21-jre、ubi9/openjdk-21-runtime已經調校好的語言 runtime

4.8 多架構映像檔

# 一次建置 amd64 與 arm64,產生 manifest list(需要 qemu-user-static 或對應的原生建置機)
podman build --platform linux/amd64,linux/arm64 \
  --manifest registry.corp.example/app/api:1.4.2 .

# 推送 manifest list 與所有架構的映像檔(6.1 新增 --retry)
podman manifest push --all --retry 3 registry.corp.example/app/api:1.4.2

# 檢視
podman manifest inspect registry.corp.example/app/api:1.4.2

4.9 直接使用 Buildah

在 CI 或需要逐步控制時,可以用 Buildah 的指令式建置:

ctr=$(buildah from registry.access.redhat.com/ubi10/ubi-micro)
buildah copy "$ctr" ./dist/app /usr/local/bin/app
buildah config --entrypoint '["/usr/local/bin/app"]' --user 1001 \
  --label org.opencontainers.image.source=https://git.corp.example/app "$ctr"
buildah commit "$ctr" registry.corp.example/app/tool:1.0
buildah rm "$ctr"

4.10 💡 本章實務建議

  1. 建立公司核准的基底映像檔清單(例如 UBI、Temurin),並由平台團隊每月重建、掃描。
  2. 一律使用多階段建置與非 root 使用者;執行階段不要包含編譯器、套件管理器、shell(能做到的話)。
  3. 機密只能透過 --secret 傳入,並在 CI 中掃描映像檔的每一層,確認沒有殘留。
  4. 加上 OCI 標準標籤(source、revision、version、created),方便追溯與產生 SBOM。
  5. 需要 HEALTHCHECK 時記得 --format docker,或統一改在 Quadlet 裡定義。

4.11 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1執行階段不是 rootpodman image inspect -f '{{.Config.User}}' <映像檔>數字 UID(例如 1001),不是空值或 root
2沒有把機密留在任何一層podman history --no-trunc <映像檔> | grep -iE 'token|password|secret'沒有結果
3建置環境沒有混進映像檔podman image inspect -f '{{.Size}}' <映像檔>與基準相比沒有暴增(例如 Java 映像檔小於 400 MB)
4多架構映像檔包含所有平台skopeo inspect --raw docker://<映像檔> | grep -o '"architecture":"[a-z0-9]*"'列出 amd64 與 arm64
5.containerignore 排除了敏感檔案grep -E '^\.git$|^\.env' .containerignore兩項都有

5. 儲存與 Volume

5.1 掛載類型總覽

類型語法範例資料位置適用情境
Named volume-v pgdata:/var/lib/postgresql/dataPodman 管理(rootless 在 ~/.local/share/containers/storage/volumes)資料庫、需要長期保存的資料
Anonymous volume-v /data,或映像檔的 VOLUME 指令同上,名稱為隨機值暫存資料
Bind mount-v /srv/conf:/etc/app:ro,Z主機上的指定目錄設定檔、開發時的原始碼
tmpfs--tmpfs /tmp:rw,size=256m,noexec記憶體暫存檔、搭配 --read-only
Image volume--mount type=image,src=IMG,dst=/models另一個映像檔的內容(唯讀)模型、靜態資源
Artifact--mount type=artifact,src=ART,dst=/cfgOCI artifact設定包、AI 模型(5.5 新增)
graph LR
    subgraph 主機
        V[(named volume)]
        B[/srv/conf 目錄/]
        M[(記憶體 tmpfs)]
    end
    subgraph 容器
        D[/var/lib/data]
        C[/etc/app]
        T[/tmp]
    end
    V --> D
    B -->|唯讀+SELinux 標籤| C
    M --> T

5.2 Volume 操作

podman volume create pgdata
podman volume create --label team=payments --uid 26 --gid 26 pgdata2   # 5.6 起可指定擁有者
podman volume ls --filter label=team=payments
podman volume inspect pgdata --format '{{.Mountpoint}}'

# 使用
podman run -d --name db -v pgdata:/var/lib/postgresql/data:Z \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/pg_pw --secret pg_pw \
  docker.io/library/postgres:17

# 重新命名(6.1 新增;使用中或由 volume driver 建立的 volume 不能改名)
podman volume rename pgdata2 pgdata-archive

# 找不到 volume 時直接報錯,而不是自動建立(6.0 新增)
podman run --mount type=volume,src=pgdata,dst=/data,nocreate ...

# 清理
podman volume prune --dry-run     # 先看會刪哪些(6.0 新增)
podman volume prune               # 6.0 起只清「未使用的匿名 volume」
podman volume prune --all         # 清除所有未使用的 volume(5.x 的預設行為)

⚠️ v2.0 更正:Podman 6 的 podman volume prune 預設只清匿名 volume,與 Docker 行為一致;要清除所有未使用的 volume 請加 --all。另外 podman volume ls 的多個 --filter 改成 AND 條件(5.x 是 OR)。既有的清理腳本需要調整。

5.3 Bind mount 與 SELinux

在啟用 SELinux 的主機(RHEL、Fedora)上,容器程序帶有 container_t 標籤,預設無法讀取主機上一般目錄的檔案。bind mount 時要加上重新標記選項:

選項效果適用
:z標記為共享(container_file_t,不帶 MCS 類別),多個容器都能存取多個容器共用的目錄
:Z標記為私有(帶有本容器專屬的 MCS 類別),只有這個容器能存取單一容器專用的目錄
不加維持原標籤,通常會被拒絕存取—

⚠️ 千萬不要對 /、/home、/usr、/etc 這類系統目錄使用 :z/:Z,重新標記會影響主機本身的運作。

# 查看 SELinux 拒絕紀錄
sudo ausearch -m AVC -ts recent | grep container

5.4 Rootless 的檔案擁有權

rootless 容器裡的 UID 會透過 user namespace 對應到主機上的 subordinate UID。容器內的 root(UID 0)對應到你自己的 UID,容器內的 UID 1001 則對應到 subuid 起始值 + 1000。

# 查看對應關係
podman unshare cat /proc/self/uid_map
#          0       1000          1
#          1     524288      65536

# 方法一::U 讓 Podman 自動把掛載內容 chown 成容器內的使用者
podman run -v ./data:/data:Z,U registry.corp.example/app/worker:1.0

# 方法二:以 user namespace 的身分修改擁有者
podman unshare chown -R 1001:1001 ./data

# 方法三:keep-id,讓容器內的使用者 UID 等於主機上的你(開發時常用)
podman run --userns=keep-id -v "$PWD:/src:Z" -w /src docker.io/library/node:24-alpine npm test

5.5 使用 --mount 的明確語法

# volume,並只掛載其中的子目錄(subpath)
podman run --mount type=volume,src=shared,dst=/app/config,subpath=config,ro ...

# bind,並設定 SELinux 標籤
podman run --mount type=bind,src=/srv/app/conf,dst=/etc/app,ro=true,relabel=private ...

# tmpfs
podman run --mount type=tmpfs,dst=/tmp,tmpfs-size=268435456 ...

# 把另一個映像檔的內容以唯讀方式掛進來(例如模型檔)
podman run --mount type=image,src=registry.corp.example/ml/model-bert:3,dst=/models ...

5.6 Storage driver 與容量管理

podman info --format '{{.Store.GraphDriverName}} {{.Store.GraphRoot}}'
podman system df            # 映像檔、容器、volume 的空間用量
podman system df -v         # 詳細清單
  • 預設 driver 為 overlay。rootless 在新版核心(RHEL 9/10、Ubuntu 22.04 以後)會使用原生 overlay,只有舊核心才需要 fuse-overlayfs。
  • 建議把 graphroot 放在獨立的檔案系統(例如 /var/lib/containers 獨立 LV),避免容器把根目錄塞滿。
  • Podman 6 的 storage.conf 棄用了 rootless_storage_path;要改 rootless 的儲存位置,請在 rootless 專用的 drop-in 目錄設定 graphroot。

5.7 備份與還原

# Volume:匯出/匯入 tar
podman volume export pgdata --output pgdata-$(date +%F).tar
podman volume create pgdata-restore
podman volume import pgdata-restore pgdata-2026-09-29.tar

# 資料庫請優先使用原生的備份工具,確保一致性
podman exec db pg_dump -U app -Fc appdb > appdb.dump

# 映像檔:保留層與 metadata
podman save -o api-1.4.2.tar registry.corp.example/app/api:1.4.2
podman load -i api-1.4.2.tar

# 容器:只匯出檔案系統(會遺失 metadata 與 volume)
podman export api > api-rootfs.tar
podman import api-rootfs.tar localhost/api-snapshot:debug
需求工具是否包含 metadata是否包含 volume
備份映像檔podman save/load✅❌
在 registry 之間搬移映像檔skopeo copy✅❌
備份容器的檔案系統podman export/import❌❌
備份 volumepodman volume export/import—✅
保存執行中的狀態podman container checkpoint(CRIU,見第 13 章)✅可選

5.8 💡 本章實務建議

  1. 資料一律放在 named volume,並加上 label(team=、app=、backup=daily),方便自動化備份與清理。
  2. bind mount 只用來放設定檔,並加上 ro 與 :Z;原始碼掛載只限開發環境。
  3. 升級到 Podman 6 前,先檢查所有 volume prune 與 volume ls --filter 腳本。
  4. 資料庫備份用原生工具(pg_dump、mysqldump、redis BGSAVE),volume export 只當作輔助。
  5. graphroot 要監控容量,並排程執行 podman system prune(見第 13 章)。

5.9 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1資料放在 named volume,不在容器層podman inspect -f '{{range .Mounts}}{{.Type}}:{{.Destination}} {{end}}' <容器>資料目錄的類型是 volume
2SELinux 主機上的 bind mount 有標籤ls -Z <主機目錄>類型是 container_file_t
3備份檔可以還原podman volume create restore-test && podman volume import restore-test backup.tar && podman run --rm -v restore-test:/d:Z registry.access.redhat.com/ubi10/ubi-minimal ls /d列出預期的檔案
4儲存空間在警戒值以下podman system df可回收(RECLAIMABLE)比例符合維運標準

6. 網路

6.1 網路架構

⚠️ v2.0 更正:v1.0 沒有說明網路後端。Podman 4.0 起預設使用 Netavark+Aardvark-dns,5.0 起 rootless 預設使用 pasta;Podman 6 已完全移除 CNI 與 slirp4netns,防火牆規則也只支援 nftables。

graph TB
    subgraph "Rootful(系統服務)"
        H1[主機網卡] --- FW1[nftables]
        FW1 --- BR1[podman0 bridge<br/>10.88.0.0/16]
        BR1 --- C1[容器 A]
        BR1 --- C2[容器 B]
        DNS1[aardvark-dns] -.->|名稱解析| C1
    end
    subgraph "Rootless(一般使用者)"
        H2[主機網卡] --- PA[pasta<br/>使用者空間 TCP/IP]
        PA --- NS[rootless network namespace]
        NS --- BR2[自訂 bridge]
        BR2 --- C3[容器 C]
        BR2 --- C4[容器 D]
    end
元件功能
Netavark建立 bridge、macvlan、ipvlan 網路,設定 IP 與 nftables 規則
Aardvark-dns自訂網路內的 DNS,讓容器可以用名稱或別名互相連線
pastarootless 容器的使用者空間網路,把主機的網路介面「複製」給容器
rootlessportrootless bridge 網路的埠號轉送(6.x 的預設)
Pesto6.0 的實驗功能:以 pasta 的 kernel 層轉送取代 rootlessport,保留客戶端的原始來源 IP

6.2 網路模式

模式語法說明rootless
pasta--network pasta(rootless 沒有指定網路時的預設)每個容器各自用 pasta 連外,沒有容器之間的 DNS✅
bridge--network mynet同一網路的容器可以用名稱互連✅
host--network host共用主機的網路堆疊,沒有隔離✅(安全性較低)
none--network none只有 loopback✅
container--network container:web共用另一個容器的網路✅
macvlan/ipvlan--network mymacvlan容器直接取得實體網段的 IP❌ 需要 rootful

⚠️ 預設網路 podman 沒有啟用 DNS。容器之間要用名稱互連,必須建立自訂網路。

6.3 自訂網路操作

# 建立(自訂網路預設啟用 DNS)
podman network create backend
podman network create --subnet 10.90.10.0/24 --gateway 10.90.10.1 \
  --ip-range 10.90.10.128/25 --label env=dev app-net

# 內部網路:不能對外連線
podman network create --internal db-net

# IPv6 雙堆疊
podman network create --ipv6 dual-net

# 封鎖特定網段(6.0 新增的 blackhole/unreachable/prohibit 路由)
podman network create --route 10.20.0.0/16,blackhole restricted-net

# 查詢與維護
podman network ls
podman network inspect backend
podman network update --dns-add 10.0.0.53 backend
podman network reload --all          # 防火牆規則被清除時(例如重啟 nftables)重新套用
podman network rm --ignore old-net   # 6.1 新增 --ignore
podman network prune
# 容器連接網路、別名、固定 IP
podman run -d --name api --network backend --network-alias order-api registry.corp.example/app/api:1.4.2
podman run -d --name db --network backend:ip=10.90.10.20 docker.io/library/postgres:17
podman network connect db-net api
podman network disconnect db-net api

# 6.0 起可以指定多個固定 IP
podman run -d --network app-net:ip=10.90.10.30,ip=10.90.10.31 ...

6.4 網路隔離(Podman 6 預設啟用)

Podman 6 起,網路的 isolate 選項預設為開啟:不同 bridge 網路上的容器不能互相連線,行為與 Docker 一致。

graph LR
    subgraph frontend-net
        W[web]
    end
    subgraph backend-net
        A[api]
        D[(db)]
    end
    W -->|同時接上兩個網路| A
    A --> D
    W -.-x|不同網路,預設被阻擋| D

設計原則:

  • 依照信任區域切分網路(例如 frontend、backend、db),需要跨區的容器(例如 API gateway)再明確接上多個網路。
  • 資料庫網路加上 --internal,防止資料外洩到網際網路。

6.5 埠號發佈

podman run -d -p 8080:80 ...                 # 所有介面
podman run -d -p 127.0.0.1:8080:80 ...       # 只允許本機
podman run -d -p 8443:443/tcp -p 8443:443/udp ...
podman run -d -P ...                         # 把所有 EXPOSE 的埠對應到隨機埠
podman port web

rootless 綁定 1024 以下的埠:

# 方法一:開放非特權埠的起始值(系統層級,需要評估)
echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee /etc/sysctl.d/99-podman-ports.conf
sudo sysctl --system

# 方法二(建議):容器使用高埠號,前面放主機上的反向代理或負載平衡器

保留客戶端的來源 IP:rootless bridge 網路預設透過 rootlessport 轉送,容器看到的來源 IP 是內部位址。需要記錄真實 IP 時,可以:

  • 在前端的反向代理加上 X-Forwarded-For 標頭(建議)。
  • 評估 6.0 的實驗選項 rootless_port_forwarder="pasta"(在 containers.conf 的 [network] 區段設定),6.1 起也支援 IPv6。

6.6 容器連到主機

# 容器內可以用 host.containers.internal 連到主機(也可以用 host.docker.internal)
podman run --rm docker.io/library/alpine:3 getent hosts host.containers.internal
  • pasta 模式預設會把主機的 IP 複製給容器,所以容器不能直接用主機 IP 連回主機;請改用 host.containers.internal(5.3 起 pasta 預設使用 --map-guest-addr 提供這個位址)。
  • 6.0 起,--network host 的容器,host.containers.internal 會解析成 127.0.0.1。

6.7 網路除錯

# 容器的網路設定
podman inspect api --format '{{json .NetworkSettings.Networks}}'
podman exec api cat /etc/resolv.conf /etc/hosts

# 名稱解析與連線
podman exec api getent hosts db
podman exec api nc -zv db 5432

# 使用 netshoot 之類的除錯映像檔,加入目標容器的網路 namespace
podman run --rm -it --network container:api docker.io/nicolaka/netshoot

# rootless 的網路 namespace
podman unshare --rootless-netns ip addr

# nftables 規則(rootful)
sudo nft list table inet netavark

6.8 從 CNI 遷移到 Netavark

# 1. 確認目前的後端
podman info --format '{{.Host.NetworkBackend}}'

# 2. 若仍是 cni:記錄既有網路的設定
podman network ls
podman network inspect backend > backend-network.json   # 每個網路各存一份

# 3. 刪除所有容器與網路後,切換後端(會清除 CNI 設定)
podman system reset          # ⚠️ 會刪除所有容器、映像檔、volume,請先備份
# 或在 containers.conf 設定 [network] network_backend = "netavark" 後重建

# 4. 依照記錄重新建立網路(podman network create ...)

📌 Podman 6 完全不會讀取 /etc/cni/net.d 裡的設定。升級前一定要先完成遷移。

6.9 💡 本章實務建議

  1. 每個應用堆疊使用自己的網路,不要讓所有容器都用預設網路 podman(沒有 DNS,也沒有區隔)。
  2. 資料庫網路使用 --internal,對外服務埠號預設綁定 127.0.0.1,再由反向代理統一對外。
  3. 子網路規劃要與公司 IP 規劃對齊,用 default_subnet_pools 避開 VPN 與內網網段。
  4. 升級到 Podman 6 前確認 NetworkBackend 是 netavark,並確認主機使用 nftables。
  5. 需要來源 IP 時優先用反向代理的標頭,rootless_port_forwarder="pasta" 在 6.x 仍屬實驗性質。

6.10 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1網路後端是 netavarkpodman info --format '{{.Host.NetworkBackend}}'netavark
2自訂網路的 DNS 可以解析服務名稱podman run --rm --network app registry.access.redhat.com/ubi10/ubi-minimal getent hosts db回傳 db 容器的 IP
3內部網路真的不能連外podman run --rm --network internal-net registry.access.redhat.com/ubi10/ubi-minimal curl -m 5 -sI https://example.com連線失敗(逾時或無法解析)
4子網路沒有和公司內網衝突podman network inspect -f '{{range .Subnets}}{{.Subnet}} {{end}}' app不在公司的保留網段內
5埠號只綁定在需要的介面ss -ltnp | grep <埠號>對內服務只綁 127.0.0.1

7. Pod 與 Kubernetes 整合

7.1 Pod 的運作方式

  • Pod 內的所有容器共享網路 namespace(同一個 IP、同一組埠號,彼此用 localhost 通訊)與 IPC namespace。
  • 埠號發佈要設定在 Pod 上(podman pod create -p),不能設定在個別容器上。
  • 每個 Pod 預設有一個 infra 容器負責持有 namespace;用 --infra=false 可以不建立,但這樣就無法使用 Quadlet 或 generate systemd 管理這個 Pod。
# 建立 Pod
podman pod create --name shop -p 8080:8080 --network backend --label app=shop

# 加入容器
podman run -d --pod shop --name shop-api registry.corp.example/shop/api:2.3.0
podman run -d --pod shop --name shop-cache docker.io/library/redis:8-alpine

# 在 Pod 內,api 可以用 localhost:6379 連到 Redis
podman pod ps
podman ps --pod --filter pod=shop
podman pod inspect shop
podman pod top shop
podman pod stats shop

# 生命週期
podman pod stop shop && podman pod start shop
podman pod restart shop
podman pod rm -f shop
選項說明
--share要共享的 namespace(預設 ipc,net,uts;加上 pid 可以讓 sidecar 看到其他容器的程序)
--exit-policy所有容器結束後 Pod 的行為:continue(預設)或 stop
--userns整個 Pod 共用的 user namespace 設定,例如 keep-id
--infra-image自訂 infra 映像檔(離線環境必須先準備好)
--memory/--cpusPod 層級的資源上限

7.2 從容器/Pod 產生 Kubernetes YAML

# 產生 Pod YAML
podman kube generate shop -f shop-pod.yaml

# 產生 Deployment(也支援 daemonset、job),並產生 Service
podman kube generate shop --type deployment --replicas 3 --service -f shop-deploy.yaml

產生的 YAML 會保留埠號、環境變數、volume(轉成 PVC)、資源限制、healthcheck(6.1 起轉成 livenessProbe)等設定,可以作為部署到 Kubernetes 的起點。

7.3 在本機執行 Kubernetes YAML

# shop.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: shop-config
data:
  SPRING_PROFILES_ACTIVE: "dev"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shop-data
spec:
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: shop
  labels:
    app: shop
spec:
  restartPolicy: Always
  containers:
    - name: api
      image: registry.corp.example/shop/api:2.3.0
      ports:
        - containerPort: 8080
          hostPort: 8080
      envFrom:
        - configMapRef:
            name: shop-config
      resources:
        limits:
          memory: 1Gi
          cpu: "1"
      livenessProbe:
        httpGet:
          path: /actuator/health
          port: 8080
        periodSeconds: 30
      volumeMounts:
        - name: data
          mountPath: /var/lib/shop
    - name: cache
      image: docker.io/library/redis:8-alpine
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: shop-data
podman kube play shop.yaml                  # 建立並啟動
podman kube play --replace shop.yaml        # 先刪除舊的,再依新內容重建
podman kube play --build shop.yaml          # image 名稱對應到子目錄的 Containerfile 時,先建置
podman kube play --network backend shop.yaml
podman kube play a.yaml b.yaml              # 5.7 起可以一次處理多個檔案
podman kube down shop.yaml                  # 停止並刪除(volume 會保留)

7.3.1 支援範圍

項目支援情況
資源種類Pod、Deployment、DaemonSet、Job、PersistentVolumeClaim、ConfigMap、Secret
Volume 類型hostPath、emptyDir、configMap、persistentVolumeClaim(對應到 named volume)、image(僅限 rootful)
Deployment 副本數預設只建立 1 個 Pod
預設 restartPolicyAlways
不支援Service 的負載平衡、Ingress、HPA、NetworkPolicy、RBAC、StatefulSet 等叢集層級功能

Podman 特有的行為可以用 annotation 控制,例如:

Annotation用途
io.podman.annotations.usernsPod 的 user namespace,例如 keep-id
io.podman.annotations.volumes-from掛載其他容器的 volume
io.podman.annotations.pids-limit/<容器名稱>PID 數量上限
io.podman.annotations.infra.nameinfra 容器名稱

7.3.2 🔭 6.2 預覽:kube play 的驗證與多副本

🔭 6.2.0-rc1(2026-10-26):以下選項只有 6.2 起才有。在 6.1.x 上執行會出現 unknown flag 錯誤;正式發布前,不要寫進正式環境的腳本。

選項作用企業用途
--validate=ignore|warn|strict處理無法辨識的 YAML 欄位與不支援的物件。預設 ignore(靜默略過)CI 用 strict,避免「YAML 寫了但 Podman 沒套用」
--multiple-podsDeployment 的 replicas 大於 1 時,真的建立多個 Pod(預設只建立 1 個)本機模擬多副本
--label key=value(-l)為建立的 Pod、PVC、Secret 加上 label依 label 清理或稽核
--build 支援子目錄可以從 context 目錄底下的子目錄建置映像檔monorepo

⚠️ 棄用通知:6.2 起,kube play 改用 YAML 中的 securityContext.seccompProfile 設定 seccomp。舊的 Kubernetes annotation 寫法(seccomp.security.alpha.kubernetes.io/pod、container.seccomp.security.alpha.kubernetes.io/<容器名稱>)已標為棄用,Podman 7.0 會移除。請現在就改成標準欄位,K8s 叢集也看得懂:

# ✅ 建議:標準欄位,Podman 與 Kubernetes 都適用
apiVersion: v1
kind: Pod
metadata:
  name: hardened
spec:
  securityContext:
    seccompProfile:
      type: RuntimeDefault
  containers:
    - name: app
      image: registry.access.redhat.com/ubi10/ubi-minimal:latest
      command: ["sleep", "infinity"]
# 🔭 6.2:CI 嚴格驗證。注意 strict 遇到錯誤時,已建立的物件不會回滾,要自己清理
podman kube play --validate=strict --label ci-run=1234 shop.yaml \
  || { podman kube down shop.yaml; exit 1; }

# 🔭 6.2:Deployment replicas: 3 時,建立 3 個 Pod
podman kube play --multiple-pods deploy.yaml

✅ 驗證方式:

podman kube play --help | grep -E -- '--validate|--multiple-pods|--label'   # 6.2 才會列出
# 故意在 YAML 中加入一個打錯的欄位(例如 spec.containers[0].imag:)
podman kube play --validate=warn typo.yaml 2>&1 | grep -i warn            # 預期:stderr 有 warning
podman pod ps --filter label=ci-run=1234                                  # 預期:列出這次建立的 Pod

7.4 部署到 Kubernetes

# 直接把本機的容器或 Pod 部署到目前 kubeconfig 指向的叢集
podman kube apply --kubeconfig ~/.kube/config --ns shop-dev shop

# 或部署 YAML 檔
podman kube apply --kubeconfig ~/.kube/config -f shop-deploy.yaml

實務上,建議把 podman kube generate 產生的 YAML 當成草稿,再交給 Helm、Kustomize 或 GitOps(Argo CD 等)管理,並補上 Service、Ingress、SecurityContext、資源 requests 等叢集設定。

7.5 從本機到平台的開發流程

flowchart LR
    A[本機<br/>podman run/pod] --> B[podman kube generate]
    B --> C[調整 YAML<br/>補上叢集設定]
    C --> D[podman kube play<br/>本機驗證]
    D --> E{通過?}
    E -->|否| C
    E -->|是| F[Git 提交]
    F --> G[CI 建置與掃描]
    G --> H[GitOps 部署<br/>K8s/OpenShift]

7.6 💡 本章實務建議

  1. 本機的多容器應用優先用 Pod 表達,這樣才能直接轉成 Kubernetes YAML,減少「本機可以、叢集不行」的落差。
  2. Kubernetes YAML 是單一事實來源:同一份 YAML 同時用於本機(kube play)、單機主機(Quadlet .kube)與叢集。
  3. 不要依賴 Podman 不支援的欄位:Service、Ingress 等叢集資源在本機會被忽略,需要在叢集上另外驗證。
  4. rootless 的 Pod 加上 io.podman.annotations.userns: keep-id,可以減少 hostPath 的權限問題。

7.7 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1YAML 可以在本機重現podman kube play --replace shop.yaml && podman pod psPod 狀態為 Running
2產生的 YAML 沒有寫死主機路徑grep -n 'hostPath' shop.yaml只有核准的路徑
3YAML 通過叢集的 schema 驗證kubectl apply --dry-run=server -f shop.yaml沒有錯誤
4seccomp 使用標準欄位grep -n 'seccomp.security.alpha.kubernetes.io' *.yaml沒有結果(改用 securityContext.seccompProfile)

8. Quadlet 與 systemd 生產部署

🆕 v2.0 新增:v1.0 沒有涵蓋 Quadlet。Quadlet 是在 Linux 主機上以 systemd 長期執行容器的官方建議做法;podman generate systemd 從 4.7 起已標示為棄用(不會移除,但只修嚴重錯誤、不再加新功能)。

8.1 Quadlet 是什麼

Quadlet 是一個 systemd generator。你只要寫一個宣告式的 .container(或 .pod、.network 等)檔案,每次開機或執行 systemctl daemon-reload 時,Quadlet 就會自動把它轉成完整的 .service 單元。這個 service 由 systemd 負責啟動順序、相依性、重啟、日誌(journald)與資源控制。

flowchart LR
    Q["web.container<br/>宣告式設定"] -->|daemon-reload| G[podman-system-generator]
    G --> S["web.service<br/>ExecStart=podman run ..."]
    S --> SD[systemd]
    SD -->|啟動、重啟、相依| C[容器]
    SD -->|日誌| J[journald]
    T[podman-auto-update.timer] -->|每日檢查新映像檔| S

與其他做法的比較

做法優點缺點建議
podman run --restart=always最簡單沒有 daemon,主機重開後不會自動恢復(除非啟用 podman-restart.service);沒有相依性管理僅限開發
podman generate systemd產生標準 unit已棄用;設定分散在產生出來的長指令裡,難以維護既有系統逐步遷移
Quadlet宣告式、可以放進 Git、支援 drop-in 與範本、整合 auto-update需要 systemd 與 cgroups v2✅ 標準做法
Compose開發者熟悉沒有與 systemd 整合,重開機與監控要另外處理開發、測試環境

8.2 單元檔類型

副檔名用途產生的 service預設的 Podman 物件名稱
.container單一容器名稱.servicesystemd-名稱
.podPod名稱-pod.servicesystemd-名稱
.network網路名稱-network.servicesystemd-名稱
.volumeVolume名稱-volume.servicesystemd-名稱
.image預先拉取映像檔名稱-image.service—
.build建置映像檔名稱-build.service—
.kube執行 Kubernetes YAML名稱.service依 YAML
.artifact拉取 OCI artifact(5.7 新增)名稱-artifact.service—

可以用 ContainerName=、PodName=、NetworkName=、VolumeName= 覆寫預設名稱。在其他 Quadlet 檔裡引用時,要寫檔名(例如 Network=backend.network),Quadlet 會自動換成真正的名稱並加上相依性。

8.3 檔案放置路徑

身分路徑(優先順序由高到低)用途
rootful/run/containers/systemd/暫時測試
/etc/containers/systemd/系統管理員定義
/usr/share/containers/systemd/發行版/套件提供
rootless$XDG_RUNTIME_DIR/containers/systemd/暫時測試
~/.config/containers/systemd/使用者自己定義
/etc/containers/systemd/users/${UID}/管理員為特定使用者提供
/etc/containers/systemd/users/管理員為所有使用者提供
/usr/share/containers/systemd/users/${UID}/、/usr/share/containers/systemd/users/發行版提供(6.0 新增)

子目錄會被遞迴搜尋,所以可以依照應用程式分資料夾存放。

8.4 第一個 Quadlet:Nginx

# ~/.config/containers/systemd/web.container
[Unit]
Description=Corporate web front-end
After=network-online.target

[Container]
ContainerName=web
Image=docker.io/nginxinc/nginx-unprivileged:stable-alpine
PublishPort=127.0.0.1:8080:8080
Volume=%h/site:/usr/share/nginx/html:ro,Z
AutoUpdate=registry
HealthCmd=wget -qO- http://localhost:8080/ || exit 1
HealthInterval=30s
HealthOnFailure=kill
Notify=healthy

[Service]
Restart=always
TimeoutStartSec=300

[Install]
WantedBy=default.target
# 讓 systemd 重新產生 unit
systemctl --user daemon-reload

# 啟動與查看狀態(Quadlet 產生的 unit 不能 enable,開機自動啟動靠 [Install] 區段)
systemctl --user start web.service
systemctl --user status web.service
journalctl --user -u web.service -f

# rootless 服務要在使用者登出後繼續執行,記得啟用 linger
sudo loginctl enable-linger "$USER"

重點說明:

  • Notify=healthy:等到 healthcheck 第一次成功,systemd 才會把服務視為「已啟動」。搭配 auto-update 的回滾功能效果最好。
  • HealthOnFailure=kill 加上 Restart=always:健康檢查失敗時終止容器,交給 systemd 重新啟動。
  • %h 是 systemd 的 specifier,代表使用者的家目錄。
  • 開機時可能需要先拉取映像檔,超過 systemd 預設的 90 秒啟動時限,所以要加大 TimeoutStartSec。

8.5 多元件應用:Pod+網路+Volume+Secret

# /etc/containers/systemd/shop/shop.network
[Network]
Subnet=10.90.20.0/24
Label=app=shop
# /etc/containers/systemd/shop/shop-db.volume
[Volume]
Label=app=shop
Label=backup=daily
# /etc/containers/systemd/shop/shop.pod
[Pod]
PodName=shop
Network=shop.network
PublishPort=8080:8080

[Install]
WantedBy=multi-user.target
# /etc/containers/systemd/shop/shop-db.container
[Unit]
Description=Shop PostgreSQL

[Container]
ContainerName=shop-db
Image=docker.io/library/postgres:17
Network=shop.network
NetworkAlias=db
Volume=shop-db.volume:/var/lib/postgresql/data:Z
Secret=shop_db_password,type=env,target=POSTGRES_PASSWORD
Environment=POSTGRES_DB=shop
Environment=POSTGRES_USER=shop
HealthCmd=pg_isready -U shop
HealthInterval=15s
HealthOnFailure=kill

[Service]
Restart=always

[Install]
WantedBy=multi-user.target
# /etc/containers/systemd/shop/shop-api.container
[Unit]
Description=Shop API
Requires=shop-db.service
After=shop-db.service

[Container]
ContainerName=shop-api
Image=registry.corp.example/shop/api:2.3.0
Pod=shop.pod
Secret=shop_db_password,type=env,target=SPRING_DATASOURCE_PASSWORD
Environment=SPRING_DATASOURCE_URL=jdbc:postgresql://db:5432/shop
AutoUpdate=registry
HealthCmd=curl -fsS http://localhost:8080/actuator/health || exit 1
HealthStartPeriod=90s
HealthOnFailure=kill
Notify=healthy
NoNewPrivileges=true
ReadOnly=true
DropCapability=ALL
Memory=1g

[Service]
Restart=always
TimeoutStartSec=600

[Install]
WantedBy=multi-user.target
# 事先建立 secret(不要寫在 Quadlet 檔裡)
printf '%s' "$DB_PASSWORD" | sudo podman secret create shop_db_password -

sudo systemctl daemon-reload
sudo systemctl start shop-pod.service
sudo systemctl status shop-api.service shop-db.service

📌 shop-api 透過 Pod=shop.pod 加入 Pod,Pod 又透過 Network=shop.network 接上網路,所以 API 可以用 DNS 名稱 db 連到資料庫。Quadlet 會自動加上 network、volume、pod 的相依性,不需要手寫 Requires=;上例的 Requires=shop-db.service 是應用層面的相依(API 需要資料庫先啟動)。

8.6 其他單元檔範例

# app.image:開機時預先拉取,並指定憑證檔
[Image]
Image=registry.corp.example/shop/api:2.3.0
AuthFile=/etc/containers/auth/corp.json
Policy=newer
# app.build:在主機上建置映像檔,給其他 .container 使用
[Build]
ImageTag=localhost/shop/report:latest
SetWorkingDirectory=unit
File=Containerfile
# legacy.kube:直接執行既有的 Kubernetes YAML
[Kube]
Yaml=/etc/containers/systemd/legacy/legacy.yaml
Network=shop.network
PublishPort=9090:9090
AutoUpdate=registry

[Install]
WantedBy=multi-user.target

8.6.1 🔭 6.2 預覽:新的 Quadlet key

🔭 6.2.0-rc1:Quadlet generator 遇到不認識的 key 會直接報錯,整個 unit 不會產生。所以在 6.1.x 主機上用到這些 key,服務會消失。請等主機升到 6.2 以後再使用。

Key區段適用檔案作用
SetMountsDependency=Requires|Wants|None[Quadlet]所有 Quadlet 檔控制 bind mount 來源路徑產生的 systemd 相依:Requires(預設,產生 RequiresMountsFor=,掛載點失效時服務會被停止)、Wants(需要 systemd 256 以上,產生 WantsMountsFor=)、None(不產生)
Umask=[Container].container設定容器的預設 umask(對應 podman run --umask)

典型用途:容器掛載 NFS/CIFS 的 automount 共用目錄。用預設的 Requires 時,共用目錄短暫斷線就會把服務一起停掉:

# /etc/containers/systemd/report.container(🔭 需要 Podman 6.2 與 systemd 256 以上)
[Quadlet]
SetMountsDependency=Wants

[Container]
Image=registry.corp.example/batch/report:3.1
Volume=/mnt/nfs/reports:/data:Z
Umask=0027

[Install]
WantedBy=multi-user.target

⚠️ 截至 6.2.0-rc1,Umask= 已經出現在 Release Notes 與 Quadlet 原始碼(KeyUmask 對應 --umask),但 podman-container.unit(5) man page 還沒有收錄。正式發布前,請先用下面的 dry-run 確認。

✅ 驗證方式:

systemctl --version | head -1                                   # Wants 需要 systemd 256 以上
/usr/lib/systemd/system-generators/podman-system-generator --dryrun 2>&1 \
  | grep -E 'WantsMountsFor|RequiresMountsFor|--umask'
# 預期:WantsMountsFor=/mnt/nfs/reports,以及 ExecStart 中有 --umask 0027
# 6.1.x 上預期:出現 unsupported key 錯誤,表示這台主機還不能用

8.7 podman quadlet 管理指令

5.6 起提供 podman quadlet 指令,用來安裝與管理目前使用者的 Quadlet:

# 安裝單一檔案(也可以是 URL)
podman quadlet install web.container

# 安裝整個目錄(含設定檔等非 Quadlet 檔案)為一個「應用程式」
podman quadlet install --application=shop ./shop/

# 一個 .quadlets 檔裡放多個 Quadlet(5.8 新增),用 --- 分隔,每段以 # FileName=<名稱> 開頭
podman quadlet install webapp.quadlets

# 更新既有的 Quadlet
podman quadlet install --replace web.container

# 列出、檢視、移除
podman quadlet list                     # 6.0 起有別名 ls,並顯示所屬 Pod
podman quadlet list --filter status=active
podman quadlet print web.container      # 別名 cat
podman quadlet rm web.container

⚠️ v2.0 更正:Podman 6 改變了 podman quadlet install 的存放方式:5.x 用 .app 檔追蹤同一個應用程式的檔案,6.0 改成每個應用程式一個子目錄,比較容易手動管理。從 5.x 升級後,建議用 podman quadlet list 檢查既有的 Quadlet。

8.8 自動更新(auto-update)

sequenceDiagram
    participant T as podman-auto-update.timer
    participant P as podman auto-update
    participant R as Registry
    participant S as systemd unit
    T->>P: 每日 00:00 觸發
    P->>R: 比對映像檔 digest
    R-->>P: 有新版本
    P->>P: 拉取新映像檔
    P->>S: 重新啟動 unit
    S-->>P: 回報啟動結果(Notify=healthy)
    alt 啟動失敗
        P->>S: 回滾到舊映像檔並再次重啟
    end
# 啟用每日排程(rootful 用 sudo systemctl;rootless 用 systemctl --user)
sudo systemctl enable --now podman-auto-update.timer

# 先看哪些容器有更新,但不執行
sudo podman auto-update --dry-run

# 手動執行
sudo podman auto-update

# 調整排程(例如改到每週日凌晨 3 點)
sudo systemctl edit podman-auto-update.timer
策略說明前提
AutoUpdate=registry比對 registry 上的 digest,不同就拉取並重啟映像檔必須寫完整名稱
AutoUpdate=local比對本機儲存的映像檔(例如 CI 推送或 .build 重建之後)—

回滾:podman auto-update 預設 --rollback=true,重啟失敗時會退回舊映像檔。要讓 systemd 能判斷「失敗」,容器必須正確回報就緒狀態,也就是 Notify=healthy,或讓應用程式自己送出 sd_notify。

企業建議:

  • 正式環境的 tag 建議採「次版本浮動」(例如 2.3),由 CI 推送修補版,auto-update 自動套用。
  • 金融業的正式環境通常要求變更管理。可以在正式環境停用 timer,只在變更時段手動執行 podman auto-update;測試環境再開啟自動更新。

8.8.1 🔭 6.2 預覽:auto-update 篩選與遠端執行

🔭 6.2.0-rc1 新功能:

  • podman auto-update --filter:只更新符合條件的容器,條件可以是 label= 或 ancestor=。
  • 遠端客戶端(podman --remote)也可以執行 auto-update,API 為 POST /libpod/autoupdate。

這兩項讓「變更時段只更新核准的服務」做得到,不必再一次更新整台主機:

# 🔭 6.2:先看 web 服務有沒有更新,不執行
sudo podman auto-update --dry-run --filter label=app=web

# 🔭 6.2:只更新使用特定映像檔的容器
sudo podman auto-update --filter ancestor=registry.corp.example/shop/api:2.3

⚠️ 篩選的是「容器」,但重新啟動的是整個 systemd unit。同一個 Pod 或有相依關係的其他容器也可能一起重啟,而且可能用到更新後的共用映像檔。條件沒有符合任何容器時,指令會成功結束,不會更新任何東西。所以請一律先執行 --dry-run。

✅ 驗證方式:--dry-run 的輸出中,UPDATED 欄位為 pending 的容器,應該只有符合篩選條件的那幾個;執行後用 podman ps --format '{{.Names}} {{.Image}} {{.Status}}' 比對映像檔與啟動時間。

8.9 Drop-in 與範本

# 覆寫單一設定而不修改原檔:/etc/containers/systemd/shop-api.container.d/10-prod.conf
[Container]
Environment=SPRING_PROFILES_ACTIVE=prod
Memory=2g
# 範本:worker@.container(%i 是實例名稱)
[Container]
Image=registry.corp.example/batch/worker:1.8
Exec=--queue %i
Volume=worker-data@.volume:/work

[Install]
WantedBy=multi-user.target
DefaultInstance=default
# 啟動多個實例
sudo systemctl start worker@orders.service worker@payments.service

🔭 6.2 預覽:可以只建立實例專屬的 drop-in 目錄(例如 worker@orders.container.d/),Quadlet 就會從 worker@.container 產生這個實例,不必再建立 worker@orders.container 檔案或 symlink。空目錄也可以,這時實例會繼承範本的 [Install],所以開機時也會啟動。6.1.x 仍然需要實例檔或 symlink。

# 🔭 6.2:/etc/containers/systemd/worker@payments.container.d/10-mem.conf(只有這個實例加大記憶體)
[Container]
Memory=4g

8.10 除錯

# 查看 Quadlet 產生的 unit 與錯誤訊息(rootless 加 --user)
/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

# 只驗證特定 unit
systemd-analyze --user --generators=true verify web.service

# 只測試某個目錄的檔案
QUADLET_UNIT_DIRS=./test /usr/lib/systemd/system-generators/podman-system-generator --user --dryrun
症狀可能原因
Unit web.service not found語法錯誤,或用了比目前 Podman 版本更新的 key;用 --dryrun 查看錯誤
開機後服務沒有啟動缺少 [Install] 區段;rootless 沒有啟用 linger
啟動逾時拉取映像檔太久:加大 TimeoutStartSec,或用 .image 先拉取
服務一直是 activating使用 Notify=healthy,但 healthcheck 一直沒有成功
在 service 裡設定 User= 沒有作用Quadlet 不支援 systemd 的 User=、Group=、DynamicUser=;rootless 請把檔案放在該使用者的路徑

8.11 從 podman generate systemd 遷移

舊做法Quadlet 對應
podman generate systemd --new --name web > web.service寫 web.container
ExecStart=/usr/bin/podman run ... --label io.containers.autoupdate=registryAutoUpdate=registry
--sdnotify=conmon預設值;需要時改用 Notify=true 或 Notify=healthy
手寫的 network/volume 建立腳本.network、.volume 單元檔
Pod 加上多個 container unit.pod 加上 Pod=

遷移步驟:

  1. 用 podman inspect 取出既有容器的參數,對照 man podman-container.unit 轉寫成 Quadlet。
  2. 停用並刪除舊的 .service 檔:systemctl disable --now container-web.service。
  3. 放入 Quadlet 檔、daemon-reload、啟動並驗證。
  4. 把 Quadlet 檔納入 Git 與組態管理(例如 Ansible 的 containers.podman.podman_container 模組已支援產生 Quadlet)。

8.12 💡 本章實務建議

  1. 正式主機一律使用 Quadlet,檔案納入 Git,並由組態管理工具佈署。
  2. 每個 .container 都要有 healthcheck、Restart=always、Notify=healthy,才能讓 auto-update 的回滾正確運作。
  3. 機密透過 Secret= 引用,不要把密碼寫在 Environment=。
  4. 環境差異放在 drop-in(*.container.d/*.conf),主檔在各環境保持一致。
  5. Quadlet 需要 cgroups v2,RHEL 8 主機要先升級。

8.13 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1Quadlet 檔案沒有語法或 key 錯誤/usr/lib/systemd/system-generators/podman-system-generator --dryrun 2>&1 | grep -i error沒有結果
2服務由 systemd 管理並正常執行systemctl status shop-api.serviceactive (running)
3就緒通知有效systemctl show shop-api.service -p TypeType=notify
4auto-update 的設定正確podman auto-update --dry-run列出預期的容器,POLICY 為 registry
5重開機後服務自動啟動重新開機後執行 systemctl is-active shop-api.serviceactive
6沒有殘留 podman generate systemd 產生的 unitgrep -l 'generate systemd' /etc/systemd/system/*.service ~/.config/systemd/user/*.service 2>/dev/null沒有結果

9. Compose 與 Docker 相容

9.1 三種執行 Compose 的方式

方式原理相容性建議情境
podman compose(4.7 起)一層薄包裝,呼叫外部的 compose provider,並自動把它連到 Podman socket依 provider 而定建議的統一入口
podman-compose(1.6.0)Python 實作,直接把 Compose 檔轉成 podman 指令大部分 Compose 規格;不需要 socket沒有 docker-compose 的 Linux 環境
docker-compose 連 Podman socket原生的 Compose v2,透過 Docker 相容 API 操作 Podman最接近 Docker 行為依賴 Compose 進階功能的團隊

podman compose 預設會依序尋找 docker-compose、podman-compose;兩者都有時,docker-compose 優先。可以在 containers.conf 的 [engine] 區段設定 compose_providers,或用 PODMAN_COMPOSE_PROVIDER 環境變數指定。

# 安裝 podman-compose
sudo dnf -y install podman-compose       # RHEL(EPEL)/Fedora
pip install --user podman-compose        # 其他平台

podman compose version

9.2 Compose 檔範例:前端+API+資料庫+快取

# compose.yaml
name: shop

services:
  web:
    image: registry.corp.example/shop/web:2.3.0
    ports:
      - "127.0.0.1:8080:8080"
    depends_on:
      api:
        condition: service_healthy
    networks: [frontend]

  api:
    build:
      context: ./api
      dockerfile: Containerfile
    image: localhost/shop/api:dev
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/shop
      SPRING_DATASOURCE_USERNAME: shop
      SPRING_DATASOURCE_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks: [frontend, backend]
    deploy:
      resources:
        limits:
          memory: 1g
          cpus: "1.0"

  db:
    image: docker.io/library/postgres:17
    environment:
      POSTGRES_DB: shop
      POSTGRES_USER: shop
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes:
      - db-data:/var/lib/postgresql/data:Z
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 10s
      retries: 5
    networks: [backend]

  cache:
    image: docker.io/library/redis:8-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - cache-data:/data:Z
    networks: [backend]

networks:
  frontend: {}
  backend:
    internal: true

volumes:
  db-data: {}
  cache-data: {}

secrets:
  db_password:
    file: ./secrets/db_password.txt

📌 SPRING_DATASOURCE_PASSWORD_FILE 需要應用程式自行讀取檔案;也可以改用 Spring Boot 的 configtree: 設定匯入 /run/secrets/。./secrets/ 要加進 .gitignore。

9.3 常用指令

podman compose up -d                    # 背景啟動
podman compose up -d --build            # 先建置再啟動
podman compose ps
podman compose logs -f api
podman compose exec db psql -U shop
podman compose run --rm api ./mvnw test # 一次性工作
podman compose up -d --scale worker=3   # 調整副本數
podman compose pull
podman compose down                     # 停止並刪除容器與網路
podman compose down -v                  # 連同 volume 一起刪除(⚠️ 資料會消失)
podman compose config                   # 顯示合併後的最終設定

podman-compose 1.6.0 新增 up --wait、--wait-timeout、COMPOSE_PROFILES 環境變數、volume.type=image 等功能,並會在 up 時先拉取映像檔再替換容器,縮短停機時間。

9.4 Docker 相容 socket

# rootless:啟用使用者層級的 socket(按需啟動,不是常駐 daemon)
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

# rootful
sudo systemctl enable --now podman.socket
# socket 位置:/run/podman/podman.sock
# 安裝 podman-docker 套件會提供 /usr/bin/docker 包裝指令與 /var/run/docker.sock 連結

# 驗證
docker version        # Server 會顯示 Podman Engine
curl -s --unix-socket $XDG_RUNTIME_DIR/podman/podman.sock http://d/v1.44/info | head -c 200
# macOS/Windows:取得 podman machine 的 socket 位置
podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}'

相容程度:Podman 6 支援 Docker Engine API v1.44,並已開始實作 v1.45。常見工具(docker-compose、Testcontainers、IDE 外掛、GitLab Runner 的 docker executor)大多可以直接使用;依賴 Swarm、BuildKit 專屬功能或 Docker plugin 的工具則不支援。

9.5 Testcontainers 設定

# ~/.testcontainers.properties(或用環境變數)
docker.host=unix:///run/user/1000/podman/podman.sock
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=$XDG_RUNTIME_DIR/podman/podman.sock
# Ryuk(清理用的容器)需要掛載 socket;rootless 遇到權限問題時可以改用特權模式或停用
export TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED=true

📌 停用 Ryuk(TESTCONTAINERS_RYUK_DISABLED=true)會讓測試中斷時留下殘留容器,CI 環境要另外安排清理工作。

9.6 遠端連線

# 透過 SSH 管理遠端主機上的 Podman
podman system connection add prod-01 ssh://deploy@prod-01.corp.example/run/user/1001/podman/podman.sock
podman system connection list
podman --connection prod-01 ps

# 5.7 起支援 TLS/mTLS 的 TCP 連線(適合不能開 SSH 的環境)
podman system connection add prod-02 tcp://prod-02.corp.example:8888 \
  --tls-ca /etc/pki/corp/ca.pem --tls-cert ~/.pki/client.pem --tls-key ~/.pki/client.key

9.7 💡 本章實務建議

  1. 開發環境統一用 podman compose 當入口,並在 containers.conf 固定 provider,避免每台電腦行為不同。
  2. Compose 用於開發與測試;正式主機改用 Quadlet(可以用 .kube 或個別的 .container 表達同樣的架構)。
  3. 需要 Docker API 的工具透過 podman.socket 連線,不要安裝 Docker daemon 與 Podman 並存,避免混淆。
  4. Compose 檔裡的密碼一律用 secrets,不要直接寫在 environment。

9.8 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1Docker 相容 socket 可以使用curl -s --unix-socket "$XDG_RUNTIME_DIR/podman/podman.sock" http://d/_pingOK
2Compose 檔可以正確解析podman compose config > /dev/null; echo $?0
3實際使用的 Compose providerpodman compose version 2>&1 | head -2第一行的 Executing external compose provider 指向公司指定的 provider
4Testcontainers 可以啟動容器執行一個使用 Testcontainers 的測試測試通過,結束後沒有殘留容器

10. 安全性強化

10.1 縱深防禦模型

graph TB
    L1["第 1 層:供應鏈<br/>核准的基底映像檔、簽章、SBOM、漏洞掃描"] --> L2
    L2["第 2 層:映像檔<br/>非 root 使用者、最小化、不含機密"] --> L3
    L3["第 3 層:執行期<br/>rootless、user namespace、capabilities、seccomp、唯讀根目錄"] --> L4
    L4["第 4 層:主機<br/>SELinux、cgroups v2 資源限制、nftables"] --> L5
    L5["第 5 層:維運<br/>稽核日誌、auto-update、事件監控"]

10.2 Rootless 與 User Namespace

rootless 是 Podman 最重要的安全特性:就算攻擊者逃出容器,在主機上也只有一般使用者的權限。

--userns 模式容器內 root 對應到主機上的你對應到用途
(rootless 預設)你的 UID容器內的 root一般用途
keep-idsubordinate UID相同的 UID開發時掛載原始碼,避免權限錯亂
keep-id:uid=1001,gid=1001subordinate UID指定的 UID/GID映像檔使用固定的非 root UID
auto自動配置一段獨立的 UID 範圍不對應多個容器彼此隔離(rootful 時需要 containers 使用者的 subuid)
nomapsubordinate UID不對應容器完全碰不到你的檔案
# 確認容器內外的身分對應
podman run --rm --userns=keep-id docker.io/library/alpine:3 id
podman top -l user huser     # 比較容器內與主機上的 UID

⚠️ rootful 容器也要降低權限:必須以 root 執行 Podman 時(例如使用 macvlan),請搭配 --userns=auto,讓每個容器使用不同的 UID 範圍。

10.3 Capabilities 與 Seccomp

Podman 預設只給容器 11 個 capabilities,比 Docker 預設的少(沒有 NET_RAW、MKNOD、AUDIT_WRITE):

CHOWN, DAC_OVERRIDE, FOWNER, FSETID, KILL, NET_BIND_SERVICE,
SETFCAP, SETGID, SETPCAP, SETUID, SYS_CHROOT
# 最小權限:全部移除,只加回需要的
podman run -d --name api \
  --cap-drop=ALL \
  --security-opt no-new-privileges \
  --read-only --tmpfs /tmp:rw,size=64m,noexec,nosuid \
  --user 1001:1001 \
  --pids-limit 512 --memory 1g --cpus 1 \
  registry.corp.example/app/api:1.4.2

# 查看容器實際擁有的 capabilities
podman inspect api --format '{{.EffectiveCaps}}'
  • Seccomp:預設套用 /usr/share/containers/seccomp.json,阻擋容器通常不需要的危險系統呼叫(例如載入核心模組、重新開機)。可以用 --security-opt seccomp=profile.json 套用更嚴格的設定;也可以用 OCI seccomp BPF hook 記錄應用程式實際用到的系統呼叫,再產生專屬設定檔。
  • ⚠️ 禁止在正式環境使用 --privileged:它會關閉 seccomp、SELinux 隔離,並給予全部 capabilities。

10.4 SELinux

# 確認 SELinux 為 enforcing
getenforce

# 容器程序的標籤:container_t 加上唯一的 MCS 類別(例如 s0:c123,c456)
podman run -d --name demo docker.io/library/nginx:stable
ps -eZ | grep nginx

# 需要特殊存取時,用 udica 產生專屬政策,而不是關閉 SELinux
podman inspect demo > demo.json
sudo udica -j demo.json my_nginx
sudo semodule -i my_nginx.cil /usr/share/udica/templates/base_container.cil
podman run --security-opt label=type:my_nginx.process ...
做法評價
setenforce 0❌ 絕對禁止
--security-opt label=disable⚠️ 只限短期除錯
bind mount 加 :Z/:z✅ 標準做法
用 udica 產生客製政策✅ 需要特殊存取時的做法

10.5 Secret 管理

# 建立(從 stdin 讀入,避免留在 shell 歷史紀錄)
printf '%s' "$DB_PASSWORD" | podman secret create db_password -
podman secret create --driver file --label app=shop tls_key ./tls.key
podman secret ls
podman secret inspect db_password            # 不會顯示內容
podman secret inspect --showsecret db_password   # 需要時才顯示

# 使用:預設掛載成 /run/secrets/<名稱>
podman run --secret db_password ...
podman run --secret db_password,type=env,target=DB_PASSWORD ...
podman run --secret tls_key,target=/etc/app/tls.key,mode=0400,uid=1001 ...

# 更新(同名 secret 直接取代)
printf '%s' "$NEW_PASSWORD" | podman secret create --replace db_password -
Driver儲存方式適用
file(預設)本機檔案(未加密,靠檔案權限保護)開發、一般主機
pass以 GPG 加密的 pass 儲存庫需要靜態加密
shell呼叫自訂腳本存取外部系統(例如 HashiCorp Vault、CyberArk)企業建議:與既有的機密管理平台整合

⚠️ ENV、ARG、Compose 的 environment 都會出現在 podman inspect 的輸出與映像檔的 metadata 裡,不能用來傳遞機密。

10.6 映像檔簽章與驗證

Podman 支援兩種簽章:sigstore(與 cosign 相容,簽章以 OCI artifact 存放在 registry,建議採用)與傳統的 GPG simple signing。

# 1. 產生金鑰(使用 cosign)
cosign generate-key-pair

# 2. 推送時簽章
podman push --sign-by-sigstore-private-key ./cosign.key \
  registry.corp.example/app/api:1.4.2
# 3. 讓 Podman 讀寫 sigstore 附件:/etc/containers/registries.d/corp.yaml
docker:
  registry.corp.example:
    use-sigstore-attachments: true
{
  "default": [{ "type": "reject" }],
  "transports": {
    "docker": {
      "registry.corp.example": [
        {
          "type": "sigstoreSigned",
          "keyPath": "/etc/pki/containers/cosign.pub",
          "signedIdentity": { "type": "matchRepository" }
        }
      ],
      "registry.access.redhat.com": [
        {
          "type": "signedBy",
          "keyType": "GPGKeys",
          "keyPath": "/etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release"
        }
      ]
    },
    "docker-daemon": { "": [{ "type": "insecureAcceptAnything" }] }
  }
}

上面是 /etc/containers/policy.json 的範例:預設拒絕,只接受公司 registry 上有正確 sigstore 簽章的映像檔,以及 Red Hat 官方簽章的映像檔。

# 檢視目前的信任策略(6.0 起 trust set 需要 --signature-policy 指定檔案)
podman image trust show

📌 如果使用 Fulcio/Rekor 的 keyless 簽章,policy.json 要改用 fulcio 與 rekorPublicKeyPath 欄位,詳見 man containers-policy.json。

10.7 SBOM 與漏洞掃描

# 建置時同時產生 SBOM(使用 syft 掃描器映像檔)
podman build --sbom syft-cyclonedx \
  --sbom-output=api.cdx.json -t registry.corp.example/app/api:1.4.2 .

# Trivy(0.76):掃描本機的 Podman 映像檔
trivy image --image-src podman --severity HIGH,CRITICAL --exit-code 1 \
  registry.corp.example/app/api:1.4.2

# Grype(0.121)
grype podman:registry.corp.example/app/api:1.4.2 --fail-on high
關卡做法未通過時
PR/建置掃描 HIGH/CRITICAL,並產生 SBOM阻擋合併
推送到 registry簽章,並把 SBOM 以 artifact 附在映像檔上禁止推送
部署policy.json 驗證簽章拒絕拉取
執行期每日重新掃描既有映像檔,比對新公布的 CVE開立修補工單

10.8 安全基準對照

控制項Podman 做法對應規範
最小權限執行rootless、--cap-drop=ALL、USER 1001NIST SP 800-190 §4.4 容器風險;CIS Docker Benchmark 第 4、5 章
映像檔來源可信policy.json 驗證簽章、內部 mirrorNIST SP 800-190 §4.1–4.2 映像檔與 registry 風險;SLSA
機密保護podman secret(shell driver 串接 Vault)ISO 27001:2022 A.5.17
資源隔離cgroups v2 限制記憶體、CPU、PIDCIS 5.x
稽核軌跡podman events 寫入 journald,轉送到 SIEMISO 27001:2022 A.8.15
弱點管理SBOM 加上持續掃描金融業資安規範的弱點管理要求

10.9 安全修補版本基準

🆕 v3.0 新增:v2.0 只寫了「使用最新版」,沒有定義「最低可接受版本」,稽核時無法判定合格與否。

10.9.1 近期影響 Podman 的 CVE

CVE影響修正版本暫時的緩解措施
CVE-2026-17106惡意 tar 透過連結寫到解壓目錄之外6.1.1不要匯入來源不明的 tar
CVE-2025-11395podman load 匯入特製的 layer tar,或 podman volume import 匯入特製的 symlink,可以覆寫主機檔案6.1.2/5.8.7只匯入來自內部 registry、而且驗證過簽章的檔案
CVE-2026-94603podman run 執行 checkpoint 映像檔(帶有 io.podman.annotations.checkpoint.runtime.name annotation 的映像檔)時,會停用所有沙箱,連使用者指定的安全設定也會失效6.1.3/5.8.8(修正方式是移除這個功能)在 policy.json 拒絕不明來源;只用 podman container restore 還原
CVE-2026-107935gvproxy(podman machine 的網路元件)6.1.4/5.8.9開發者桌面升級 Podman 或 Podman Desktop 1.30.5

10.9.2 公司基準與檢查腳本

版本線最低可接受版本理由
6.x6.1.3涵蓋上表前三項 CVE(主機端)
5.x5.8.8同上,供還不能升級到 6.x 的主機(Windows 10、Intel Mac、RHEL 隨附版本)使用
開發者桌面6.1.4/5.8.9另外涵蓋 gvproxy 的 CVE
RHEL依 RHSA 判定Red Hat 會回補修正,版本號不會跟著上游變
#!/usr/bin/env bash
# podman-patch-check.sh:檢查這台主機的 Podman 是否達到公司的最低修補版本
# 用法:./podman-patch-check.sh            (讀取本機 podman version)
#       ./podman-patch-check.sh 6.1.2      (直接檢查指定的版本字串,供 CI 測試)
# 結束碼:0 = 合格;1 = 低於基準;2 = 無法判斷
set -euo pipefail

MIN_6="6.1.3"   # CVE-2026-94603(checkpoint 映像檔沙箱繞過)、CVE-2025-11395
MIN_5="5.8.8"

# podman --version 不需要連到服務端(podman machine 沒啟動也能用);輸出如 "podman version 6.1.4"
ver="${1:-$(podman --version 2>/dev/null | awk '{print $3}' || true)}"
ver="${ver%%-*}"                       # 去掉 -rc1、-dev 等後綴
if [[ ! "$ver" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
  echo "UNKNOWN:無法取得 Podman 版本('$ver')"; exit 2
fi

case "${ver%%.*}" in
  6) min="$MIN_6" ;;
  5) min="$MIN_5" ;;
  *) echo "FAIL:$ver 已不在維護範圍,請升級到 6.x"; exit 1 ;;
esac

# sort -V 排序後,最小的若不是 min,代表 ver < min
lowest="$(printf '%s\n%s\n' "$ver" "$min" | sort -V | head -1)"
if [[ "$lowest" == "$min" ]]; then
  echo "PASS:$ver ≥ $min"
else
  echo "FAIL:$ver < $min,請升級(RHEL 請改查 rpm -q --changelog podman 是否含修補)"
  exit 1
fi

✅ 驗證方式(腳本本身的測試,可以放進 CI):

bash -n podman-patch-check.sh                       # 語法檢查
./podman-patch-check.sh 6.1.4;     echo $?          # 預期:PASS,0
./podman-patch-check.sh 6.1.2;     echo $?          # 預期:FAIL,1
./podman-patch-check.sh 6.2.0-rc1; echo $?          # 預期:PASS,0(後綴會被去掉)
./podman-patch-check.sh 5.8.7;     echo $?          # 預期:FAIL,1
./podman-patch-check.sh 4.9.4;     echo $?          # 預期:FAIL,1(不在維護範圍)
./podman-patch-check.sh garbage;   echo $?          # 預期:UNKNOWN,2

📌 作者在 Windows 11(Git Bash)上,以上述 11 個版本字串與本機 Podman 5.8.3 實際執行過這支腳本,結果與預期相符:本機的 5.8.3 被判定為 FAIL。

RHEL 主機不要只看版本號,要確認 Red Hat 已經回補修正:

rpm -q --changelog podman | grep -E 'CVE-2025-11395|CVE-2026-94603' \
  || echo "尚未看到回補紀錄,請查 RHSA 公告"

10.10 💡 本章實務建議

  1. rootless 是預設值:rootful 必須申請例外,並搭配 --userns=auto。
  2. 執行期的安全基準:--cap-drop=ALL、no-new-privileges、--read-only、資源限制,寫進 Quadlet 範本強制套用。
  3. SELinux 永遠是 enforcing,權限問題用 :Z 或 udica 解決。
  4. policy.json 採預設拒絕,只信任公司 registry 的簽章與原廠簽章。
  5. 機密透過 shell driver 串接公司的機密管理平台,不要把機密留在主機的檔案裡。
  6. 🆕 把 podman-patch-check.sh 納入主機合規掃描(例如 Ansible 或 Satellite 排程)。低於基準的主機列入修補工單,修補版的 breaking change 請對照 1.4.2。

10.11 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1以 rootless 執行podman info --format '{{.Host.Security.Rootless}}'true
2只有必要的 capabilitiespodman inspect -f '{{.EffectiveCaps}}' <容器>只有核准清單上的項目
3禁止取得新權限podman inspect -f '{{.HostConfig.SecurityOpt}}' <容器>包含 no-new-privileges
4SELinux 為 enforcinggetenforceEnforcing
5拉取時會驗證簽章podman pull <未簽章的映像檔>失敗,訊息含 signature
6版本達到修補基準./podman-patch-check.shPASS,結束碼 0

11. 企業 Registry 與供應鏈

11.1 企業 Registry 架構

graph LR
    subgraph 外部
        DH[docker.io]
        RH[registry.access.redhat.com<br/>registry.redhat.io]
        Q[quay.io]
    end
    subgraph 公司 DMZ
        PX[Registry Proxy/Mirror<br/>Harbor、Quay、Nexus、Artifactory]
    end
    subgraph 公司內網
        INT[內部 Registry<br/>公司自有映像檔]
        DEV[開發者/CI]
        PRD[正式主機]
    end
    DH --> PX
    RH --> PX
    Q --> PX
    PX -->|掃描+核准| INT
    DEV -->|push 簽章後的映像檔| INT
    INT -->|pull 並驗證簽章| PRD

設計原則:

  • 正式主機不直接連網際網路,只從內部 registry 拉取。
  • 外部映像檔經過 proxy 快取、掃描、核准後,才複製到內部 registry。
  • 每個專案或團隊使用自己的命名空間,並設定推送權限與保留政策。

11.2 registries.conf

# /etc/containers/registries.conf.d/10-corp.conf(Podman 6 只接受 V2 格式)

# 短名稱只搜尋公司的 registry
unqualified-search-registries = ["registry.corp.example"]

# 短名稱有歧義時直接失敗(不詢問)
short-name-mode = "enforcing"

# docker.io 一律走公司 mirror
[[registry]]
prefix = "docker.io"
location = "docker.io"
  [[registry.mirror]]
  location = "mirror.corp.example/dockerhub"

# Red Hat 映像檔走 mirror
[[registry]]
prefix = "registry.access.redhat.com"
location = "registry.access.redhat.com"
  [[registry.mirror]]
  location = "mirror.corp.example/redhat"

# 封鎖未核准的來源
[[registry]]
location = "ghcr.io"
blocked = true

# 測試用的內部 registry(沒有 TLS,正式環境禁止)
[[registry]]
location = "registry-test.corp.example:5000"
insecure = true
欄位說明
unqualified-search-registries短名稱的搜尋清單
short-name-modeenforcing(有歧義就失敗)、permissive、disabled
prefix/location把符合 prefix 的映像檔導向 location
mirror依序嘗試的鏡像站;可以加上 pull-from-mirror = "digest-only" 只在用 digest 拉取時使用 mirror
blocked禁止拉取
insecure允許 HTTP 或不驗證 TLS

另外,/etc/containers/registries.conf.d/000-shortnames.conf 提供了常見短名稱的別名(例如 nginx 對應到 docker.io/library/nginx)。

⚠️ v2.0 更正:v1.0 的範例把 V1 格式([registries.search]、[registries.block])與 V2 格式([[registry]])寫在同一個檔案裡,這種混用會讓 Podman 直接報錯;而且 Podman 6 已經完全移除 V1 格式。請改用本節的 V2 寫法,並用 podman info --format '{{.Registries}}' 確認實際生效的設定。

11.3 登入與憑證

# 互動式登入
podman login registry.corp.example

# CI:從 stdin 讀入 token
echo "$REGISTRY_TOKEN" | podman login -u "$REGISTRY_USER" --password-stdin registry.corp.example

# 指定憑證檔(預設:rootless 為 $XDG_RUNTIME_DIR/containers/auth.json,重開機後會消失)
podman login --authfile /etc/containers/auth/corp.json registry.corp.example
export REGISTRY_AUTH_FILE=/etc/containers/auth/corp.json

podman login --get-login registry.corp.example
podman logout registry.corp.example

Credential helper:在 auth.json 裡設定 credHelpers,把憑證交給作業系統的金鑰管理(例如 secretservice、wincred、osxkeychain)或雲端的 helper(例如 ecr-login),避免以明文存放。

{
  "credHelpers": {
    "123456789012.dkr.ecr.ap-northeast-1.amazonaws.com": "ecr-login"
  }
}

11.4 自建 Registry

# 快速測試用的 Registry(CNCF Distribution v3)
podman volume create registry-data
podman run -d --name registry -p 5000:5000 \
  -v registry-data:/var/lib/registry:Z \
  docker.io/library/registry:3

podman tag localhost/shop/api:dev localhost:5000/shop/api:dev
podman push --tls-verify=false localhost:5000/shop/api:dev

正式環境建議使用具備以下功能的產品:

功能HarborRed Hat Quay說明
RBAC 與 LDAP/OIDC 整合✅✅帳號與權限管理
漏洞掃描TrivyClair推送時自動掃描
簽章驗證政策✅✅阻擋未簽章的映像檔
Proxy cache✅✅快取外部 registry
複寫✅✅異地備援、多資料中心
保留政策✅✅自動清理舊的 tag

11.5 Skopeo:不落地的映像檔操作

# 不拉取映像檔,直接檢視 metadata
skopeo inspect docker://registry.access.redhat.com/ubi10/ubi-minimal
skopeo list-tags docker://docker.io/library/postgres

# 在 registry 之間複製(包含所有架構)
skopeo copy --all \
  docker://docker.io/library/postgres:17 \
  docker://registry.corp.example/base/postgres:17

# 保留原始 digest(簽章依 digest 驗證,改變 digest 會讓簽章失效)
skopeo copy --all --preserve-digests \
  docker://registry.access.redhat.com/ubi10/ubi-minimal:latest \
  docker://registry.corp.example/base/ubi-minimal:latest

# 刪除 registry 上的 tag
skopeo delete docker://registry.corp.example/shop/api:old

11.6 離線(Air-gapped)環境

# sync.yaml:要帶進離線環境的映像檔清單
registry.access.redhat.com:
  images:
    ubi10/ubi-minimal: ["latest"]
    ubi9/openjdk-21-runtime: ["latest"]
docker.io:
  images:
    library/postgres: ["17"]
    nginxinc/nginx-unprivileged: ["stable-alpine"]
# 1. 在可連外的主機,同步到本機目錄
skopeo sync --all --src yaml --dest dir sync.yaml /media/transfer/images

# 2. 以核准的媒介帶入離線環境後,同步到內部 registry
skopeo sync --all --src dir --dest docker /media/transfer/images registry.airgap.corp.example

# 單一映像檔也可以用 save/load
podman save --multi-image-archive -o bundle.tar img1 img2
podman load -i bundle.tar

# 在主機之間直接傳送映像檔(透過 SSH)
podman image scp registry.corp.example/shop/api:2.3.0 deploy@prod-01::

⚠️ 離線環境還要準備 Pod 的 infra 映像檔(podman info 可以查到預設值)以及 podman machine 的 VM 映像檔。

11.7 OCI Artifact

podman artifact 把任意檔案(設定檔、AI 模型、SBOM、Helm chart)當成 OCI artifact,存放在同一個 registry 裡,沿用同一套權限、簽章與複寫機制。

# 建立並推送
podman artifact add registry.corp.example/config/shop:2026.09 ./app.yaml ./logback.xml
podman artifact push registry.corp.example/config/shop:2026.09

# 拉取、檢視、解開
podman artifact pull registry.corp.example/config/shop:2026.09
podman artifact ls
podman artifact inspect registry.corp.example/config/shop:2026.09
podman artifact extract registry.corp.example/config/shop:2026.09 ./out/

# 直接掛進容器(5.5 新增)
podman run --mount type=artifact,src=registry.corp.example/config/shop:2026.09,dst=/etc/shop \
  registry.corp.example/shop/api:2.3.0

podman artifact rm registry.corp.example/config/shop:2026.09

在 Quadlet 裡可以用 .artifact 單元檔(5.7 新增)在開機時預先拉取 artifact。

11.8 映像檔標記策略

Tag用途是否可變
1.4.2正式發行版本❌ 不可覆寫(在 registry 設定不可變)
1.4/1自動套用修補版(搭配 auto-update)✅
sha-<git短雜湊>對應到 commit,方便追溯❌
latest只用於開發✅(正式環境禁用)

11.9 💡 本章實務建議

  1. 所有主機統一派送 registries.conf.d/10-corp.conf:短名稱只搜尋公司 registry,外部來源一律走 mirror。
  2. 正式主機只能拉取內部 registry,並以 policy.json 驗證簽章(見第 10 章)。
  3. 憑證不要長期存放在主機上:CI 使用短期 token;主機使用唯讀帳號,並透過 credential helper 管理。
  4. 離線環境用 skopeo sync 搭配清單檔,清單納入 Git 管理,每次同步都要留下紀錄。
  5. 設定檔與模型改用 OCI artifact 發佈,與映像檔共用同一套治理機制。

11.10 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1短名稱策略為 enforcinggrep -r 'short-name-mode' /etc/containers/registries.conf*short-name-mode = "enforcing"
2docker.io 走公司 mirrorpodman pull docker.io/library/alpine:3 --log-level=debug 2>&1 | grep -m1 'Trying to access'主機名稱是公司的 mirror
3封鎖的來源真的被擋podman pull <被封鎖的 registry>/x:1失敗,訊息含 blocked
4複製時保留 digest比較 skopeo inspect --format '{{.Digest}}' 在來源與目的的結果兩個 digest 相同
5登入憑證不在版本庫中git ls-files | grep -E 'auth\.json$'沒有結果

12. CI/CD 整合

12.1 標準流水線

flowchart LR
    A[Checkout] --> B[建置映像檔<br/>Buildah/podman build]
    B --> C[單元與整合測試<br/>Testcontainers]
    C --> D[漏洞掃描+SBOM]
    D --> E{HIGH/CRITICAL?}
    E -->|有| X[失敗並通知]
    E -->|無| F[簽章 sigstore]
    F --> G[推送到內部 Registry]
    G --> H[部署<br/>Quadlet/GitOps]

Podman/Buildah 在 CI 裡的優點:不需要 Docker daemon,也不需要掛載 /var/run/docker.sock,建置工作可以在一般權限(rootless)下完成,避免「CI 工作可以控制整台 runner」的風險。

12.2 GitHub Actions

# .github/workflows/image.yml
name: build-image

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]

env:
  REGISTRY: registry.corp.example/shop
  IMAGE: api

jobs:
  build:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7

      - name: Build image
        id: build
        uses: redhat-actions/buildah-build@v3
        with:
          image: ${{ env.IMAGE }}
          tags: ${{ github.sha }} ${{ github.ref_type == 'tag' && github.ref_name || 'dev' }}
          containerfiles: ./Containerfile
          oci: true
          labels: |
            org.opencontainers.image.revision=${{ github.sha }}
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}

      - name: Scan image
        run: |
          podman save --format oci-archive -o image.tar ${{ steps.build.outputs.image-with-tag }}
          podman run --rm -v "$PWD:/work:Z" docker.io/aquasec/trivy:0.74.0 \
            image --input /work/image.tar --severity HIGH,CRITICAL --exit-code 1

      - name: Push image
        if: github.event_name != 'pull_request'
        uses: redhat-actions/push-to-registry@v3
        with:
          image: ${{ steps.build.outputs.image }}
          tags: ${{ steps.build.outputs.tags }}
          registry: ${{ env.REGISTRY }}
          username: ${{ secrets.REGISTRY_USER }}
          password: ${{ secrets.REGISTRY_TOKEN }}
          sigstore-private-key: ${{ secrets.COSIGN_PRIVATE_KEY }}
Action目前版本(2026-09)用途
actions/checkoutv7取出原始碼
redhat-actions/buildah-buildv3(3.1.0)用 Buildah 建置,支援多架構;3.1.0 新增 sequential 模式
redhat-actions/podman-loginv2登入 registry
redhat-actions/push-to-registryv3推送,並可以用 sigstore 簽章

需要多架構映像檔時,可以在 buildah-build 加上 archs: amd64, arm64(runner 要先安裝 qemu-user-static),並改用 skopeo inspect --raw 逐一取出各架構映像檔來掃描。

⚠️ v2.0 更正:v1.0 使用 actions/checkout@v3,並在 runner 上用 apt-get install podman。GitHub 的 Ubuntu runner 已經預先安裝 Podman 與 Buildah,不需要另外安裝;Action 的版本也已更新。

金融業通常使用 self-hosted runner。建議在 RHEL runner 上以一般使用者執行 Podman,並定期清理 ~/.local/share/containers。

12.3 GitLab CI

# .gitlab-ci.yml
stages: [build, test, scan, publish]

variables:
  IMAGE: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
  # 在沒有特權的容器內執行 Buildah
  STORAGE_DRIVER: vfs
  BUILDAH_ISOLATION: chroot
  BUILDAH_FORMAT: oci

.buildah:
  image: quay.io/buildah/stable:latest
  before_script:
    - echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"

build:
  extends: .buildah
  stage: build
  script:
    - buildah build --layers -t "$IMAGE" .
    - buildah push "$IMAGE"
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

test:
  stage: test
  image: $IMAGE
  script:
    - ./run-tests.sh

scan:
  stage: scan
  image:
    name: docker.io/aquasec/trivy:0.74.0
    entrypoint: [""]
  script:
    - trivy image --severity HIGH,CRITICAL --exit-code 1 "$IMAGE"

publish:
  extends: .buildah
  stage: publish
  script:
    - buildah pull "$IMAGE"
    - buildah tag "$IMAGE" "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
    - buildah push "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG

重點:

  • STORAGE_DRIVER=vfs 與 BUILDAH_ISOLATION=chroot 讓 Buildah 可以在沒有特權的 Kubernetes executor 容器內執行(代價是建置速度較慢、占用較多空間)。
  • 如果 runner 允許 /dev/fuse,可以改用 overlay 加上 fuse-overlayfs 提升速度。
  • 部署到主機的步驟,建議改用 Ansible 或 GitOps 更新 Quadlet 檔與映像檔 tag,而不是在 CI 裡直接 podman run。

12.4 Jenkins

// Jenkinsfile(agent 為安裝了 Podman 的 RHEL 節點,以一般使用者執行)
pipeline {
  agent { label 'podman' }
  environment {
    IMAGE = "registry.corp.example/shop/api:${env.GIT_COMMIT.take(8)}"
  }
  stages {
    stage('Build') {
      steps {
        sh 'podman build --pull=always -t "$IMAGE" .'
      }
    }
    stage('Test') {
      steps {
        sh 'podman run --rm "$IMAGE" ./run-tests.sh'
      }
    }
    stage('Scan') {
      steps {
        sh 'trivy image --image-src podman --severity HIGH,CRITICAL --exit-code 1 "$IMAGE"'
      }
    }
    stage('Push') {
      when { branch 'main' }
      steps {
        withCredentials([usernamePassword(credentialsId: 'corp-registry',
                         usernameVariable: 'U', passwordVariable: 'P')]) {
          sh 'echo "$P" | podman login -u "$U" --password-stdin registry.corp.example'
          sh 'podman push --sign-by-sigstore-private-key /etc/pki/ci/cosign.key "$IMAGE"'
        }
      }
    }
  }
  post {
    always {
      sh 'podman image prune -f || true'
    }
  }
}

12.5 Tekton/OpenShift Pipelines

在 OpenShift 上,建議使用 OpenShift Pipelines(Tekton)內建的 buildah Task,或改用 Shipwright。建置在叢集內以受限的權限(SCC)執行,並可以串接 Tekton Chains,自動產生簽章與 SLSA provenance。

# 片段:在 Pipeline 裡使用 buildah Task
- name: build-image
  taskRef:
    resolver: cluster
    params:
      - name: kind
        value: task
      - name: name
        value: buildah
      - name: namespace
        value: openshift-pipelines
  params:
    - name: IMAGE
      value: image-registry.openshift-image-registry.svc:5000/shop/api:$(params.revision)
  workspaces:
    - name: source
      workspace: shared-workspace

12.6 CI 環境的注意事項

問題原因處理方式
potentially insufficient UIDs or GIDs availableCI 使用者沒有 subuid/subgid在 runner 映像檔設定 /etc/subuid,或改用 --userns=host 的 Buildah 映像檔
建置越來越慢、磁碟被塞滿快取與 dangling 映像檔累積在 post 階段執行 podman image prune,並定期執行 podman system prune
在容器內執行 Podman 失敗缺少 /dev/fuse 或 user namespace使用 quay.io/podman/stable 並參考官方的「Podman in a container」指引
Testcontainers 找不到 Docker沒有 socketsystemctl --user start podman.socket 並設定 DOCKER_HOST

12.7 💡 本章實務建議

  1. CI 裡不要掛載 Docker socket,改用 Buildah/Podman rootless 建置。
  2. 建置、掃描、簽章、推送四個步驟缺一不可,並把掃描結果與 SBOM 保存為建置產物。
  3. Action 與掃描器要固定版本(例如 trivy:0.74.0),並用 Dependabot 或 Renovate 定期更新。
  4. 部署與建置分離:CI 只負責產出經過簽章的映像檔,部署交給 GitOps 或 Ansible 更新 Quadlet。

12.8 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1CI 以 rootless 建置在 CI job 執行 podman info --format '{{.Host.Security.Rootless}}'true
2每個映像檔都有 SBOM 與簽章cosign verify --key cosign.pub <映像檔>驗證成功
3掃描關卡真的會擋故意使用含已知 CVE 的舊版基底映像檔重跑流水線流水線在掃描階段失敗
4映像檔的 tag 對應 commitpodman image inspect -f '{{index .Labels "org.opencontainers.image.revision"}}' <映像檔>等於該次建置的 Git commit SHA

13. 監控、日誌與維運

13.1 日誌

13.1.1 Log driver

Driver說明輪替方式
journald寫入 systemd journal(systemd 系統的預設值)由 journald.conf 的 SystemMaxUse 等設定控制
k8s-file寫入 Kubernetes 格式的文字檔--log-opt max-size=10mb,或 containers.conf 的 log_size_max
passthrough直接交給 systemd 的 stdout/stderr(只用於 systemd 管理的容器)由 journald 控制
none不記錄—

⚠️ v2.0 更正:v1.0 的範例 --log-driver journald --log-opt max-size=10m --log-opt max-file=3 是 Docker 的 json-file 寫法:max-size 只對 k8s-file 有效,Podman 也沒有 max-file 選項。使用 journald 時,保留量與輪替要在 journald 設定。

# 查看日誌
podman logs -f --since 10m --tail 200 api
podman logs --timestamps api

# journald:可以用欄位過濾
journalctl CONTAINER_NAME=api --since "1 hour ago"
journalctl --user -u web.service -o json-pretty | head

# 用 tag/label 加上可供搜尋的欄位(label 為 6.0 新增,只支援 journald)
podman run -d --log-driver journald \
  --log-opt tag='{{.ImageName}}' \
  --log-opt label=APP=shop \
  registry.corp.example/shop/api:2.3.0

# k8s-file 並限制大小
podman run -d --log-driver k8s-file --log-opt max-size=20mb ...

13.1.2 集中式日誌

graph LR
    C1[容器] -->|journald| J[systemd-journald]
    C2[容器] -->|journald| J
    J --> A[收集代理<br/>Fluent Bit/Vector/rsyslog]
    A --> S[(SIEM/Elasticsearch/Loki)]
    E[podman events] --> J

建議讓容器使用 journald,再由主機上的代理程式統一轉送。這樣容器本身不需要安裝任何收集元件,也能保留 CONTAINER_NAME、CONTAINER_ID、IMAGE_NAME 等結構化欄位。

13.2 事件

# 即時監看
podman events
podman events --filter event=died --filter event=health_status --format json

# 查詢過去的事件
podman events --since 24h --until 1h --filter type=image
事件類型常見事件監控用途
containercreate、start、died(6.0 起帶有 OOMKilled 屬性)、health_status異常重啟、記憶體不足、健康檢查失敗
imagepull、push、remove供應鏈稽核
volume/network/podcreate、remove變更追蹤
secretcreate、remove(5.5 起)機密存取稽核
artifactcreate、pull、push、remove(6.0 起)設定與模型發佈追蹤

containers.conf 的 events_logger 預設為 journald。如果主機上有大量 healthcheck,可以設定 healthcheck_events = false,避免 health_status 事件洗版。

13.3 資源監控

podman stats                               # 即時
podman stats --no-stream --format json     # 給腳本使用
podman pod stats shop
podman top api pid user %cpu %mem
podman system df

13.3.1 Prometheus 整合

prometheus-podman-exporter(2.0.0)透過 Podman API 匯出容器、Pod、映像檔、volume、網路的指標,預設監聽 :9882。

# 方法一:以套件安裝(Fedora/RHEL 系列)
sudo dnf -y install prometheus-podman-exporter

# 方法二:以容器執行(rootless)
systemctl --user enable --now podman.socket
podman run -d --name podman-exporter \
  -e CONTAINER_HOST=unix:///run/podman/podman.sock \
  -v $XDG_RUNTIME_DIR/podman/podman.sock:/run/podman/podman.sock \
  -p 9882:9882 \
  --userns=keep-id:uid=65534 \
  --security-opt label=type:container_runtime_t \
  quay.io/navidys/prometheus-podman-exporter \
  --collector.enable-all
# prometheus.yml
scrape_configs:
  - job_name: podman
    static_configs:
      - targets: ["app-host-01:9882", "app-host-02:9882"]

建議的告警規則

告警條件嚴重度
容器頻繁重啟15 分鐘內 died 事件超過 3 次高
健康檢查失敗health_status 為 unhealthy 超過 5 分鐘高
OOMdied 事件的 OOMKilled=true高
儲存空間graphroot 使用率超過 80%中
映像檔過舊執行中的映像檔建立時間超過 90 天低

13.4 系統維護

# 清理
podman container prune                  # 停止的容器
podman image prune -a                   # 沒有被使用的映像檔
podman volume prune                     # 6.0 起只清匿名 volume
podman network prune
podman system prune                     # 以上全部(不含 volume)
podman system prune --all --volumes     # ⚠️ 包含所有未使用的映像檔與 volume

# 儲存一致性檢查與修復(例如不正常關機之後)
podman system check
podman system check --repair

# 完全重置(刪除所有容器、映像檔、volume、網路與設定)
podman system reset

排程清理可以用 systemd timer:

# ~/.config/systemd/user/podman-prune.service
[Unit]
Description=Weekly podman cleanup

[Service]
Type=oneshot
ExecStart=/usr/bin/podman image prune -a -f --filter until=720h
ExecStart=/usr/bin/podman container prune -f --filter until=168h
# ~/.config/systemd/user/podman-prune.timer
[Timer]
OnCalendar=Sun 03:00
Persistent=true

[Install]
WantedBy=timers.target
systemctl --user daemon-reload
systemctl --user enable --now podman-prune.timer

13.5 開機自動啟動

做法說明
Quadlet(建議)[Install] WantedBy= 設定,見第 8 章
podman-restart.service開機時重新啟動所有 --restart=always 的容器:systemctl enable podman-restart.service(rootless 加 --user)

13.6 Checkpoint/Restore(CRIU)

Podman 可以透過 CRIU 把執行中的容器狀態(記憶體、程序)存成檔案,之後在同一台或另一台主機還原。適合用在長時間暖機的應用、主機維護時的遷移,或保存故障現場供分析。

# 需要 rootful 與 criu 套件
sudo dnf -y install criu

# 建立 checkpoint 並匯出
sudo podman container checkpoint --export /backup/api.tar.gz api

# 保持容器繼續執行(6.0 起會暫停容器直到 checkpoint 完成,確保一致性)
sudo podman container checkpoint --leave-running --export /backup/api-live.tar.gz api

# 在另一台主機還原
sudo podman container restore --import /backup/api.tar.gz

# 也可以存成 checkpoint 映像檔,推送到 registry
sudo podman container checkpoint --create-image registry.corp.example/ckpt/api:20260929 api

# 從 checkpoint 映像檔還原:一律用 restore
sudo podman container restore --name api-restored registry.corp.example/ckpt/api:20260929

⚠️ v3.0 更正(CVE-2026-94603):v2.0 沒有提醒 checkpoint 映像檔的安全風險。6.1.3/5.8.8 起,podman run 不再接受 checkpoint 映像檔。舊版用 podman run 執行 checkpoint 映像檔時,會忽略使用者指定的安全設定,並停用所有沙箱。只能用 podman container restore 還原。checkpoint 映像檔裡有記憶體內容,可能包含密碼、token 等機密,所以要放在存取受控的獨立 repository,並設定保存期限。

# ❌ 6.1.3 起會失敗;舊版會在沒有沙箱的情況下執行
sudo podman run registry.corp.example/ckpt/api:20260929

# ✅ 正確做法
sudo podman container restore registry.corp.example/ckpt/api:20260929

✅ 驗證方式:

# 1. 確認映像檔是 checkpoint 映像檔(有這個 annotation)
sudo podman image inspect registry.corp.example/ckpt/api:20260929 \
  --format '{{index .Annotations "io.podman.annotations.checkpoint.runtime.name"}}'
# 預期:crun(或 runc)

# 2. 在 6.1.3 以上的主機用 podman run 執行它,預期會失敗;成功執行代表主機版本過舊
# 3. 還原後確認是「接續執行」而不是重新啟動:近期日誌中不應出現應用程式的啟動訊息
sudo podman logs --since 2m api-restored | grep -c 'Started ' # Spring Boot 的啟動訊息;預期 0

限制:需要 root;有外部 TCP 連線時要加 --tcp-established;還原的主機需要相同的 CPU 功能與相容的核心版本。

13.7 容量規劃

項目建議
graphroot 容量映像檔總大小 × 3(新舊版本並存加上建置快取),最少 50 GiB
記憶體所有容器的 --memory 上限總和,再加 20% 給主機與 page cache
PIDpids_limit 預設 1024;Java 應用程式執行緒多時要調高
inotify大量容器時調高 fs.inotify.max_user_instances、max_user_watches
subuid 範圍每個 rootless 使用者至少 65536;使用 --userns=auto 時要更大

13.8 💡 本章實務建議

  1. 日誌一律使用 journald,由主機的代理程式轉送到 SIEM,並在 journald 設定保留量。
  2. 把 podman events 納入監控:died、health_status、OOM 是最重要的三個訊號。
  3. 每台主機部署 prometheus-podman-exporter,並套用統一的告警規則。
  4. 清理工作用 systemd timer 排程,並在升級到 Podman 6 前確認 volume prune 的行為差異。
  5. 不正常關機之後先執行 podman system check,再啟動服務。

13.9 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1日誌寫入 journaldpodman inspect -f '{{.HostConfig.LogConfig.Type}}' <容器>journald
2可以依容器查日誌journalctl CONTAINER_NAME=<容器> -n 5有輸出
3監控指標有被收集curl -s localhost:9882/metrics | grep -m1 podman_container_info有輸出
4定期清理排程有啟用systemctl --user list-timers | grep podman-prune列出下一次執行時間
5checkpoint 只用 restore 還原grep -rn 'podman run .*ckpt' scripts/沒有結果

14. 疑難排解

14.1 診斷流程

flowchart TD
    A[問題發生] --> B{podman info 正常?}
    B -->|否| C[安裝/machine/設定檔問題<br/>見 14.2]
    B -->|是| D{容器能建立?}
    D -->|否| E[映像檔、名稱衝突、權限<br/>見 14.3]
    D -->|是| F{容器持續執行?}
    F -->|否| G[看 logs、exit code、OOM<br/>見 14.4]
    F -->|是| H{服務可以連線?}
    H -->|否| I[網路、埠號、DNS<br/>見 14.5]
    H -->|是| J[效能、儲存<br/>見 14.6]

必備的診斷指令

podman version && podman info                    # 版本與執行環境
podman --log-level=debug run --rm docker.io/library/alpine:3 true   # 顯示詳細的執行過程
podman ps -a --format "{{.Names}} {{.Status}} {{.ExitCode}}"
podman inspect api --format '{{.State.Error}} {{.State.OOMKilled}}'   # api 換成實際的容器名稱
podman logs --tail 100 api
podman events --since 30m --filter container=api
journalctl --user -xe                            # rootless 的 systemd 紀錄

14.2 安裝與環境

症狀原因處置
podman: command not found未安裝,或 PATH 沒有更新依第 2 章安裝;Windows 請重新開啟終端機
Cannot connect to Podman... connection refused(macOS/Windows)VM 沒有啟動podman machine start;用 podman system connection list 確認預設連線
Windows 上 podman machine init 失敗WSL 沒有安裝或版本太舊;或選了 Hyper-V 但沒有管理員權限wsl --update;Hyper-V 請管理員先執行 podman system hyperv-prep
Podman 6 啟動時出現 cgroups 錯誤主機仍是 cgroups v1改用 cgroups v2(RHEL 8 請升級到 9 以上),或維持 5.8.x
升級到 6.0 後,容器與網路消失BoltDB 自動遷移失敗,或 CNI 網路不再被讀取查看 journalctl 的遷移訊息;依第 15 章重建
WARN: "/" is not a shared mountrootless 環境下根目錄不是 shared mount通常可以忽略;需要 mount propagation 時執行 sudo mount --make-rshared /
macOS/Windows 上 VM 與主機的版本不一致只更新了主機端的 CLIpodman machine os update,或重建 VM

14.3 權限與 Rootless

症狀:cannot set up namespace ... permission denied 或 potentially insufficient UIDs or GIDs available

# 原因:使用者沒有 subuid/subgid,或範圍太小
grep "^$(whoami):" /etc/subuid /etc/subgid

# 處置:由管理員新增範圍,再讓 Podman 重新套用
sudo usermod --add-subuids 524288-589823 --add-subgids 524288-589823 "$(whoami)"
podman system migrate

症狀:掛載的目錄出現 Permission denied

可能原因判斷方式處置
SELinuxsudo ausearch -m AVC -ts recent 有紀錄掛載加上 :Z(私有)或 :z(共享)
UID 對應容器內的使用者不是 root,檔案屬於主機上的你加上 :U、--userns=keep-id,或 podman unshare chown
家目錄權限其他使用者的目錄是 700把資料移到專用目錄

症狀:rootlessport cannot expose privileged port 80

原因是 rootless 不能綁定 1024 以下的埠。處置方式:改用高埠號,或調整 net.ipv4.ip_unprivileged_port_start(見第 6 章)。

14.4 容器啟動與執行

結束碼意義常見原因
125Podman 本身出錯參數錯誤、名稱衝突、映像檔不存在
126指令無法執行沒有執行權限、架構不符(exec format error)
127找不到指令entrypoint 或 command 路徑錯誤
137被 SIGKILL 終止OOM、podman stop 逾時、healthcheck 設定 kill
143被 SIGTERM 終止正常停止
# 名稱已被使用
podman run --name api ...      # Error: ... name "api" is already in use
podman run --replace --name api ...

# 確認是否為 OOM
podman inspect api --format '{{.State.OOMKilled}}'
podman events --filter event=died --filter container=api --since 1h

# 架構不符:在 ARM Mac 上執行只有 amd64 的映像檔
podman image inspect <映像檔> --format '{{.Architecture}}'
podman run --platform linux/amd64 ...   # 透過模擬執行(較慢)

# 短名稱無法解析
podman pull nginx      # Error: short-name "nginx" did not resolve to an alias ...
podman pull docker.io/library/nginx:stable

14.5 網路

症狀原因處置
容器之間無法用名稱連線使用預設網路 podman(沒有 DNS)建立自訂網路,把容器接上同一個網路
升級到 6.0 後,跨網路的容器不通6.0 預設啟用 network isolation把需要互通的容器接上共同的網路
容器連不到主機上的服務pasta 模式下容器與主機使用相同 IP改用 host.containers.internal
容器無法連外proxy 沒有傳入、DNS 錯誤、內網防火牆確認 HTTP_PROXY、podman exec <容器> cat /etc/resolv.conf
重啟 nftables/firewalld 後埠號轉送失效防火牆規則被清除podman network reload --all
應用程式記錄的來源 IP 都是內部位址rootless 的埠號轉送使用 rootlessport在反向代理加上 X-Forwarded-For,或評估 rootless_port_forwarder="pasta"
Windows 主機連不到 WSL 裡的服務(6.1)沒有設定 force_port_listen重建 VM,或在 VM 的 containers.conf 加上設定

14.6 效能與儲存

# 找出耗用資源的容器
podman stats --no-stream --format "table {{.Name}} {{.CPUPerc}} {{.MemUsage}} {{.PIDs}}"

# 找出占空間的映像檔與 volume
podman system df -v

# 儲存層損壞(例如磁碟滿或斷電後)
podman system check
podman system check --repair
症狀原因處置
建置很慢沒有利用層快取;vfs driver調整 Containerfile 順序;改用 overlay
rootless 的 I/O 很慢仍在使用 fuse-overlayfs確認核心版本,並檢查 podman info 的 graphDriverName 與 overlay 設定
磁碟被塞滿dangling 映像檔、建置快取、日誌排程執行 podman system prune;k8s-file 設定 max-size
Java 容器被 OOMheap 設定超過容器記憶體上限用 -XX:MaxRAMPercentage=75 取代寫死的 -Xmx

14.7 Quadlet 與 systemd

見 8.10 除錯。最常見的三個問題:

  1. 檔案語法錯誤,導致 Unit not found:用 podman-system-generator --dryrun 查看錯誤。
  2. rootless 服務在使用者登出後停止:執行 loginctl enable-linger。
  3. 開機時拉取映像檔逾時:加大 TimeoutStartSec,或用 .image 單元預先拉取。

14.8 💡 本章實務建議

  1. 先跑 podman info,再看其他東西:多數問題是環境或設定檔造成的。
  2. 建立團隊的疑難排解知識庫,以「症狀 → 原因 → 處置」格式記錄,並附上 podman version 與作業系統版本。
  3. 不要用 --privileged 或 label=disable 來「解決」權限問題,要找出真正的原因。
  4. 正式環境的問題先保存現場(podman inspect、logs、events,必要時做 checkpoint),再重新啟動。

14.9 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1問題能以最少的資訊重現依 14.1 收集 podman info、podman inspect、日誌交給另一位同仁可以重現
2儲存層一致podman system check沒有錯誤
3事件中沒有反覆的異常podman events --since 1h --filter event=died --format '{{.Name}}' | sort | uniq -c沒有容器反覆結束
4修復後有回歸測試執行該服務的健康檢查與冒煙測試全部通過

15. 從 Docker 遷移與升級到 Podman 6

🆕 v2.0 新增

15.1 從 Docker 遷移

15.1.1 遷移評估清單

項目檢查內容風險
CLI 腳本是否使用 Docker 專屬子指令(docker swarm、docker plugin、docker buildx 進階功能)中
短名稱腳本與 Compose 檔是否依賴 nginx 這類短名稱低(改成完整名稱即可)
Socket工具是否直接存取 /var/run/docker.sock低(改用 podman.socket)
權限是否依賴 root 權限(綁定低埠號、直接寫入 root 擁有的目錄)中
Compose是否使用 profiles、extends、develop.watch 等進階功能中(改用 docker-compose 作為 provider)
restart policy是否依賴 dockerd 在開機時拉起容器高(改用 Quadlet)
網路是否依賴預設 bridge 的行為、--link中
日誌是否依賴 json-file 的路徑與格式中
建置是否依賴 BuildKit 專屬語法(# syntax=、heredoc)中(Buildah 支援大多數語法,要實測)

15.1.2 遷移步驟

# 1. 安裝 Podman 與相容套件
sudo dnf -y install podman podman-docker podman-compose

# 2. 把 Docker 的映像檔搬過來(不需要重新拉取)
docker save myimage:1.0 | podman load
# 或直接從 Docker daemon 讀取
podman pull docker-daemon:myimage:1.0

# 3. 讓工具改用 Podman socket
systemctl --user enable --now podman.socket
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

# 4. 驗證 Compose 專案
cd project && podman compose up -d && podman compose ps

# 5. 把正式服務轉成 Quadlet(見第 8 章)

# 6. 確認沒有問題後,停用 Docker
sudo systemctl disable --now docker.service docker.socket

15.1.3 Docker Desktop 替換

  1. 安裝 Podman Desktop 並建立 podman machine。
  2. 在 Podman Desktop 的設定中啟用「Docker compatibility」,讓 /var/run/docker.sock(macOS)或 npipe:////./pipe/docker_engine(Windows)指向 Podman。
  3. 驗證 IDE(VS Code Dev Containers、IntelliJ)、Testcontainers、Kind 等工具。
  4. 移除 Docker Desktop,並由 IT 部門統一派送 Podman Desktop 的設定。

15.2 升級到 Podman 6

15.2.1 升級前稽核

#!/usr/bin/env bash
# podman6-precheck.sh:在每台主機執行,確認是否可以升級到 Podman 6
echo "== Podman 版本";       podman version --format '{{.Client.Version}}'
echo "== cgroups 版本";      podman info --format '{{.Host.CgroupsVersion}}'          # 需要 v2
echo "== 網路後端";          podman info --format '{{.Host.NetworkBackend}}'          # 需要 netavark
echo "== 資料庫後端";        podman info --format '{{.Host.DatabaseBackend}}'         # 建議 sqlite
echo "== rootless 網路";     podman info --format '{{.Host.RootlessNetworkCmd}}'      # 需要 pasta
echo "== 防火牆";            sudo nft list tables 2>/dev/null | head -5                 # 需要 nftables
echo "== 設定檔中的舊設定"
grep -RIn -E 'slirp4netns|network_backend *= *"cni"|rootless_storage_path|\[registries\.' \
  /etc/containers ~/.config/containers 2>/dev/null
echo "== 腳本中的舊用法"
grep -RIn -E 'network[= ]slirp4netns|volume prune|generate systemd' /opt/scripts 2>/dev/null
檢查項目通過條件未通過時的處置
cgroupsv2升級作業系統(RHEL 8 → 9/10)
NetworkBackendnetavark依 6.8 遷移
DatabaseBackendsqlite5.8 會在重開機時自動遷移;6.0 啟動時也會嘗試,先備份
RootlessNetworkCmdpasta移除所有 slirp4netns 設定
防火牆nftables停用 iptables-legacy
設定檔沒有 V1 registries.conf、containers.rootless.conf 主檔改寫成 V2 與 drop-in
腳本volume prune 與 filter 語意已確認依需要加上 --all
桌面Windows 11、Apple Silicon其他設備維持 5.8.x

15.2.2 升級步驟

flowchart LR
    A[執行預檢腳本] --> B[備份<br/>volume、Quadlet、設定檔]
    B --> C[測試環境升級]
    C --> D[回歸測試<br/>網路、volume、Quadlet、auto-update]
    D --> E{通過?}
    E -->|否| F[修正後重測]
    F --> D
    E -->|是| G[正式環境分批升級]
    G --> H[升級後驗證]
# 1. 備份
podman volume ls -q | xargs -I{} podman volume export {} --output /backup/{}.tar
tar czf /backup/quadlet.tgz /etc/containers/systemd ~/.config/containers

# 2. 停止服務並升級(以 Fedora 為例;RHEL 依 AppStream 的發布時程)
sudo systemctl stop 'shop-*'
sudo dnf -y upgrade podman buildah skopeo netavark aardvark-dns

# 3. 驗證
podman version
podman info --format '{{.Host.DatabaseBackend}} {{.Host.NetworkBackend}}'
sudo systemctl daemon-reload && sudo systemctl start shop-pod.service
podman quadlet list

15.2.3 5.8 維護線策略

情境建議
新建主機(RHEL 10、Fedora)使用發行版提供的最新版本
暫時無法移除 CNI、cgroups v1 的主機維持 5.8.x,列入技術債並排定遷移時程
Intel Mac、Windows 10 開發機維持 5.8.x,並排入設備汰換計畫
跨版本混用CI 與正式環境以正式環境的主版本為準,避免行為差異

📌 上游會持續發布 5.8 的修補版(目前為 5.8.9,2026-10-12,與 6.1.4 同日發布),但停止維護的時間還沒有公布。第三方網站 endoflife.date 把 5.8 的安全支援結束日標為 2026-09-26,但這是它依規則推算的日期,與上游之後仍發布 5.8.8、5.8.9 的事實不符,不要拿來當作依據。請以官方公告為準(見附錄 E.1)。

⚠️ 5.x 主機一樣要達到 10.9 的最低修補版本 5.8.8。

15.2.4 🔭 6.1 → 6.2 升級前檢查

6.2 正式發布後,升級前請先處理以下項目(依 6.2.0-rc1 的 Release Notes 整理):

項目6.2 的變更要做的事
kube play 的 seccomp annotation標為棄用,7.0 移除改用 securityContext.seccompProfile(見 7.3.2)
--cpu-rt-period/--cpu-rt-runtime從文件中隱藏;移除 cgroups v1 後本來就沒有作用,7.0 會移除從腳本中刪除
--image-volume=bind會印出棄用警告;預設值為 anonymous改用 anonymous 或 tmpfs
podman inspect 的 Aliases只列出使用者加的 DNS 別名;新增 DNSNames 欄位解析 Aliases 的監控或 CMDB 腳本改讀 DNSNames
healthcheck 的 systemd unit 名稱改為 libpod-healthcheck-<容器ID>-<亂數>.service依 unit 名稱過濾的告警規則要更新
podman exec 的訊號按 Ctrl-C 會一併結束容器內的程序確認維運腳本沒有依賴舊行為
journald 事件事件內容不再帶時間戳記(journald 本身已記錄)解析事件文字的 SIEM 規則要調整

✅ 驗證方式:在升級前,對腳本與設定庫執行以下搜尋,有命中的就要處理:

grep -rnE 'seccomp\.security\.alpha\.kubernetes\.io|cpu-rt-(period|runtime)|image-volume[= ]bind|\.Aliases' \
  /etc/containers /opt/ops-scripts ~/.config/containers 2>/dev/null

15.3 💡 本章實務建議

  1. 遷移以「先開發、再 CI、最後正式環境」的順序進行,每個階段都保留回退方案。
  2. 正式服務遷移時順便改成 Quadlet,一次解決開機自動啟動、auto-update、日誌整合三個問題。
  3. 在每台主機執行 Podman 6 預檢腳本,把結果彙整成資產清單。
  4. 升級前一定要備份 volume 與設定檔,特別是仍在使用 BoltDB 的舊主機。

15.4 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1升級前檢查全部通過./podman6-precheck.sh每一項都符合 15.2.1 表格的通過條件
2升級後資料庫已遷移podman info --format '{{.Host.DatabaseBackend}}'sqlite
3舊映像檔與 volume 都還在比較升級前後的 podman images -q | wc -l 與 podman volume ls -q | wc -l數量相同
4服務恢復運作podman quadlet list 與各服務的冒煙測試全部 active,測試通過
5沒有使用 6.2 起棄用的選項執行 15.2.4 的 grep沒有結果

16. 實務練習與認證準備

16.1 📝 專案實務練習

目標:把一個「前端+API+PostgreSQL+Redis」的應用程式,從本機開發一路帶到單機正式部署。

步驟任務對應章節
1為 API 與前端撰寫多階段 Containerfile(非 root、有 OCI 標籤)第 4 章
2撰寫 compose.yaml,用 podman compose up 啟動整個堆疊第 9 章
3把前端與 API 改成 Pod,並用 podman kube generate 產生 YAML第 7 章
4建立 GitHub Actions 或 GitLab CI 流水線:建置、掃描、簽章、推送第 12 章
5在測試主機用 Quadlet 部署,資料庫密碼使用 podman secret第 8 章
6啟用 podman-auto-update.timer,推送修補版,驗證自動更新與回滾8.8
7部署 prometheus-podman-exporter,並設定 OOM 與健康檢查告警第 13 章

驗證標準

  • 所有容器都以非 root 身分執行,並設定 --cap-drop=ALL 或等效的 Quadlet 設定
  • 映像檔沒有 HIGH/CRITICAL 弱點,並附有 SBOM 與簽章
  • 主機重開機後,服務依正確順序自動啟動
  • 故意推送一個健康檢查會失敗的版本,auto-update 能自動回滾

16.2 📝 進階實務練習

  1. 離線部署:用 skopeo sync 把所需的映像檔帶進一台不能連外的 VM,並設定 registries.conf 只允許內部 registry。
  2. 簽章強制:設定 policy.json 為預設拒絕,驗證未簽章的映像檔無法拉取。
  3. Podman 6 升級演練:在 5.8 主機上建立 CNI 網路與 BoltDB 狀態,執行預檢腳本、遷移並升級,記錄所有問題。
  4. Checkpoint 遷移:把一個執行中的容器 checkpoint 後,在另一台主機還原,並量測停機時間。
  5. 安全加固:用 udica 為一個需要讀取主機日誌的容器產生 SELinux 政策,取代 label=disable。

16.3 認證概述

⚠️ v2.0 更正:v1.0 以 EX180(Red Hat Certified Specialist in Containers and Kubernetes)為主軸,但這個考試已於 2023 年退役,由 EX188 取代。v1.0 列出的各題型比例(30%、25%……)沒有官方出處,已經刪除。

認證考試與 Podman 的關聯
Red Hat Certified Developer in Cloud-native ApplicationsEX188(實機操作,2.5 小時)以 RHEL 10、Podman v5、OpenShift 4.22 為基準;主要的 Podman 認證
Red Hat Certified System Administrator(RHCSA)EX200考試目標包含以 Podman 管理容器,並用 systemd 讓 rootless 容器開機自動啟動
Certified Kubernetes Application Developer(CKAD)CNCF/Linux FoundationPod、YAML 概念可以延伸到 Kubernetes

官方建議的課程為 DO188(Red Hat OpenShift Developer I: Introduction to Containers with Podman),並要求考生具備在 Linux 上使用 Podman v5 的經驗。

16.4 EX188 考試目標

以下依 Red Hat 官方考試頁面整理(查證日 2026-09-29),並標示本手冊對應的章節:

mindmap
  root((EX188))
    以 Podman 與 Containerfile 建置映像檔
      基底映像檔與內容
      使用者、工作目錄、指令
      埠號、環境變數、參數
      Volume 與安全性
    管理映像檔
      私有 registry 安全
      tag 與推拉
      備份映像檔與容器狀態
    在本機執行容器
      logs、events、inspect
      環境參數與對外服務
    多容器應用
      相依、環境變數
      secret、volume、設定
    疑難排解
      資源描述、日誌
      連線到執行中的容器
#考試目標(官方原文的中文整理)本手冊章節
1以 Podman 與 Containerfile 建置映像檔:指定基底映像檔、加入內容、設定執行身分/工作目錄/指令、暴露埠號、傳入環境變數與建置參數、指定啟動指令、使用 volume 與主機共享資料、理解主機與網路存取的安全性與權限要求、管理容器與映像檔的生命週期第 3 章、第 4 章、第 5 章、第 10 章
2管理映像檔:理解私有 registry 的安全性、與多個 registry 互動、使用 tag、推送與拉取、備份映像檔(含層與 metadata)與備份容器狀態的差異第 11 章、5.7
3在本機以 Podman 執行容器:執行容器、取得容器日誌、監聽主機上的容器事件、使用 podman inspect、指定環境參數、對外公開應用程式、取得應用程式日誌、檢視執行中的應用程式第 3 章、第 13 章
4以 Podman 執行多容器應用:建立應用堆疊、理解容器間的相依性、使用環境變數、secret、volume 與設定第 7 章、第 9 章
5疑難排解容器化應用:理解應用資源的描述、取得應用程式日誌、檢視執行中的應用程式、連線到執行中的容器第 14 章

16.5 模擬題

以下為依考試目標自行設計的練習題,不是官方考題。

題 1(建置映像檔):以 registry.access.redhat.com/ubi10/ubi-minimal 為基底,建置 localhost/hello:1.0:安裝 httpd、以 UID 1001 執行、監聽 8080、預設首頁內容為 EX188。

FROM registry.access.redhat.com/ubi10/ubi-minimal
RUN microdnf install -y httpd && microdnf clean all \
 && sed -i 's/^Listen 80$/Listen 8080/' /etc/httpd/conf/httpd.conf \
 && echo 'EX188' > /var/www/html/index.html \
 && chown -R 1001:0 /run/httpd /var/log/httpd \
 && chmod -R g=u /run/httpd /var/log/httpd
USER 1001
EXPOSE 8080
CMD ["httpd", "-D", "FOREGROUND"]
podman build -t localhost/hello:1.0 .
podman run -d --name hello -p 8080:8080 localhost/hello:1.0
curl -s localhost:8080

題 2(映像檔管理):把 localhost/hello:1.0 加上 tag registry.lab.example:5000/team/hello:1.0 並推送;再把映像檔(含所有層)備份到 /tmp/hello.tar。

podman tag localhost/hello:1.0 registry.lab.example:5000/team/hello:1.0
podman login registry.lab.example:5000
podman push registry.lab.example:5000/team/hello:1.0
podman save -o /tmp/hello.tar localhost/hello:1.0

題 3(多容器應用):建立網路 app-net;以 secret dbpw 提供密碼,啟動 MariaDB(資料保存在 volume dbdata);再啟動一個 WordPress 容器連到資料庫,並對外公開 8081。

podman network create app-net
printf 'S3cret!' | podman secret create dbpw -
podman volume create dbdata

podman run -d --name db --network app-net \
  --secret dbpw,type=env,target=MARIADB_ROOT_PASSWORD \
  -e MARIADB_DATABASE=wp \
  -v dbdata:/var/lib/mysql:Z \
  docker.io/library/mariadb:11

podman run -d --name wp --network app-net -p 8081:80 \
  -e WORDPRESS_DB_HOST=db -e WORDPRESS_DB_USER=root -e WORDPRESS_DB_NAME=wp \
  --secret dbpw,type=env,target=WORDPRESS_DB_PASSWORD \
  docker.io/library/wordpress:6

題 4(事件與檢視):在背景監看 wp 容器的事件並寫入檔案;取出 db 容器的 IP 位址與重啟次數。

podman events --filter container=wp --format json > /tmp/wp-events.json &
podman inspect db --format '{{(index .NetworkSettings.Networks "app-net").IPAddress}} {{.RestartCount}}'

題 5(疑難排解):容器 broken 一啟動就結束。找出原因並修正。

podman ps -a --filter name=broken --format '{{.Status}} {{.ExitCode}}'
podman logs broken
podman inspect broken --format '{{.Config.Cmd}} {{.Config.Entrypoint}} {{.State.Error}}'
# 依原因修正(例如:指令路徑錯誤 → 以正確的 command 重建;權限不足 → 加上 :Z 或調整 UID)
podman run -d --replace --name broken ...

16.6 考試策略

階段建議
考前在 RHEL 10(或 Fedora)上實際操作過每一個考試目標;熟悉 man 與 --help 的查詢方式
開始時先完整讀過所有題目,標出彼此相依的題目(例如後面的題目要用前面建好的映像檔)
作答中每題完成後立即驗證(curl、podman ps、podman logs);需要「重開機後仍有效」的題目,要實際檢查 systemd 設定
常見失分映像檔名稱或 tag 打錯、忘了 :Z、埠號對應寫反、rootless 綁定低埠號、secret 名稱不一致
結束前保留 10~15 分鐘,重新檢查所有容器與服務的狀態

快速查詢技巧

man podman-run | grep -A3 -- '--secret'
podman run --help | grep -i health
man containers-registries.conf
man podman-container.unit    # Quadlet 的 [Container] 設定(6.0 起依類型分成多個 man page)

16.7 考前檢查清單

知識點

  • 能說明 image、container、pod 的差異與生命週期
  • 能說明 rootless、user namespace、SELinux 標籤的作用
  • 能說明 tag 與 digest、save 與 export 的差異
  • 能說明自訂網路與預設網路在 DNS 上的差異

實作能力

  • 能在 10 分鐘內寫出可以正常執行的非 root Containerfile
  • 能用 secret、volume、網路組出多容器應用
  • 能用 podman logs、events、inspect、exec 找出問題
  • 能登入私有 registry 並推送、拉取映像檔

16.8 💡 本章實務建議

  1. 認證以 EX188 為目標;系統管理職務再加考 RHCSA,平台團隊再往 CKA/CKAD 延伸。
  2. 練習環境與考試一致:使用 RHEL 10 或對應版本的 Podman 5 練習。本手冊以 Podman 6 為基準,兩者的差異請參考第 15 章。
  3. 團隊內部每季舉辦一次實作演練,以本章的專案練習作為新人訓練的結業驗收。

16.9 ✅ 本章審查與驗證清單

審查者請逐項執行「驗證指令」,並把實際輸出與「預期結果」比對。全部相符才算通過;不相符的項目請記錄在變更單或審查紀錄中。<容器>、<映像檔> 等請換成實際名稱。

#檢查項目驗證指令預期結果
1每個練習都有可驗證的成果依各題的「驗證」步驟執行結果與題目要求一致
2練習環境與考試環境一致podman --version與 EX188 公布的基準版本相同(Podman 5)
3不依賴網路查資料也能完成關閉瀏覽器,只用 man 與 --help 完成一道模擬題在時間內完成

附錄 A:指令速查

A.1 映像檔

指令功能範例
podman pull拉取podman pull docker.io/library/nginx:stable
podman images列出podman images --filter dangling=true
podman build建置podman build -t app:1.0 -f Containerfile .
podman tag加上 tagpodman tag app:1.0 registry.corp.example/app:1.0
podman push推送podman push registry.corp.example/app:1.0
podman rmi刪除podman rmi app:1.0
podman image inspect檢視podman image inspect --format '{{.Digest}}' app:1.0
podman image history/tree檢視層podman image tree app:1.0
podman save/load備份/還原podman save -o app.tar app:1.0
podman image scp經由 SSH 傳送podman image scp app:1.0 user@host::
podman manifest多架構podman manifest push --all app:1.0
podman image prune清理podman image prune -a

A.2 容器

指令功能範例
podman run建立並啟動podman run -d --name web -p 8080:80 IMAGE
podman create/start分開建立與啟動podman create --name job IMAGE && podman start job
podman ps列出podman ps -a --pod
podman stop/restart/kill停止/重啟/送訊號podman stop -t 30 web
podman rm刪除podman rm -f web
podman logs日誌podman logs -f --since 10m web
podman exec執行指令podman exec -it web sh
podman inspect檢視podman inspect web --format '{{.State.Health.Status}}'
podman update修改資源、restart、healthcheck、環境變數podman update --memory 1g web
podman cp複製檔案podman cp web:/etc/nginx/nginx.conf .
podman diff檔案系統變更podman diff web
podman stats/top資源/程序podman stats --no-stream
podman healthcheck run手動執行健康檢查podman healthcheck run web
podman container checkpoint/restore保存與還原狀態podman container checkpoint -e ckpt.tar.gz web

A.3 Pod 與 Kubernetes

指令功能範例
podman pod create建立 Podpodman pod create --name shop -p 8080:8080
podman pod ps/inspect列出/檢視podman pod inspect shop
podman pod start/stop/rm生命週期podman pod rm -f shop
podman kube generate產生 YAMLpodman kube generate shop --type deployment -f shop.yaml
podman kube play執行 YAMLpodman kube play --replace shop.yaml
podman kube down停止並刪除podman kube down shop.yaml
podman kube apply部署到叢集podman kube apply -f shop.yaml --kubeconfig ~/.kube/config

A.4 網路與 Volume

指令功能範例
podman network create建立網路podman network create --internal db-net
podman network ls/inspect列出/檢視podman network inspect db-net
podman network connect/disconnect連接/中斷podman network connect db-net api
podman network reload重新套用防火牆規則podman network reload --all
podman network rm/prune刪除podman network rm --ignore old-net
podman volume create建立 Volumepodman volume create --label backup=daily data
podman volume ls/inspect列出/檢視podman volume inspect data
podman volume export/import備份/還原podman volume export data -o data.tar
podman volume rename改名(6.1)podman volume rename old new
podman volume prune清理podman volume prune --dry-run

A.5 Quadlet、machine 與系統

指令功能範例
podman quadlet install安裝 Quadletpodman quadlet install --replace web.container
podman quadlet list/print/rm管理 Quadletpodman quadlet list --filter status=active
podman auto-update自動更新podman auto-update --dry-run
podman machine init/start/stopVM 管理podman machine init --now --cpus 4
podman machine os update更新 VM 作業系統(6.0)podman machine os update
podman secret create/ls/rm機密printf '%s' "$PW" | podman secret create pw -
podman artifact add/push/pullOCI artifactpodman artifact push registry.corp.example/cfg:1
podman events事件podman events --filter event=died
podman system df/prune容量與清理podman system prune -f
podman system check儲存一致性檢查podman system check --repair
podman system connection遠端連線podman system connection add prod ssh://...
podman info/version環境資訊podman info --format '{{.Host.NetworkBackend}}'

附錄 B:設定檔範本

B.1 正式環境 Containerfile 範本(Java)

FROM docker.io/library/maven:3.9-eclipse-temurin-21 AS build
WORKDIR /workspace
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 mvn -B -q dependency:go-offline
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 mvn -B -q package -DskipTests \
 && java -Djarmode=tools -jar target/*.jar extract --layers --launcher --destination extracted

FROM docker.io/library/eclipse-temurin:21-jre
ARG APP_VERSION=0.0.0
LABEL org.opencontainers.image.title="app" \
      org.opencontainers.image.version="${APP_VERSION}" \
      org.opencontainers.image.vendor="Corp"
WORKDIR /app
COPY --from=build /workspace/extracted/dependencies/ ./
COPY --from=build /workspace/extracted/spring-boot-loader/ ./
COPY --from=build /workspace/extracted/snapshot-dependencies/ ./
COPY --from=build /workspace/extracted/application/ ./
USER 1001
EXPOSE 8080
ENV JAVA_TOOL_OPTIONS="-XX:MaxRAMPercentage=75 -XX:+ExitOnOutOfMemoryError"
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

B.2 正式環境 Quadlet 範本

# /etc/containers/systemd/<app>/<app>.container
[Unit]
Description=<app> service
Wants=network-online.target
After=network-online.target

[Container]
ContainerName=<app>
Image=registry.corp.example/<team>/<app>:<major.minor>
Network=<app>.network
PublishPort=127.0.0.1:8080:8080
EnvironmentFile=/etc/<app>/app.env
Secret=<app>_db_password,type=env,target=DB_PASSWORD
Volume=<app>-data.volume:/var/lib/<app>:Z
# 安全基準
User=1001
NoNewPrivileges=true
DropCapability=ALL
ReadOnly=true
Tmpfs=/tmp:rw,size=64m,noexec,nosuid
PidsLimit=1024
Memory=1g
# 健康檢查與更新
HealthCmd=curl -fsS http://localhost:8080/health || exit 1
HealthInterval=30s
HealthStartPeriod=60s
HealthOnFailure=kill
Notify=healthy
AutoUpdate=registry
# 日誌
LogDriver=journald
Label=app=<app>
Label=team=<team>

[Service]
Restart=always
RestartSec=5
TimeoutStartSec=600

[Install]
WantedBy=multi-user.target

B.3 containers.conf drop-in

# /etc/containers/containers.conf.d/10-corp.conf
[containers]
tz = "Asia/Taipei"
log_driver = "journald"
pids_limit = 2048

[engine]
events_logger = "journald"
compose_warning_logs = false

[network]
default_subnet = "10.89.0.0/24"
default_subnet_pools = [
  {"base" = "10.90.0.0/16", "size" = 24},
]

B.4 registries.conf drop-in

# /etc/containers/registries.conf.d/10-corp.conf
unqualified-search-registries = ["registry.corp.example"]
short-name-mode = "enforcing"

[[registry]]
prefix = "docker.io"
location = "docker.io"
  [[registry.mirror]]
  location = "mirror.corp.example/dockerhub"

[[registry]]
location = "ghcr.io"
blocked = true

B.5 開發用 compose.yaml 骨架

name: <project>
services:
  app:
    build: .
    image: localhost/<project>/app:dev
    ports: ["127.0.0.1:8080:8080"]
    env_file: [.env.dev]
    depends_on:
      db:
        condition: service_healthy
    networks: [backend]
  db:
    image: docker.io/library/postgres:17
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets: [db_password]
    volumes: ["db-data:/var/lib/postgresql/data:Z"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
    networks: [backend]
networks:
  backend: {}
volumes:
  db-data: {}
secrets:
  db_password:
    file: ./secrets/db_password.txt

附錄 C:檢查清單

C.1 開發環境

  • Podman 與 Podman Desktop 已安裝,版本符合團隊基準
  • podman machine 已使用 --import-native-ca(macOS/Windows)
  • 公司的 registries.conf.d、containers.conf.d 設定已套用
  • rootless 可以正常執行 podman run --rm quay.io/podman/hello
  • podman compose 的 provider 已經固定
  • 需要 Docker API 的工具已經改連 podman.socket
  • IDE(Dev Containers、Testcontainers)已驗證可以使用

C.2 正式部署

  • 映像檔來自內部 registry,並固定版本(或 digest)
  • 映像檔已通過漏洞掃描,並附有 SBOM 與 sigstore 簽章
  • policy.json 採預設拒絕,只信任公司與原廠的簽章
  • 以 Quadlet 部署,檔案納入 Git 與組態管理
  • rootless 服務帳號已啟用 linger
  • 容器以非 root 執行,並設定 DropCapability=ALL、NoNewPrivileges=true、ReadOnly=true
  • 已設定 Memory、PidsLimit 等資源上限
  • 已設定 healthcheck、Restart=always、Notify=healthy
  • 機密透過 Secret= 提供,沒有寫在 Environment=
  • 日誌寫入 journald,並已轉送到集中式平台
  • 已部署 prometheus-podman-exporter 與告警規則
  • volume 已納入備份排程,並完成還原演練
  • auto-update 策略(自動或變更時段手動)已經核准
  • 🆕 podman-patch-check.sh 結果為 PASS(6.x ≥ 6.1.3、5.x ≥ 5.8.8;RHEL 依 RHSA 判定)
  • 🆕 沒有任何腳本以 podman run 執行 checkpoint 映像檔

C.3 故障排查

容器無法啟動

  • podman logs 與 podman inspect --format '{{.State.Error}}'
  • 結束碼(125/126/127/137)
  • 映像檔是否存在、架構是否相符
  • 埠號或名稱是否衝突
  • SELinux(ausearch -m AVC)與 UID 對應

效能問題

  • podman stats 的 CPU、記憶體、PID
  • 是否發生 OOM(died 事件的 OOMKilled)
  • graphroot 的容量與 storage driver
  • 網路延遲與 DNS 解析

安全事件

  • 保存現場:podman inspect、logs、events,必要時做 checkpoint
  • 確認容器的 capabilities、user namespace、SELinux 標籤
  • 比對映像檔 digest 與簽章
  • 檢查 secret 是否外洩,並立即輪替

C.4 Podman 6 升級

  • cgroups v2、netavark、sqlite、pasta、nftables 五項檢查皆通過
  • 沒有 V1 格式的 registries.conf 與 containers.rootless.conf 主檔
  • volume prune、volume ls --filter 相關腳本已經調整
  • 已備份 volume、Quadlet 與設定檔
  • 已在測試環境完成回歸測試
  • 🆕 準備升級到 6.2 時,15.2.4 的搜尋指令沒有任何結果

附錄 D:版本紀錄

D.1 版本歷程

版本日期說明
1.02025-10-31初版:基礎入門、專案實務、進階操作、EX180 考照準備、附錄
2.02026-09-29以 Podman 6.1 為基準全面改寫;新增 Quadlet、Kubernetes 整合、供應鏈、監控維運、遷移升級等章節;修正過時與錯誤的內容;目錄改為自動產生
3.02026-11-06以 6.1.4/5.8.9 為基準逐章查證並預覽 6.2.0-rc1;新增安全修補基準、checkpoint 映像檔更正、RHEL 對照、MSI 大量佈署、Podman Desktop 管理設定,以及 16 份章末審查與驗證清單(見 D.4)

D.2 v1.0 → v2.0 更正表

#v1.0 內容問題v2.0 修正章節
1沒有標示適用版本讀者無法判斷內容是否適用加上文件資訊表,以 Podman 6.1.x 為基準開頭
2「Docker 需要 root 權限」Docker 從 20.10 起有 Rootless mode改為比較「預設值」與「有無 daemon」1.3
3沒有提到網路後端已改用 Netavark/pasta;6.0 移除 CNI、slirp4netns新增網路架構與遷移說明6.1、6.8
4Windows 安裝只寫 winget/Chocolatey6.0 起不支援 Windows 10;安裝檔改為 MSI;可選 WSL2/Hyper-V補充平台矩陣與 provider 比較2.1、2.3
5macOS 以 Homebrew 為主要安裝方式官方建議使用 .pkg 安裝程式;6.0 預設 provider 為 libkrun,不支援 Intel Mac改寫安裝方式2.4
6registries.conf 範例混用 V1 與 V2 格式混用會報錯;6.0 已移除 V1改為 V2 的 drop-in 範例11.2
7基底映像檔使用 openjdk:11-jre-slim、maven:3.8-openjdk-11openjdk 官方映像檔已停止發布;Java 11 過舊改用 eclipse-temurin:21-jre、UBI OpenJDK4.3
8前端範例使用 node:16-alpine 與 npm ci --only=productionNode.js 16 已 EOL;會漏掉建置需要的 devDependencies改用 node:24-alpine 與 npm ci4.4
9在 nginx:alpine 中切換成自建使用者並監聽 80 埠非 root 無法綁定 80 埠,也無法寫入 nginx 的暫存目錄改用 nginx-unprivileged(8080 埠)4.4
10Containerfile 中使用 HEALTHCHECK 但沒有說明格式OCI 格式會忽略 HEALTHCHECK說明 --format docker 或改在執行期/Quadlet 設定4.1
11--log-driver journald --log-opt max-size=10m --log-opt max-file=3max-size 只對 k8s-file 有效;Podman 沒有 max-file改寫 log driver 與輪替說明13.1
12完全沒有說明如何讓容器在主機上長期執行(開機啟動、重啟、更新)正式環境缺少標準做法;舊的 podman generate systemd 自 4.7 起已棄用新增 Quadlet 章節第 8 章
13podman run --user 1000:1000 被當作 rootless 示範--user 只是容器內的身分,與 rootless 無關改為說明 user namespace 與 --userns 模式10.2
14以 EX180 為考照主軸EX180 已於 2023 年退役改以 EX188 的官方考試目標為主16.3
15考題類型比例(30%、25%、20%、15%、10%)沒有官方出處刪除,改為考試目標與章節對照表16.4
16GitHub Actions 使用 actions/checkout@v3 並以 apt 安裝 Podman版本過舊;GitHub runner 已預先安裝 Podman改用 redhat-actions 並固定新版本12.2
17GitLab CI 直接在 runner 上執行 podman run 部署建置與部署未分離,也沒有處理無特權容器內的建置改用 Buildah(vfs+chroot),部署交給 GitOps/Ansible12.3
18使用 consul:latest、ELK 等映像檔的 latest tagConsul 官方映像檔已改名為 hashicorp/consul;latest 不適合企業移除微服務元件的示範,改為強調固定版本與完整名稱11.8
19資料庫範例使用 postgres:13、redis:6-alpine,密碼寫在環境變數版本過舊;密碼暴露在 inspect 中改用 postgres:17、redis:8-alpine 與 podman secret5.2、8.5
20Volume 清理只寫 podman volume prune6.0 起預設只清匿名 volume說明 --all、--dry-run 與 filter 的 AND 語意5.2
21附錄 5.1~5.6 在總結之後又重複出現一次,另有第二個「總結」重複內容造成錨點衝突,舊版 5.1.1 內容被截斷刪除重複段落,重新整理附錄全文
22目錄手動維護容易與內文不一致改為自動產生,並以 Hugo 實際渲染驗證目錄
23學習資源只列出名稱(「Udemy 課程」「YouTube」)無法連結、無法查證改為附有連結的官方與社群資源清單附錄 F
24專案倉庫連結指向 github.com/containers/podman2026-08 已移到 CNCF 組織更新為 github.com/podman-container-tools/podman全文

D.3 v2.0 新增章節

章節內容
執行摘要五個決策問題與企業導入路線圖
1.4 版本演進4.4~6.1 版本時間軸與 Podman 6 的企業影響
2.7 設定檔體系Podman 6 的設定檔解析規則與企業 drop-in 範例
第 7 章Pod、kube generate/play/apply
第 8 章Quadlet、auto-update、drop-in、範本、除錯
第 10 章user namespace、seccomp、udica、secret driver、sigstore、SBOM、規範對照
第 11 章registries.conf、Skopeo、離線環境、OCI artifact
第 13 章journald、events、Prometheus、checkpoint/restore、容量規劃
第 15 章Docker 遷移與 Podman 6 升級預檢
附錄 E查證紀錄與待確認事項

D.4 v2.0 → v3.0 更正表

#v2.0 內容問題v3.0 修正章節
1基準版本 6.1.2/5.8.7上游已發布 6.1.3、6.1.4、5.8.8、5.8.9,其中有安全修正與 breaking change基準改為 6.1.4/5.8.9,新增修補版重點表1.4.2
2checkpoint 映像檔可以「推送到 registry」,但沒有安全提醒,也沒有說明怎麼還原CVE-2026-94603:6.1.3/5.8.8 起 podman run 不再接受 checkpoint 映像檔改用 podman container restore,並加上存放與保存期限的要求13.6
3沒有定義最低修補版本稽核時無法判定合格與否新增 6.1.3/5.8.8 基準與檢查腳本10.9
4RHEL「目前隨附 5.x」太籠統,無法用來規劃補上 RHEL 9.5~10.2 與 Podman 版本對照,並說明回補修正的判斷方式2.2.1
5Windows「MSI 靜默安裝的參數請見官方指南」官方指南沒有列出參數從安裝程式原始碼整理 MACHINE_PROVIDER、ALLUSERS、MSIINSTALLPERUSER、SKIP_CONFIG_FILE_CREATION2.3.2
6Podman Desktop 1.29.3,「1.30 為預覽版」1.30.5 已於 2026-10-13 成為穩定版更新版本與新功能;補上 managed configuration 的做法2.6
7「企業可以用設定檔鎖定選項」沒有說明檔名與路徑新增 default-settings.json/locked.json 範例與驗證方式2.6.1
8kube play --validate、--multiple-pods「尚未發布」已進入 6.2.0-rc1新增 6.2 預覽小節與 seccomp annotation 棄用通知7.3.2
9Trivy 0.74、Grype 0.119已有新版更新為 Trivy 0.76、Grype 0.12110.7
10Buildah 1.45.1Podman 6.1.4 內建 1.45.2;獨立版為 1.46.0分別列出1.5
11OCI 規範只列名稱沒有版本,也沒有說明 Referrers API補上 runtime-spec v1.3.0、image-spec/distribution-spec v1.1.1,以及 Referrers API 的確認方式1.2.3
12Windows 舊安裝程式與 MSI 的差異沒有說明改用新版 MSI 前必須先移除舊版(5.7.0 以前的 bundle 安裝程式)新增注意事項2.3.2
13各章只有「實務建議」讀者無法自行驗證內容是否正確每章新增「✅ 本章審查與驗證清單」各章結尾

D.5 v3.0 新增章節

章節內容
1.4.2 6.1.x/5.8.x 修補版重點修補版的 CVE 與 breaking change
2.3.2 大量佈署:MSI 靜默安裝MSI 屬性、指令與驗證方式
2.6.1 企業管理設定Podman Desktop 的鎖定設定
7.3.2 6.2 預覽:kube play--validate、--multiple-pods、--label、seccomp 欄位
8.6.1 6.2 預覽:新的 Quadlet keySetMountsDependency=、Umask=
8.8.1 6.2 預覽:auto-update--filter、遠端執行
10.9 安全修補版本基準CVE 對照、最低版本、檢查腳本
15.2.4 6.1 → 6.2 升級前檢查6.2 的行為變更與搜尋指令
各章「✅ 本章審查與驗證清單」共 16 份,每項都有驗證指令與預期結果

附錄 E:查證紀錄

以下為 v2.0(2026-09-29) 的查證紀錄,依官方來源查證;v3.0 的查證紀錄見 E.2。來源欄的 man page 以 podman-container-tools/podman main 分支的 docs/source/markdown/ 為準。

#事實來源
1最新版本 6.1.2(2026-09-16);5.8.7(2026-09-16)為 5.x 維護線GitHub Releases
26.0.0 發布於 2026-06-24;6.1.0 發布於 2026-08-12GitHub Releases
36.0 移除 BoltDB、Intel Mac、Windows 10、cgroups v1、iptables、CNI、slirp4netns;預設啟用 network isolationRELEASE_NOTES.md(6.0.0 Breaking Changes)
46.0 起 volume prune 預設只清匿名 volume,新增 --all、--dry-run;volume ls 的 filter 改為 ANDRELEASE_NOTES.md(6.0.0)
56.0 起 macOS 的預設 provider 為 libkrun;新增 podman machine os update、podman system hyperv-prep、--import-native-caRELEASE_NOTES.md(6.0.0)
66.1 新增 podman volume rename、podman machine restart、Quadlet ImageVolume=、kube generate 產生 livenessProbe、force_port_listenRELEASE_NOTES.md(6.1.0)
72026-08-04 起 Podman、Buildah、Skopeo 移到 podman-container-tools 組織;Go import path 改為 go.podman.io/podman/v6CNCF 專案頁、RELEASE_NOTES.md
8Podman Container Tools 於 2025-01-21 成為 CNCF Sandbox 專案cncf.io/projects/podman-container-tools
9Quadlet 於 4.4 推出;podman generate systemd 於 4.7 棄用(不會移除)RELEASE_NOTES.md、podman-generate-systemd(1)
10SQLite 於 4.8 成為新安裝的預設資料庫;pasta 於 5.0 成為 rootless 預設網路RELEASE_NOTES.md
11podman quadlet install/list/print/rm 於 5.6 推出;podman artifact 於 5.6 標為穩定RELEASE_NOTES.md(5.6.0)
12Quadlet 的單元檔類型、搜尋路徑、systemd- 名稱前綴、除錯指令podman-systemd.unit(5)、podman-network.unit(5)、podman-volume.unit(5)
13podman compose 預設 provider 為 docker-compose 與 podman-compose,前者優先podman-compose(1)
14Podman 6 的設定檔解析規則(主檔取第一個、drop-in、{append=true}、移除 V1 registries.conf)contrib/design-docs/config-file-parsing.md
15containers.conf 預設值:pids_limit=1024、default_subnet=10.88.0.0/16、預設 11 個 capabilities、secret driver 為 file/passcontainers.conf(5)(container-libs)
16--log-opt max-size 用於 k8s-file;tag、label 只支援 journaldpodman-run(1) 的 log-opt 選項
17podman kube play 支援 Pod、Deployment、PersistentVolumeClaim、ConfigMap、Secret、DaemonSet、Jobpodman-kube-play(1)
18EX188 名稱為 Red Hat Certified Developer in Cloud-native Applications;2.5 小時;以 RHEL 10、Podman v5、OCP 4.22 為基準;建議課程 DO188redhat.com EX188 頁面
19EX180 於 2023 年退役並由 EX188 取代Red Hat Learning Community
20Windows 安裝檔為 podman-installer-windows-{amd64,arm64}.msi;macOS 為 podman-installer-macos-arm64.pkgGitHub Releases v6.1.2 assets
21Homebrew 版本由社群維護,官方建議使用安裝程式podman.io/docs/installation
22Ubuntu 26.04 LTS 為 5.7.0、Debian 13 為 5.4.2、Debian experimental 為 6.1.1Launchpad、sources.debian.org
23Fedora 45 導入 Podman 6Fedora Wiki Changes/Podman6
24RHEL 9/10 的 Container Tools 為滾動 AppStream,每年最多更新四次Red Hat Container Tools AppStream 政策
25Podman Desktop 1.29.3(穩定)、Buildah 1.45.1、Skopeo 1.24.1、Netavark 2.1.0、crun 1.30.1、podman-compose 1.6.0、prometheus-podman-exporter 2.0.0各專案 GitHub Releases
26redhat-actions:buildah-build v3.1.0、push-to-registry v3.0.0、podman-login v2.0;actions/checkout v7各專案 GitHub Releases
27Trivy 0.74.0、Grype 0.119.0、cosign 3.1.3各專案 GitHub Releases
28prometheus-podman-exporter 預設監聽 :9882,預設只啟用 container collector專案 README、install.md

E.1 待確認事項

🆕 v3.0 更新(2026-11-06):已結案的項目保留在表中,並在「狀態」欄寫出結論與章節。

#項目狀態結論或追蹤方式
1RHEL 10.x/9.x 各次版本實際隨附的 Podman 版本✅ 已結案9.7/10.1 為 5.6.0,9.8/10.2 為 5.8.2,見 2.2.1。之後的新次版本,請在主機上執行 rpm -q podman 確認
2RHEL 何時提供 Podman 6⏳ 待確認RHEL 10.2(2026-05)仍為 5.8.2。追蹤 RHEL 10.3/9.9 的 Release Notes
35.8.x 的停止維護時間⏳ 待確認上游在 2026-10-12 仍發布 5.8.9。endoflife.date 推算的 2026-09-26 與事實不符,不採用
4rootless_port_forwarder="pasta"(Pesto)何時成為預設⏳ 待確認6.2.0-rc1 的 Release Notes 沒有提到改為預設
5Podman Desktop 1.30 何時發布穩定版✅ 已結案1.30.5 於 2026-10-13 發布(1.30.0~1.30.4 為 prerelease),見 2.6
6podman kube play --validate、--multiple-pods🔭 部分結案已進入 6.2.0-rc1(見 7.3.2)。等 6.2.0 正式發布後,移除 🔭 標示
7未來的映像檔 ID 格式(非 SHA256 digest)⏳ 待確認6.2.0-rc1 仍未改變
8Windows MSI 靜默安裝的參數名稱✅ 已結案見 2.3.2;參數來源為 contrib/win-installer(v6.1.4)
9🆕 Quadlet Umask= 的 man page⏳ 待確認Release Notes 與原始碼已有,但 6.2.0-rc1 的 podman-container.unit(5) 尚未收錄
10🆕 6.2.0 正式版的發布日與最終內容⏳ 待確認RC 階段的功能可能還會調整。正式發布後,請重新比對 7.3.2、8.6.1、8.8.1、15.2.4
11🆕 RHEL 套件是否已回補 CVE-2026-94603⏳ 待確認查詢對應的 RHSA 公告,或執行 rpm -q --changelog podman

E.2 v3.0 查證紀錄

以下事實於 2026-11-06 查證。版本號一律以下載的原始檔 grep 確認,不採用網頁摘要。

#事實來源
16.1.3(2026-09-29)、6.1.4(2026-10-12)、5.8.8(2026-09-29)、5.8.9(2026-10-12)、6.2.0-rc1(2026-10-26,prerelease)GitHub Releases API(gh api repos/podman-container-tools/podman/releases)
26.1.3/5.8.8 修正 CVE-2026-94603,並移除 podman run 對 checkpoint 映像檔的支援(Breaking Changes)RELEASE_NOTES.md(v6.2.0-rc1 tag)的 6.1.3 段落;v5.8.8 release body
36.1.2/5.8.7 修正 CVE-2025-11395(podman load、podman volume import);6.1.1 修正 CVE-2026-17106RELEASE_NOTES.md 6.1.1、6.1.2 段落
46.1.4/5.8.9:gvproxy 0.9.0(CVE-2026-107935)、修正 WSL 3;6.1.4 內建 Buildah 1.45.2,5.8.9 內建 Buildah 1.43.5RELEASE_NOTES.md 6.1.4 段落;v5.8.9 release body
56.2 新增 kube play --validate/--label/--multiple-pods、push --platform、auto-update --filter、Quadlet Umask/SetMountsDependency;seccomp annotation 棄用(7.0 移除)RELEASE_NOTES.md 6.2.0 段落
6--validate 的值為 ignore(預設)/warn/strict;strict 失敗時不回滾已建立的物件podman-kube-play.1.md.in(v6.2.0-rc1)
7SetMountsDependency= 位於 [Quadlet] 區段,值為 Requires(預設)/Wants(需要 systemd 256)/Nonepodman-systemd.unit.5.md(v6.2.0-rc1)
8Umask 對應 --umask,在 6.1.4 的 Quadlet 原始碼中不存在;Quadlet 遇到不支援的 key 會回報 unsupported key 錯誤pkg/systemd/quadlet/quadlet.go(v6.2.0-rc1 與 v6.1.4)
9auto-update --filter 支援 label=、ancestor=;--dry-run 的 UPDATED 欄位以 pending 表示有新版podman-auto-update.1.md.in(v6.2.0-rc1)
106.2 可以用實例專屬的 drop-in 目錄建立範本實例podman-systemd.unit.5.md(v6.2.0-rc1)的 Template files 一節
11MSI 屬性:MACHINE_PROVIDER(預設 wsl)、ALLUSERS=1、MSIINSTALLPERUSER=1、SKIP_CONFIG_FILE_CREATION;新版 MSI 從 5.7.0 起提供contrib/win-installer/wix/podman-main.wxs、test.ps1(v6.1.4);RELEASE_NOTES.md 5.7.0
12Windows 安裝範圍:使用者範圍為預設(%LOCALAPPDATA%\Programs\Podman);安裝程式不會自動安裝 WSLdocs/tutorials/podman-for-windows.md(v6.1.4)
13RHEL 9.7/10.1 為 Podman 5.6.0(Buildah 1.41.0、Skopeo 1.20.0);9.8/10.2 為 5.8.2Red Hat Jira(RHEL 10.1 Container Tools epic)、RHEL 10.2 Release Notes 搜尋摘要;以 tangentsoft.com「Stable Versions」對照表交叉核對
14Podman Desktop 1.30.5 於 2026-10-13 發布(非 prerelease);內建 Podman 6.1.4/5.8.9GitHub Releases API;extensions/podman/…/podman.json;官方部落格 2026-10-14
15Podman Desktop managed configuration 的檔名、路徑與優先順序website/docs/configuration/managed-configuration.mdx
16kube play 的 seccomp annotation 為 seccomp.security.alpha.kubernetes.io/pod 與 container.seccomp.security.alpha.kubernetes.io/<容器名稱>,原始碼標記 Podman 7 移除pkg/specgen/generate/kube/seccomp.go(v6.2.0-rc1)
17新版 configfile 解析器的 debug 訊息為 Read config file "<路徑>"container-libs:storage/pkg/configfile/parse.go
18Buildah 1.46.0、Skopeo 1.24.1、crun 1.30.1、Netavark/Aardvark-dns 2.1.0、podman-compose 1.6.0、prometheus-podman-exporter 2.0.0各專案 GitHub Releases API
19Trivy 0.76.2、Grype 0.121.2、Syft 1.57.0、cosign 3.1.4各專案 GitHub Releases API
20OCI runtime-spec v1.3.0(2025-11)、image-spec v1.1.1(2025-03)、distribution-spec v1.1.1(2025-01)opencontainers 各規格的 GitHub Releases
21redhat-actions buildah-build v3.1.0、push-to-registry v3.0.0、podman-login v2.0;actions/checkout v7.0.1,與 v2.0 相同各專案 GitHub Releases API
22EX188 仍以 RHEL 10、Podman v5、OCP 4.22 為基準redhat.com EX188 頁面(韓文版);日文版仍是舊的 RHEL 9 基準
23podman container restore 可以接受映像檔,並支援 --name;podman machine info --format '{{.Host.VMType}}' 可以使用本機 Podman 5.8.3 CLI 的 --help 與實際執行
24podman-patch-check.sh 對 11 個測試版本字串與本機 5.8.3 的判定結果都符合預期作者在 Git Bash 上實際執行(見 10.9.2)

附錄 F:參考資料

F.1 官方文件

F.2 Red Hat 資源

F.3 標準與規範

F.4 生態系工具


📚 總結

本手冊以 Podman 6.1.4 為基準(並預覽 6.2),涵蓋從開發者桌面到正式主機的完整生命週期:

  1. 基礎(第 1~3 章):架構、安裝、核心操作。
  2. 建置與資源(第 4~6 章):Containerfile、儲存、網路。
  3. 部署(第 7~9 章):Pod 與 Kubernetes、Quadlet、Compose。
  4. 治理(第 10~13 章):安全、供應鏈、CI/CD、監控維運。
  5. 維運與成長(第 14~16 章):疑難排解、遷移升級、EX188 認證準備。

企業導入的核心原則可以歸納為五點:rootless 為預設、Quadlet 管理服務、簽章驗證供應鏈、Kubernetes YAML 銜接平台、主機維持在安全修補基準以上。建議依執行摘要的路線圖分階段導入。每章完成後,用該章的「✅ 本章審查與驗證清單」自我檢核;整體驗收則使用附錄 C。