01x05.Ubuntu Server 24.04.2 LTS 部署Docker可视化管理系统

📄 文档说明

项目	内容
文档编号	55K-RPT-2025-Ubuntu-05

👥 信息介绍

• 测试人员：雾里看浮光
• 运营人员：南知意、庭吖
• 公众号：55K-学安全
• 优快云：HackShield_Pro的技术博客
• 博客园：JaseLee的个人博客

⚠️ 免责声明

重要提示
本次文章中所有内容均在本地授权环境中进行。目的仅为安全研究与学习，提升安全防护能力。
请勿将文中所述技术用于任何非法用途，否则后果自负。

---

版权声明：本文由 55K-学安全 团队原创，转载请注明出处。

---

一、Portainer简介

Portainer是一个轻量级的Docker可视化管理系统，具有以下特点：

 - 用户友好：提供直观的Web界面，无需记忆复杂命令
 - 功能全面：支持容器、镜像、网络、卷等全方位管理
 - 多环境支持：可管理本地和远程Docker环境
 - 安全可靠：支持用户权限管理和访问控制
 - 开源免费：社区版完全免费使用

二、环境准备

在安装 Portainer 之前，请确保你的系统已经满足以下基础要求：

 - 已安装 Docker和Docker Compose
 - 系统内存和磁盘空间至少1GB以上
 - 开放必要的防火墙端口（默认端口：8000、9443；自定义端口：9000、9080）#注：根据自己实际需要配置端口

三、安装Portainer

3.1.Docker快速安装

3.1.1.创建Portainer数据卷

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

# 验证卷是否创建成功
docker volume inspect portainer_data

详细说明：

• portainer_data卷用于持久化存储Portainer的配置、用户数据、集群信息等
• 避免容器删除后数据丢失
• 默认存储路径：/var/lib/docker/volumes/portainer_data/_data

3.1.2.安装Portainer Server容器

# 标准端口映射（推荐）
docker run -d \
  -p 9080:8000 \
  -p 9000:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:lts

# 单端口映射（简化）
docker run -d \
  -p 9000:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:lts

命令参数详解：
-d：让容器在后台运行（detach模式）
-p 9080:8000 -p 9000:9443：端口映射说明：

• 9443：Web UI 管理界面（HTTPS）
• 8000：Edge Agent 通信端口（用于管理边缘节点）

–name portainer：为容器指定名称
–restart=always：设置容器始终自动重启
-v /var/run/docker.sock:/var/run/docker.sock：挂载 Docker socket，使 Portainer 能够管理 Docker
-v portainer_data:/data：持久化 Portainer 数据 portainer/portainer-ce:lts：使用 Portainer 社区版的 LTS（长期支持）版本

3.1.3.验证安装状态

# 查看容器运行状态
docker ps --filter "name=portainer"
# 查看容器日志（用于排查问题）
docker logs -f portainer
# 检查端口占用情况
netstat -tulpn | grep -E "8000|9443|9000|9080"

常见问题排查：

• 如果端口被占用，修改-p参数（如-p 8001:8000）
• 如果权限不足，确保当前用户有Docker操作权限
• 查看日志确认具体错误信息

3.2.使用Docker Compose安装

3.2.1.创建docker-compose.yml文件

# docker-compose-portainer.yml
version: '3.8'

services:
  portainer:
    image: portainer/portainer-ce:lts
    container_name: portainer
    restart: always
    ports:
      - "9080:8000"
      - "9000:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    networks:
      - portainer_net

networks:
  portainer_net:

volumes:
  portainer_data:

3.2.2.文件操作

# 启动portainer
docker-compose -f docker-compose-portainer.yml up -d
# 查看容器状态
docker-compose -f docker-compose-portainer.yml ps
# 停止容器（保留数据）
docker-compose -f docker-compose-portainer.yml down
# 停止并删除数据卷（谨慎，数据会丢失）
docker-compose -f docker-compose-portainer.yml down -v
# 重启容器（停止后重新启动，数据不会丢失）
docker-compose -f docker-compose-portainer.yml restart

3.3.二进制安装（不推荐）

• 对于特殊环境，可以考虑二进制安装，但Docker安装方式更为推荐。

四、访问与初始配置

4.1.访问和初始化

4.1.1.访问Portainer

本地访问：
	https://IP:9000
远程访问：
	https://[服务器IP]:9000

4.1.2.首次登录设置

浏览器可能会提示证书不安全（自签名证书），选择继续访问
创建管理员账户：
用户名：admin
密码：********（建议使用强密码）

# 输入用户密码登录Portainer
用户名：admin
密码：********

4.1.3.问题解决：

问题描述：

New Portainer installation
Your Portainer instance timed out for security purposes. To re-enable your Portainer instance, you will need to restart Portainer.

For further information, view our documentation.

出现原因：

Portainer 为保障安全，默认启用会话超时机制：当用户长时间未操作（默认会话超时时间通常为 1 小时），系统会自动锁定实例，防止未授权访问，属于正常的安全防护设计。

解决方法：

• 重启 Portainer 容器（核心解决步骤）

步骤一:通过 Docker Compose 重启（推荐，适用于用 Compose 部署的场景）
# 进入 docker-compose-portainer.yml 文件所在目录
cd /data/docker/docker-compose/
# 执行重启命令
docker-compose -f docker-compose-portainer.yml restart

步骤二:通过 Docker 命令直接重启（适用于任何部署方式）
# 查看 Portainer 容器名称或 ID
docker ps --filter "name=portainer" 
# 用名称重启（更直观）  
docker restart portainer  
# 用 ID 重启（替换为实际容器 ID）  
docker restart 容器ID前4位（例如 aa0a）  

4.1.4.环境配置

选择"Get Started"

4.2.仪表盘

登录后进入主仪表盘，可以查看：

 - 运行中的容器数量
 - 镜像数量
 - 卷和网络状态
 - 系统资源使用情况

4.3.容器管理

在"Containers"页面可以：

 - 查看所有容器状态
 - 启动/停止/重启容器
 - 创建新容器
 - 查看容器日志
 - 进入容器终端

4.4.镜像管理

在"Images"页面可以：

 - 查看本地镜像
 - 拉取新镜像
 - 删除无用镜像
 - 构建自定义镜像

4.5.堆栈管理

在"Stacks"页面可以：

 - 部署Docker Compose应用
 - 管理多容器应用
 - 更新堆栈配置

5. 汉化部署方法

5.1.删除原有容器

# 停止并删除原有Portainer容器
docker stop portainer
docker rm portainer

5.2.创建挂载目录

# 创建汉化文件目录
mkdir -p /data/docker/portainer/public

5.3.下载汉化包

# 下载汉化文件
cd /data/docker/portainer 
wget https://github.com/eysp/public/archive/refs/heads/public.zip

# 如wget不可用，也可使用curl
curl -L -o public.zip https://github.com/eysp/public/archive/refs/heads/public.zip

如果下载失败，可以使用浏览器进行下载

5.4.解压汉化包

使用上传工具将汉化包上传至服务器中

# 安装解压工具（如未安装）
apt-get update && apt-get install -y unzip
# 解压汉化文件
unzip public-public.zip
# 复制汉化文件到指定目录
cp -r public-public/* public/

# 确认目录存在且汉化文件
ls -l /data/docker/portainer/public
# 赋予可读权限
chmod -R 755 /data/docker/portainer/public

5.5.创建汉化容器

docker run -d \
  -p 9000:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  -v /data/docker/portainer/public:/public \
  portainer/portainer-ce:2.9.1

问题描述：

Portainer CE 2.9.1 容器启动后立即崩溃，查看日志（docker logs portainer）显示 boltDB 数据库索引越界错误（panic: runtime error: index out of range [18446744073709547520] with length 281474976710655），错误溯源至 github.com/boltdb/bolt.Open 函数，最终导致 Portainer 无法正常提供管理服务

出现原因：

1.boltDB 数据库文件损坏
	Portainer 2.x 版本默认使用 boltDB（数据库文件为 portainer.db）存储配置（如用户、集群连接、权限等），该文件存储在 portainer_data 数据卷中。若出现以下情况，会导致文件损坏：
		- 宿主机磁盘存在错误（如坏道、IO 异常）；
		- Portainer 容器异常退出（如强制 kill、断电、资源耗尽），导致数据库写入中断。

2.数据卷版本不兼容若
	portainer_data 数据卷此前用于其他版本的 Portainer（如 1.x 版本升级到 2.9.1，或从更高版本降级到 2.9.1），会因 boltDB 数据库格式不兼容，导致启动时读取失败。
	
3.旧版本软件 bug
	Portainer 2.9.1 依赖的 boltDB 版本为 v1.3.1（日志中可见 github.com/boltdb/bolt@v1.3.1），该版本存在已知的 “特定场景下数据读取索引越界” bug，且 Portainer 2.9.1 未修复此问题，在旧数据卷复用场景下易触发崩溃

解决方案：

步骤 1：停止并删除异常容器
# 先终止当前无法启动的容器，避免资源占用或重复报错：
# 停止容器
docker stop portainer
# 删除容器（仅删除容器实例，不删除数据卷，保留备份可能）
docker rm portainer

步骤 2：备份旧数据卷（关键！避免配置丢失）
# 若需保留旧配置（如已配置的集群、用户），需先备份 portainer_data 中的数据库文件：
# 1. 启动临时 alpine 容器，同时挂载旧数据卷和宿主机目录（用于存放备份）
docker run -it --rm -v portainer_data:/source -v $(pwd):/backup alpine sh
# 2. 在临时容器内，复制数据库文件到宿主机备份目录
cp /source/portainer.db /backup/portainer.db.bak
# 3. 输入 exit 退出临时容器（容器会自动删除，备份文件留在宿主机当前目录）
exit

步骤 3：验证数据卷是否损坏
# 启动临时容器，使用全新数据卷（不依赖旧 portainer_data），判断是否为数据卷问题：
docker run -d \
  -p 9080:8000 -p 9000:9443 \
  --name portainer-test \
  --restart=no \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data_test:/data \  # 全新临时数据卷
  portainer/portainer-ce:2.9.1

1.若 portainer-test 能正常启动(docker logs portainer-test 无 panic 报错)，则确认旧数据卷损坏，执行步骤 4
2.若仍存在报错，则为 Portainer 2.9.1 本身的 bug，直接执行步骤 5 升级版本

步骤 4：删除损坏数据卷，重新部署
# 确认旧数据卷损坏后，删除损坏卷并使用原命令重新启动（自动创建干净数据卷）：
# 删除损坏的数据卷（已备份，可放心删除）
docker volume rm portainer_data
# 用原命令重新部署 Portainer（自动生成新的 portainer_data 卷）
docker run -d \
  -p 9080:8000 -p 9000:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  -v /data/docker/portainer/public:/public \
  portainer/portainer-ce:2.9.1

步骤 5：升级 Portainer 版本（彻底解决旧版 bug）
# Portainer 2.9.1 及更早版本的 boltDB 问题已在 2.18.x 以上版本修复，建议升级到稳定版（如 2.19.4）
# 注意：由于汉化包只支持2.9.1版本，升级版本后可能会导致汉化失效

# 1. 停止并删除旧容器
docker stop portainer && docker rm portainer
# 2. （可选）若无需恢复旧配置，删除旧数据卷；若需恢复，跳过此步
docker volume rm portainer_data
# 3. 用新版镜像启动（以 2.19.4 为例，可替换为官网最新稳定版）
docker run -d \
  -p 9080:8000 -p 9000:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  -v /data/docker/portainer/public:/public \
  portainer/portainer-ce:2.19.4

我这里直接使用了步骤1和步骤4方法进行操作

5.6.访问效果

完成上述步骤后

 - 重新访问 https://localhost:9000 地址
 - 进行创建管理员用户
 - 创建完成登录后则看到中文界面

六、总结

通过本文的详细步骤，您可以轻松完成Portainer的安装和配置：

 - 选择安装方式：推荐使用Docker直接安装或Docker Compose安装
 - 数据持久化：使用数据卷确保配置不丢失
 - 安全访问：通过HTTPS访问管理界面
 - 中文支持：通过汉化部署获得更好的中文体验

Portainer极大简化了Docker环境的管理工作，无论是个人开发还是团队协作，都能显著提升工作效率。建议定期更新Portainer版本以获得最新功能和安全更新。

后续维护建议：

 - 定期备份portainer_data卷
 - 关注Portainer版本更新
 - 配置适当的防火墙规则
 - 设置定期日志清理策略