Beszel项目：单机部署Hub与Agent的容器网络配置指南

容器网络通信的核心挑战

在容器化环境中实现组件间通信时，网络配置往往成为关键挑战。Beszel作为监控管理工具，其Hub与Agent组件的协同工作需要特别注意网络连通性问题。当两者部署在同一主机时，需要理解Docker网络模型才能正确配置。

典型配置方案解析

方案一：Host网络模式与网关映射

这是Beszel官方推荐的标准解决方案，适用于大多数Linux环境：

services:
  beszel:
    image: henrygd/beszel
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "1625:8090"

  beszel-agent:
    image: henrygd/beszel-agent
    network_mode: host

技术要点：

1. extra_hosts创建了主机名映射，使容器能通过host.docker.internal访问宿主机
2. network_mode: host让Agent共享主机网络栈
3. 添加系统时应使用host.docker.internal作为主机地址

方案二：自定义桥接网络

适用于需要隔离网络环境的场景：

networks:
  beszel-net:

services:
  beszel:
    networks:
      - beszel-net

  beszel-agent:
    networks:
      - beszel-net
    hostname: beszel-agent

技术优势：

1. 创建专属网络提高安全性
2. 通过容器hostname直接通信
3. 避免使用host网络模式的风险

特殊环境适配方案

MacOS Docker Desktop适配

由于MacOS的Docker实现差异，需要特殊处理：

services:
  beszel-agent:
    ports:
      - "45876:45876"
    # 移除network_mode配置

关键差异：

1. MacOS虚拟化层限制host网络模式效果
2. 内置host.docker.internal解析无需额外配置
3. 必须显式暴露Agent端口

最佳实践建议

1. 生产环境推荐使用方案二的桥接网络模式
2. 测试环境可使用方案一的简化配置
3. MacOS开发者必须注意端口映射
4. 始终检查/var/run/docker.sock的挂载权限
5. 监控日志确认连接状态

故障排查checklist

当Agent未正常连接时，建议检查：

1. 容器间网络连通性（使用ping/telnet测试）
2. 端口映射是否正确
3. 防火墙规则是否放行
4. 密钥配置是否匹配
5. 文件系统挂载点是否正确

通过理解这些网络配置原理，可以确保Beszel系统在各种环境下稳定运行。不同方案各有优劣，应根据实际需求选择最适合的部署方式。