---
title: "Portainer"
tags: [docker, container, management, web-ui]
date: 2026-04-22
---

# Portainer

## Description
Portainer 是一个开源的 Docker 和 Kubernetes 可视化管理工具，通过 Web UI 简化容器、镜像、卷、网络、配置的日常运维操作。Community Edition（CE）免费开源，BE（Business Edition）提供额外安全和企业功能。

## Versions
- **Portainer CE**（社区版）：免费开源，通过 `portainer/portainer-ce:lts` 镜像部署
- **Portainer BE**（商业版）：面向企业，支持 RBAC、审计日志、团队管理等

## Deployment
```yaml
services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9443:9443"   # HTTPS API
      - "8000:8000"   # Edge Agent
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    volumes:
  portainer_data:
```

## Key Ports
| 端口 | 用途 |
|------|------|
| 9443 | HTTPS 管理 API（Web UI） |
| 8000 | Edge Agent 通信端口 |

## Key Concepts

### Volume
Portainer 的 `portainer_data` 卷存储所有持久化数据：
- 用户账户和认证信息
- 环境配置和设置
- Edge Agent 连接信息
- 团队和角色定义（BE 版）

**删除该卷会永久丢失所有数据**，重装前务必确认是否需要保留。

### Network
Portainer 默认创建 `portainer_network` bridge 网络（或类似名称），供 Agent 和 Core 通信。

### 重装流程
当需要重新部署 Portainer 时，必须先清理旧资源，否则会产生警告：
```bash
# 1. 查找容器
docker ps -a | grep portainer

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

# 3. 查看旧卷（可选）
docker volume ls | grep portainer

# 4. 如需保留数据，不删卷；如需全新开始，删卷
docker volume rm portainer_data

# 5. 查看旧网络（可选）
docker network ls | grep portainer

# 6. 如需重建，删旧网络
docker network rm portainer_network

# 7. 重新启动
docker compose up -d
```

### External Mode（数据保留重装）
若需保留现有配置和数据，在 compose 文件中声明：
```yaml
volumes:
  portainer_data:
    external: true
networks:
  portainer_network:
    external: true
```
这样 `docker compose up` 不会尝试创建同名卷/网络，而是直接复用已存在的。

## Common Warnings

### WARN 1: Network 已存在但不是当前项目创建
**原因**：之前的 compose 文件（或不同项目名）已创建了同名网络。
**解决**：在 compose 中声明 `external: true` 复用，或删除旧网络后重建。

### WARN 2: Volume 已存在但属于另一个 compose 项目
**原因**：使用不同项目名部署过 Portainer，遗留了旧卷。
**解决**：同上。

## Alternatives
- **CLI 工具**：`docker ps`、`docker volume ls`、`docker network ls` 等命令行管理
- **LazyDocker**：终端 TUI 工具
- **DockStation**：桌面应用

## Related Concepts
- [[Docker]] — Portainer 管理的底层容器化平台
- [[Docker Compose]] — Portainer 的推荐部署方式
- [[Docker卷]] — Portainer 的持久化存储
- [[Docker Network]] — Portainer 的网络连接
- [[external配置]] — compose 中复用外部资源的机制

## Related Entities
- [[LinuxServer.io]] — 开源 Docker 镜像维护组织（Portainer 是独立组织）
- [[群晖 NAS]] — Portainer 常见的部署平台
- [[Docker]] — Portainer 管理的核心对象