Docker 部署 Portainer CE

Portainer CE 提供 Docker 环境的可视化管理界面。本文示例适用于 Linux Docker Engine，并独立于任何业务项目。

Portainer 通过 Docker Socket 管理宿主机时拥有近似宿主管理员的能力。只有受信管理员可以访问该实例，不能把它当作普通低权限 Web 应用。

版本与前置条件

安装 Docker Engine 与 Docker Compose v2。
本文示例固定为 Portainer CE 2.39.6 LTS。部署前应根据 Portainer 支持矩阵确认 Docker Engine、操作系统和 CPU 架构兼容性。
确认主机的 9443 端口未被占用，并准备防火墙或反向代理访问策略。
不使用 latest、lts 或 sts 浮动标签，升级时改为经过验证的明确补丁版本。

Compose 部署

.env：

PORTAINER_VERSION=2.39.6

compose.yaml：

services:
  portainer:
    image: portainer/portainer-ce:${PORTAINER_VERSION}
    restart: unless-stopped
    ports:
      - "127.0.0.1:9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer-data:/data

volumes:
  portainer-data:
    name: portainer-data

此配置只把 HTTPS 管理界面绑定到回环地址。需要远程访问时，应通过受控的反向代理、VPN 或零信任入口提供 TLS 和身份保护，而不是把 9443 直接开放到公网。

Portainer 的 8000 端口只用于部分 Edge Agent 功能，默认无需开放；旧版 HTTP 端口 9000 也不应为新部署启用。

启动：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 portainer

首次初始化与验证

访问 https://127.0.0.1:9443。首次启动使用自签名证书，浏览器会显示证书警告；生产环境应配置受信证书或由反向代理终止 TLS。

首次初始化应立即创建高强度管理员密码。初始化页面有安全超时，如果超时，重启容器后重新访问即可。

验证 API 和容器状态：

# -k 仅用于验证默认自签名证书；生产证书验证不要使用 -k
curl -kfsS https://127.0.0.1:9443/api/status
docker compose ps
docker compose logs --since=10m portainer

权限与网络安全

Docker Socket 可以创建特权容器、挂载宿主目录并读取容器配置，因此必须按宿主管理员权限保护 Portainer。
限制管理员数量，启用适用的身份认证和会话策略，并定期审计操作。
不要把 Docker Remote API 以无 TLS 的 TCP 方式暴露给 Portainer。
管理远程环境时优先使用官方 Agent 或 Edge Agent，并限制 Agent 端口来源。
在 SELinux、rootless Docker 或 Docker Desktop 环境中，挂载方式和功能限制可能不同，应按对应平台官方文档配置。

数据与备份

Portainer 配置和数据库位于 portainer-data 卷。备份前停止容器可获得一致的文件级副本：

docker compose stop portainer
docker run --rm \
  -v portainer-data:/source:ro \
  -v "$PWD:/backup" \
  alpine:3.22 \
  tar -czf /backup/portainer-data-backup.tgz -C /source .
docker compose start portainer

备份可能包含端点信息、访问令牌和其他敏感配置，应加密并限制访问。也可以使用 Portainer 提供的备份功能，但仍需验证恢复流程。

升级

查看 Portainer 发布说明和支持矩阵，确认升级路径。
完成 portainer-data 备份并保存当前镜像版本。
修改 .env 中的明确版本号。
执行 docker compose pull && docker compose up -d。
验证登录、端点连接、堆栈和 API 状态。

不要跨越官方不支持的升级路径；老版本可能需要先升级到指定中间版本。

停止与清理

# 删除容器和网络，保留配置数据
docker compose down

# 查看相关数据卷
docker volume ls --filter name=portainer

只有确认备份可恢复并且不再需要 Portainer 配置时，才执行 docker compose down --volumes。

版本与前置条件​

Compose 部署​

首次初始化与验证​

权限与网络安全​

数据与备份​

升级​

停止与清理​

官方资料​