portainer

Portainer 部署与核心功能详解

一、Portainer部署

推荐用容器部署

sudo docker run -d   -p 9999:9000   --name portainer   --restart=always   -v /var/run/docker.sock:/var/run/docker.sock   -v /server/dev/portainer:/data   portainer/portainer-ce:latest

参数	说明
-p 9999:9000	Web UI
-v docker.sock	关键：赋予 Portainer 管理宿主 Docker 的权限
-v /server/dev/portainer:/data	持久化 Portainer 配置、用户、Stack 定义

• 首次访问设置管理员密码。
• 根据提示通过docker logs获取安装时的token(新版本需要此逻辑)。

---

二、镜像

1. 拉取镜像

输入镜像名称后从 Registry（Docker Hub / 私有仓库）拉取到本地。

2. 构建镜像

通过 UI 上传或编写 Dockerfile，底层执行 docker build。

• Web editor：直接在页面写 Dockerfile
• Upload：上传本地 .dockerfile 或 .tar(需要包含dockerfile文件) 构建上下文
• URL：指定远程 Dockerfile 地址

⚠️ 要求宿主机 支持Docker API，构建后的镜像保存在本地镜像列表。

3. 导入 / 导出镜像

• Import image：上传 docker save 生成的 .tar 文件，导入为本地镜像（等价于 docker load -i xxx.tar）
• Export image：将选中的本地镜像导出为 .tar 文件（等价于 docker save）
• 常用于离线环境迁移镜像。

4. 基于容器创建镜像

在 Containers → 某容器详情页 → Create image from container，底层执行 docker commit。

• 填写新镜像名如 myapp:snapshot
• 可选勾选 Pause container during commit

重要限制：

• ✅ 保存容器可写层（文件增删改、配置）
• ❌ 不包含 -v Volume 挂载的数据
• ❌ 不可复现、无构建历史，仅适合调试快照或应急备份，不推荐生产使用

5. 推送镜像

选中镜像 → Push，需提前在 Portainer → Registries 配置 Docker Hub / Harbor 凭据。

---

三、模板

内置模板

Portainer 预置 Nginx、MySQL、Redis、PostgreSQL、WordPress 等常用服务模板。

• 点击模板 → 填端口/密码/卷 → Deploy the container / Deploy the stack
• 适合快速拉起标准单容器或简单多服务，无需手写 Compose。

自定义模板

入口：App Templates → Custom Templates → Add custom template

• 粘贴 Docker Compose YAML 或单容器配置
• Build method 支持 Web editor / Upload / Git repository
• 部署时填写 Stack Name 即可一键生成 Stack

注意事项：

• Custom Template 仅是生成器，修改模板不会自动同步已部署的 Stack，需手动去 Stack 里 Update
• CE 版不支持模板变量 {{variable}}（BE 版支持）

💡 若需模板改动自动同步实例，建议使用 Stack from Git Repository + Pull and redeploy。

---

四、堆栈（Compose 管理）

入口：左侧菜单 → Stacks → Add stack

Stack 是 Portainer 对 docker compose 的可视化封装，管理一组关联容器。

部署方式

方式	说明
Web editor	直接粘贴 docker-compose.yml，最常用
Upload	上传本地 docker-compose.yml
Repository	指定 Git 仓库 + 分支 + Compose 路径，支持轮询 / Webhook 触发重部署（推荐生产）

更新 Stack

修改 YAML 后点 Update the stack，底层执行 docker compose up -d，只更新修改的容器(docker compose原理，未修改的容器不受影响)。

场景	操作
image tag 变了（v1→v2）	直接 Update，自动重建
tag 未变（覆盖 latest）	需 CLI 执行 docker compose up -d --force-recreate（CE UI 无此勾选框）
改端口/环境变量/挂载	直接 Update，自动重建

删除 Stack

会停止并删除 Stack 创建的所有容器、网络，但不会自动删除镜像和 Volume（需手动清理）。

---

五、Containers / Networks / Volumes

模块	作用
Containers	单容器生命周期管理（Add Container 表单化创建、启动/停止/重启/删除/Console/Logs/Inspect）适合快速测试单容器
Networks	创建自定义 Bridge / Overlay / Macvlan 网络，控制容器间互通与隔离
Volumes	创建/删除/查看挂载卷，识别孤儿卷（未使用的 Volume 可安全清理）

---

六、关键注意事项汇总

1. -v 挂载内容不会被 docker commit 或 docker build 打入镜像，想固化必须 COPY。
2. Custom Template ≠ Stack 实例，模板更新不联动已部署 Stack。
3. 生产镜像用 Dockerfile + docker build，避免 docker commit。
4. Stack 更新 latest 标签镜像，Portainer CE 需用 CLI docker compose up -d --force-recreate。
5. Portainer 需挂载 /var/run/docker.sock 才有管理权限，否则只能管理自身。
6. 删除 Stack 不删 Volume/Image，注意定期 Prune 释放空间。

---