使用 Portainer 管理多台远程 Docker 主机 (Edge Agent) 实战指南

如果你有多台 VPS 服务器，或者在家里部署了多台 Homelab 设备（如群晖 NAS、树莓派、软路由），在每个设备上单独敲命令或者部署单独的控制面板会变得极为低效。

Portainer 是最流行的 Docker 可视化管理面板。许多人只用它来管理本机，但实际上它支持多主机统一管理（Multi-Environment Management）。

传统的 Agent 模式需要开放远程主机的 Docker API 端口（2375 或 9001），这会将你的服务器直接暴露在公网上，极易遭受黑客扫描和勒索病毒。

本文将教你使用更安全的 Portainer Edge Agent（边缘代理） 模式。通过“反向轮询”机制，在不开放远程主机任何入口端口的情况下，安全地用一个控制面板一站式接管你所有的远程 Docker 主机。

---

🧭 Edge Agent（边缘代理）的工作原理

传统的 Agent 模式是“主控端主动去连受控端”（需要受控端公网 IP 且开放端口）。而 Edge Agent 模式 则是：

1. 主控端（Portainer Server）生成一个唯一的凭证 Key。
2. 受控端（Portainer Edge Agent）在后台运行，主动向主控端发起反向连接。
3. 优势：受控端即使在 NAT 宽带内、无公网 IP、或者开启了严格的防火墙，只要它能访问主控端，就能在主控端面板里无感显示，安全性极高。

graph LR
    Sub[受控端 Docker 主机 (Edge Agent)] -->|主动发起安全连接 / 轮询| Main[主控端 Portainer Server]
    Main -->|下发管理指令| Sub

---

🛠️ 第一步：在主控端 (Portainer Server) 新建环境

1. 登录你的主控端 Portainer 面板（通常部署在主力 VPS 或家里主力 NAS 上）。
2. 在左侧菜单点击 “Environments (环境)” -> 点击右上角 “Add environment (添加环境)”。
3. 选择 “Docker Standalone (独立 Docker 主机)” -> 点击 “Connect (连接)”。
4. 在连接选项中，务必选择 “Edge Agent”（第二个选项）。
5. 配置参数：
   • Name：给远程主机起个名字，如 vps-hk-1。
   • Portainer server URL：主控端面板的外部可达地址（极其重要，远程代理将通过这个地址连回来，必须确保远程主机能 Ping 通此地址与 8000 端口）。例如：http://1.2.3.4:9000 或域名 https://portainer.example.com。
6. 点击 “Create environment”。

---

⚙️ 第二步：在受控端 (远程主机) 部署 Edge Agent

点击创建后，Portainer 会为你自动生成一段单行 Docker 启动脚本，类似于：

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  --name portainer_edge_agent \
  --restart always \
  -e EDGE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -e EDGE_KEY=aHR0cHM6Ly9wb3J0YWluZXIuZXhhbXBsZS5jb206ODAwMHx... \
  -e EDGE_INSECURE_POLL=1 \
  portainer/agent:2.19.4

1. 通过 SSH 登录你的 受控端远程服务器。
2. 确保该服务器已经安装了 Docker，且没有占用 portainer_edge_agent 的名称。
3. 粘贴并回车运行 刚刚复制的那行 Docker 命令。

---

🔍 第三步：回到主控端验证连接

1. 回到主控端的 Portainer 页面。
2. 等待大约 10 - 30 秒（Agent 第一次反向握手需要时间）。
3. 你会发现状态栏由黄色的 Waiting for association 变为绿色的 Associated (已关联)。
4. 回到 Portainer 首页（Home），你现在可以直接点击进入 vps-hk-1 环境。
5. 现在，你可以像管理本机一样，直接查看这台远程 VPS 上的镜像、容器、卷、网络，甚至直接在线部署 Docker Compose (Stacks)，或者打开容器的日志与命令行终端！

---

🔒 进阶安全与排错建议

1. 确保开放 8000 端口

Portainer Server 使用 8000 端口 作为 Edge Agent 的通信隧道（Tunnel）端口。如果受控端显示黄色的等待连接，请检查主控端 VPS 的防火墙是否放行了 TCP 8000 端口（如 ufw allow 8000/tcp）。

2. 多主机 Stack 协同部署

在管理远程主机时，建议全部使用 Portainer 的 “Web editor” 编写 Compose。Portainer 会自动将你的 YAML 配置文件推送到受控端主机的临时目录，并在该主机本地构建容器，非常优雅。

---

💬 总结

使用 Portainer Edge Agent，你能以极高的安全性将散落在各处的 VPS 与内网 Homelab 设备聚集在单个控制台下，大大缩减了日常运维服务器的精力和成本。

• 数据备份：如何对这些远程主机的数据卷进行自动备份？阅读 Docker Volume 备份与网盘同步实战。
• 网盘挂载：使用网盘备份服务器文件？参考 Rclone 挂载云盘与自动备份。