server-deploy/portainer/README.md

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/   # 备份文件

快速部署

第一步：上传文件到服务器

# 在本地执行，上传 portainer 目录
scp -r portainer/ root@<服务器IP>:/opt/portainer

# 如果服务器上还没有部署过 base（首台服务或全新服务器），还需上传 base
scp -r base/ root@<服务器IP>:/opt/base

第二步：登录服务器执行部署

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 会自动锁定。需要重启容器重新计时：

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	指定版本号

日常运维

查看日志

cd /opt/portainer
docker compose logs -f
docker compose logs --tail 100

备份

cd /opt/portainer
bash backup.sh

备份内容包括：

• Portainer 数据（BoltDB 数据库 + TLS 证书 + 设置）
• 部署配置（docker-compose.yml + .env + nginx/）

备份文件保存在 /var/backups/portainer/，自动清理 30 天前的旧备份。

恢复备份

# 查看可用备份
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

升级

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

停止 / 启动

cd /opt/portainer
docker compose down      # 停止
docker compose up -d     # 启动
docker compose restart   # 重启

完全卸载

如果需要从服务器上完全移除 Portainer，使用卸载脚本：

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/ 始终保留，不会被删除。

卸载后如需恢复，参考上方「恢复备份」章节。

手动卸载步骤（不使用脚本）

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/

安全加固建议

1. 设置强密码

管理员密码至少 12 位，包含大小写字母、数字和特殊字符。

2. 禁用不需要的功能

在「Settings」→「Authentication」中：

• 关闭匿名访问
• 配置会话超时时间

3. 限制 Docker Socket 访问

当前使用只读挂载 Docker Socket（:ro），Portainer 仍可管理容器但安全性更高。如需完整功能（如构建镜像），可移除 :ro。

4. 定期更新

Portainer CE 定期发布安全更新，建议关注 GitHub Releases 并及时升级。

故障排查

首次访问超时锁定

如果首次访问时超过 5 分钟未创建管理员账号：

cd /opt/portainer
docker compose restart
# 然后立即访问 Web 界面创建账号

容器无法启动

# 查看容器状态
docker compose ps

# 查看详细日志
docker compose logs --tail 50

访问返回 502

# 检查 Portainer 容器是否运行
docker compose ps

# 检查 9000 端口
curl -I http://127.0.0.1:9000

# 检查 Nginx 配置
nginx -t

Docker Socket 权限问题

如果 Portainer 无法连接 Docker：

# 确认 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）