Portainer 故障排查：当管理面板显示节点离线时

问题背景

我在使用 Portainer 管理多台 Docker 主机时，发现管理面板显示 102 机器离线了，无法管理该节点上的 Docker 容器。这种情况通常会导致运维工作受阻，因此需要及时解决。

排查过程

第一步：检查基础连接

我的第一反应是检查 102 机器的连接性：

登录 102 机器验证密码是否被修改 - 排除
检查 docker ps 命令输出，确认 Portainer 容器是否在运行 - 确认正常运行

第二步：尝试重启服务

我尝试重启 Portainer 服务，但犯了一个错误 - 复制了重启管理端（CE）的命令而非代理端：

docker pull 6053537/portainer-ce:latest && docker run -d \
  -p 8000:8000 \
  -p 6582:9443 \
  --name=portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  6053537/portainer-ce:latest

重启后问题依然存在，102 机器仍然无法被管理。

第三步：登录本地面板

我尝试登录 102 机器自身的 Portainer 面板。这时我意识到一个特殊情况：我之前在 102 机器上同时部署了管理端和代理端，使其既可以作为管理面板管理所有机器，也能看到自身的 Docker 状态。

但我陷入了另一个误区 - 尝试使用已删除的 admin 账户登录。

第四步：尝试重置密码

我按照 Portainer 官方文档尝试重置密码：

查看所有容器：docker ps -a
停止 Portainer 容器：docker stop 507566f7086e
查看挂载信息：docker inspect 507566f7086e
执行重置密码命令：

docker run —rm -v /mnt/docker/portainer:/data portainer/helper-reset-password


5. 重启容器：`docker start 507566f7086e`



尽管重置了两次密码，仍然无法登录。



### 第五步：恍然大悟



我突然想起来，我早已将默认用户名从 `admin` 改为 `root`！使用正确的用户名后，成功登录到 102 机器的 Portainer 面板。



## 问题根源



登录后，我查看了以前接入 Portainer 的文档，并对比 `docker ps` 的输出，发现了真正的问题所在：**Portainer Agent 容器被删除了**。



这就解释了为什么管理面板可用，但无法管理 Docker - 因为负责与主 Portainer 实例通信的 Agent 不存在了。



## 解决方案



我执行了以下命令重新部署 Portainer Agent：



```bash
docker pull portainer/agent:2.16.2 && docker run -d \
  -p 6583:9001 \
  --name portainer_agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  portainer/agent:2.16.2

部署完成后，102 机器立即在主 Portainer 面板中恢复在线状态，问题解决。

经验总结

理解 Portainer 的架构：
- 管理端（CE）：提供 Web UI，负责整体管理
- 代理端（Agent）：部署在各节点上，负责与管理端通信
特殊部署模式注意事项：
- 我的部署是一种混合模式，102 机器同时作为管理端和被管理端
- 这种模式下，需要同时维护两个容器的正常运行
排查思路优化：
- 先确认问题的具体表现（节点离线 vs 无法登录）
- 检查相关容器状态（docker ps -a 包括已停止的容器）
- 查看容器日志获取更多信息（docker logs 容器ID）
账户管理最佳实践：
- 修改默认凭据后，务必记录新的用户名和密码
- 考虑使用密码管理工具存储这些凭据
容器管理安全措施：
- 限制能够删除关键容器的用户权限
- 为关键容器设置 --restart=always 确保自动恢复
- 定期备份 Portainer 配置数据

结论

这次故障排查让我深刻认识到，在复杂的容器管理环境中，清晰理解各组件的职责和关系至关重要。当遇到类似问题时，应该系统性地排查，从基础连接到具体服务，最终定位到真正的问题所在。

同时，这也提醒我们在日常运维中做好文档记录和权限管理，避免关键容器被意外删除导致服务中断。

Perfecto