PORTAINER-CE Docker 容器化部署指南

共计 6756 个字符，预计需要花费 17 分钟才能阅读完成。

概述

PORTAINER-CE（Portainer Community Edition）是一款轻量级的容器化应用交付平台，提供直观的图形用户界面和强大的 API，支持无缝管理 Docker、Swarm、Kubernetes 及 ACI 等多种容器环境。通过 PORTAINER-CE，用户可以高效管理容器、镜像、卷、网络等编排资源，简化容器化应用的部署与运维流程。作为开源社区版本，PORTAINER-CE 适合个人开发者、中小企业及开发团队使用，提供了丰富的功能工具箱和简洁的操作界面，降低了容器技术的使用门槛。

环境准备

Docker 环境安装

PORTAINER-CE 基于 Docker 容器运行，需先部署 Docker 环境。推荐使用官方一键安装脚本，支持主流 Linux 发行版（Ubuntu、Debian、CentOS 等）：

# 一键安装 Docker 环境（包含 Docker Engine、Docker CLI、Docker Compose）bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本执行过程中需保持网络连接，根据系统提示完成安装。安装完成后，可通过以下命令验证 Docker 是否正常运行：

# 检查 Docker 服务状态
systemctl status docker

# 验证 Docker 版本信息
docker --version
docker compose version

验证加速配置是否生效：

# 查看 Docker 镜像加速配置
cat /etc/docker/daemon.json

正常输出应包含 "registry-mirrors": ["https://xxx.xuanyuan.run"] 字段，表明加速配置已生效。

镜像准备

镜像拉取命令

使用轩辕镜像加速拉取命令：

# 拉取 PORTAINER-CE 最新版镜像
docker pull xxx.xuanyuan.run/portainer/portainer-ce:latest

命令说明：

• docker pull：Docker 拉取镜像命令
• xxx.xuanyuan.run：轩辕镜像加速地址
• portainer/portainer-ce：镜像路径（非官方镜像）
• latest：推荐标签（可替换为特定版本号，如 2.19.4）

镜像验证

拉取完成后，验证镜像是否成功获取：

# 查看本地镜像列表
docker images | grep portainer/portainer-ce

预期输出示例：

xxx.xuanyuan.run/portainer/portainer-ce   latest    abc12345   2 weeks ago   280MB

若输出包含上述信息，表明镜像拉取成功。

容器部署

部署规划

PORTAINER-CE 容器部署需考虑以下关键配置：

• 端口映射：Web 管理界面（9000）、Edge 代理（8000）
• 数据持久化：配置数据（/data）、Docker 套接字（/var/run/docker.sock）
• 重启策略：容器异常退出后自动重启
• 权限配置：挂载 Docker 套接字需确保权限正确

部署命令

# 创建 PORTAINER-CE 数据持久化目录
mkdir -p /data/portainer

# 启动 PORTAINER-CE 容器
docker run -d \
  --name portainer \
  --restart always \
  -p 9000:9000 \
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /data/portainer:/data \
  xxx.xuanyuan.run/portainer/portainer-ce:latest

参数说明：

• -d：后台运行容器
• --name portainer：指定容器名称为 portainer
• --restart always：容器退出时自动重启
• -p 9000:9000：映射 Web 管理界面端口（主机: 容器）
• -p 8000:8000：映射 Edge 代理端口（用于远程管理）
• -v /var/run/docker.sock:/var/run/docker.sock：挂载 Docker 守护进程套接字（实现容器管理宿主机 Docker）
• -v /data/portainer:/data：挂载数据卷（持久化配置数据）
• xxx.xuanyuan.run/portainer/portainer-ce:latest：使用的镜像及标签

部署验证

容器启动后，验证部署状态：

# 查看容器运行状态
docker ps | grep portainer

预期输出示例：

abc123456   xxx.xuanyuan.run/portainer/portainer-ce:latest   "/portainer"   5 minutes ago   Up 5 minutes   0.0.0.0:8000->8000/tcp, 0.0.0.0:9000->9000/tcp   portainer

关键状态说明：

• Up 5 minutes：容器正常运行（若显示 Exited 则表示启动失败）
• 端口映射：0.0.0.0:9000->9000/tcp表明端口映射成功

查看容器日志，确认服务启动状态：

# 查看 PORTAINER-CE 容器日志
docker logs portainer

若日志包含2024/05/20 12:00:00 server: Listening on 0.0.0.0:9000...，表明服务启动正常。

功能测试

Web 界面访问

1. 访问地址：在浏览器中输入 http://< 服务器 IP>:9000
2. 初始设置：首次访问需创建管理员账户
   • 设置管理员用户名（默认 admin）
   • 设置强密码（至少 8 位，包含大小写字母、数字和特殊符号）
3. 环境选择：选择 ”Docker” 作为管理环境（本地 Docker）

基础功能验证

1. 仪表盘检查

• 登录后进入仪表盘，验证是否显示宿主机 Docker 信息
• 检查容器数量、镜像数量、CPU/ 内存使用率等指标是否正常

2. 容器管理测试

# 在宿主机创建测试容器
docker run -d --name test-nginx nginx:alpine

在 PORTAINER-CE 界面中：

• 导航至 ” 容器 ” 菜单
• 确认 ”test-nginx” 容器状态为 ” 运行中 ”
• 尝试执行 ” 停止 ”→” 启动 ”→” 删除 ” 操作，验证管理功能

3. 镜像管理测试

在 PORTAINER-CE 界面中：

• 导航至 ” 镜像 ” 菜单
• 查看本地镜像列表，确认包含 portainer/portainer-ce 和 nginx:alpine
• 尝试拉取新镜像（如 ubuntu:latest），验证镜像拉取功能

4. 数据卷测试

在 PORTAINER-CE 界面中：

• 导航至 ” 卷 ” 菜单
• 查看已挂载的 portainer 数据卷（/data/portainer）
• 验证卷大小、挂载点等信息是否正确

服务可用性验证

持续观察 30 分钟，确认以下指标：

• 容器稳定运行，无异常退出
• Web 界面响应正常，无卡顿
• 功能操作（如创建 / 删除容器）无错误提示
• 资源占用稳定（CPU<10%，内存 <200MB）

生产环境建议

数据持久化强化

PORTAINER-CE 的配置数据（包括用户账户、权限设置、环境配置等）存储在 /data 目录，生产环境需采取以下措施：

1. 使用命名卷而非主机目录：

# 创建专用数据卷
docker volume create portainer_data

# 使用命名卷启动容器（替换原 -v /data/portainer:/data）-v portainer_data:/data

2. 定期备份数据卷：

# 创建数据备份脚本（backup-portainer.sh）#!/bin/bash
BACKUP_DIR="/backup/portainer"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# 备份 portainer 数据卷
docker run --rm -v portainer_data:/source -v $BACKUP_DIR:/backup alpine \
  tar -czf /backup/portainer_backup_$TIMESTAMP.tar.gz -C /source .

# 保留最近 30 天备份
find $BACKUP_DIR -name "portainer_backup_*.tar.gz" -mtime +30 -delete

安全配置优化

1. 启用 HTTPS 访问：
   PORTAINER-CE 支持使用 SSL 证书加密 Web 访问，配置方法：

# 停止现有容器
docker stop portainer && docker rm portainer

# 使用 HTTPS 启动容器（替换原端口映射）docker run -d \
  --name portainer \
  --restart always \
  -p 9443:9443 \  # HTTPS 端口
  -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  -v /etc/ssl/certs/portainer.crt:/certs/portainer.crt \  # SSL 证书
  -v /etc/ssl/private/portainer.key:/certs/portainer.key \  # SSL 密钥
  xxx.xuanyuan.run/portainer/portainer-ce:latest \
  --ssl --sslcert /certs/portainer.crt --sslkey /certs/portainer.key

2. 最小权限原则 ：
   避免直接挂载/var/run/docker.sock（具有 root 权限），生产环境建议：

• 使用 Docker API 代理（如 docker-proxy）限制权限
• 配置 Docker 用户命名空间，隔离容器权限

3. 网络隔离：

• 将 PORTAINER-CE 部署在独立 Docker 网络
• 配置防火墙，仅允许特定 IP 访问 9000 端口

资源限制配置

为防止 PORTAINER-CE 过度占用系统资源，生产环境需设置资源限制：

# 添加资源限制参数（启动命令中）--memory=512m \          # 最大内存限制
--memory-swap=1g \       # 最大内存 + 交换空间限制
--cpus=0.5 \             # CPU 核心限制（0.5 核）--cpu-shares=512 \       # CPU 权重（默认 1024，降低优先级）

高可用部署

对关键业务场景，建议采用 PORTAINER-CE 高可用部署方案：

1. Swarm 模式部署：

# 初始化 Swarm 集群（管理节点）docker swarm init

# 部署 PORTAINER-CE stack
docker stack deploy -c docker-compose.yml portainer

docker-compose.yml 示例：

version: '3.8'
services:
  portainer:
    image: xxx.xuanyuan.run/portainer/portainer-ce:latest
    command: -H tcp://tasks.agent:9001 --tlsskipverify
    ports:
      - "9000:9000"
      - "8000:8000"
    volumes:
      - portainer_data:/data
    deploy:
      replicas: 1
      placement:
        constraints: [node.role == manager]
  
  agent:
    image: xxx.xuanyuan.run/portainer/agent:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
    deploy:
      mode: global
      placement:
        constraints: [node.platform.os == linux]
volumes:
  portainer_data:

2. 多节点数据同步：

• 使用 NFS 共享存储挂载 /data 目录
• 配置数据库主从复制（PORTAINER-CE 使用 sqlite，可考虑迁移至 PostgreSQL）

故障排查

容器启动失败

症状

执行 docker ps 未显示 portainer 容器，或 docker logs portainer 显示错误信息。

排查步骤

1. 查看详细日志：

docker logs portainer

2. 常见错误及解决方法：

Web 界面无法访问

症状

浏览器访问 http://<IP>:9000 无响应或显示 ” 无法连接 ”。

排查步骤

1. 网络连通性检查：

# 服务器本地测试端口
curl -I http://127.0.0.1:9000

# 客户端测试网络连通性
telnet < 服务器 IP> 9000

2. 防火墙配置检查：

# 查看防火墙规则（CentOS/RHEL）firewall-cmd --list-ports

# 开放 9000 端口（若未开放）firewall-cmd --add-port=9000/tcp --permanent
firewall-cmd --reload

# 查看防火墙规则（Ubuntu/Debian）ufw status
ufw allow 9000/tcp

3. SELinux/AppArmor 检查：

# 查看 SELinux 状态（CentOS/RHEL）getenforce

# 临时关闭 SELinux（排查用）setenforce 0

# 查看 AppArmor 状态（Ubuntu/Debian）aa-status

数据丢失问题

症状

PORTAINER-CE 配置信息（用户、权限等）丢失或重置。

排查步骤

1. 数据卷挂载检查：

# 查看容器挂载信息
docker inspect -f '{{.Mounts}}' portainer

确认 /data 目录正确挂载到持久化存储（主机目录或命名卷）。

2. 存储介质检查：

• 检查数据卷所在磁盘空间：df -h /data/portainer
• 检查文件系统完整性：fsck /dev/sdX（需卸载后执行）

3. 恢复数据 ：
   使用之前创建的备份恢复数据：

# 恢复数据到 portainer_data 卷
docker run --rm -v portainer_data:/target -v /backup/portainer:/source alpine \
  sh -c "rm -rf /target/* && tar -xzf /source/portainer_backup_20240520_120000.tar.gz -C /target"

性能问题

症状

Web 界面卡顿、操作响应缓慢、容器管理延迟。

排查步骤

1. 资源占用检查：

# 查看容器资源占用
docker stats portainer --no-stream

# 查看系统整体资源
top

2. 日志级别调整：

# 修改日志级别为 debug（启动命令添加）--log-level debug

# 分析详细日志
docker logs portainer | grep -i error

3. 优化建议：

• 增加内存限制（如 –memory=1g）
• 清理无用容器 / 镜像释放磁盘空间
• 升级服务器硬件（适用于长期高负载场景）

参考资源

官方文档

• PORTAINER-CE 官方文档：https://xuanyuan.cloud/r/portainer/portainer-ce
• 镜像标签列表：https://xuanyuan.cloud/r/portainer/portainer-ce/tags
• Portainer 官方文档：https://docs.portainer.io

技术社区

• GitHub 仓库：https://github.com/portainer/portainer
• Issue 跟踪：https://github.com/portainer/portainer/issues

相关工具

• Docker 官方文档：https://docs.docker.com
• Docker Compose 文档：https://docs.docker.com/compose
• 轩辕镜像加速：https://xuanyuan.cloud