Nginx UI 多主机管理实战：基于 Cluster Node 的集群联邦部署指南

Nginx UI 多主机管理实战基于 Cluster Node 的集群联邦部署指南【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui导读当需要从单一 Nginx UI 控制台统一管理分布在多台主机上的 Nginx 时官方推荐使用Cluster Node集群节点能力而非传统的 host_via_ssh 模式。本文以官方文档 manage-multi-host-nginx-with-cluster.md 为主线结合仓库内集群注册、节点鉴权与配置同步的源码实现带你从零搭建一套一主多从的 Nginx 集群联邦包括场景选型、拓扑设计、节点注册配置、Web UI 切换以及集群与 SSH 模式的组合用法。读完本文你将能独立完成多主机 Nginx 的统一纳管、远程 reload/restart 与配置同步。一、什么时候该用 Cluster Node在动手之前先明确选择依据。官方文档给出了一个非常直观的选型表需求host_via_sshcluster Node主机 A 上的容器管理主机 A 自身的 nginx✓✓杀鸡用牛刀主机 A 上的容器管理主机 B 的 nginx✗✓一个 Web UI 跨主机查看配置与日志否✓对端失联时各主机保持自治否✓从源码结构看两种模式的能力边界是完全不同的host_via_ssh 依赖 SSH 通道直连目标主机而 cluster Node 是每台主机各自运行一个 Nginx UI 实例再通过节点联邦把请求转发到对应实例上执行。因此单机场景容器和 nginx 在同一主机用 host_via_ssh 即可无需引入集群跨主机场景容器在 A 机、nginx 在 B 机或者需要一套 UI 纵览多主机就必须使用 cluster Node自治性peer 节点即使与控制端失联自身仍可独立工作这是 SSH 模式不具备的。二、推荐的联邦拓扑官方推荐的拓扑分为四层层级角色说明浏览器打开主导leadNginx UI 实例日常操作只用一个控制台Lead 节点注册 peer 节点并提供节点切换器也可以管理本机自己的 nginxPeer 节点各自运行一套 Nginx UI 实例每个 peer 管理所在主机的 nginxCluster federation连接 lead 节点与 peer 节点所有请求在选中的节点上执行关键设计要点文档明确强调源码亦可印证Lead 节点不会 SSH 进入其他主机。所有跨主机操作都是通过集群节点连接转发的——这一点可以在 api/cluster/nginx.go 的syncReload/syncRestart中看到lead 节点对每个目标节点构造一个基于 nodeauth 的 Resty 客户端然后向该节点的/api/nginx/reload、/api/nginx/restart发起 HTTP 请求并发执行sync.WaitGroup goroutine并对成功/失败推送通知。每个节点只管理本机 nginx。如果某个节点在 Docker 里运行 Nginx UI、却要管理同一台宿主机上安装的 nginx只需要在该节点上单独配置 Manage Host Nginx from Docker与集群联邦互不冲突。三、搭建步骤四步走1. 在每个主机安装 nginx-ui尽量在所有节点上使用相同的部署类型。原生 Linux 安装执行官方一键脚本bash -c $(curl -L https://cloud.nginxui.com/install.sh) installDocker 部署同样支持完整安装方式见 Install Script 与 Getting Started。2. 在每个 peer 上生成 Node Secret登录 peer 的 Web UI进入Settings → Node对应 api/cluster/router.go 中的节点管理 API复制页面上显示的Node Secret。从 internal/cluster/cluster.go 的注册逻辑看node_secret 是节点关系的起点凭证它会被解析后以加密形式EncryptedLegacySecret见 model/node.go存入数据库绝不以明文落库。3. 在 lead 节点注册 peers有两种配置入口app.ini配置文件或 Docker 环境变量。两种方式本质相同——环境变量会被映射进settings.ClusterSettings.Node见 settings/cluster.go该字段声明了ini:,,allowshadow以支持多行重复键同时标记为protected:true sensitive:true即敏感字段。app.ini 方式[cluster] Node http://10.0.0.2:9000?namehost-bnode_secrethost-b-secretenabledtrue Node http://10.0.0.3:9000?namehost-cnode_secrethost-c-secretenabledtruedocker-compose.yml 方式services: nginx-ui: environment: - NGINX_UI_CLUSTER_NODEhttp://10.0.0.2:9000?namehost-bnode_secret...enabledtrue,http://10.0.0.3:9000?namehost-cnode_secret...enabledtrue每条 Node 配置项的 URL 结构为详见 config-cluster.mdScheme://Host(:Port)?nameENV_NAMEnode_secretNODE_SECRETenabled(true/false)参数含义参数说明Scheme://Host(:Port)对端 Nginx UI 的访问地址端口可省略默认按 http/https 推导 80/443name节点在 Web UI 中显示的名称必填node_secret第 2 步复制的 Node Secret必填enabled是否启用该节点取值true/false缺省视为 false加载时机与冲突规避源码依据Nginx UI 会在引导bootstrapping阶段自动调用RegisterPredefinedNodesinternal/cluster/cluster.go对每条配置执行parseNodeUrl解析并入库同时在 Web UI 的环境列表中提供Load from Config按钮对应 api/cluster/node.go 的LoadNodeFromSettings内部会ReloadCluster后重新执行RegisterPredefinedNodes用于手动触发同步。为避免与数据库中已存在的环境冲突注册时只以Scheme://Host(:Port)部分判断唯一性若该地址在库中不存在则按配置创建已存在则不做任何操作。反之如果你从配置文件里删除了某个节点数据库中的记录不会被自动删除需要到 Web UI 中手动处理。安全细节注册过程中任何打印到日志的节点 URL 都会经过sanitizePredefinedNodeURL脱敏处理——node_secret查询参数会被替换为[REDACTED]后再输出避免敏感信息泄露。4. 在 Web UI 中切换节点注册完成后顶栏会出现节点切换器node switcher。选定某个节点后后续所有操作都会路由到该节点执行且每个操作都只发生在该节点本地——主机之间不存在任何 SSH 连接。如果你使用仅共享密钥的旧式鉴权legacy_secret新版本会自动触发升级流程把关系升级为基于 Ed25519 密钥对的配对鉴权paired_ed25519升级过程可见 api/cluster/node_auth.go 的UpgradeLegacyPairing。节点列表中会展示auth_upgrade_status、connection_error等状态字段见 api/cluster/node.go 的nodeResponse。需要重新查看已存储的 Node Secret 时必须通过已验证的安全会话启用了双因素认证的用户才能调起GetNodeSecret接口。四、集群 host_via_ssh 的组合玩法官方文档明确支持一种混合布局让每个集群 peer 内部再运行 host_via_ssh。在这种布局下每个 peer 的容器通过 host_via_ssh 管理自己所在主机上的 nginx集群联邦负责跨主机的编排与统一入口。即SSH 解决单机容器↔宿主机通信集群解决多主机统一管理两者各司其职、互不干扰。配套文档请参考 Cluster configuration reference 与 Manage Host Nginx from Docker。五、进阶跨节点配置同步与远程重载集群联邦不只是切换视角还提供了主动同步能力对应 api/cluster/sync.goPOST /api/nodes/sync把 lead 节点本地的配置configs、站点sites、流streams推送到选定的节点支持overwrite覆盖选项——新加入的节点可以用一次请求快速补齐数据POST /api/namespaces/:id/sync把某个命名空间连同其下所有站点/流复制到该命名空间的每个节点实现一处编辑、处处生效远程重载/重启通过 api/cluster/nginx.go 的syncReload/syncRestart并行对多个节点调用/api/nginx/reload、/api/nginx/restart结果通过通知中心提示成功或失败详情。六、注意事项小结部署一致性所有节点尽量使用相同部署类型降低排障成本端口可达lead 节点必须能通过 HTTP/HTTPS 访问到 peer 的 9000 端口或自定义端口新增节点 URL 只允许 http/https scheme且不允许携带认证信息、查询参数或 fragment见 api/cluster/node.go 的validateNodeURL密钥保管node_secret 为敏感配置落库加密、日志脱敏泄露后可在节点管理中对配对凭证执行轮换rotate删除语义删除配置文件中的节点不会删除数据库记录需在 UI 中操作自治性红利peer 与控制端失联不影响 peer 自身管理本机 nginx适合对高可用有要求的边缘部署。通过以上四步你就拥有了一个统一入口、多主机自治、支持配置下发与远程重载的 Nginx 集群联邦日常的跨主机 nginx 运维从此只需打开一个控制台。【免费下载链接】nginx-uiYet another WebUI for Nginx项目地址: https://gitcode.com/gh_mirrors/ngi/nginx-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考