Portainer 完全安装与使用指南

一、什么是 Portainer？

Portainer 是一个开源的、轻量级的 Docker 可视化管理工具，它通过提供图形化 Web 界面，让用户无需记忆复杂的命令行即可完成 Docker 容器、镜像、网络、卷等资源的管理。

核心功能：

功能模块说明
容器管理启动/停止/重启/删除容器，查看日志，进入容器终端
镜像管理拉取/删除/构建镜像，查看镜像详情
网络管理创建/删除 Docker 网络，管理网络配置
卷管理创建/删除数据卷，管理数据持久化
Stack 管理通过 Compose 文件批量部署服务
资源监控实时查看 CPU、内存、网络使用情况
多环境管理同时管理多个 Docker 环境（本地、远程、Swarm、Kubernetes）

架构说明：Portainer 由两个核心组件组成 —— Portainer Server（主服务）和 Portainer Agent（代理）。Server 提供 Web 界面和 API，Agent 部署在被管理的节点上，负责与 Docker 守护进程通信。

二、准备工作

2.1 系统要求

项目要求
操作系统Ubuntu 20.04 / 22.04 / 24.04（推荐）
CPU最低 2 核，推荐 4 核
内存最低 2GB，推荐 4GB
磁盘空间至少 10GB 可用空间

2.2 软件依赖

  • Docker：20.10 及以上版本
  • Docker Compose：v2 版本（推荐）

2.3 网络端口

端口协议用途是否必须
9443TCPPortainer Web 界面（HTTPS）必须
8000TCPEdge Agent 通信端口可选（使用 Edge 功能时需要）
9000TCP旧版 HTTP 端口可选（已弃用，建议用 9443）

重要说明：

  • 从 Portainer 2.0 版本开始，默认使用 HTTPS 端口 9443，不再使用 9000
  • 如果必须使用 9000 端口，需在启动命令中显式添加 -p 9000:9000

2.4 域名（可选）

如果希望通过域名 HTTPS 访问 Portainer，可以配置 Nginx 反向代理。需要添加 DNS 记录（如 portainer.example.com 指向服务器 IP）。

三、安装 Docker

如果尚未安装 Docker，执行以下命令：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装依赖
sudo apt install -y ca-certificates curl

# 安装 Docker（官方一键脚本）
curl -fsSL https://get.docker.com | sudo sh

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER

执行完上述命令后，必须退出 SSH 重新登录，或者执行 newgrp docker 使权限生效。

验证 Docker 安装成功：

docker --version
docker compose version

四、安装 Portainer

4.1 方式一：使用 docker run 命令安装（推荐）

这是官方推荐的最简单安装方式。

# 创建 Portainer 数据卷（用于持久化存储数据库）
docker volume create portainer_data

# 运行 Portainer 容器
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

参数说明：

参数说明
-d后台运行容器
-p 8000:8000映射 Edge Agent 通信端口
-p 9443:9443映射 Web 界面 HTTPS 端口
--name portainer容器名称
--restart=always容器自动重启
-v /var/run/docker.sock挂载 Docker 套接字，让 Portainer 与 Docker 守护进程通信
-v portainer_data:/data挂载数据卷，持久化配置

验证容器运行状态：

docker ps | grep portainer

预期输出显示 Up 状态。

4.2 方式二：使用 Docker Compose 安装（推荐用于已用 Compose 的项目）

创建 docker-compose.yml 文件：

mkdir -p ~/portainer && cd ~/portainer
nano docker-compose.yml
services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    ports:
      - "8000:8000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

启动：

docker compose up -d

五、首次访问与初始化配置

5.1 访问 Web 界面

浏览器打开 https://你的服务器IP:9443

注意：

  • 使用 https 而非 http
  • Portainer 默认使用自签名 SSL 证书，浏览器会提示不安全，点击”高级”→”继续访问”即可
  • 如果使用域名，建议后续配置正式 SSL 证书

5.2 创建管理员账户

首次访问会显示初始设置页面，需要：

  1. 设置管理员密码：输入密码并确认（建议使用强密码）
  2. 点击 “Create User”

5.3 连接 Docker 环境

初始化完成后，会显示环境设置向导：

  1. 选择 “Get Started”（本地 Docker 环境）
  2. 确认连接信息：显示连接本地 Docker 的配置
  3. 点击 “Connect”

连接成功后进入 Portainer 主界面。

5.4 切换中文界面

Portainer 官方支持多语言，包括简体中文：

  1. 登录后，点击左下角您的用户名
  2. 选择 Settings
  3. 在 Language 下拉菜单中选择 Chinese (Simplified)
  4. 保存设置

注意：无需额外下载汉化包，语言切换是内置功能。

六、配置 Nginx 反向代理（可选）

如果希望通过域名 HTTPS 访问 Portainer，可使用 Nginx 反向代理。

6.1 安装 Nginx 和 Certbot

sudo apt install -y nginx certbot python3-certbot-nginx

6.2 创建 Nginx 配置

sudo nano /etc/nginx/sites-available/portainer
server {
    listen 80;
    server_name portainer.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name portainer.example.com;

    ssl_certificate /etc/letsencrypt/live/portainer.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portainer.example.com/privkey.pem;

    location / {
        proxy_pass https://127.0.0.1:9443;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_set_header X-Forwarded-Proto $scheme;
    }
}

注意：proxy_pass 使用 https 协议连接到 Portainer 的 9443 端口。

6.3 启用配置并申请证书

sudo ln -s /etc/nginx/sites-available/portainer /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d portainer.example.com

七、Portainer 主要功能使用

7.1 仪表盘（Dashboard）

登录后首先看到仪表盘，显示：

  • 当前环境信息（本地 Docker、Swarm、Kubernetes 等）
  • 容器/镜像/网络/卷的数量统计
  • 系统资源使用概况

7.2 容器管理（Containers）

左侧菜单点击 Containers：

操作说明
查看列表显示所有容器（包括运行中和已停止）
启动/停止/重启点击容器行内按钮
查看日志点击容器 → Logs
进入终端点击容器 → Console
查看详情点击容器 → Inspect
删除容器点击删除按钮
创建容器点击 Add container 按钮，填写配置

7.3 镜像管理（Images）

左侧菜单点击 Images：

操作说明
查看列表显示已下载的所有镜像
拉取镜像点击 Pull image，输入镜像名称（如 nginx:latest）
删除镜像点击删除按钮（需先删除依赖的容器）
构建镜像点击 Build image，上传 Dockerfile

7.4 网络管理（Networks）

左侧菜单点击 Networks：

操作说明
查看列表显示所有 Docker 网络
创建网络点击 Add network，选择驱动类型（bridge、overlay 等）
删除网络点击删除按钮（需先移除连接的容器）

7.5 卷管理（Volumes）

左侧菜单点击 Volumes：

操作说明
查看列表显示所有数据卷
创建卷点击 Add volume，输入名称
删除卷点击删除按钮（需先删除使用该卷的容器）

7.6 Stack 管理（Compose 项目）

左侧菜单点击 Stacks：

操作说明
添加 Stack点击 Add stack
Web 编辑器选择 Web editor，粘贴 docker-compose.yml 内容
上传文件选择 Upload，上传 compose 文件
部署点击 Deploy the stack

部署后可以：

  • 查看 Stack 详情
  • 更新 Stack（修改配置后 Update）
  • 删除 Stack（同时删除相关容器）

7.7 主机监控（Host）

左侧菜单点击 Host：

  • 查看宿主机系统信息（操作系统、内核版本、CPU、内存）
  • 实时资源使用图表

八、防火墙配置

8.1 阿里云/腾讯云等云服务器

在云控制台的安全组中添加入方向规则：

端口协议授权对象说明
9443TCP0.0.0.0/0Portainer Web 界面（HTTPS）
8000TCP0.0.0.0/0Edge Agent 通信（如需使用）
80TCP0.0.0.0/0HTTP（Nginx 反向代理）
443TCP0.0.0.0/0HTTPS（Nginx 反向代理）

8.2 系统防火墙（如已启用 ufw）

sudo ufw allow 9443/tcp
sudo ufw allow 8000/tcp
sudo ufw reload

九、常用管理命令

9.1 容器管理

# 查看容器状态
docker ps

# 停止 Portainer
docker stop portainer

# 启动 Portainer
docker start portainer

# 重启 Portainer
docker restart portainer

# 查看日志
docker logs portainer --tail 50

# 删除 Portainer（同时删除数据卷需谨慎）
docker rm -f portainer
docker volume rm portainer_data  # 删除配置数据

9.2 更新 Portainer

# 停止并删除旧容器
docker stop portainer
docker rm portainer

# 拉取最新镜像
docker pull portainer/portainer-ce:lts

# 重新运行容器（使用相同参数）
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

9.3 备份与恢复

备份数据卷：

# 备份 portainer_data 卷
docker run --rm -v portainer_data:/source -v $(pwd):/backup \
  alpine tar czf /backup/portainer_backup.tar.gz -C /source .

恢复数据卷：

# 先确保卷已被删除
docker volume rm portainer_data

# 重新创建卷
docker volume create portainer_data

# 恢复数据
docker run --rm -v portainer_data:/target -v $(pwd):/backup \
  alpine tar xzf /backup/portainer_backup.tar.gz -C /target

十、常见问题排查

Q1: 访问 Portainer 显示无法连接

原因：容器未运行或端口未开放

解决：

# 检查容器状态
docker ps | grep portainer

# 检查端口监听
sudo ss -tulnp | grep -E '9443|8000'

# 检查防火墙/安全组是否开放 9443 端口

Q2: 浏览器提示”您的连接不是私密连接”

原因：Portainer 使用自签名 SSL 证书

解决：

  • 点击”高级” → “继续访问”（安全，仅用于测试）
  • 或配置 Nginx 反向代理并申请正式 SSL 证书

Q3: 无法管理容器（提示权限不足）

原因：/var/run/docker.sock 挂载权限问题

解决：

# 检查 Docker 套接字权限
ls -la /var/run/docker.sock

# 确保容器启动命令中有 -v /var/run/docker.sock:/var/run/docker.sock

Q4: 页面空白或样式错乱

原因：浏览器缓存

解决：

  • 强制刷新：Ctrl + Shift + R（Windows）或 Cmd + Shift + R（Mac）
  • 清除浏览器缓存
  • 使用无痕模式访问

Q5: 忘记管理员密码

解决：需要重置数据卷

docker stop portainer
docker rm portainer
docker volume rm portainer_data
# 重新运行容器，重新创建管理员账户

十一、总结

安装流程回顾

步骤操作验证方法
1安装 Dockerdocker --version
2创建数据卷docker volume ls 看到 portainer_data
3运行 Portainer 容器docker ps 显示 Up
4访问 Web 界面浏览器打开 https://IP:9443
5创建管理员账户登录成功
6连接 Docker 环境看到仪表盘

端口速查表

端口协议用途必须开放
9443HTTPSPortainer Web 界面✅ 是
8000TCPEdge Agent 通信可选
9000TCP旧版 HTTP（已弃用）不推荐

为什么选择 Portainer？

优势说明
开源免费CE 版本完全开源，无功能限制
轻量级单容器部署，资源占用低
功能完整覆盖 Docker 所有核心操作
多语言支持包括简体中文，无需汉化包
跨平台支持 Docker、Swarm、Kubernetes
活跃社区官方文档完善，更新频繁

作者

老丹

关注我
其他文章