这是「Docker 好项目」系列的第 28 期。这个系列写了 27 期自托管服务,但有一个角色一直缺席:管理这些容器的东西本身。装了十几个服务之后,docker ps 一屏刷不完、想知道哪个容器在吃内存还得 docker stats、改个 compose 要 SSH 上去 vim——这期介绍 Portainer,把整台服务器的容器装进一个网页里。Docker 官方 README 提到的图形界面工具里,它是社区版免费、装机量最大的那个(38.6k stars)。

portainer 效果图

痛点开场

容器一多,命令行的边际成本就开始上升:

  • 看状态要记一堆命令:docker ps、docker stats、docker logs -f、docker inspect、docker volume ls……每个都会,但每天来回敲十几次,还是不如一个列表页直观
  • 改 compose 要上机:想给某个容器加个环境变量、改个端口映射,得 SSH 上去找到 compose 文件改完再 up -d。人在外面用手机的时候干瞪眼
  • 多台机器各看各的:家里 NAS 一套容器、云上 VPS 一套,两边 docker ps 来回切,没有一个统一的地方
  • 新人接手成本高:服务器交给别人维护,对方不一定熟 Docker 命令,但一定会点网页

Portainer 的答案很直接:一个容器,把 Docker Engine 的 API 包成 Web 界面——容器、镜像、网络、卷、compose 栈(它叫 Stack)、容器日志、Web 终端,全在浏览器里点。还能通过 Agent 把别的 Docker 主机也接进来,一个面板管所有机器。

Portainer 官方标识

能力边界

能干什么(以下基于 v2.45.2 镜像与官方文档核实)

  • 容器全生命周期:启动/停止/重启/删除、看日志(支持实时滚动和下载)、进 Web 终端(exec 进容器)、看实时资源占用曲线(CPU/内存/网络/进程列表)
  • Stack 管理:在网页里直接贴 docker-compose.yml 部署,或者从 Git 仓库拉 compose 文件部署;已部署的 Stack 可以在网页里改 YAML 重新更新——这是它比「一个容器列表页」强得多的地方
  • 镜像 / 网络 / 卷:拉镜像(支持指定 registry 和 tag)、清理悬空镜像、建网络、建卷、看每个卷被哪些容器用着
  • 多环境(多主机):本机之外,用 Agent(9001 端口)或直接暴露的 Docker API 接入其他机器,首页一键切换环境。家里 NAS + 云上 VPS 的组合,一个面板全看到
  • 应用模板:内置一批常用应用的模板(nginx、mysql、redis 之类),填几个参数就能部署;也支持自定义模板列表
  • 用户与团队:本地账号体系,管理员/普通用户/只读用户三种角色,密码默认最少 12 位,会话有效期默认 8 小时
  • 事件与操作留痕:Settings → Activity 之外,容器操作在 Docker 事件层面可查(审计日志是 BE 的活)

不干什么

  • 不做监控告警。它没有告警中心,也不会在容器挂掉时给你发通知——那是第 1 期 Uptime Kuma 和第 27 期 Beszel 的活,本期「告警/通知配置」一节细说
  • 不做日志检索。看单个容器日志行,但要按关键字跨容器搜索、长期留存日志的,用第 22 期 Dozzle 或上 Loki
  • 不是 1Panel 的替代品。1Panel 管的是整台服务器(网站、数据库、防火墙、备份),Portainer 只管 Docker 这一亩三分地。两者可以共存,定位见下文 1Panel 一节
  • CE 版本官方定位是 homelab。2026 年 9 月官方重写了 README:CE 明确定位为「homelab、学习、非生产环境」,按原样提供、无支持承诺、无发布节奏保证;生产环境要 BE(免费 3 节点的 Take 3 计划可以白嫖)。个人服务器完全没问题,公司生产环境自己掂量

部署前准备

项 说明
镜像 portainer/portainer-ce(Docker Hub);老教程里的 portainer/portainer 是 1.x 时代的名字,别再用
tag 规则 没有滚动的主版本/次版本 tag——实测 tag 列表里 2.45.2 存在,但 2、2.45 都不存在。lts == sts == latest == 2.45.2(digest 完全一致,逐个对比过)。本期直接钉 2.45.2;想跟着走就用 :lts(官方文档同款写法),但要知道它每次升级都会变
双版本线 2.45.x 是新 LTS 线;2.39.8 还在单独发维护版(2026-09-16),两条线镜像不同(digest 不同),别混
平台 amd64 / arm64 / arm(树莓派 32 位也有),还有 -alpine 变体
端口 9443 = HTTPS UI(默认自签证书);8000 = Edge Agent 隧道(不用 Edge 功能可以不开);9000 = 遗留 HTTP 端口(镜像里有,2.x 仍能用,官方称 legacy,建议不开)
数据卷 /data——SQLite 数据库 + 配置 + TLS 证书全在这里,一个命名卷搞定
基础镜像 默认镜像近似 scratch(核实过镜像 history:只有 CA 证书、二进制、静态资源三样),没有 shell、没有 curl/wget,docker exec -it portainer sh 进不去;要 shell 的用 -alpine 变体
前置条件 Docker 20.10+;SELinux 开启的机器要加 --privileged;rootless Docker 有额外配置,别一上来就折腾
安全底线 必须挂载 /var/run/docker.sock——拿到 socket 约等于拿到宿主机 root(官方原话是 near-root control)。所以 Portainer 只给信任的人用,端口不暴露公网

docker run 一行版

docker volume create portainer_data
docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:2.45.2

几个选择的原因:8000 不映射——那是 Edge Agent 隧道端口,不用边缘设备就用不上,少开一个是一个;没映射 9000——明文 HTTP 管理界面留它干嘛;docker.sock 没加 :ro——加了也白加(socket 是双向通信,只读挂载不影响写入),真正的防线是别暴露公网 + 强密码。国内拉不动 Docker Hub 的,先走加速再改回名字:

docker pull docker.1panel.live/portainer/portainer-ce:2.45.2
docker tag  docker.1panel.live/portainer/portainer-ce:2.45.2 portainer/portainer-ce:2.45.2

docker-compose 推荐版

services:
  portainer:
    image: portainer/portainer-ce:2.45.2
    container_name: portainer
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "9443:9443"
      # - "8000:8000"   # 只有用 Edge Agent 才需要
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:
    name: portainer_data

比 docker run 多的两处:no-new-privileges:true 禁止容器内提权(Portainer 官方 compose 模板就带这个);命名卷显式命名,备份命令里好写。数据量很小(几十 MB 级),bind mount 和命名卷都行,用命名卷省心。

要管别的机器,在那台机器上装 Agent(版本跟 Server 保持一致):

docker run -d \
  -p 9001:9001 \
  --name portainer_agent \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:2.45.2

Agent 同样等于把那台机器的 Docker 交出去,9001 端口用防火墙限定只允许 Portainer Server 的 IP 访问。

配置项逐项解释

Portainer 的日常配置几乎全在网页里,启动参数不多但都很关键:

参数 推荐值 为什么这么写
-v /var/run/docker.sock 必挂 Portainer 管理容器的唯一通道(默认 -H unix:///var/run/docker.sock)。不挂它就是个空壳
-v portainer_data:/data 必挂 用户账号、环境配置、TLS 证书全在里面。不挂卷的 Portainer 重启就回到初始状态,这也是老教程最常见的翻车点
-p 9443:9443 只开这个 HTTPS UI。默认自签证书,浏览器会有警告(见「首次访问」)
--admin-password '<bcrypt哈希>' 无人值守部署用 启动时直接预置管理员密码(要 bcrypt 哈希,不是明文):htpasswd -nbB admin '密码' \| cut -d: -f2 生成。用了它就不会生成 setup token,适合脚本化部署。明文版用 --admin-password-file /tmp/pw(文件内容才是明文),把文件挂进容器
--no-setup-token 仅完全内网用 彻底跳过 setup token 机制。官方态度很明确:只在你完全信任的网络里用
--setup-token <自定义值> 脚本化场景 自己指定 token,方便自动化。一般不用管,默认自动生成
-l <标签> 可选 隐藏带指定 label 的容器,比如把监控探针藏起来不进列表
--sslcert /certs/tls.crt --sslkey /certs/tls.key 有真证书时 把自己的证书挂进容器,替换自签证书。也可以事后在 Settings → SSL certificates 网页里传

网页里的关键设置:Session lifetime 默认 8 小时(Settings → Authentication),管理面板建议改短;密码策略默认最少 12 位,别调低。

1Panel 面板怎么搞

1Panel 应用商店里收录了 Portainer(DevOps 分类),应用市场搜「Portainer」一键装。但装之前想清楚一个定位问题:

  • 1Panel 本身就是容器管理面板(容器列表、镜像、网络、编排都有),功能上跟 Portainer 有一大块重叠
  • 1Panel 的强项是服务器层:网站、SSL、数据库、防火墙、计划任务、备份到云存储
  • Portainer 的强项是容器层做得更细:Stack 在线编辑与更新、容器统计曲线、Web 终端、多机 Agent 组网、应用模板

结论:1Panel 用户如果日常管理没觉得别扭,不必为了装而装;典型值得装的场景是「多台机器想一个面板看完」或「想要网页里直接改 compose 重新部署」的 Stack 工作流。装的时候:

  1. 应用市场 → 搜 Portainer → 安装,端口默认映射 9443(冲突就在弹窗里改宿主端口)
  2. 装完在「容器」列表能看到 portainer 容器;面板防火墙和云安全组放行 9443(华为云 ECS 记得同时检查安全组,只放行给自己的常用 IP 最稳)
  3. 商店版本可能滞后,想钉 2.45.2 就走「容器 → 编排」贴上面的 compose,效果一样

首次访问

浏览器打开 https://服务器IP:9443,第一件事是接受自签证书警告(高级 → 继续访问),这不是被劫持,是 Portainer 默认自己签的证书。

然后是 2.43 版本起新增的一道门:Setup Token。全新的 Portainer 实例要求输入一个一次性 token 才能创建管理员,token 只在容器日志里:

docker logs portainer 2>&1 | grep setup_token

输出里 setup_token=eyJ... 一长串,复制进网页的 Setup token 输入框。接下来 5 分钟内要完成管理员创建(用户名默认 admin,密码最少 12 位)——这是防「新实例刚起就被别人抢先认领」的安全机制,超时会看到 Your Portainer instance has timed out for security purposes,处理办法是重启容器再来一次:

docker stop portainer && docker start portainer

(又有新的 5 分钟,动作快点。)创建完管理员,选 Get Started 纳管本机 Docker 环境,进主页就能看到容器列表。要加别的机器:Environments → Add environment → Docker Standalone → Agent,地址填 那台机器IP:9001。

最小可用配置

部署完成即是最小可用——Portainer 没有必填的配置文件,起来就能管。上手之后建议顺手做三件事:

  1. 改强密码:My account 里确认密码强度;管理面板的密码重要性等同服务器 root
  2. 收紧会话:Settings → Authentication → Session lifetime,8 小时改 2 小时左右(管理面板不该挂一半天不掉线)
  3. 加第二台机器(如果有):Agent 装好后 Environments 里点进去,首页顶部下拉一键切换,两台机器的容器、Stack、镜像在一个界面里管

日常最高频的三个页面:Containers(日志、终端、统计曲线都在列表行内,堆叠的 quick action 一排小图标)、Stacks(compose 即改即更,Editor 里粘贴保存就 up -d)、Images(拉镜像 + 一键清理悬空层,docker system prune 的图形版)。

告警/通知配置

先把话说直:Portainer CE 没有告警和通知功能,容器挂了它不会告诉你。它管「看见和操作」,「出了事主动喊人」要靠组合拳,这个系列的老朋友们正好接上:

需求 方案
Portainer 面板本身挂没挂 第 1 期 Uptime Kuma 加一条 HTTP(s) 探测 https://服务器IP:9443(自签证书记得勾「忽略 TLS 错误」)
容器挂了要通知 两条路:① Uptime Kuma 的 Docker 容器监控(挂 docker.sock 即可逐容器探测);② 第 27 期 Beszel 的容器状态告警。通知都走第 13 期 ntfy
谁在吃内存 Portainer 容器详情页有实时曲线(看现场),Beszel 有历史曲线(看趋势),配合着用
挂了自动拉起 不需要 Portainer——compose 里 restart: unless-stopped 才是第一道防线,Portainer 的 restart 按钮是第二道

一句话:Portainer 是驾驶舱,不是仪表报警灯。报警系统另配,别指望它。

反向代理与 HTTPS

两种上 HTTPS 的路子,按你的拓扑选:

路子 A:反代到 9443(HTTPS 后端)。Portainer 自己已经是 HTTPS(自签),反代要忽略后端证书校验。第 2 期 Nginx Proxy Manager:Proxy Host 转发 scheme 选 https、Forward 到 127.0.0.1:9443,SSL 页签申请真证书 + Force SSL,Websockets Support 打开(容器终端和实时统计要用),再在 Advanced 里加自定义 Nginx 配置 proxy_ssl_verify off;。

路子 B:给 9000 开 HTTP 反代(推荐给内网)。把 9000 映射出来(-p 127.0.0.1:9000:9000 只绑回环更稳),反代直接转发 HTTP,不用管自签证书问题:

server {
    listen 443 ssl;
    server_name portainer.example.com;
    # ssl_certificate / ssl_certificate_key 略

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Upgrade/Connection 两行不能省——Portainer 的 Web 终端(exec)和实时统计走 WebSocket,缺了会出现「终端黑屏/一直连接中」。注意 -p 127.0.0.1:9000:9000 的写法:9000 只绑在本机回环上,外面扫不到,只能被同机的 nginx 转发,这比 0.0.0.0 直接暴露干净得多。

有自己的域名证书也可以不走反代:把证书挂进容器再用 --sslcert/--sslkey 指定(见配置项表格),9443 直接就是真证书。

踩坑清单

  1. 卡在 Setup Token——2.43(LTS 线 2.39.4)起的新机制,token 只在 docker logs portainer 里(搜 setup_token=),一次性使用。看到「找不到创建管理员的入口」基本都是没翻日志
  2. Your Portainer instance has timed out——启动后 5 分钟内没建完管理员,服务自动停掉防劫持。docker restart portainer 重来,或用 --admin-password 预置密码绕过整个流程
  3. 重启后变回初始状态——/data 卷没挂。这是老教程翻车重灾区,compose 里两个 volume 一个都不能少
  4. docker exec -it portainer sh 报 no such file——默认镜像近似 scratch,没有 shell。排障用 docker logs,要进容器的场景换 -alpine 变体
  5. Web 终端打不开/一直转圈——反代没配 WebSocket。补 Upgrade/Connection 两行(或 NPM 勾 Websockets Support)
  6. 浏览器证书警告吓退——9443 默认自签证书,属预期行为。上真证书走反代或 --sslcert,内网用接受一次警告也无妨
  7. tag 写 :2 或 :2.45 拉不到镜像——Portainer 没有滚动主/次版本 tag,实测只有完整版本号和 lts/sts/latest/-alpine。写 2.45.2 或 lts
  8. Agent 连不上——版本要跟 Server 匹配(都用 2.45.2);防火墙放行 9001 且最好限定来源 IP;地址填 IP:9001 不用加协议头
  9. 把 9443 直接暴露公网——docker.sock 的权限在那儿摆着,等于把服务器 root 挂在公网上。至少:强密码 + 反代 HTTPS + 防火墙限 IP(华为云安全组只放行自己常用 IP),更稳的是只走内网/VPN 访问
  10. 生产环境直接上 CE——官方 README 已明确 CE 定位 homelab/非生产,无支持无承诺。公司场景用 BE(Take 3 免费三节点)或者干脆 1Panel + 本系列其他工具组合

备份

Portainer 自身的状态很轻(/data 卷,几十 MB 级 SQLite + 配置),但丢了很烦(账号、环境、Stack 定义全没)。

网页导出:Settings → Backup Portainer,可下载一份配置归档(可设密码保护),恢复在同一页面。注意它只包含 Portainer 自己的配置,不包含你容器们的数据卷——那些数据走各服务自己的备份(比如第 21 期 Kopia)。

暴力方案(迁移到新机器最省事):

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

新机器上反向解包 + 起容器,账号、Stack、环境配置原样回来。

管理员密码忘了:用官方 helper 镜像重置(临时容器,跑完即删):

docker stop portainer
docker run --rm -v portainer_data:/data portainer/helper-reset-password
docker start portainer

日志里会打印临时密码,登录后再改。

小结

适合谁:容器装到十个以上、docker ps 已经一屏刷不完的人;家里 NAS + 云上 VPS 多机部署、想一个面板看完的(Agent 组网是它最值钱的功能);讨厌为改一行 compose 就 SSH 上服务器的人;刚入坑 Docker、想先看见再理解的新手。

不适合谁:服务器上就跑着一两个容器的(命令行更快,别为一棵树装面板);已经在用 1Panel 且只管一台机器、对现状满意的(功能重叠度太高);需要细粒度权限、审计日志、LDAP/OAuth 团队同步的生产环境(那是 BE 的清单,CE 官方也明说了不背生产的锅)。

一句话定位:它是「Docker 的驾驶舱」,不是「监控报警器」也不是「服务器面板」——把「看见并操作容器」这一件事做到顺手,就值回一个容器的部署成本了。

项目地址