Portainer 完整教學 2026：Docker 圖形化管理與自架實戰

Portainer 是用網頁介面管理 Docker、Swarm、Podman 與 Kubernetes 的容器管理工具；社群版 CE 免費、zlib 授權，最新 CE 2.45.3 LTS 於 2026-10-22 發布，GitHub 約 3.87 萬星。安裝只要一行 docker run，但 2.43 版之後多了一道 setup token，本文把流程走完。

為什麼需要 GUI：不是為了偷懶

命令列派的讀者常問「docker ps 不就好了」。實際上痛點不在「看」，而在這幾件事：

對單機使用者，這些只是「方便」；但只要有第二台機器、或有人要接手，GUI 的價值就會立刻出現。

一表看懂 Portainer

CE 與 BE 的分野，看官方 README 最準：CE 是「免費、輕量、給 homelab／學習／個人專案用」；BE 在其上加 RBAC、GitOps、邊緣管理、稽核、SSO 與商業支援。README 甚至白紙黑字寫：CE 不是為生產環境或「停機、安全態勢、資料完整性很重要的場景」設計，也沒有 SLA。

這句話不是行銷話術，而是使用前就該知道的邊界——後面「已知限制」會再談。

運作架構：Server / Agent / Edge Agent

Portainer 由兩個角色組成：Portainer Server（跑 UI 與資料庫）與 Portainer Agent（跑在被管理的機器上，把該機器的 Docker 資源暴露給 Server）。

官方文件現在明確標注：傳統 Agent 是 legacy 選項，不支援 edge 功能與 policy management；多數情況建議直接用 Edge Agent。 只要機器不是「Server 主動連得到」的內網環境，就直接選 Edge Agent，省掉一堆 port forwarding。

安裝（一）：docker run，官方原文

先建資料 volume：

docker volume create portainer_data

再啟動容器（這段是官方文件原文，建議照抄）：

docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts

三個細節值得說明：

• portainer/portainer-ce:lts 是 LTS 標籤，追穩定版就固定用它；想試新功能才換 sts。
• -v /var/run/docker.sock:/var/run/docker.sock 等於把 Docker 控制權交給 Portainer。這是最大權限，不是普通掛載，任何能登入 Portainer 的人實質上就是該機的 root 等級。
• -p 8000:8000 只有要用 Edge Agent 才需要；純單機管理可以拿掉。

需要舊版 HTTP 9000 的話，再加 -p 9000:9000。

安裝（二）：Docker Compose

官方提供現成 compose 檔：

curl -L https://downloads.portainer.io/ce-sts/portainer-compose.yaml -o portainer-compose.yaml

或自己寫（官方範例）：

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 9443:9443
      - 8000:8000  # Remove if you do not intend to use Edge Agents

volumes:
  portainer_data:
    name: portainer_data

networks:
  default:
    name: portainer_network

docker compose -f portainer-compose.yaml up -d
docker ps   # 確認 portainer 容器 Up，9443/8000 有對外

Compose 版的好處是「Portainer 自己也被宣告式管理」，日後升級只要改 image tag 再 up -d。若還不熟 compose 語法，站上另一篇 Docker Compose 完整教學 有從 compose.yaml 到 AI models 的完整說明。

首次登入：2.43 之後多了 setup token

這是 2026 年最多人卡住的一步。從 2.43 / 2.39.4 版起，全新的 Portainer 實例在首次設定時需要一組 setup token，目的是防止剛開機、還沒設密碼的實例被別人搶先接管（對應安全公告 GHSA-x626-fcwx-f5pc）。舊安裝不受影響。

取得方式：token 印在容器 log 裡。

docker logs portainer 2>&1 | grep setup_token

• Docker Swarm 也在 manager 節點用 docker logs；Podman 用 podman logs；Kubernetes 用 kubectl logs <pod> -n portainer。
• 開瀏覽器到 https://<主機IP>:9443，貼上 token、設定 admin 密碼即可。
• token 是一次性的，而且建立管理員必須在 5 分鐘內完成，逾時要重來。
• 若 token 貼錯或沒帶，設定會被拒絕並提示回 log 找。

三種跳過／自訂的方法（官方文件列在 CLI 選項）：

實務建議：雲端主機開 9443 對外時，千萬不要用 --no-setup-token。那段幾分鐘的空窗，就是自動掃描機器人最愛的窗口。

放到反向代理後面：三個一定要設的參數

直接暴露 9443 可行，但多數人會想用網域＋既有憑證，掛在 Traefik、Nginx 或 Caddy 後面。這時有三個參數必調：

反向代理的實際設定可以直接抄站上既有文章：Traefik 完整教學（Docker Labels 自動路由）、Nginx 反向代理完整教學、Caddy 完整教學。三篇都有對應的 WebSocket／長連線設定，Portainer 的 UI 需要它。

用 Stack 管一組服務

Stack 就是 Portainer 對 compose 專案的稱呼：一個 stack 可以包含 web server、資料庫等多個 service。日常操作的重點：

• 部署：Stacks → Add stack，可貼上 compose 內容、從 Git repo 拉、或上傳檔案。
• 更新：改完按 Update，Portainer 會重建有變動的容器，其他不動。
• Webhook：每個 stack 可產生 webhook URL，讓 CI／腳本觸發重新部署，不必登入 UI。
• 映像有新版的提示：啟用 image update indicator 後，stack 列表會用綠勾／橘叉標示「遠端 registry 是否有新映像」，按一下即可重查。
• 孤兒 stack：若某個 environment 被刪掉，它的 stack 會變成 orphaned，要用右上角選單「Show all orphaned stacks」找回並重新綁定。

對個人自架，最常用的其實是「把原本手打的 docker-compose.yml 搬進來」，之後改環境變數、看 log、重啟都在同一個畫面完成。

備份與還原：備份那個 volume 就好

Portainer 的狀態全在 /data（volume portainer_data）裡，所以備份邏輯很單純：

# 備份（先停容器，避免 BoltDB 寫入中）
docker stop portainer
docker run --rm -v portainer_data:/data -v "$PWD":/backup alpine \
  tar czf /backup/portainer-data-$(date +%F).tar.gz -C /data .
docker start portainer

還原時把 tar 解回同名 volume、docker start 即可。兩個實務注意：

1. 資料庫變大後啟動會慢，官方提供 --compact-db 啟動參數，可在啟動時壓縮資料庫回收空間。
2. 有啟用 Git 部署的 stack，repo 會被 clone 進 data volume，多個大 repo 會把 volume 撐大；官方 requirements 頁特別提醒這件事，也要注意不要讓它把磁碟吃滿。

升級流程也簡單：改 image tag（或 docker pull），重建容器，volume 不動。

常用 CLI 旗標速查

完整清單在官方文件「CLI configuration options」頁，本文只挑日常會動到的。

多少錢：CE 免費，付費版的界線在哪

計價單位是「節點」而不是「人頭」：一台跑 Portainer Server 的機器、或任何被它管理的機器（含 Raspberry Pi、VM、筆電）都算一個 node，並以 vCPU 數分級。

與其他自架方案的定位差異

以下為定性比較（功能定位與適用場景），不是實測 benchmark：

選型一句話：已經有一堆既存容器要「看與管」→ Portainer；要「從 Git 部署新服務」→ Coolify；只有單機幾個 compose 檔 → Dockge 或直接 CLI。

已知限制與踩雷點（官方自述＋查證補充）

1. CE 不是生產級產品：官方 README 明列 CE 為 homelab／學習用途，不支援生產環境、無 SLA、無回應保證。要在公司跑，官方要求買 BE。
2. setup token 有時效：全新實例必須在 5 分鐘內建立管理員，否則要重來；腳本化部署要用 --setup-token 或 --admin-password-file。
3. 需要 root 級 Docker 存取：預設掛 /var/run/docker.sock、假設 Docker 以 root 執行；rootless Docker 有功能限制、需額外設定。
4. SELinux 環境要 --privileged：官方文件直接寫明，若機器啟用 SELinux 需加 --privileged——等於再放大一次權限，資安上要自己評估。
5. Agent 是 legacy：傳統 Agent 不支援 edge 功能與 policy；跨網段請用 Edge Agent（不需開埠）。
6. 本文未實測的部分：沒有實際部署多節點 Edge、沒有跑 BE 的 RBAC／GitOps、沒有做 K8s 環境測試；上述行為描述皆來自官方文件，版本與價格以查證當日官網為準。

誰適合、誰不需要

適合：有一台以上的 Docker 主機、想用網頁集中管理；常需要看 log／重啟／改 compose；要給非工程背景的家人或同事一個「只能按按鈕」的入口；想用 App Templates 快速起常見服務。

不需要：只有一個 compose 檔、服務幾乎不改；已經用 Coolify 之類 PaaS 全自動部署；公司有合規要求但沒有預算買 BE——那反而應該跳過 CE，避免把非生產工具放進生產。

站內延伸閱讀

• Docker Compose 完整教學 2026：compose.yaml 到 AI models
• Traefik 完整教學 2026：Docker Labels 自動路由與自動 HTTPS
• Nginx 反向代理完整教學 2026
• Coolify 完整教學：自架版 Vercel／Heroku
• Uptime Kuma 完整教學：自架監控與告警

資料來源與查證方法

• 官方文件：docs.portainer.io 的 Install CE with Docker on Linux、Requirements and prerequisites、CLI configuration options、Stacks、Install Portainer Agent on Docker Standalone、setup token FAQ（皆為 2026-10-27 讀取，可直接在頁面網址後加 .md 取得 Markdown 原檔）。
• 官方 repo：portainer/portainer README（CE／BE 定位與授權說明）、GitHub API（stars 38,731、zlib 授權、最後推送 2026-10-27、最新 release 2.45.3 於 2026-10-21 發布）。
• 定價：portainer.io/pricing 與 portainer.io/homeandstudent（2026-10-27）。
• 版本／相容性：官方 requirements 頁的 CE 版本對照表（CE 2.45.3 LTS 標示 2026-10-22）。
• 安全公告：GHSA-x626-fcwx-f5pc（setup token 機制的由來）。
• 未查證項目：Dockge、Coolify 的功能描述為定性整理，未在本次做同環境實測；若要做正式選型，建議以各自官方文件核對當下版本。