Nginx UI Node 配置完全指南：Name、Secret 与 SkipInstallation 的实战与源码解析

• 后端
• 前端
• 运维
• MCP 服务

Nginx UI 从v2.0.0-beta.37起，将原本散落在 Server 配置节中的节点级选项收拢为独立的[node]配置节，用于定制单台 Nginx UI 服务器的本地名称、服务器间通信认证密钥以及跳过安装模式。本文以官方文档 docs/guide/config-node.md 为骨架，结合仓库源码逐项讲解Name、Secret、SkipInstallation三个核心配置项的含义、作用与配置方法，并补充InstanceID、UpgradeChannel、ICPNumber、PublicSecurityNumber等同样归属于该配置节的实用选项，帮助你在单机部署、多服务器集群和免交互批量部署三种场景下正确完成配置。

Node 配置节概览

在 Nginx UI 的 INI 格式配置文件（默认app.ini）中，node配置节对应源码中的settings.Node结构体，定义于 settings/node.go：

type Node struct { Name string `json:"name" binding:"omitempty,safety_text"` Secret string `json:"secret" protected:"true" sensitive:"true"` InstanceID string `json:"instance_id" protected:"true"` SkipInstallation bool `json:"skip_installation" protected:"true"` Demo bool `json:"demo" protected:"true"` UpgradeChannel string `json:"upgrade_channel" binding:"omitempty,oneof=stable prerelease dev"` ICPNumber string `json:"icp_number" binding:"omitempty,safety_text"` PublicSecurityNumber string `json:"public_security_number" binding:"omitempty,safety_text"` }

从结构体标签可以读出几条重要信息：

• Secret标记了protected:"true"与sensitive:"true"，属于敏感配置，在前端保存设置时会被脱敏处理（详见 api/settings/settings.go 中的restoreRedactedSensitiveSettings），不会明文回显；
• SkipInstallation、InstanceID、Demo均为protected:"true"，属于受保护配置；
• UpgradeChannel限定取值只能是stable、prerelease、dev三者之一。

在 settings/settings.go 的envPrefixMap中，NODE段被映射到NodeSettings，因此这三个核心选项（以及该节其他选项）都可以通过环境变量注入，对应关系如下（完整清单见 docs/guide/env.md）：

Name：自定义环境指示器中的本地服务器名称

• 类型：string
• 版本要求：>= v2.0.0-beta.37

Name用于自定义本地服务器在 WebUI「环境指示器」（environment indicator）中显示的名称。当你在 WebUI 中查看当前处于哪个环境（本机节点还是某个远程节点）时，显示的就是这个值。

后端对应的读取入口是GetServerName，见 api/settings/settings.go：

func GetServerName(c *gin.Context) { c.JSON(http.StatusOK, gin.H{ "name": settings.NodeSettings.Name, }) }

配置示例（app.ini）：

[node] Name = my-local-server

或通过环境变量注入：

export NGINX_UI_NODE_NAME="my-local-server"

Name的取值约束是safety_text，即只允许安全的普通文本，避免在页面渲染时引入注入风险。未设置时，环境指示器将按默认规则展示服务器标识。

Secret：服务器间通信认证密钥

• 类型：string
• 版本要求：>= v2.0.0-beta.37

Secret是 Nginx UI 服务器之间通信的认证密钥，承担两个核心职责：

1. 集群/节点间通信认证：在集群模式下，控制器（Controller）节点访问被管理节点（Node）的 API 时，需要使用该密钥对请求进行签名认证。从 internal/cluster/cluster.go 可以看到，node_secret作为 legacy 认证方式被写入集群节点 URL 的 query 参数中（形如http://10.0.0.1:9000?name=node1&node_secret=my-node-secret&enabled=true，详见 docs/guide/config-cluster.md）。目前代码中仍保留了对这一方式的兼容：node_secret查询参数会被记录为encrypted_legacy_secret，但同时会输出警告日志，提示应升级为更安全的配对认证（paired authentication）。
2. 免密访问 API：持有该密钥即可在不对 WebUI 登录的情况下访问 Nginx UI API，适用于自动化脚本、节点间同步等无交互场景。

在v2.0.0-beta.37之后，节点的安全模型引入了基于 Ed25519 密钥对的配对认证体系（见 api/cluster/node_auth.go），Secret被定位为 legacy 共享密钥，用于控制器节点首次接入时的鉴权与「升级配对」（UpgradeLegacyPairing接口会把共享密钥认证的控制器迁移到独立的密钥对上）。因此：

• 该值应足够随机且保密，不要泄露给不受信任的第三方；
• 在多节点部署时，各节点间需使用一致的密钥才能正常通信；
• 新部署建议优先走配对认证流程，Secret仅作为迁移与兼容手段。

SkipInstallation：跳过安装流程，实现批量部署

• 类型：boolean
• 版本要求：>= v2.0.0-beta.37

SkipInstallation用于跳过 Nginx UI 服务器首次启动时的安装引导流程（即 WebUI 中创建管理员账号、设置邮箱的初始化页面）。

典型应用场景

当你想用同一份配置文件或同一组环境变量把 Nginx UI 部署到多台服务器时，开启该选项可以避免每台机器都要手动走一遍安装向导。配合预定义用户环境变量，可以实现完全免交互的批量初始化。

密钥自动生成行为

按文档约定，如果开启了跳过安装模式，但[app]节的JwtSecret和[node]节的Secret都未设置，Nginx UI 会为这两个选项自动生成随机的 UUID 值。该逻辑实现在 internal/kernel/skip_install.go 的skipInstall()中：

func skipInstall() { logger.Info("Skip installation mode enabled") var nodeSecret string err := settings.Update(func() { if cSettings.AppSettings.JwtSecret == "" { cSettings.AppSettings.JwtSecret = uuid.New().String() } if settings.NodeSettings.Secret == "" { nodeSecret = uuid.New().String() settings.NodeSettings.Secret = nodeSecret } }) ... }

注意：每台服务器会各自生成不同的随机 UUID。对于多节点集群部署而言，如果你期望节点之间能够互通（共享Secret进行认证），应当在配置文件中显式指定相同的JwtSecret与Secret值，而不是依赖自动生成——否则每台机器的密钥彼此独立，集群节点将无法相互认证。

启动链路中的实际位置

从 internal/kernel/boot.go 可以看到，SkipInstallation在数据库初始化阶段被读取：

func InitDatabase(ctx context.Context) { cModel.ResolvedModels() // Skip install if settings.NodeSettings.SkipInstallation { skipInstall() } db := cosy.InitDB(sqlite.Open(path.Dir(cSettings.ConfPath), settings.DatabaseSettings)) model.Use(db) query.Init(db) ... }

也就是说，跳过安装模式在数据库建立之前生效：它先补齐JwtSecret与Node.Secret，随后照常初始化数据库并创建预定义用户。这一顺序保证跳过安装后的系统开箱即可登录使用。

预定义用户

在跳过安装模式下，可以通过两个环境变量预置初始管理员账号（见 docs/guide/env.md）：

export NGINX_UI_PREDEFINED_USER_NAME="admin" export NGINX_UI_PREDEFINED_USER_PASSWORD="your-strong-password"

对应的实现是 internal/kernel/skip_install.go 中的registerPredefinedUser()：它以NGINX_UI_PREDEFINED_USER_为前缀解析环境变量，若数据库为空则创建 ID 为 1 的初始用户，若初始用户已存在但密码为空则为其补上密码，密码使用bcrypt哈希后落库：

pwd, _ := bcrypt.GenerateFromPassword([]byte(pUser.Password), bcrypt.DefaultCost) if errors.Is(err, gorm.ErrRecordNotFound) { // Create the initial user when the database is empty err = u.Create(&model.User{ Model: model.Model{ID: 1}, Name: pUser.Name, Password: string(pwd), }) }

完整配置示例

以下是一份可直接用于多服务器批量部署的配置（app.ini）：

[app] JwtSecret = your-shared-jwt-secret-please-change [node] Name = prod-node-01 Secret = your-shared-node-secret-please-change SkipInstallation = true

对应的环境变量写法：

export NGINX_UI_APP_JWT_SECRET="your-shared-jwt-secret-please-change" export NGINX_UI_NODE_NAME="prod-node-01" export NGINX_UI_NODE_SECRET="your-shared-node-secret-please-change" export NGINX_UI_NODE_SKIP_INSTALLATION="true" export NGINX_UI_PREDEFINED_USER_NAME="admin" export NGINX_UI_PREDEFINED_USER_PASSWORD="your-strong-password"

需要注意：SkipInstallation在v2.0.0-beta.37之前位于[server]配置节，从该版本起已废弃旧位置并迁移到[node]节（详见 docs/guide/config-server.md 中的废弃说明），配置时应使用新的Node.SkipInstallation路径。

同节的补充选项：从源码结构看

除了文档明确列出的三个核心选项，Node结构体还包含几个在 WebUI 中同样可配置的字段，一并说明：

• InstanceID：节点实例的唯一标识，启动时若为空会自动生成 UUID（见 internal/kernel/boot.go 的InitNodeInstanceID）。它被用于配对认证体系中标识目标实例（如 api/cluster/node_auth.go 响应中的TargetInstanceID），由系统维护，一般无需手动设置。
• UpgradeChannel：升级渠道，取值仅限stable、prerelease、dev。系统升级接口读取该值决定检查哪个发布渠道的更新（见 api/system/upgrade.go）。
• ICPNumber/PublicSecurityNumber（>= v2.0.0-beta.42）：分别用于设置 ICP 备案号与公安备案号，渲染在 WebUI 页脚（见 api/pages/maintenance.go 与 api/public/layout.go），适用于需要合规展示备案信息的站点。

与安装流程的关系：正常安装时 Secret 从哪来

如果你不启用SkipInstallation，正常安装向导（POST /api/install，见 api/system/install.go）会在创建管理员账号时自动为App.JwtSecret与Node.Secret生成 UUID并写入配置：

err := settings.Update(func() { cSettings.AppSettings.JwtSecret = uuid.New().String() settings.NodeSettings.Secret = uuid.New().String() settings.CertSettings.Email = json.Email })

同时，启动时若发现Node.Secret为空，InitNodeSecret()（internal/kernel/boot.go）也会兜底生成 UUID。这两处共同保证了：无论走安装向导还是跳过安装，系统都不会以空密钥运行。

总结

Node配置节是 Nginx UI 多服务器部署的基石：

• Name负责环境指示器中的本地服务器显示名，纯展示用途；
• Secret负责服务器间通信认证与免密 API 访问，集群场景必须保证各节点一致，且注意其 legacy 定位与配对认证的演进方向；
• SkipInstallation配合NGINX_UI_PREDEFINED_USER_NAME/NGINX_UI_PREDEFINED_USER_PASSWORD环境变量，可实现多服务器一键免交互部署。

配置时建议优先使用环境变量（便于容器化与配置管理工具注入），并显式设置共享密钥，避免多节点间因自动生成的随机 UUID 不同而导致通信失败。更详细的配置项与环境变量对照，可继续阅读 docs/guide/env.md 与 docs/guide/config-cluster.md。

• 后端
• 前端
• 运维
• MCP 服务