Portainer：轻量级容器管理 UI 部署与使用指南

一、项目官方信息

Portainer Community Edition（CE） 是一个免费、轻量的容器管理 UI，面向 Docker、Docker Swarm、Podman、Kubernetes 与 ACI 环境。官方 README 明确它的定位：以“as-is”方式免费提供，方便 homelab 玩家、爱好者、学生以及在自己硬件上折腾容器的人使用。

与之配套的 Portainer Business Edition（BE） 基于同一开源底座，额外提供 RBAC 细粒度权限、GitOps、边缘节点管理（edge）、审计、SSO 等生产与企业级能力。CE 定位是 homelab、学习、个人项目等非生产场景。

二、官方图片

上图为 Portainer 官方 GitHub 仓库的 Banner 图。部署完成后，控制台会提供一个图形化界面，用来管理容器、镜像、网络、卷以及 Kubernetes 集群资源。

三、环境要求

• 已安装 Docker 引擎（单机版即可）。
• 对外端口：9443（HTTPS 控制台）；8000 用于 Edge Agent 隧道（若不使用边缘节点可不开）。
• 资源：CPU 0.5 核、内存 256MB 以上即可，非常轻量。
• 浏览器访问 https://服务器IP:9443（自签名证书，首次需在浏览器确认）。
• README 强调 CE 面向非生产场景；生产 / 业务关键环境应使用 Portainer Business Edition。

四、完整部署步骤

1. 创建数据卷

docker volume create portainer_data

该卷用来持久化 Portainer 的配置、用户与状态，避免容器重建后丢失。

2. 启动 Portainer CE 容器

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

参数说明：

• -p 9443:9443：HTTPS Web 控制台端口，部署后浏览器访问它。
• -p 8000:8000：Edge Agent 反向隧道端口；不用边缘节点时可不暴露。
• -v /var/run/docker.sock:/var/run/docker.sock：挂载 Docker 套接字，Portainer 才能管理本机容器。
• -v portainer_data:/data：把数据持久化到上面创建的卷。
• --restart=always：开机 / 崩溃后自动重启。
• 镜像使用 :lts 长期支持标签，跟随官方稳定版本。

3. 确认启动

docker logs -f portainer

日志中应看到 Portainer 监听 9443，无报错。

4. 首次初始化

1. 浏览器打开 https://服务器IP:9443（自签名证书，选择继续访问）。
2. 创建管理员用户：设置用户名与密码（首启后需在 5 分钟内完成设置，否则会自动锁死需重启容器）。
3. 选择管理环境：本地 Docker 选「Get Started」即接入本机 Docker 环境。

5. 验证

登录后进入控制台首页，应能看到本地环境（local），并可在左侧菜单看到 Containers、Images、Networks、Volumes 等管理项；点进 Containers 能看到当前所有容器，与 docker ps 一致即部署成功。

五、使用方法

• 管理容器：Containers 页面可启停、重启、进入终端（Console）、查看日志、删除容器，也可一键「Add container」新建容器。
• 管理镜像 / 网络 / 卷：Images、Networks、Volumes 菜单分别对应 docker images、docker network、docker volume 的可视化操作。
• 部署 Compose Stack：Stacks 菜单可直接粘贴 docker-compose.yml 或从 Git 仓库拉取，一键部署整套服务。
• 多环境管理：可添加远程 Docker（通过 Agent）、Docker Swarm 集群、Kubernetes、Podman 环境，统一在一个控制台管理。
• Edge 节点：通过 8000 端口的 Edge Agent 隧道，可纳管远程、跨网络的边缘节点（BE 能力更强，CE 也有基础支持）。
• CE 与 BE 切换：需要 RBAC、GitOps、SSO、审计等企业能力时，按 README 指引升级到 Business Edition。

六、常见问题 FAQ

1. 打开 https://IP:9443 浏览器提示证书不安全？ 正常。Portainer 默认使用自签名证书，点击“高级 → 继续访问”即可。生产环境建议在反向代理后更换为可信证书。

2. 首次登录提示需要创建管理员，但页面报错 / 超时？ 首启后必须在 5 分钟内设置管理员密码，超时会锁死。重启容器后重试：docker restart portainer。

3. 控制台看不到本机容器？ 检查启动命令是否挂载了 -v /var/run/docker.sock:/var/run/docker.sock；没有挂载 Docker 套接字，Portainer 无法读取本机容器。

4. 9443 与 8000 分别是什么端口？ 9443 是 HTTPS Web 控制台；8000 是 Edge Agent 反向隧道端口。不使用边缘节点管理时，8000 可以不对外暴露。

5. CE 能直接用于生产公司环境吗？ README 明确 CE 面向 homelab、学习等非生产场景，不提供 SLA 与支持。生产 / 业务关键环境请使用 Portainer Business Edition。

6. 数据存在哪里？容器重建会丢吗？ 配置与状态持久化在 portainer_data 卷（容器内 /data）。只要不删除该卷，删除并重建容器后数据仍在。

七、跳转链接

• GitHub 仓库：https://github.com/portainer/portainer
• 官方文档与安装指南：https://docs.portainer.io/start/install-ce
• Business Edition 功能：https://www.portainer.io/features
• Release 列表：https://github.com/portainer/portainer/releases