329 lines
7.6 KiB
Markdown
329 lines
7.6 KiB
Markdown
# Portainer CE 部署指南
|
||
|
||
Docker 可视化管理工具，支持容器、镜像、网络、卷的 Web 管理，以及实时日志、终端接入、堆栈管理等功能。
|
||
|
||
## 功能特性
|
||
|
||
- Web 可视化管理 Docker 容器、镜像、网络、卷
|
||
- Docker Compose 堆栈管理（在线编辑、部署、更新）
|
||
- 容器实时日志查看
|
||
- 容器内终端（Web Console）
|
||
- 镜像拉取、构建、删除
|
||
- 容器资源监控（CPU、内存、网络）
|
||
- 多用户权限管理
|
||
- 支持 Docker Standalone / Swarm / Kubernetes
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| Portainer CE | 2.39 LTS | Docker 可视化管理（社区版） |
|
||
| Nginx | 系统包 | 反向代理 + HTTPS 接入 |
|
||
| Docker | 最新版 | 容器运行环境 |
|
||
|
||
## 前置条件
|
||
|
||
1. 一台 Linux 服务器（Ubuntu 22.04/24.04 推荐）
|
||
2. 一个已解析到服务器的域名（如 `docker.example.com`）
|
||
3. 服务器 80/443 端口可从外网访问
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
portainer/
|
||
├── docker-compose.yml # 容器编排
|
||
├── .env.example # 配置模板
|
||
├── deploy.sh # 一键部署脚本
|
||
├── backup.sh # 备份脚本
|
||
├── uninstall.sh # 完全卸载脚本
|
||
├── nginx/
|
||
│ └── portainer.conf # Nginx 反向代理配置
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
服务器上的数据目录：
|
||
|
||
```
|
||
/var/lib/portainer/ # Portainer 数据（BoltDB + TLS 证书）
|
||
/var/backups/portainer/ # 备份文件
|
||
```
|
||
|
||
## 快速部署
|
||
|
||
### 第一步：上传文件到服务器
|
||
|
||
```bash
|
||
# 在本地执行，上传 portainer 目录
|
||
scp -r portainer/ root@<服务器IP>:/opt/portainer
|
||
|
||
# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
|
||
scp -r base/ root@<服务器IP>:/opt/base
|
||
```
|
||
|
||
### 第二步：登录服务器执行部署
|
||
|
||
```bash
|
||
ssh root@<服务器IP>
|
||
|
||
# 如果是全新服务器，先安装基础环境
|
||
cd /opt/base
|
||
cp .env.example .env
|
||
bash setup.sh
|
||
|
||
# 部署 Portainer
|
||
cd /opt/portainer
|
||
bash deploy.sh
|
||
# 首次运行会生成 .env，按提示修改配置后重新运行
|
||
vi .env
|
||
bash deploy.sh
|
||
```
|
||
|
||
### 第三步：配置域名解析
|
||
|
||
在域名服务商（如阿里云 DNS）添加 A 记录：
|
||
|
||
| 记录类型 | 主机记录 | 记录值 |
|
||
|----------|----------|--------|
|
||
| A | docker | `<服务器公网IP>` |
|
||
|
||
### 第四步：创建管理员账号
|
||
|
||
1. 浏览器访问 `https://docker.yourdomain.com`
|
||
2. **首次访问必须在 5 分钟内创建管理员账号**
|
||
3. 设置管理员用户名和密码（密码至少 12 位）
|
||
|
||
> **⚠️ 重要：如果超过 5 分钟未创建账号，Portainer 会自动锁定。需要重启容器重新计时：**
|
||
>
|
||
> ```bash
|
||
> cd /opt/portainer && docker compose restart
|
||
> ```
|
||
|
||
### 第五步：连接本地 Docker
|
||
|
||
1. 登录后选择「Get Started」
|
||
2. 点击「local」环境即可管理本机 Docker
|
||
3. 可以看到所有运行中的容器、镜像、网络、卷
|
||
|
||
## 配置说明
|
||
|
||
### .env 配置项
|
||
|
||
| 变量 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `PORTAINER_DOMAIN` | 访问域名 | 必填 |
|
||
| `CERTBOT_EMAIL` | Let's Encrypt 邮箱 | 必填 |
|
||
| `PORTAINER_IMAGE` | Docker 镜像 | `portainer/portainer-ce:lts` |
|
||
| `PORTAINER_DATA_DIR` | 数据目录 | `/var/lib/portainer` |
|
||
| `BACKUP_DIR` | 备份目录 | `/var/backups/portainer` |
|
||
|
||
### 镜像版本说明
|
||
|
||
| 标签 | 说明 |
|
||
|------|------|
|
||
| `lts` | 长期支持版（推荐，当前为 2.39.x） |
|
||
| `sts` | 短期支持版（功能更新更快） |
|
||
| `latest` | 最新版（等同于 sts） |
|
||
| `2.39.1` | 指定版本号 |
|
||
|
||
## 日常运维
|
||
|
||
### 查看日志
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
docker compose logs -f
|
||
docker compose logs --tail 100
|
||
```
|
||
|
||
### 备份
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
bash backup.sh
|
||
```
|
||
|
||
备份内容包括：
|
||
- Portainer 数据（BoltDB 数据库 + TLS 证书 + 设置）
|
||
- 部署配置（`docker-compose.yml` + `.env` + `nginx/`）
|
||
|
||
备份文件保存在 `/var/backups/portainer/`，自动清理 30 天前的旧备份。
|
||
|
||
### 恢复备份
|
||
|
||
```bash
|
||
# 查看可用备份
|
||
ls /var/backups/portainer/
|
||
|
||
# 停止服务
|
||
cd /opt/portainer && docker compose down
|
||
|
||
# 恢复数据
|
||
tar xzf /var/backups/portainer/<日期>/portainer-data.tar.gz -C /var/lib/
|
||
|
||
# 重启服务
|
||
cd /opt/portainer && docker compose up -d
|
||
```
|
||
|
||
### 升级
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
|
||
# 1. 备份当前数据
|
||
bash backup.sh
|
||
|
||
# 2. 拉取新镜像
|
||
docker compose pull
|
||
|
||
# 3. 停止旧容器并启动新容器
|
||
docker compose down
|
||
docker compose up -d
|
||
|
||
# 4. 检查运行状态
|
||
docker compose ps
|
||
docker compose logs --tail 20
|
||
```
|
||
|
||
### 停止 / 启动
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
docker compose down # 停止
|
||
docker compose up -d # 启动
|
||
docker compose restart # 重启
|
||
```
|
||
|
||
## 完全卸载
|
||
|
||
如果需要从服务器上完全移除 Portainer，使用卸载脚本：
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
bash uninstall.sh
|
||
```
|
||
|
||
脚本会**交互式确认**每个危险操作，按顺序执行：
|
||
|
||
| 步骤 | 操作 | 确认方式 |
|
||
|------|------|----------|
|
||
| 0 | 卸载前备份（可选） | y/N |
|
||
| 1 | 停止并删除 Portainer 容器 | 输入 YES |
|
||
| 2 | 删除 Docker 镜像 | 自动 |
|
||
| 3 | 删除 Nginx 站点配置并重载 | 自动 |
|
||
| 4 | 删除 Let's Encrypt SSL 证书 | 自动 |
|
||
| 5 | 清理 Certbot 定时任务（仅当无其他证书时） | 自动 |
|
||
| 6 | 删除数据目录 | 输入 DELETE |
|
||
| 7 | 删除部署目录 `/opt/portainer` | y/N |
|
||
|
||
**备份目录 `/var/backups/portainer/` 始终保留**，不会被删除。
|
||
|
||
> 卸载后如需恢复，参考上方「恢复备份」章节。
|
||
|
||
<details>
|
||
<summary>手动卸载步骤（不使用脚本）</summary>
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
|
||
# 1. 建议先备份
|
||
bash backup.sh
|
||
|
||
# 2. 停止并删除容器
|
||
docker compose down -v
|
||
|
||
# 3. 删除 Docker 镜像（可选）
|
||
docker image rm portainer/portainer-ce:lts
|
||
|
||
# 4. 删除 Nginx 配置
|
||
rm -f /etc/nginx/sites-enabled/portainer /etc/nginx/sites-available/portainer
|
||
nginx -t && systemctl reload nginx
|
||
|
||
# 5. 删除 SSL 证书
|
||
certbot delete --cert-name 你的域名
|
||
|
||
# 6. 删除数据目录（⚠ 不可恢复）
|
||
rm -rf /var/lib/portainer
|
||
|
||
# 7. 删除部署目录（可选）
|
||
rm -rf /opt/portainer
|
||
|
||
# 备份目录保留在 /var/backups/portainer/
|
||
```
|
||
|
||
</details>
|
||
|
||
## 安全加固建议
|
||
|
||
### 1. 设置强密码
|
||
|
||
管理员密码至少 12 位，包含大小写字母、数字和特殊字符。
|
||
|
||
### 2. 禁用不需要的功能
|
||
|
||
在「Settings」→「Authentication」中：
|
||
- 关闭匿名访问
|
||
- 配置会话超时时间
|
||
|
||
### 3. 限制 Docker Socket 访问
|
||
|
||
当前使用只读挂载 Docker Socket（`:ro`），Portainer 仍可管理容器但安全性更高。如需完整功能（如构建镜像），可移除 `:ro`。
|
||
|
||
### 4. 定期更新
|
||
|
||
Portainer CE 定期发布安全更新，建议关注 [GitHub Releases](https://github.com/portainer/portainer/releases) 并及时升级。
|
||
|
||
## 故障排查
|
||
|
||
### 首次访问超时锁定
|
||
|
||
如果首次访问时超过 5 分钟未创建管理员账号：
|
||
|
||
```bash
|
||
cd /opt/portainer
|
||
docker compose restart
|
||
# 然后立即访问 Web 界面创建账号
|
||
```
|
||
|
||
### 容器无法启动
|
||
|
||
```bash
|
||
# 查看容器状态
|
||
docker compose ps
|
||
|
||
# 查看详细日志
|
||
docker compose logs --tail 50
|
||
```
|
||
|
||
### 访问返回 502
|
||
|
||
```bash
|
||
# 检查 Portainer 容器是否运行
|
||
docker compose ps
|
||
|
||
# 检查 9000 端口
|
||
curl -I http://127.0.0.1:9000
|
||
|
||
# 检查 Nginx 配置
|
||
nginx -t
|
||
```
|
||
|
||
### Docker Socket 权限问题
|
||
|
||
如果 Portainer 无法连接 Docker：
|
||
|
||
```bash
|
||
# 确认 socket 文件存在
|
||
ls -la /var/run/docker.sock
|
||
|
||
# 确认 Docker 服务运行
|
||
systemctl status docker
|
||
```
|
||
|
||
## 端口说明
|
||
|
||
| 端口 | 协议 | 说明 |
|
||
|------|------|------|
|
||
| 80 | TCP | HTTP → HTTPS 重定向 |
|
||
| 443 | TCP | HTTPS（Nginx 反向代理） |
|
||
| 9000 | TCP | Portainer HTTP（仅监听 127.0.0.1） |
|